[[see discussion for changes at [Aqua toplevels]]]

There is a useful [MacOS X] command to create toplevel windows with a variety of appearances.  It can be used in two different forms:

 ::tk::unsupported::MacWindowStyle style <win> <style>

or

 ::tk::unsupported::MacWindowStyle style <win> <class> <attribute list>

In the first form, <style> uses pre-Appearance Manager styles, which are deprecated.  They equate to some variation of the 2nd, more general form, which should be used instead.  They can be any of
   * documentProc == document standardDocument
   * dBoxProc == modal none
   * plainDBox == plain none
   * altDBoxProc == altPlain none
   * movableDBoxProc == moveableModal none
   * zoomDocProc == moveableModal {closeBox resizable horizontalZoom verticalZoom}
   * floatProc == floating none
   * floatZoomProc == floating {closeBox resizable horizontalZoom verticalZoom}
   * floatSideProc == floating {closeBox resizable horizontalZoom verticalZoom sideTitlebar}
   * ...

See the documentation "Carbon: Window Manager Legacy Reference: Pre-Appearance Window Definition IDs" [http://developer.apple.com/documentation/Carbon/Reference/WindowManagerLegacy/wind_mgr_leg_ref/constant_1.html] for a description of each style.  In my (very limited) experience, this list does not correspond exactly to the implementation.  For example, rDocProc is not implemented, and floatGrowProc is implemented but not listed.

In the second form, <class> can be any of
   * alert
   * moveableAlert
   * modal
   * moveableModal
   * floating
   * help
   * document
   * sheet
   * toolbar
   * plain
   * altPlain
   * drawer

and <attribute list> should be

   * standardDocument
   * standardFloating
   * or some combination of closeBox, horizontalZoom, verticalZoom, collapseBox, resizable, sideTitlebar, metal.

See the documentation "Carbon: Window Manager Reference" for a description [http://developer.apple.com/documentation/Carbon/Reference/Window_Manager/index.html] (see Window Constants and Window Attributes).

In exploring the use of this command, there are two important points of which you should be aware.  Firstly, it is only possible to specify the window style when it is created; it cannot be altered.  This means that to use the command interactively, it must be given in the same Tcl/Tk command as creates the window.  For example:

 toplevel .t; ::tk::unsupported::MacWindowStyle style .t floatGrowProc

It is not usually necessary to do this in a script, so long as care is taken to make sure that no return to the event loop is possible in between.  Secondly, not all combinations of attributes are supported for each window class.  Unsuported combinations result in the shell being aborted.  For example, '''do''' try:

 toplevel .t; ::tk::unsupported::MacWindowStyle style .t floating {closeBox resizable}

On the other hand, '''do not''' try:

 toplevel .t; ::tk::unsupported::MacWindowStyle style .t moveableAlert {closeBox resizable}

Thirdly, be aware the "movable" in the Apple API and documents is usually rendered "moveable" in the Tcl/Tk ones.

Alastair Davies - 2005/01/27

----
[Category GUI]