Panel: check_button

Syntax

{<name>:} check_button {<string>}

Description

Toggle-button sub-panel, text or image.

Membership

• Panel window

• Tab window

• Table window

• Menupane

Parameters

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

• <string>
  The text shown alongside the button. This can be omitted when the button is shown in image form.

Switches

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

For text check buttons, the background color of the parent window is used and cannot be changed.

• -cam=<num>
  Display the num th cameo from a Fire image file (indicated by the -cr switch).

• -cr=<file>
  Display a Fire image. This can be the name of a image file with, optionally, a cameo number.

• -dim=<screen_xy>
  Define the dimensions of the button in pixels. This is usually redundant because buttons 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 image. This is applicable to monochrome images only.

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

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

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

• -j=<just>
  The justification of the button 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.

• -q
  When this switch is present, the indicator button is visible only when its state is logically on. This option has no effect on Windows systems.

• -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.

• -set=<color>
  The color of the indicator button when set (i.e. logically on). If omitted, a suitable default is used. This option has no effect on Windows systems.

• -t=<strings>
  Two user-defined strings which can be used to reflect the current state of the check button:
      panel.text[1] corresponds to 0 (not set),
      panel.text[2] corresponds to 1 (set).
  The default values are "off" and "on".

• -tc=<color>
  The color for text in the button (or the image frame color). If omitted the parent window "other color" is used.

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

• -tt=<string>
  A tool tip to appear when the user rests the mouse cursor over the panel. This feature is available only in panel windows on Windows systems.

• -v=<num>
  Whether to initially show the check button as set or not. <num> should have a value of 1 or 0. The default is 0 (not set).

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

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

Callbacks

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

Called on a change of toggle state using mouse button 1:

• Panel/Tab Window

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

• Table Window

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

Notes

Switches -j, -pj, -x and -y apply only to check buttons within a panel window. Check buttons within other windows and menupanes cannot have a user-defined position or justification.

Examples

Create a panel window containing two text check buttons in an italic font.

window w = wpanel {
    sof: check_button 'Send Output to File',-fo=xitalic
    sot: check_button 'Send Output to Printer',-fo=xitalic
}

Create a panel window containing three text buttons one of which is initially set, using different colored text in "quiet" mode. Commit a neatness by making them all left-justified.

window w = wpanel {
    b: check_button 'Add Border',-tc=white,-q,-j='L'
    s: check_button 'Auto-Size',-tc=red,-v=1,-q,-j='L'
    g: check_button 'Add Grid',-tc=yellow,-q,-j='L'
}

Create a panel window containing two framed single image check buttons with associated "return text".

window w = wpanel {
    m: check_button -cr='modem.xpm',-th=2,\ 
        -t=<'Inactive','Active'>
    p: check_button -cr='printer.xpm',-th=2,\ 
        -t=<'Inactive','Active'>
}