<section ID="chapter.widgets.toplevel">
  <TITLE>Toplevel widgets</TITLE>


<subsection> <TITLE>Description</TITLE>

<P>

The very first widget you can use to build a window must be either <<td>> or <<lr>>. This particular widget is called the toplevel widget. A toplevel widget is a <<td>> or <<lr>> widget with added features and functionalities. This section will only describe these new parameters, see the specific <<td>> and <<lr>> documentation for the other supported parameters (See <ptr to="chapter.widgets.tdlr">).

</P>
<P>
Note that the <<glue>> parameter is <<nswe>> by default and that can't be changed (the toplevel widget is always glued to the border of the window).
</P>
<P>
Note also that a freshly created toplevel window is not displayed by default. Use the <<show>> method to display it once built.
</p>

<subsection> <TITLE>Parameters</TITLE>

<P>

<LIST>

<ITEM> <<action:C>> : Specifies an action to execute just after the user has clicked the close button of the window but before doing anything such as actually closing the window. <<C>> can take several different forms (see <ptr to="basics.events">). <<C>> defaults to <<toplevel#close>> to close the window.

<ITEM> <<return:V>> : If the execution of the action of the toplevel closes the window, <<V>> is bound to true. In all other cases where the window is closed, <<V>> is bound to false. This parameter is valid at creation time only. <<V>> must be a free variable.

<ITEM> <<title:VS>> : <<VS>> specifies a virtual string to pass to the the window manager for use as the title for the window. <<VS>> must be a virtual string.

<ITEM> <<aspect:R>> : <<R>> specifies a range to pass to the window manager for acceptable ratios for the window. <<R>> must be either the atom <<aspect>> to remove all aspect ratio restrictions, or an atom of the form <<aspect(minNumer:I1 minDenom:I2 maxNumer:I3 maxDenom:I4)>> where <<I1>> to <<I4>> must be integers. In such a case, the aspect ratio of window (width/length) will be  constrained to lie between <<I1>>/<<I2>> and <<I3/I4>>. 

<ITEM> <<client:VS>> : Stores <<VS>> (which should be the name of the host on which the application is executing) in window's WM_CLIENT_MACHINE property for use by the window manager or session manager. If <<VS>> is <<nil>>, the command deletes the WM_CLIENT_MACHINE property from window. <<VS>> must be a virtual string.

<ITEM> <<focusmodel:A>> : Specifies the focul model for the window. If <<A>> is the atom <<active>>, the window will claim the input focus for itself or its descendants, even at times when the focus is currently in some other application. If <<A>> is the atom <<passive>>, the window will never claim the focus for itself: the window manager should give the focus to window at appropriate times. However, once the focus has been given to window or one of its descendants, the application may re-assign the focus among window's descendants. The focus model defaults to <<passive>> and the <<focus>> method of widgets assumes a passive model of focusing. <<A>> must be one of the following atoms : <<passive>> or <<active>>.

<ITEM> <<geometry:R>> : Specifies a new geometry for the window (a geometry is the location and size of the window on the screen).<<R>> must be a record of the form <<geometry(x:I1 y:I2 width:I3 height:I4)>>, <<geometry(x:I1 y:I2)>> or <<geometry(widht:I3 height:I4)>>  where <<I1>> to <<I4>> are positive integers. <<I1>> specifies the number of pixels between the left edge of the screen and the left edge of window's border while <<I2>> specifies the number of pixels between the top edge of the screen and the top edge of the window's border. <<I3>> and <<I4>> specifies the desired dimensions of the window.

<ITEM> <<grid:R>> : Specifies that the window is to be managed as a gridded window. <<R>> must be either the atom <<grid>> to remove all gridding restrictions, are a record of the form <<grid(baseWidth:I1 baseWidth:I2 heightInc:I3 widthInc:I4)>> where <<I1>> to <<I4>> are positive integers. In such a case, <<I1>> and <<I2>> specify the number of grid units corresponding to the pixel dimensions requested internally by the window. <<I3>> and <<I4>> specifies the number of pixels in each horizontal and vertical grid unit.  These four values determine a range of acceptable sizes for the window, corresponding to grid-based widths and heights that are non-negative integers. during manual resizing, the window manager will restrict the window's size to one of these acceptable sizes. Furthermore, during manual resizing the window manager will display the window's current size in terms of grid units rather than pixels.

<ITEM> <<group:H>> : Specifies a window for the leader of a group of related windows. The window manager may use this information, for example, to unmap all of the windows in a group when the group's leader is iconified. <<H>> must be either a handle of another toplevel window, or <<nil>> to remove the window from any group association.

<ITEM> <<iconbitmap:I>> : Specifies a bitmap to be displayed in the window's icon. <<I>> must be a valid bitmap (see <ptr to="misc.bitmap">).

<ITEM> <<iconmask:I>> : Specifies a bitmap to be used as a mask in confunction with the <<iconbitmap>> parameter. Where the mask has zeroes no icon will be displayed; where it has ones, the bits from the icon bitmap will be displayed. <<I>> must be a valid bitmap (see <ptr to="misc.bitmap">).

<ITEM> <<iconname:VS>> : Specifies a virtual string to use inside the icon associated with the window. <<VS>> must be a virtual string.

<ITEM> <<iconposition:R>> : Specifies a position for the icon of the window. <<R>> must be a record of the form <<iconposition(x:I1 y:I2)>> where <<I1>> and <<I2>> are integers that specify the desired position of the icon.

<ITEM> <<iconwindow:H>> : Specifies a window to use as icon. When iconified, the window specified by <<H>> is mapped and when uniconified, <<H>> is unmapped. <<H>> must be a handle to another window.

<ITEM> <<maxsize:R>> : Specifies the maximum size the window can claim. <<R>> must be a record of the form <<maxsize(width:I1 height:I2)>> where <<I1>> and <<I2>> are integers specifying the maximum dimension in pixels (or in grid units if the window is gridded).

<ITEM> <<minsize:R>> : Specifies the minimum size the window can claim. <<R>> must be a record of the form <<minsize(width:I1 height:I2)>> where <<I1>> and <<I2>> are integers specifying the minimum dimension in pixels (or in grid units if the window is gridded).

<ITEM> <<resizable:R>> : Specifies if the window can be resized vertically and/or horizontally. <<R>> must be a record of the form <<resizable(width:B1 height:B2)>> where <<B1>> and <<B2>> are booleans that are <<true>> if the window is to be resizable in that direction or <<false>> otherwise.

<ITEM> <<transient:H>> : Specifies that the window must work on behalf of the window <<H>>. Some window managers will use this information to manage the window specially. If <<H>> is specified as <<nil>> then the window is marked as not being a transient window any more. Oetherwise <<H>> must be a handle to another toplevel window.

</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

<ITEM> <<show(wait:B1 modal:B2)>> : Makes the window to be visible. If <<B1>> is <<true>>, the call to this method blocks until the window is closed. <<B1>> defaults to <<false>>. If <<B2>> is true, the window is made modal, that is it claims all the user input for the Oz process. Warning use this option with care as a modal window will prevent any other window in the current process to be active, even if the modal window is modal. Modal windows should always be transient windows that requires a user input before doing any further action.

<ITEM> <<wait>> : Waits for the window to be closed.
<ITEM> <<hide>> : Hides the window. The window can be displayed again by using the <<show>> method.

<ITEM> <<close>> : Closes the window. The variables specified as the  <<return>> parameters of widgets are bound to their corresponding value. No more action can be taken on the window of the widgets displayed inside.

<item> <<iconify>> : Iconifies the window.

<ITEM> <<deiconify>> : Deiconifies the window.

</LIST>


</section>
