Panel: options

Syntax

{<name>:} options {<strings>}

Description

Option menu sub-panel. A sub-panel with a pulldown menu of selectable options. The currently selected option is shown in the sub-panel. Options can be text or image.

Membership

• Panel window

• Tab window

• Table window

Parameters

• <name> A name to be given to the sub-panel for reference purposes.

• <strings>
  The text (labels) to appear in the pulldown menu. They can be omitted when the options are to be shown in image form.

Switches

• -bc=<color>
  The background color for the options sub-panel and pulldown menu. When the menu is an image menu, a value of no_change will use the color of the sub-panel’s parent window. This is applicable to monochrome image files only.

• -cr=<file(s)>
  Display a raster image. This can be the name of one image file containing many cameos, or more when images from different files are required. Multiple files should be comma-separated all enclosed within < and >.

• -c=<num>
  The width of the options box in characters. This option is only used for text menus on Win32 systems and is ignored on other configurations.

• -d=<num>
  The default option to be initially displayed in the sub-panel. If omitted, option one is displayed.

• -dim=<screen_xy>
  Define the dimensions of the sub-panel in pixels. This is usually redundant because option menus are by default created sized-to-fit, but is useful when the size needs to be overridden. This is a two-element numeric array providing width and height. If only one is required, the other can be set to -1 and will be ignored.

• -fc=<color>
  The foreground color for the images. This is applicable to monochrome images only.

• -fo=<font>
  The font to be used for option text. This must be a fixed font. If omitted the menu inherits the font of its parent row or column. This is ignored for image menus.

• -gh
  The options menu should be initially ghosted, i.e. insensitive to user-interaction.

• -h=<num>
  The height (in options) of the pulldown menu. By default the height is the number of options in the menu unless the -w switch is present. This switch is ignored on Windows systems.

• -inv
  Make the sub-panel invisible on creation.

• -j=<just>
  The justification of the options menu within its parent row or column. Within a parent row the value should be one of L, M, R. Within a parent column the value should be one of T, M or B. The default in both cases is M.

• -link=<text>
  The resize linkage for the panel. This ties panel edges to one or more edges of the parent window, with the result that when the parent window gets resized, the panel gets automatically resized as well. <text> is a combination of the characters L, R, T, B and M. A value of "LRTB" means that the left, right, top and bottom edges of a sub-panel are linked to its parent. The default value is "TL", which links the left and top edges to the parent window but does no resizing because its right and bottom edges are not linked. Note that the linkage is to edges of the parent window, not to column/row extremities. More complicated linkage requirements should be done via the window.resize callback on the parent window.

• -pj=<just>
  The position justification of the sub-panel within the panel window. This combined with the -x and -y switches can be used to position the sub-panel by one of its corners. The default is ’TL’. It also defines the control point to be used when repositioning the sub-panel after creation.

• -res=<num>
  Used in conjunction with the -cr switch, this defines a scaling factor for the image. For example, a value of 0.5 will show the image half-size.

• -t=<strings>
  User-defined strings which can be used as values corresponding to options, e.g when the options are in image form. There should be as many elements in <strings> as there options. The default values for non-image sub-panels are the labels appearing in the pulldown menu.

• -tc=<color>
  The color for text in the options menu. If omitted the parent window "other color" is used.

• -th=<num>
  Draw a border of width <num> pixels around each image in the menu. The color used is the parent window "other color". This is ignored for text menus.

• -v
  Option numbering should run vertically. The default is horizontal.

• -w=<num>
  The width (in options) of the pulldown menu. By default the width is one. On Windows systems the width is 1 and this switch has no effect.

• -x=<num>
  The x position of the sub-panel relative to the top-left corner of its parent row or column. If omitted, the sub-panel is placed adjacent to the previously defined sub-panel.

• -y=<num>
  The y position of the sub-panel relative to the top-left corner of its parent row or column. If omitted, the sub-panel is placed below the previously defined sub-panel.

Callbacks

Called when the selected option changes.

<panel>.exec(<window>,<panel>{,<row>})

• Panel/Tab Window

panel.exec {
    args w=window, p=panel
}

• Table Window:

panel.exec {
    args w=window, p=panel, row=numeric
}

Notes

Option menus within other windows cannot have a user-defined position or justification.

On Unix systems, the size of an options menu is determined by the size of the largest option within the menu and cannot be changed. Any subsequent change to menu option text will automatically resize the panel.

On Windows systems, the width of a text menu is determined by the value of the -c switch, a width provided by the -dim switch, or the length of the longest text option. The size can be changed subsequently only be resizing the panel via the panel.width attribute.

Examples

Create a panel window containing an options menu of text items in a specified font.

window w = wpanel {
    dev: options -fo=big_xfont,\ 
        <'Dat','CD','Diskette','QIC','Exabyte'>
}

Create a similar panel window to the previous example but with color change and an initial value.

window w = wpanel {
    dev: options -bc=blue,-tc=white,-d=3,\ 
        <'Dat','CD','Diskette','QIC','Exabyte'>
}

Create a panel window containing an options menu with image options. The options have associated text values. The background color of the images is made the same as that of the menu. We assume that states.ras is a Fire image file containing four cameos.

window w = wpanel {
    state: options -cr='states.ras',-bc=no_change,\ 
        -t=<'NY','FLA','LA','COL'>
}

Create a similar panel window to the previous example but with the images named individually to illustrate multiple image definition.

window w = wpanel {
    state: options -cr=<'newyork.gif','florida.gif',\ 
        'louisiana.gif','colorado.gif'>,\ 
    -bc=no_change,-t=<'NY','FLA','LA','COL'>
}