The Edit Toggle Button Dialog

Note: This dialog presents the attributes of the generic class of form field objects called "toggle buttons". "Toggle buttons" include check boxes, three-state check boxes, radio buttons, image toggle buttons, image optional buttons and image three-state buttons. The dialog caption reflects the specific type of toggle button being edited. The dialog itself supports switching among the different types of toggle buttons. In the following discussion, the generic term "toggle button" is used although the user should take note of the dialog caption to determine the specific toggle button type. Also note that radio buttons which are owned by option boxes do not fall into this generic class of "toggle buttons". They have distinct attributes and have their own edit dialog (refer to the Edit Option Button dialog).

The Edit Toggle Button dialog can be displayed by either double clicking anywhere within a toggle button form field object or selecting the toggle button and clicking on the "attribute edit" icon in the tool bar. This dialog presents the current attributes of the toggle button. The dialog consists of three sections: identification, appearance, and properties.

Identification Section

This section displays naming and other identifying information for the toggle button form field object.

Field Name

This field contains the name of the toggle button. The Screen Painter automatically generates a unique name for it. This name can be maintained or changed, as long as the new name conforms to the Zim Object Naming Rules.

Form Name

This field contains the name of the form in which the toggle button was created. The field can be viewed by selecting it and scrolling left and right, but its value cannot be changed.

Directory

This field contains the name of the Zim directory that owns the form in which the toggle button was created. The field can be viewed by selecting it and scrolling left and right, but its value cannot be changed.

Field Number

This field contains an automatically generated identifying number for the toggle button. The value in this field can be used to identify the toggle button if it triggers a callback event. Refer to Form Fields and Callback Events for more detailed information about associating form fields with callback events. The value in this field can be changed and need not be unique.

Field Tag

This field contains an identifying text string for the toggle button. The value in this field can be used to identify the toggle button if it triggers a callback event. Refer to Form Fields and Callback Events for more detailed information about associating form fields with callback events. The value in this field can be changed and need not be unique. If left blank (the default), the value contained in Field Name is used for Field Tag.

Help Message

This field contains the text to display in an field of type "message" (if one exists in the form) when the toggle button receives the input focus. The message that appears at the bottom left of this dialog is itself a "message" field, and the help message associated with each field in the dialog is automatically displayed there when the field receives the input focus. If you intend to have a "message" field in your form, enter an appropriate help message in this Help Message field.

Appearance Section

This section presents the display or appearance attributes of the toggle button form field object.

Visible

This check box determines if the toggle button is visible by default. The visibility attribute of all form fields other than labels can be dynamically modified under Zim program control.

Pointer Style

This list box is used to select the pointer (or cursor) style to use when the pointer is over or in the toggle button, and the toggle button is available. By default, the value is "default", which for a toggle button field, is the "Arrow" pointer style.

Style / Button Type

This list box provides for selecting the specific type of toggle button required. The choices are "Radio Button", "Check Box", "Check 3-State", "Image Toggle", "Image Optional" and "Image 3-State". The types with the "3-State" designation support the three value states Off, On and Null (i.e. neither Off nor On). The types with the "Toggle" designation (that includes the "Check Box" and "Check 3-State") exhibit the property that within the context of their parent form field object (e.g. a frame object), multiple toggle buttons can be in the same state (i.e. Off, On or Null) simultaneously. Hence an "Image Toggle" button behaves like a "Check Box" and an "Image 3-State" behaves like a "Check 3-State". The types with the "Optional" designation (which includes the "Radio Button"), exhibit the property that within the context of their parent form field object (e.g. a frame object), no two toggle buttons can be in the On state simultaneously. Hence an "Image Optional" button behaves like a "Radio Button". When the required toggle button type is selected, the dialog caption changes appropriately.
If the toggle button type selected is not an "Image" type toggle button, then the fields Auto Size, Image Type and the push button Images are not available, and the field Label is available. Conversely, if the toggle button type selected is an "Image" type toggle button, then the fields Auto Size, Image Type and the push button Images are available, and the field Label is not available.

Style / Image Type

This list box is available only for "Image" type toggle buttons. It can be used to select from the three supported image file types, "Bit Map", "(Windows) Meta File", and "Icon".

Style / Auto Size

This list box is available only for "Image" type toggle buttons. It can be used to select from four different automatic image sizing options. These are "None-clipped", "Image to object", "Image proportional" and "Object to image". Refer to Image Auto Size Options for more detailed information about the different automatic image sizing options.

Style / Images

This push button is available only for "Image" type toggle buttons. It presents the Select Button Image Files dialog from which the image files to represent the Off, On and Null (if available) states can be selected.

Style / Label

This entry field is available only for the text-based toggle button types "Radio Button", "Check Box" and "Check 3-State". The text entered in this field is the label displayed alongside the toggle button. Note that the first ampersand character (&) within the text is interpreted as an instruction to underline the following character.

Properties Section

This section presents the behavioral attributes of the toggle button field.

Availability

This field determines the "availability" attribute of the toggle button field. The values are "Available", "Unavailable", "Guarded" and "Protected". Refer to Form Field Availability Attributes for a more detailed description of the characteristics of these different availability values.

Tab Stop

This check box field determines if the toggle button is included in the tab order. If cleared, the end-user is not able to access this field by using the tab keys. The toggle button is still directly accessible by accelerator keys and the mouse.

Tab Index

This field contains a number that represents the relative position of the field in the tab sequence order. A value of zero (0) means use the tab sequence order as defined by the relative position of the field in the structure chart.

Values / True/False

This radio button sets the toggle button field's data type to "alphanumeric", its Off state value to "0", its On state value to "1" and its Null state value to "2" (if applicable). These are the most common setting for toggle buttons as the Off and On values correspond to the Zim system variables $false and $true, which always have the values "0" and "1" respectively. By default, all toggle buttons are created with the True/False settings.

Values / Custom

This radio button provides for customization of the toggle button's data type, Off state value, On state value and Null state value (if applicable). Selecting this radio button does not actually change the toggle button's current value settings. Rather it makes the Customize push button available. Clicking on this push button  presents the Customize Toggle Button Values dialog.

Values / Default / Off

This radio button sets the default state for the radio button to be Off.

Values / Default / On

This radio button sets the default state for the radio button to be On.

Values / Default / Null

If available, this radio button sets the default state for the radio button to be Null.

Dialog Push Buttons

OK

This push button performs any required data validation, commits any changes that were made to the toggle button field's attributes, and returns to the Screen Painter's layout mode.

Cancel

This push button discards any changes that were made in this dialog and returns to the Screen Painter's layout mode.

Help

This push button invokes the Zim Help facility, initially displaying the section entitled Edit Toggle Button dialog (this section).

Options

This push button displays the Toggle Button Options dialog that enables additional attributes of the toggle button to be viewed and/or modified.