Skip to main content
Version: 20 R5

Text and Picture

Background pathname

Sets the path of the picture that will be drawn in the background of the object. If the object uses an icon with different states, the background picture will automatically support the same number of states.

The pathname to enter is similar as for the Pathname property for static pictures.

JSON Grammar

NameData TypePossible Values
customBackgroundPicturestringRelative path in POSIX syntax. Must be used in conjunction with the style property with the "custom" option.

Objects Supported

Custom Button - Custom Check Box - Custom Radio Button


Button Style

General appearance of the button. The button style also plays a part in the availability of certain options.

JSON Grammar

NameData TypePossible Values
styletext"regular", "flat", "toolbar", "bevel", "roundedBevel", "gradientBevel", "texturedBevel", "office", "help", "circular", "disclosure", "roundedDisclosure", "custom"

Objects Supported

Button - Radio Button - Check Box - Radio Button


Horizontal Margin

This property allows setting the size (in pixels) of the horizontal margins of the button. This margin delimits the area that the button icon and title must not surpass.

This parameter is useful, for example, when the background picture contains borders:

With / WithoutExample
Without margin
With 13-pixel margin

This property works in conjunction with the Vertical Margin property.

JSON Grammar

NameData TypePossible Values
customBorderXnumberFor use with "custom" style. Minimum: 0

Objects Supported

Custom Button - Custom Check Box - Custom Radio Button


Icon Location

Designates the placement of an icon in relation to the form object.

JSON Grammar

NameData TypePossible Values
iconPlacementstring"none", "left", "right"

Objects Supported

List Box Header


Icon Offset

Sets a custom offset value in pixels, which will be used when the button is clicked

The title of the button will be shifted to the right and toward the bottom for the number of pixels entered. This allows applying a customized 3D effect when the button is clicked.

JSON Grammar

NameData TypePossible Values
customOffsetnumberminimum: 0

Objects Supported

Custom Button - Custom Check Box - Custom Radio Button


Number of States

This property sets the exact number of states present in the picture used as the icon for a button with icon, a check box or a custom radio button.

The picture can contain from 2 to 6 states.

  • 2 states: false, true
  • 3 states: false, true, rollover,
  • 4 states: false, true, rollover, disabled,
  • 5 states (check box and radio button only): false, true, false rollover, true rollover, disabled
  • 6 states (check box and radio button only): false, true, false rollover, true rollover, false disabled, true disable.
note
  • "false" means button not clicked/not selected or check box unchecked (variable value=0)
  • "true" means button clicked/selected or check box checked (variable value=1)

Each state is represented by a different picture. In the source picture, the states must be stacked vertically:

JSON Grammar

NameData TypePossible Values
iconFramesnumberNumber of states in the icon picture. Minimum: 1

Objects Supported

Button (all styles except Help) - Check Box - Radio Button


Picture pathname

Sets the path of the picture that will be used as icon for the object.

The pathname to enter is similar as for the Pathname property for static pictures.

When used as icon for active objects, the picture must be designed to support a variable number of states.

JSON Grammar

NameData TypePossible Values
iconpictureRelative or filesystem path in POSIX syntax.

Objects Supported

Button (all styles except Help) - Check Box - List Box Header - Radio Button


Title/Picture Position

This property allows modifying the relative location of the button title in relation to the associated icon. This property has no effect when the button contains only a title (no associated picture) or a picture (no title). By default, when a button contains a title and a picture, the text is placed below the picture.

Here are the results using the various options for this property:

OptionDescriptionExample
LeftThe text is placed to the left of the icon. The contents of the button are aligned to the right.
TopThe text is placed above the icon. The contents of the button are centered.
RightThe text is placed to the right of the icon. The contents of the button are aligned to the left.
BottomThe text is placed below the icon. The contents of the button are centered.
CenteredThe text of the icon is centered vertically and horizontally in the button. This parameter is useful, for example, for text included in an icon.

JSON Grammar

NameData TypePossible Values
textPlacementstring"left", "top", "right", "bottom", "center"

Objects Supported

Button (all styles except Help) - Check Box - Radio Button


Image hugs title

This property allows you to define whether the title and the picture of the button should be visually adjoined or separated, according to the Title/Picture position and Horizontal Alignment properties.

This property has no effect when the button contains only a title (no associated picture) or a picture (no title).

By default, when a button contains a title and a picture, the elements are joined. The following graphic shows the effect of the imageHugsTitle property (true when property is enabled) with different button alignments:

JSON Grammar

NameData TypePossible Values
imageHugsTitlebooleantrue (default), false

Objects Supported

Button (all styles except Help) - Check Box (all styles except Regular, Flat, Disclosure and Collapse/Expand) - Radio Button (all styles except Regular, Flat, Disclosure and Collapse/Expand).


Vertical Margin

This property allows setting the size (in pixels) of the vertical margins of the button. This margin delimits the area that the button icon and title must not surpass.

This parameter is useful, for example, when the background picture contains borders.

This property works in conjunction with the Horizontal Margin property.

JSON Grammar

NameData TypePossible Values
customBorderYnumberFor use with "custom" style. Minimum: 0

Objects Supported

Custom Button - Custom Check Box - Custom Radio Button


With pop-up menu

This property allows displaying a symbol that appears as a triangle in the button to indicate the presence of an attached pop-up menu:

The appearance and location of this symbol depends on the button style and the current platform.

Linked and Separated

To attach a pop-up menu symbol to a button, there are two display options available:

LinkedSeparated

The actual availability of a "separated" mode depends on the style of the button and the platform.

Each option specifies the relation between the button and the attached pop-up menu:

  • When the pop-up menu is separated, clicking on the left part of the button directly executes the current action of the button; this action can be modified using the pop-up menu accessible in the right part of the button.
  • When the pop-up menu is linked, a simple click on the button only displays the pop-up menu. Only the selection of the action in the pop-up menu causes its execution.
info

Refer to the On Alternative Click event description for more information on the handling of events in this case.

Managing the pop-up menu

It is important to note that the "With Pop-up Menu" property only manages the graphic aspect of the button. The display of the pop-up menu and its values must be handled entirely by the developer, more particularly using form events and the Dynamic pop up menu and Pop up menu commands.

JSON Grammar

NameData TypePossible Values
popupPlacementstring
  • "none"
  • "linked"
  • "separated"
  • Objects Supported

    Toolbar Button - Bevel Button - Rounded Bevel Button - OS X Gradient Button - OS X Textured Button - Office XP Button - Circle Button - Custom