<CHAPTER ID="chapter.misc">
  <TITLE>Miscellaneous</TITLE>

<P> This section describes several miscellaneous point of QTk.

<section ID="misc.color"><TITLE>Colors</TITLE>

<P>
Valid colors are atoms that describe the color like
<<red>>, <<blue>>, <<green>>, <<yellow>>, <<white>>, <<black>>

or records of the form
<<c(RR GG BB)>>

where <<RR>>, <<GG>> and <<BB>> are integers ranging from 0 to 255 and corresponding to the level of red, green and blue colors.

<section ID="misc.look"><TITLE>Looks</TITLE>

<P>
Default parameters of widgets can be specified and grouped into "looks". A look is obtained by :
<<<L={QTk.newLook}>>>

And you can specify the default for a widget by :
<<<{L.set widgetname(param1:value1 ... paramX:valueX)}>>>
For example :
<<<{L.set entry(background:white)}>>>
specifies that the entries will have a white background by default for the look L.
</P>
<P>
All widgets have a <<look>> parameter that specifies the look to use. Except when explicitly stated, widgets that serve as container for other widgets propagate their look parameter.

<section ID="misc.bitmap"><TITLE>Bitmaps</TITLE>

<subsection> <TITLE>Description</TITLE>
<P>
A bitmap is an image whose pixels can display either of two colors or be transparent. A bitmap image is defined by four things: a background color, a foreground color, and two bitmaps, called the source and the mask. Each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions. For pixels where the mask is zero, the image displays nothing, producing a transparent effect. For other pixels, the image displays the foreground color if the source data is one and the background color if the source data is zero. 
</P>
<P>
In QTk, bitmaps are built by the <<QTk.newImage>> function. This function takes one parameter : a record of the form : <<bitmap(param1:value1 ... paramX:valueX)>> and returns an object allowing to reference that bitmap and change it as needed. The valid parameters and methods are described below.
</P>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>

<ITEM> <<background:C>> : Specifies a background color for the image. If this option is set to <<nil>> then the background pixels will be transparent. This effect is achieved by using the source bitmap as the mask bitmap, ignoring any <<maskdata>>, <<maskfile>> or <<maskurl>> options.

<ITEM> <<data:VS>> : Specifies the contents of the source bitmap as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

<ITEM> <<file:VS>> : <<VS>> gives the name of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). 

<ITEM> <<url:VS>> : <<VS>> gives the url of a file whose contents define the source bitmap. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). 

<ITEM> <<foreground:C>> : Specifies a foreground color for the image. 

<ITEM> <<maskdata:VS>> : Specifies the contents of the mask as a string. The string must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

<ITEM> <<maskfile:VS>> : <<VS>> gives the name of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). 

<ITEM> <<maskurl:VS>> : <<VS>> gives the url of a file whose contents define the mask. The file must adhere to X11 bitmap format (e.g., as generated by the bitmap program). 

</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>
<P>
<LIST>
&interface_set;
&interface_get;
</LIST>


<section ID="misc.image"><TITLE>Photos</TITLE>

<P>
<subsection> <TITLE>Description</TITLE>
<P>
A photo is an image whose pixels can display any color or be transparent. A photo image is stored internally in full color (24 bits per pixel), and is displayed using dithering if necessary. Image data for a photo image can be obtained from a file, a string or a url. At present, only GIF and PPM/PGM formats are supported. A photo image is transparent in regions where no image data has been supplied.
</P>
<P>
In QTk, photos are built by the <<QTk.newImage>> function. This function takes one parameter : a record of the form : <<photot(param1:value1 ... paramX:valueX)>> and returns an object allowing to reference that photo and change it as needed. The valid parameters and methods are described below.
</P>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>
<ITEM> <<channel:C>> : <<C>> gives the name of a channel open for reading which is to be read to supply data for the photo image. The data format in the channel must be one of those for which there is an image format handler that can read data from a file or channel. 

<ITEM> <<data:VS>> : Specifies the contents of the image as a string. The format of the string must be one of those for which there is an image file format handler that will accept string data.

<ITEM> <<url:VS>> : <<VS>> gives the url of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data from a file or channel. 

<ITEM> <<format:VS>> : Specifies the name of the file format for the data specified with the <<data>>, <<url>> or <<file>> option. 

<ITEM> <<file:VS>> : <<VS>> gives the name of a file that is to be read to supply data for the photo image. The file format must be one of those for which there is an image file format handler that can read data from a file or channel. 

<ITEM> <<gamme:F>> : Specifies that the colors allocated for displaying this image in a window should be corrected for a non-linear display with the specified gamma exponent value. (The intensity produced by most CRT displays is a power function of the input value, to a good approximation; gamma is the exponent and is typically around 2). The value specified must be greater than zero. The default value is one (no correction). In general, values greater than one will make the image lighter, and values less than one will make it darker. <<F>> must be a float.

<ITEM> <<height:I>> : Specifies the height of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink vertically to fit the data stored in it. <<I>> must be non-negative integer.

<ITEM> <<palette:VS>> : Specifies the resolution of the color cube to be allocated for displaying this image, and thus the number of colors used from the colormaps of the windows where it is displayed. The <<VS>> string may be either a string containing a single decimal number, specifying the number of shades of gray to use, or a string containing three decimal numbers separated by slashes (/), specifying the number of shades of red, green and blue to use, respectively. If the first form (a single number) is used, the image will be displayed in monochrome (i.e., grayscale). 

<ITEM> <<width:I>> : Specifies the width of the image, in pixels. This option is useful primarily in situations where the user wishes to build up the contents of the image piece by piece. A value of zero (the default) allows the image to expand or shrink horizontally to fit the data stored in it. <<I>> must be non-negative integer.

</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>
<P>
<LIST>
&interface_set;
&interface_get;

<ITEM> <<blank()>> : Blank the image; that is, set the entire image to have no data, so it will be displayed as transparent, and the background of whatever window it is displayed in will show through. 

<ITEM> <<copy(I param1:value1 ... paramX:valueX)>> : Copies a region from the image <<I>> (which must be a photo image) to this image, possibly with pixel zooming and/or subsampling. If no options are specified, this command copies the whole of <<I>> into this image, starting at coordinates (0,0) in this image. The following options may be specified: 

<LIST>
<ITEM> <<from:R>> : Specifies a rectangular sub-region of the source image to be copied. <<R>> must be a record of the form : <<o(X1 Y1 X2 Y2)>>, where (X1,Y1) and (X2,Y2) specify diagonally opposite corners of the rectangle. If <<X2>> and <<Y2>> are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the <<from>> option is not given, the default is the whole source image. 

<ITEM> <<to:R)>> : Specifies a rectangular sub-region of the destination image to be affected.  <<R>> must be a record of the form : <<o(X1 Y1 X2 Y2)>>, where (X1,Y1) and (X2,Y2) specify diagonally opposite corners of the rectangle. If <<X2>> and <<Y2>> are not specified, the default value is (X1,Y1) plus the size of the source region (after subsampling and zooming, if specified). If <<X2>> and <<Y2>> are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion. 

<ITEM> <<"-shrink">> : Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the <<width>> or <<height>> configuration option, respectively. 

<ITEM> <<zoom:R>> : Specifies that the source region should be magnified by a factor. <<R>> must be a record of the form : <<o(X Y)>> where <<X>> is the factor in the X direction and <<Y>> the one in the Y direction. If <<Y>> is not given, the default value is the same as <<X>>. With this option, each pixel in the source image will be expanded into a block of <<X>> x <<Y>> pixels in the destination image, all the same color. <<X>> and <<Y>> must be greater than 0. 

<ITEM> <<subsample:R>> : Specifies that the source image should be reduced in size. <<R>> must be a record of the form <<o(X Y)>> where only <<X>>th pixel are kept in the X direction and only <<Y>>th pixel in the Y direction. Negative values will cause the image to be flipped about the Y or X axes, respectively. If <<Y>> is not given, the default value is the same as <<X>>. 

</LIST>

<ITEM> <<getColor(X Y V)>> : Binds <<V>> to the color of the pixel at coordinates (X,Y) in the image as a list of three integers between 0 and 255, representing the red, green and blue components respectively.

<ITEM> <<put(LR to:R)>> : Sets pixels in the photo to the colors specified in <<LR>>. <<LR>> is used to form a two-dimensional array of pixels that are copied into the photo. <<LR>> is a record of the form :
<<<
q(q(P11 P21 ... Px1)
  q(P12 P22 ... Px2)
  ...
  q(P1y P2y ... Pxy))>>>

Where all <<Pij>> are valid colors (see <ptr to="misc.color">). The <<to>> option can be used to specify the area of the photo to be affected. <<R>> must be a record of the corm <<o(X1 Y1 X2 Y2)>>. If only <<X1>> and <<Y1>> are given, the area affected has its top-left corner at (X1,Y1) and is the same size as the array given in data. If all four coordinates are given, they specify diagonally opposite corners of the affected rectangle, and the array given in data will be replicated as necessary in the X and Y directions to fill the rectangle. 

<ITEM> <<read(VS param1:value1 ... paramX:valueX)>> : Reads image data from the file named <<VS>> into the image. This command first searches the list of image file format handlers for a handler that can interpret the data in <<VS>>, and then reads the image in <<VS>> into the photo. The following options may be specified: 
<LIST>
<ITEM> <<format:VS>> : Specifies the format of the image data in filename. Specifically, only image file format handlers whose names begin with format-name will be used while searching for an image data format handler to read the data. 

<ITEM> <<from:R>> : Specifies a rectangular sub-region of the source image to be copied. <<R>> must be a record of the form : <<o(X1 Y1 X2 Y2)>>, where (X1,Y1) and (X2,Y2) specify diagonally opposite corners of the rectangle. If <<X2>> and <<Y2>> are not specified, the default value is the bottom-right corner of the source image. The pixels copied will include the left and top edges of the specified rectangle but not the bottom or right edges. If the <<from>> option is not given, the default is the whole source image. 

<ITEM> <<"-shrink">> : Specifies that the size of the destination image should be reduced, if necessary, so that the region being copied into is at the bottom-right corner of the image. This option will not affect the width or height of the image if the user has specified a non-zero value for the <<width>> or <<height>> configuration option, respectively. 

     -to x y
         Specifies the coordinates of the top-left corner of the region of imageName into which data from filename are to be read. The default is (0,0). 

<ITEM> <<to:R)>> : Specifies a rectangular sub-region of the destination image to be affected.  <<R>> must be a record of the form : <<o(X1 Y1 X2 Y2)>>, where (X1,Y1) and (X2,Y2) specify diagonally opposite corners of the rectangle. If <<X2>> and <<Y2>> are not specified, the default value is (X1,Y1) plus the size of the source region (after subsampling and zooming, if specified). If <<X2>> and <<Y2>> are specified, the source region will be replicated if necessary to fill the destination region in a tiled fashion. 

</LIST>

<ITEM> <<redither()>> : The dithering algorithm used in displaying photo images propagates quantization errors from one pixel to its neighbors. If the image data is supplied in pieces, the dithered image may not be exactly correct. Normally the difference is not noticeable, but if it is a problem, this command can be used to recalculate the dithered image in each window where the image is displayed. 


<ITEM> <<write(VS param1:value1 ... paramX:valueX)>> : Writes image data to a file named <<VS>>. The following options may be specified: 
<LIST>

<ITEM> <<format:VS>> : Specifies the name of the image file format handler to be used to write the data to the file. Specifically, this subcommand searches for the first handler whose name matches a initial substring of format-name and which has the capability to write an image file. If this option is not given, the first handler that has the capability to write an image file is used. 

<ITEM> <<from:R>> : Specifies a rectangular region of the image to be written to the image file. <<R>> must be a record of the form <<o(X1 Y1 X2 Y2)>>. If only <<X1>> and <<Y1>> are specified, the region extends from (X1,Y1) to the bottom-right corner of the photo. If all four coordinates are given, they specify diagonally opposite corners of the rectangular region. The default, if this option is not given, is the whole image. 

</LIST>

</LIST>

<section ID="misc.imagelibrary"><TITLE>Image libraries</TITLE>
<P>
When an application uses several bitmaps or photos, it is usefull to group all these images into a single file called an image library. Image librairies can be saved to files and loaded later, restoring all images that were stored inside the library. Moreover image libraires files are functors that can be linked to your application so that graphical ressources like images can be packaged inside your application binaries.
</P>
<P>
The function <<QTk.newImageLibrary>> returns an empty image library. An image library is an object that implements the following interface :

<LIST>

<ITEM> <<newPhoto(...)>> : Adds a photo to the image library. All the parameters are the same as the ones for <<QTk.newImage photo(...)>>, except a supplementary one : <<name:A>> that defines the image's name inside the image library. If not specified, a name is determined by the file name or url, or an error is raised if no name could be determined. <<A>> must be an atom.

<ITEM> <<newBitmap(...)>> : Adds a bitmap to the image library. All the parameters are the same as the ones for <<QTk.newImage bitmap(...)>>, except a supplementary one : <<name:A>> that defines the image's name inside the image library. If not specified, a name is determined by the file name or url, or an error is raised if no name could be determined. <<A>> must be an atom.

<ITEM> <<get(name:A image:V)>> : Binds <<V>> to the image in the image library that has the name <<A>>. The returned image is similar the images built using then <<QTk.newImage>> function. However, if you modify these images after they were created inside the image library, the image libray won't be updated. You need to explicitly save and reload the modified image into the library.

<ITEM> <<getNames(V)>> : Binds <<V>> to a list of atoms that are all the names of all avalaible images in the library.

<ITEM> <<remove(name:A)>> : Removes the image named <<A>> from the library if present, does nothing otherwise.
</LIST>

Image libraries can be also be saved and loaded to files :
<LIST>
<ITEM> <<{QTk.saveImageLibrary L VS}>> : This procedure saves the image library <<L>> to a file named <<VS>>.

<ITEM> <<{QTk.loadImageLibray VS}>> : This function returns an image library loaded from the file <<VS>>.
</LIST>
Saved image libraries are functors that you can directly import and link into your application's functor. To achieve this, you must do the following :

<LIST>

<ITEM> Build an image library, place all needed images inside and save it to a file ending with <<.ozf>> and whose first letter is uppercase (for example <<MyLib.ozf>>).

<ITEM> In your application's functor, you must <<require>> the image library and <<prepare>> the library by adding the following similar lines :
<<<
require MyLib
prepare BL=MyLib.buildLibrary
>>>
Note that the <<require>> and <<prepare>> part of functors are placed just before the <<define>> part.
<ITEM> In your <<define>> part, you must rebuild the image library by using a similar line :
<<<
Lib={QTk.buildImageLibrary BL}
>>>
</LIST>

Compiling your functor now staticaly includes all the required data for rebuilding the image library, and all the necessary commands for creating a new one from this data. The original image library file is no more needed for the correct execution of your application.

<section ID="misc.distance"><TITLE>Screen distances</TITLE>

<P>
A screen distance can be specified in different ways depending on the distance unit you want to use :
<LIST>
<ITEM> float : a distance in screen pixels.
<ITEM> a pair float#c : a distance in centimeters.
<ITEM> a pair float#i : a distance in inches.
<ITEM> a pair float#m : a distance in millimeters.
<ITEM> a pair float#p : a distance in picas.
</LIST>

<section ID="misc.cursor"><TITLE>Mouse cursors</TITLE>

<P>
The mouse cursor can be changed to a built-in mouse cursor or to a bitmap. The different built-in mouse cursors are the following atoms : <<<
X_cursor
arrow
based_arrow_down
based_arrow_up
boat
bogosity
bottom_left_corner
bottom_right_corner
bottom_side
bottom_tee
box_spiral
center_ptr
circle
clock
coffee_mug
cross
cross_reverse
crosshair
diamond_cross
dot
dotbox
double_arrow
draft_large
draft_small
draped_box
exchange
fleur
gobbler
gumby
hand1
hand2
heart
icon
iron_cross
left_ptr
left_side
left_tee
leftbutton
ll_angle
lr_angle
man
middlebutton
mouse
pencil
pirate
plus
question_arrow
right_ptr
right_side
right_tee
rightbutton
rtl_logo
sailboat
sb_down_arrow
sb_h_double_arrow
sb_left_arrow
sb_right_arrow
sb_v_double_arrow
shuttle
sizing
spider
spraycan
star
target
tcross
top_left_arrow
top_left_corner
top_right_corner
top_side
top_tee
trek
ul_angle
umbrella
ur_angle
watch
xterm
>>>

You can also specify a bitmap.

<section ID="misc.font"><TITLE>Text fonts</TITLE>

<subsection><TITLE>Description</TITLE>

<P>
Fonts are obtained by the <<QTk.newFont>> function. The only parameter of that function is a record describing the font in the following form : <<font(param1:value1 ... paramX:valueX)>>. Once obtained, a font can be used several times in different contexts (parameters of different widgets for example). Fonts can also be dynamically reconfigured and all widgets using the font redisplays themselves using the new attributes.
</P>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>
<ITEM> <<family:VS>> : The case-insensitive font family name. The following families are garanteed to exist on all platforms : <<Courier>> (a monospaced ``typewriter'' font), <<Times>> (a serifed ``newspaper'' font), and <<Helvetica>> (a sans-serif ``European'' font). The most closely matching native font family will automatically be substituted when one of the above font families is used. The name may also be the name of a native, platform-specific font family; in that case it will work as desired on one platform but may not display correctly on other platforms. If the family is unspecified or unrecognized, a platform-specific default font will be chosen. 

<ITEM> <<size:I>> : The desired size of the font. If <<I>> is a positive number, it is interpreted as a size in points. If <<I>> is a negative number, its absolute value is interpreted as a size in pixels. If a font cannot be displayed at the specified size, a nearby size will be chosen. If size is unspecified or zero, a platform-dependent default size will be chosen.  Sizes should normally be specified in points so the application will remain the same ruler size on the screen, even when changing screen resolutions or moving scripts across platforms. However, specifying pixels is useful in certain circumstances such as when a piece of text must line up with respect to a fixed-size bitmap.

<ITEM> <<weight:A>> : The nominal thickness of the characters in the font. The atom <<normal>> specifies a normal weight font, while <<bold>> specifies a bold font. The closest available weight to the one specified will be chosen. The default weight is <<normal>>. 

<ITEM> <<slant:A>> : The amount the characters in the font are slanted away from the vertical. Valid values for slant are the atoms <<roman>> and <<italic>>. A roman font is the normal, upright appearance of a font, while an italic font is one that is tilted some number of degrees from upright. The closest available slant to the one specified will be chosen. The default slant is <<roman>>. 

<ITEM> <<underline:B>> : Specifies whether characters in this font should be underlined. The default value for <<underline>> is <<false>>. <<B>> must be a boolean value.

<ITEM> <<overstrike:B>> : Specifies whether a horizontal line should be drawn through the middle of characters in this font. The default value for <<overstrike>> is <<false>>. <<B>> must be a boolean value.

</LIST>

<subsection><TITLE>Interface</TITLE>

<P>
Fonts obtained by <<Qtk.newFont>> are objects that support the following methods :

<LIST>

&interface_set;
&interface_get;

<ITEM> <<delete>> : Delete the font. If there are widgets using that font, it won't actually be deleted until all the instances are released. Those widgets will continue to display using the last known values for the font.

<ITEM> <<families(V)>> : Binds <<V>> to a list a string containing all available font families on the platform.

<ITEM> <<measure(VS V ?displayof:D)>> : Binds <<V>> to the amount of space the string <<VS>> would use in the given font when displayed in the window <<D>>. If the window <<D>> argument is omitted, it defaults to the main window. The return value is the total width in pixels of text, not including the extra pixels used by highly exagerrated characters such as cursive ``f''. If the string contains newlines or tabs, those characters are not expanded or treated specially when measuring the string. 

<ITEM> <<metrics(A V ?displayof:D>> : Binds <<V>> to metrics information of the font (font-specific data) when displayed in the window <<D>> or in the main window is the <<displayof>> parameter is not specified. The returned information depends on the value of <<A>> :

<LIST>
<ITEM> <<ascent>> : The amount in pixels that the tallest letter sticks up above the baseline of the font, plus any extra blank space added by the designer of the font. 

<ITEM> <<descent>> : The largest amount in pixels that any letter sticks down below the baseline of the font, plus any extra blank space added by the designer of the font. 

<ITEM> <<linespace>> :  Returns how far apart vertically in pixels two lines of text using the same font should be placed so that none of the characters in one line overlap any of the characters in the other line. This is generally the sum of the ascent above the baseline line plus the descent below the baseline. 

<ITEM> <<fixed>> : Returns a boolean flag that is ``1'' if this is a fixed-width font, where each normal character is the the same width as all the other characters, or is ``0'' if this is a proportionally-spaced font, where individual characters have different widths. The widths of control characters, tab characters, and other non-printing characters are not included when calculating this value. 
</LIST>

</LIST>

<section ID="misc.winfo"><TITLE>Window-related informations</TITLE>

<P>
All widgets have a <<winfo(parameter1:value1 ... parameterX:valueX)>> method that obtains window-related informations. <<parameterX>> must be a valid parameter for the <<winfo>>. <<valueX>> must be a free variable which will receive the current value of the parameter. The parameters for this method are :

<LIST>

<ITEM> <<cells>> : Returns an integer giving the number of cells in the color map for window. 

<ITEM> <<colormapfull>> : Returns <<true>> if the colormap for window is known to be full, <<false>> otherwise. The colormap for a window is
    ``known'' to be full if the last attempt to allocate a new color on that window failed and this application
    hasn't freed any colors in the colormap since the failed allocation. 

<ITEM> <<depth>> : Returns an integer giving the depth of window (number of bits per pixel).

<ITEM> <<fpixels>> : Returns a one parameter function. Giving a valid screen distance to this function (see <ptr to="misc.distance">) returns a floating-point value giving the number of pixels in the widget corresponding to that distance. The return value may be fractional; for an integer value, use <<winfo(pixels:V)>>. 

<ITEM> <<geometry>> : Returns a record of the form <<geometry(width:W height:H x:X y:Y)>> describing the size and position of the widget inside its parent.

<ITEM> <<height>> : Returns an integer giving widget's height in pixels. When a window is first created its height will be
    1 pixel; the height will eventually be changed by a geometry manager to fulfill the window's needs. If you
    need the true height immediately after creating a widget, invoke update to force the geometry manager to
    arrange it, or use <<winfo(reqheight:N)>> to get the window's requested height instead of its actual height. 

<ITEM> <<id>> : Returns a string giving a low-level platform-specific identifier for window. On Unix
    platforms, this is the X window identifier. Under Windows, this is the Windows HWND.

<ITEM> <<ismapped>> : Returns <<true>> if the widget is currently mapped, <<false>> otherwise. 

<ITEM> <<name>> : Returns widget's Tk name (i.e. its name within its parent, as opposed to its full path name).

<ITEM> <<parent>> : Returns the Tk path name of widget's parent, or an empty string if window is the main window of the
    application.

<ITEM> <<pixels>> : Returns a one parameter function. Giving a valid screen distance to this function (see <ptr to="misc.distance">) returns an integer value giving the number of pixels in the widget corresponding to that distance. The value is rounded to the nearest fractional value; for a fractional value, use <<winfo(fpixels:V)>>. 

<ITEM> <<pointerx>> : If the mouse pointer is on the same screen as the widget, returns an integer that is the pointer's x coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer isn't on the same screen as the widget then -1 is returned.  

<ITEM> <<pointery>> : If the mouse pointer is on the same screen as the widget, returns an integer that is the pointer's y coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer isn't on the same screen as the widget then -1 is returned.  

<ITEM> <<pointerxy>> : If the mouse pointer is on the same screen as the widget, returns a record of the form <<pointerxy(x:X y:Y)>> with <<X>> and <<Y>> being integers that are the pointer's coordinate, measured in pixels in the screen's root window. If a virtual root window is in use on the screen, the position is measured in the virtual root. If the mouse pointer isn't on the same screen as the widget then -1 is returned for both <<X>> and <<Y>>.

<ITEM> <<reqheight>> : Returns an integer giving widget's requested height, in pixels. This is the value used by window's
    geometry manager to compute its geometry. 

<ITEM> <<reqwidth>> : Returns an integer giving widget's requested width, in pixels. This is the value used by window's
    geometry manager to compute its geometry. 

<ITEM> <<rgb>> : Returns a one parameter function. Giving a valid color (see <ptr to="misc.color">) to this function, it returns a record of the form <<rgb(red:R green:G blue:B)>> which are the red, green, and blue intensities that correspond to the color in the widget. 

<ITEM> <<rootx>> : Returns an integer giving the x-coordinate, in the root window of the screen, of the upper-left
    corner of the widget's border 

<ITEM> <<rooty>> : Returns an integer giving the y-coordinate, in the root window of the screen, of the upper-left
    corner of the widget's border 

<ITEM> <<screen>> : Returns a string that is the name of the screen associated with the widget, in the form displayName.screenIndex. 

<ITEM> <<screencells>> : Returns an integer giving the number of cells in the default color map for the widget's screen. 

<ITEM> <<screendepth>> : Returns a decimal string giving the depth of the root window of the widget's screen (number of bits per
    pixel). 

<ITEM> <<screenheight>> : Returns an integer giving the height of window's screen, in pixels. 

<ITEM> <<screenmmheight>> : Returns an integer giving the height of window's screen, in millimeters. 

<ITEM> <<screenmmwidtht>> : Returns an integer giving the width of window's screen, in millimeters. 

<ITEM> <<screenvisual>> : Returns one of the following atoms to indicate the default visual class for the widget's screen: <<directcolor>>,
    <<grayscale>>, <<pseudocolor>>, <<staticcolor>>, <<staticgray>>, or <<truecolor>>. 

<ITEM> <<screenwidth>> : Returns an integer giving the width of the widget's screen, in pixels. 

<ITEM> <<server>> : Returns a string containing information about the server for the widget's display. The exact format of this
    string may vary from platform to platform. For X servers the string has the form ``XmajorRminor vendor
    vendorVersion'' where major and minor are the version and revision numbers provided by the server (e.g.,
    X11R5), vendor is the name of the vendor for the server, and vendorRelease is an integer release number
    provided by the server. 

<ITEM> <<toplevel>> : Returns an handle to the toplevel window of the widget.

<ITEM> <<viewable>> : Returns <<true>> if the widget and all of its ancestors up through the nearest toplevel window are mapped. Returns <<false>> if any of these windows are not mapped. 

<ITEM> <<visual>> : Returns one of the following atoms to indicate the visual class for the widget: <<directcolor>>, <<grayscale>>,
    <<pseudocolor>>, <<staticcolor>>, <<staticgray>>, or <<truecolor>>. 

<ITEM> <<visualid>> : Returns a string which is the X identifier for the visual for the widget. 

<ITEM> <<visualsavailable>> : Returns a list of records of the form <<visual(visual:A depth:I id:VS)>> with <<A>> and atom describing a visual class, <<I>> an integer and <<VS>> a string which is an X identifier. The list is composed of all the different visuals available on the screen that display's the widget.

<ITEM> <<vrootheight>> : Returns an integer that is the height of the virtual root window associated with the widget if there is one; otherwise returns the
    height of the widget's screen. 

<ITEM> <<vrootwidth>> : Returns an integer that is the width of the virtual root window associated with the widget if there is one; otherwise returns the
    width of the widget's screen. 

<ITEM> <<vrootx>> : Returns an integer that is the x-offset of the virtual root window associated with the widget, relative to the root window of its
    screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for the widget. 

<ITEM> <<vrooty>> : Returns an integer that is the y-offset of the virtual root window associated with the widget, relative to the root window of its
    screen. This is normally either zero or negative. Returns 0 if there is no virtual root window for the widget. 

<ITEM> <<width>> : Returns an integer giving widget's width in pixels. When a window is first created its width will be
    1 pixel; the width will eventually be changed by a geometry manager to fulfill the window's needs. If you
    need the true width immediately after creating a widget, invoke update to force the geometry manager to
    arrange it, or use <<winfo(reqwidth:N)>> to get the window's requested width instead of its actual width. 

<ITEM> <<x>>: Returns an integer giving the x-coordinate, in widget's parent, of the upper-left corner of
    widget's border. 

<ITEM> <<y>>: Returns an integer giving the y-coordinate, in widget's parent, of the upper-left corner of
    widget's border. 

</LIST>

<section ID="misc.menu"><TITLE>Menus</TITLE>

<subsection><TITLE>Description</TITLE>

<P>
A menu is a widget that displays a collection of one-line entries arranged in one or more columns. There exist several different types of entries, each with different properties. Entries of different types may be combined in a single menu. Menu entries are not the same as entry widgets. In fact, menu entries are not even distinct widgets; the entire menu is one widget. 
</P>
<P>
Menus are described by a record of the form <<menu(E1 E2 .. Ex param1:value1 ... paramY:valueY)>> where <<Ex>> are entries description like <<command(...)>>, <<checkbutton(...)>>, <<radiobutton(...)>>, <<cascade(...)>> or <<separator>>. The first three entry types (<<command>>, <<checkbutton>> and <<radiobutton>>) are very similar to the widgets of the same name, and have many parameters in common. The <<cascade(...)>> entry is very similar to the <<menu(...)>> itselves as that entry pulls out a complete menu. The <<separator>> entry is just an horizontal line. 
</P>
<P>
Menus are created either directly from their description by the <<menubutton>> widget, or using the <<Qtk.newMenu>> function. This function takes a menu description as parameter and returns a menu. This menu can be posted by called its <<post>> method for example.
<P>
<EM>MENUBARS</EM>
</P>
<P>
Any menu can be set as a menubar for a toplevel window, using the <<menu>> parameter of the toplevel <<td>> or <<lr>> widget. This menu's items will be displayed in a menubar accross the top of the window. These menus will behave according to the interface guidelines of their platforms. For every menu set as a menubar, a clone menu is made. See
the CLONES section for more information. 
</P>
<P>
<EM>CLONES</EM>
</P>
<P>
When a menu is set as a menubar for a toplevel window, or when a menu is torn off, a clone of the menu is made. This clone is a menu widget in its own right, but it is a child of the original. Changes in the configuration of the original are reflected in the clone. Additionally, any cascades that are pointed to are also cloned so that menu traversal will work right. Clones are destroyed when either the tearoff or menubar goes away, or when the original menu is destroyed. 
</P>

<subsection> <TITLE>Parameters</TITLE>
<P>
The menu description support the following parameters :

<LIST>
<ITEM> <<x:R>> : Where <<x>> starts from 1 and goes up one by one. <<R>> must be record describing a valid menu entry. This parameter defines the menu's <<x>>th entry. 

&param_activebackground;
&param_activeforeground;

<ITEM> <<activeborderwidth:P>> : Specifies a non-negative value indicating the width of the 3-D border to draw around active elements. <<P>> must be a valid screen distance (see  <ptr to="misc.distance">).

&param_background;
&param_borderwidth;
&param_cursor;
&param_disabledforeground;
&param_font;
&param_foreground;
&param_relief;
&param_takefocus;

<ITEM> <<tearoff:B>> : Specifies whether or not the menu should include a tear-off entry at the top. The default menu bindings arrange for the menu to be torn off when the tear-off entry is invoked. <<B>> must be a boolean.

<ITEM> <<title:VS>> : Specifies title of the window created when this menu is torn off. If the title is NULL, then the window will have the title of the menubutton or the text of the cascade item from which this menu was invoked. 

<ITEM> <<type:A>> : This option can be one of the following atoms : <<menubar>>, <<tearoff>>, or <<normal>>, and is set when the menu is created.

<ITEM> <<action:C>> : Specifies an Oz command to execute just before the menu is posted.

</LIST>

<subsection> <TITLE>Interface</TITLE>
<P>
<LIST>

<ITEM> <<insert(I T)>> : Inserts the menu entry specified by <<T>> at the position the position <<I>> of the menu. <<T>> must be a record describing a value menu entry, <<I>> must be a positive integer.

<ITEM> <<index(I V)>> : Binds <<V>> to the object controlling the menu entry referenced by <<I>>, or binds <<V>> to the atom <<none>> if no menu entry is referenced by <<I>>. <<I>> can be one of the following :

<LIST>

<ITEM> integer : Specifies the entry numerically, where 1 is the first one (topmost).

<ITEM> <<active>> : Indicates the entry that is currently active. If no entry is active then this form is equivalent to <<none>>.

<ITEM> <<end>> : Indicates the bottommost entry in the menu. If there are no entries in the menu then this form is equivalent to <<none>>.

<ITEM> <<last>> : Same as end. 

<ITEM> <<none>> : Indicates ``no entry at all''.

<ITEM> <<"@"#Y>> : Where <<Y>> is an integer. In this form, <<Y>> is treated as a y-coordinate in the menu's window; the entry closest to that y-coordinate is used.

</LIST> 

<ITEM> <<post(X Y)>> : Arrange for the menu to be displayed on the screen at the root-window coordinates given by x and y. These coordinates are adjusted if necessary to guarantee that the entire menu is visible on the screen. 

</LIST>

<subsection> <TITLE>Menu entries</TITLE>
<P>
Menu entries are displayed with up to three separate fields. The main field is a label in the form of a text string, a bitmap, or an image, controlled by the <<label>>, <<bitmap>>, and <<image>> options for the entry. If the <<accelerator>> option is specified for an entry then a second textual field is displayed to the right of the label. The accelerator typically describes a keystroke sequence that may be typed in the application to cause the same result as invoking the menu entry. The third field is an indicator. The indicator is present only for checkbutton or radiobutton entries. It indicates whether the entry is selected or not, and is displayed to the left of the entry's string. 
</P>
<P>
In normal use, an entry becomes active (displays itself differently) whenever the mouse pointer is over the entry. If a mouse button is released over the entry then the entry is invoked. The effect of invocation is different for each type of entry; these effects are described below in the sections on individual entries. 
</P>
<P>
Entries may be disabled, which causes their labels and accelerators to be displayed with dimmer colors. The default menu bindings will not allow a disabled entry to be activated or invoked. Disabled entries may be re-enabled, at which point it becomes possible to activate and invoke them again. 
</P>
<P>
Whenever a menu's active entry is changed, a <<MenuSelect>> virtual event is send to the menu. The active item can then be queried from the menu, and an action can be taken, such as setting context-sensitive help text for the entry. 
</P>

<subsubsection> <TITLE>Tear-off</TITLE>
<P>
A tear-off entry appears at the top of the menu if enabled with the <<tearoff>> option of the menu. It is not an entry like others because it is not created the same way. When a tear-off entry is created it appears as a dashed line at the top of the menu. Under the default bindings, invoking the tear-off entry causes a torn-off copy to be made of the menu and all of its submenus. 
</P>
<subsubsection> <TITLE>Command</TITLE>

<P><EM>Description</EM></P><P>

The most common kind of menu entry is a command entry, which behaves much like a button widget. When a command entry is invoked, the Oz command specified by the <<action>> parameter is executed.
</P>
<P>
A command menu entry is described by a record of the form :
<<<command(parameter1:value1 ... parameterX:valueX)>>>
</P>
<P><EM>Parameters</EM></P><P>

<LIST>

&param_activebackground;
&param_activeforeground;
&param_background;
&param_bitmap;

<ITEM> <<columnbreak:B>> : When this option is <<true>>, the entry appears below the previous entry. When this option is<<false>>, the menu appears at the top of a new column in the menu. 

&param_font;
&param_foreground;

<ITEM> <<hidemargin:B>> : Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. <<true>> indicates that the margin for the entry is hidden; <<false>> means that the margin is used. 

&param_image;

<ITEM> <<state:A>> : Specifies one of three states for the button: <<normal>>, <<active>>, or <<disabled>>. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the <<activeforeground>> option for the menu along with the <<activebackground>> option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the <<disabledforeground>> option for the menu and the <<background>> option from the entry.

&param_underline;
&param_text;

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the entry. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<accelerator:R>> : Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows: 

   <Table>
	<TR>
	  <TH/<<key>> option value/
	  <TH/accelerator/
	  <TH/event binding/
	<TR>
	  <TD/<<a>>/
	  <TD/<Key/a//
	  <TD/<Samp/a//
	<TR>
	  <TD/<<ctrl(a)>>/
	  <TD/<Key/C-a//
	  <TD/<Samp/&lt;Control-a&gt;//
	<TR>
	  <TD/<<alt(a)>>/
	  <TD/<Key/A-a//
	  <TD/<Samp/&lt;Alt-a&gt;//
	<TR>
	  <TD/<<alt(ctrl(a))>>/
	  <TD/<Key/A-C-a//
	  <TD/<Samp/&lt;Alt-Control-a&gt;//
	<TR>
	  <TD/<<ctrl(alt(a))>>/
	  <TD/<Key/C-A-a//
	  <TD/<Samp/&lt;Control-Alt-a&gt;//
        <TR>
          <TD/virtual string/
          <TD/virtual string/
          <TD/none/
      </Table>

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

&param_handle;
&param_feature;

</LIST>

</P><P><EM>Interface</EM></P><P>

The object controlling the menu entry implements the following methods :
<LIST>
&interface_set;
&interface_get;
<ITEM> <<invoke>> : Invoke the action of the menu entry. If the menu entry is disabled then nothing happens. 

<ITEM> <<delete>> : Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

<ITEM> <<position(Y)>> : Binds <<Y>> to a postive integer giving the y-coordinate within the menu window of the topmost pixel of the entry. 

<ITEM> <<type(V)>> : Binds <<V>> to the type of the entry (in this case, to <<command>>).

</LIST>

<subsubsection> <TITLE>Checkbutton</TITLE>

<P><EM>Description</EM></P><P>

A checkbutton menu entry behaves much like a checkbutton widget. When it is invoked it toggles back and forth between the selected and deselected states. An indicator box is displayed to the left of the label in a checkbutton entry. If the entry is selected then the indicator's center is displayed in the color given by the <<selectcolor>> option for the entry; otherwise the indicator's center is displayed in the background color for the menu. If an <<action>> option is specified for a checkbutton entry, then the Oz command is executed each time the user change the state of the entry; this happens after toggling the entry's selected state. 
</P>
<P>
A checkbutton menu entry is described by a record of the form :
<<<checkbutton(parameter1:value1 ... parameterX:valueX)>>>
</P>
<P><EM>Parameters</EM></P><P>

<LIST>

<ITEM> <<1:B>> : Specifies whether or not the menu entry is toggled on or off. This option can be used with the <<set()>> and <<get()>> methods only. <<B>> must be a boolean.

<ITEM> <<init:B>> : Specifies whether or not the menu entry is toggled on or off. This option can be used at creation time only. <<B>> must be a boolean.

&param_activebackground;
&param_activeforeground;
&param_background;
&param_bitmap;

<ITEM> <<columnbreak:B>> : When this option is <<true>>, the entry appears below the previous entry. When this option is<<false>>, the menu appears at the top of a new column in the menu. 

&param_font;
&param_foreground;

<ITEM> <<hidemargin:B>> : Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. <<true>> indicates that the margin for the entry is hidden; <<false>> means that the margin is used. 

&param_image;

<ITEM> <<indicatoron:B>> : Specifies whether or not the indicator should be displayed. <<B>> must be a boolean.

<ITEM> <<selectcolor:C>> : Specifies the color to display in the indicator when the entry is selected. If the value is <<nil>> (default) then the <<selectcolor>> option for the menu determines the indicator color. 

<ITEM> <<selectimage:I>> : Specifies an image to display in the entry (in place of the <<image>> option) when it is selected. <<I>> must be a valid image (see above). This option is ignored unless the <<image>> option has been specified. 

<ITEM> <<state:A>> : Specifies one of three states for the button: <<normal>>, <<active>>, or <<disabled>>. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the <<activeforeground>> option for the menu along with the <<activebackground>> option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the <<disabledforeground>> option for the menu and the <<background>> option from the entry.

&param_underline;
&param_text;

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the entry. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<accelerator:R>> : Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows: 

   <Table>
	<TR>
	  <TH/<<key>> option value/
	  <TH/accelerator/
	  <TH/event binding/
	<TR>
	  <TD/<<a>>/
	  <TD/<Key/a//
	  <TD/<Samp/a//
	<TR>
	  <TD/<<ctrl(a)>>/
	  <TD/<Key/C-a//
	  <TD/<Samp/&lt;Control-a&gt;//
	<TR>
	  <TD/<<alt(a)>>/
	  <TD/<Key/A-a//
	  <TD/<Samp/&lt;Alt-a&gt;//
	<TR>
	  <TD/<<alt(ctrl(a))>>/
	  <TD/<Key/A-C-a//
	  <TD/<Samp/&lt;Alt-Control-a&gt;//
	<TR>
	  <TD/<<ctrl(alt(a))>>/
	  <TD/<Key/C-A-a//
	  <TD/<Samp/&lt;Control-Alt-a&gt;//
        <TR>
          <TD/virtual string/
          <TD/virtual string/
          <TD/none/
      </Table>

<ITEM> <<return:V>> : When the toplevel window is closed, <<V>> is binded to <<true>> is the menu entry is selected, otherwise it is binded to <<false>>.

&param_handle;
&param_feature;

</LIST>

</P><P><EM>Interface</EM></P><P>

The object controlling the menu entry implements the following methods :
<LIST>
&interface_set;
&interface_get;
<ITEM> <<invoke>> : Invoke the action of the menu entry. If the menu entry is disabled then nothing happens. 

<ITEM> <<delete>> : Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

<ITEM> <<position(Y)>> : Binds <<Y>> to a postive integer giving the y-coordinate within the menu window of the topmost pixel of the entry. 

<ITEM> <<type(V)>> : Binds <<V>> to the type of the entry (in this case, to <<checkbutton>>).

</LIST>

<subsubsection> <TITLE>Radiobutton</TITLE>

<P><EM>Description</EM></P><P>

A radiobutton menu entry behaves much like a radiobutton widget. Radiobutton entries are organized in groups along with the <<radiobutton>> and <<tbradiobutton>> widgets. Widgets are grouped together if their <<group>> parameters are set to the same atom. Only one entry of a group may be selected at a time. An indicator diamond is displayed to the left of the label in each radiobutton entry. If the entry is selected then the indicator's center is displayed in the color given by the <<selectcolor>> option for the entry; otherwise the indicator's center is displayed in the
background color for the menu. If an <<action>> option is specified for a radiobutton entry, then the specified Oz command is executed just after the user selects the entry.
</P>
<P>
A radiobutton menu entry is described by a record of the form :
<<<radiobutton(parameter1:value1 ... parameterX:valueX)>>>
</P>
<P><EM>Parameters</EM></P><P>

<LIST>

<ITEM> <<1:B>> : Specifies if the button is on or off. If <<B>> is <<true>> then the button is selelected. All other radiobuttons in the same group are deselected. If <<B>> is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter can be used with the <<set()>> and <<get()>> methods only. <<B>> must be a boolean.

<ITEM> <<init:B>> : Specifies if the button is on or off. If <<B>> is <<true>> then the button is selelected. All other radiobuttons in the same group are deselected. If <<B>> is false then the button is deselected. This can end in no radiobutton in the same group selected at all. This parameter is valid at creation time only. <<B>> must be a boolean.

<ITEM> <<return:V>> : When the window is closed, <<V>> is bound to <<true>> if the radiobutton, false otherwise. This parameter is valid at creation time only. <<V>> must be a free variable.

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the button. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<group:A>> : Specifies what group the radiobutton belongs to. All radiobuttons that use the same <<A>> belong to the same group (only one can be selected at a time in a group). Valid at necessary at creation time only. <<A>> must be an atom.

&param_activebackground;
&param_activeforeground;
&param_background;
&param_bitmap;

<ITEM> <<columnbreak:B>> : When this option is <<true>>, the entry appears below the previous entry. When this option is<<false>>, the menu appears at the top of a new column in the menu. 

&param_font;
&param_foreground;

<ITEM> <<hidemargin:B>> : Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. <<true>> indicates that the margin for the entry is hidden; <<false>> means that the margin is used. 

&param_image;

<ITEM> <<indicatoron:B>> : Specifies whether or not the indicator should be displayed. <<B>> must be a boolean.

<ITEM> <<selectcolor:C>> : Specifies the color to display in the indicator when the entry is selected. If the value is <<nil>> (default) then the <<selectcolor>> option for the menu determines the indicator color. 

<ITEM> <<selectimage:I>> : Specifies an image to display in the entry (in place of the <<image>> option) when it is selected. <<I>> must be a valid image (see above). This option is ignored unless the <<image>> option has been specified. 

<ITEM> <<state:A>> : Specifies one of three states for the button: <<normal>>, <<active>>, or <<disabled>>. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the <<activeforeground>> option for the menu along with the <<activebackground>> option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the <<disabledforeground>> option for the menu and the <<background>> option from the entry.

&param_underline;
&param_text;

<ITEM> <<accelerator:R>> : Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows: 

   <Table>
	<TR>
	  <TH/<<key>> option value/
	  <TH/accelerator/
	  <TH/event binding/
	<TR>
	  <TD/<<a>>/
	  <TD/<Key/a//
	  <TD/<Samp/a//
	<TR>
	  <TD/<<ctrl(a)>>/
	  <TD/<Key/C-a//
	  <TD/<Samp/&lt;Control-a&gt;//
	<TR>
	  <TD/<<alt(a)>>/
	  <TD/<Key/A-a//
	  <TD/<Samp/&lt;Alt-a&gt;//
	<TR>
	  <TD/<<alt(ctrl(a))>>/
	  <TD/<Key/A-C-a//
	  <TD/<Samp/&lt;Alt-Control-a&gt;//
	<TR>
	  <TD/<<ctrl(alt(a))>>/
	  <TD/<Key/C-A-a//
	  <TD/<Samp/&lt;Control-Alt-a&gt;//
        <TR>
          <TD/virtual string/
          <TD/virtual string/
          <TD/none/
      </Table>

&param_handle;
&param_feature;

</LIST>

</P><P><EM>Interface</EM></P><P>

The object controlling the menu entry implements the following methods :
<LIST>
&interface_set;
&interface_get;
<ITEM> <<invoke>> : Invoke the action of the menu entry. If the menu entry is disabled then nothing happens. 

<ITEM> <<delete>> : Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

<ITEM> <<position(Y)>> : Binds <<Y>> to a postive integer giving the y-coordinate within the menu window of the topmost pixel of the entry. 

<ITEM> <<type(V)>> : Binds <<V>> to the type of the entry (in this case, to <<radiobutton>>).

</LIST>

<subsubsection> <TITLE>Cascade</TITLE>

<P><EM>Description</EM></P><P>
A cascade entry is one with an associated menu (determined by the <<menu>> option). Cascade entries allow the construction of cascading menus. 
</P>
<P>
A cascade menu entry is described by a record of the form :
<<<cascade(parameter1:value1 ... parameterX:valueX)>>>
</P>
<P><EM>Parameters</EM></P><P>

<LIST>

&param_activebackground;
&param_activeforeground;
&param_background;
&param_bitmap;

<ITEM> <<columnbreak:B>> : When this option is <<true>>, the entry appears below the previous entry. When this option is<<false>>, the menu appears at the top of a new column in the menu. 

&param_font;
&param_foreground;

<ITEM> <<hidemargin:B>> : Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. <<true>> indicates that the margin for the entry is hidden; <<false>> means that the margin is used. 

&param_image;

<ITEM> <<state:A>> : Specifies one of three states for the button: <<normal>>, <<active>>, or <<disabled>>. In normal state the entry is displayed using the foreground option for the menu and the background option from the entry or the menu. The active state is typically used when the pointer is over the entry. In active state the entry is displayed using the <<activeforeground>> option for the menu along with the <<activebackground>> option from the entry. Disabled state means that the entry should be insensitive: the default bindings will refuse to activate or invoke the entry. In this state the entry is displayed according to the <<disabledforeground>> option for the menu and the <<background>> option from the entry.

&param_underline;
&param_text;

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the entry. <<C>> can take several different forms (see <ptr to="basics.events">).

<ITEM> <<accelerator:R>> : Specifies the keyboard accelerator and event binding to be created for the menu entry. They can be used as follows: 

   <Table>
	<TR>
	  <TH/<<key>> option value/
	  <TH/accelerator/
	  <TH/event binding/
	<TR>
	  <TD/<<a>>/
	  <TD/<Key/a//
	  <TD/<Samp/a//
	<TR>
	  <TD/<<ctrl(a)>>/
	  <TD/<Key/C-a//
	  <TD/<Samp/&lt;Control-a&gt;//
	<TR>
	  <TD/<<alt(a)>>/
	  <TD/<Key/A-a//
	  <TD/<Samp/&lt;Alt-a&gt;//
	<TR>
	  <TD/<<alt(ctrl(a))>>/
	  <TD/<Key/A-C-a//
	  <TD/<Samp/&lt;Alt-Control-a&gt;//
	<TR>
	  <TD/<<ctrl(alt(a))>>/
	  <TD/<Key/C-A-a//
	  <TD/<Samp/&lt;Control-Alt-a&gt;//
        <TR>
          <TD/virtual string/
          <TD/virtual string/
          <TD/none/
      </Table>

<ITEM> <<menu:O>> : Specifies the menu that is posted when the user selects the cascade entry. <<O>> must be a record describing a proper menu. See <ptr to="misc.menu"> for menu details.

&param_handle;
&param_feature;

</LIST>

</P><P><EM>Interface</EM></P><P>

The object controlling the menu entry implements the following methods :
<LIST>
&interface_set;
&interface_get;
<ITEM> <<invoke>> : Invoke the action of the menu entry. If the menu entry is disabled then nothing happens. 

<ITEM> <<delete>> : Deletes the menu entry from the menu. Further access to this menu entry will raise errors.

<ITEM> <<position(Y)>> : Binds <<Y>> to a postive integer giving the y-coordinate within the menu window of the topmost pixel of the entry. 

<ITEM> <<type(V)>> : Binds <<V>> to the type of the entry (in this case, to <<cascade>>).

</LIST>

<subsubsection> <TITLE>Separator</TITLE>

<P><EM>Description</EM></P><P>
A separator is an entry that is displayed as a horizontal dividing line. A separator may not be activated or invoked, and it has no behavior other than its display
appearance. 

</P>
<P>
A separator menu entry is described by a record of the form :
<<<separator(parameter1:value1 ... parameterX:valueX)>>>
</P>
<P><EM>Parameters</EM></P><P>

<LIST>

<ITEM> <<columnbreak:B>> : When this option is <<true>>, the entry appears below the previous entry. When this option is<<false>>, the menu appears at the top of a new column in the menu. 

<ITEM> <<hidemargin:B>> : Specifies whether the standard margins should be drawn for this menu entry. This is useful when creating palette with images in them, i.e., color palettes, pattern palettes, etc. <<true>> indicates that the margin for the entry is hidden; <<false>> means that the margin is used. 

&param_handle;
&param_feature;

</LIST>

</P><P><EM>Interface</EM></P><P>

The object controlling the menu entry implements the following methods :
<LIST>
&interface_set;
&interface_get;

<ITEM> <<type(V)>> : Binds <<V>> to the type of the entry (in this case, to <<separator>>).

</LIST>

</CHAPTER>
