## ToolButton

### Description

The ToolButton class is similar to a Button, but allows you to specify one or more images (as bitmaps) which can be displayed on the button face, depending on its state. It can optionally also display a text caption. In addition, it has built-in capability to act as a toggle button (like a Check box), or as one of a group (like a Radio button).

### Specifying the images

You specify the images displayed on the button using the `bitmap` property. This is an integer matrix, containing between 1 and 4 images laid out side-by-side. These correspond to:

1. The image displayed when the button is in its 'normal' (Up) state.
2. The image displayed when the button is disabled.
3. The image displayed during the time that the button is being clicked. If the button is acting as an Action button (i.e. its `group` property is 0), the 'normal' (Up) image reappears when the user releases the mouse button.
4. The image displayed when the button is in its 'selected' (Down) state. This applies only if the button is used as a radio or toggle button.

If you provide fewer than 4 images, the ToolButton will represent the other states automatically by altering the image slightly.

The actual images are specified as an APL integer matrix, where each element contains an RGB color for the corresponding pixel. The color value is encoded as 256ƒBlue Green Red, where each color value is in the range 0 to 255. If you want to supply more than one image, these should be laid out horizontally; you specify the `imagecount` property to indicate how the array should be be divided up. For example, suppose you supply an array 20 pixels high and 60 pixels wide. If you set `imagecount` to 1, the whole array will be treated as a single image of size 20 by 60, and will be used when the button is in its 'normal' (Up) state; images for the remaining states will be simulated automatically. If you set `imagecount` to 2, the array will be treated as representing two images side-by-side, each 20 by 30 pixels, representing the button in its 'normal' and disabled states respectively. If you set `imagecount` to 3, it will be treated as representing three images, each of 20 by 20 pixels, corresponding to the first three states listed above.

Depending on the `style` property, the bitmap may be transparent. If so, the pixel value in the lower left corner of each image will be used as the transparent color value; any other pixel with the same value will not be displayed, so the background shows through.

### Determining the behavior of the button

The `group` property is an integer scalar which determines the behavior of the button. If it is 0 (the default), the button behaves like an ordinary 'action' button; when the user clicks on it, it temporarily displays the third image, and when the user releases the mouse it reverts to the normal ('up') state. You would typically use this by hooking it to the `onClick` callback to take some action when the button is pressed.

If the `group` property is non-zero, the button can remain selected after the user has clicked it. In this state, it displays the fourth image, and its `value` property becomes 1 rather than 0. However, it also interacts with other ToolButtons with the same `group` property; only one button in the group can be selected at a time, so clicking on one de-selects all the others. In addition, you can specify whether all the buttons in the group can be deselected, using the `style` property (see below). If the `style` property contains 8, it is legal for none of the buttons in the group to be selected; if it does not contain 8, exactly one of the buttons in the group will be selected at all times.

Thus, you can use the button in three main ways:

- As an 'Action' button: Leave the `group` property as 0, and use the `onClick` event to detect when it is pressed. It never stays selected.
- As a 'Toggle' button: Set the `group` property to a unique non-zero value, so the button does not interact with any other buttons. When the user clicks on the button, it will change to the 'selected' (Down) state (`value` = 1). When the user clicks on it again, it will revert to the 'normal' (Up) state (`value` = 0). For this to work, you must ensure that the `style` property contains 8, otherwise the button can never be deselected.
- As a 'Radio' button: Set the `group` property to a non-zero value which is common to several ToolButtons with the same parent. When the user clicks on the button, it will change to the 'selected' (Down) state (`value` = 1), and any button in the group which is currently selected will be de-selected. If the `style` property contains 8, the user can click on the currently-selected button to de-select it, so that no buttons in the group are selected. Otherwise, exactly one of the buttons in the group will always be selected.

In the second and third of these cases, you can optionally use the `onClick` event to detect transitions, or you can simply the read the `value` property when you need it.

### Other key properties

`style`: An integer scalar comprising one of:

        0  Caption (if any) appears below image (default)
        1  Caption (if any) appears above image
        2  Caption (if any) appears to left of image
        3  Caption (if any) appears to right of image

to which can be added:

        4  If this bit is set, the button appears 'flat',
           without a border.  Recommended for toolbars.
        8  Specifies that all buttons in a group can be deselected.
       16  Specifies that the button is transparent

`caption`: A character vector, which specifies a caption to be displayed on the button. It defaults to an empty vector, meaning no caption is displayed. The location of the caption relative to the image is determined by the `style` property.

`value`: A boolean scalar indicating whether the button is selected. You can set this to select a button under program control.

`tooltip`: A character vector which gets displayed as help text when the user moves the mouse pointer over the control and pauses. You normally use this to provide information about what the button does. (It will be suppressed if you set the `tooltipenabled` property of the system object to 0).

`enabled`: A boolean scalar. If you set this to 0, the button will be disabled, will not responds to clicks, and cannot be selected. It will display the second of the images you supply, or a greyed-out image if you supply one one.

### Example

         ’DEMO_ToolButton;NORMAL;DISABLED;CLICKED;SELECTED;X;STATE;DEMO
    [1]   © Sample function demonstrating use of theTool Button object
    [2]   DEMO„'Œ' ŒNEW 'Dialog' ª DEMO.scale„5 ª DEMO.size„60 235
    [3]   DEMO.title„'ToolButton Example'
    [4]   STATE„'Unselected' 'Selected'
    [5]   ©
    [6]   © Create a simple 20 by 20 bitmap of a triange shape, which we use to make
    [7]   © four images for up/down/left/right, in four colors
    [8]   X„(²X),X„20 10†0,[1]2/[1]œ9†¨(¼9)½¨1
    [9]   ©
    [10]  © Choose some colors for our simple images.
    [11]  NORMAL„256ƒ0 255 0        © Green
    [12]  DISABLED„256ƒ160 160 255  © Pale Red
    [13]  CLICKED„256ƒ170 240 170   © Pale green
    [14]  SELECTED„256ƒ255 0 0      © Blue
    [15]  ©
    [16]  © Make four tool buttons, with triangle in different color for each state
    [17]  © Style 0+4+8+16 for caption below image, 'flat', allow all up, transparent
    [18]  © Create the buttons in a radio group, so only one can be down at any time.
    [19]  DEMO.UP.New 'ToolButton'
    [20]  DEMO.UP.tooltip„'Up direction (disabled)' ª DEMO.UP.caption„'Up'
    [21]  DEMO.UP.where„0 0 50 40 ª DEMO.UP.style„28
    [22]  DEMO.UP.imagecount„4 ª DEMO.UP.group„99
    [23]  DEMO.UP.bitmap„((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))
    [24]  DEMO.UP.onClick„"Œ„'Up Hit!'"
    [25]  © Show effect of disabling the Up button; we'll get the second (red) image
    [26]  DEMO.UP.enabled„0
    [27]  ©
    [28]  ©
    [29]  X„´X
    [30]  DEMO.DN.New 'ToolButton'
    [31]  DEMO.DN.tooltip„'Down direction' ª DEMO.DN.caption„'Down'
    [32]  DEMO.DN.where„0 40 50 40 ª DEMO.DN.style„28
    [33]  DEMO.DN.imagecount„4 ª DEMO.DN.group„99
    [34]  DEMO.DN.bitmap„((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))
    [35]  DEMO.DN.onClick„"Œ„'Down Hit! ',STATE[ŒIO+ŒWSELF ŒWI 'value']"
    [36]  ©
    [37]  X„³X
    [38]  DEMO.RT.New 'ToolButton'
    [39]  DEMO.RT.tooltip„'Right direction' ª DEMO.RT.caption„'Right'
    [40]  DEMO.RT.where„0 80 50 40 ª DEMO.RT.style„28
    [41]  DEMO.RT.imagecount„4 ª DEMO.RT.group„99
    [42]  DEMO.RT.bitmap„((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))
    [43]  DEMO.RT.onClick„"Œ„'Right Hit!',STATE[ŒIO+ŒWSELF ŒWI 'value']"
    [44]  ©
    [45]  X„²X
    [46]  DEMO.LF.New 'ToolButton'
    [47]  DEMO.LF.tooltip„'Left direction' ª DEMO.LF.caption„'Left'
    [48]  DEMO.LF.where„0 120 50 40 ª DEMO.LF.style„28
    [49]  DEMO.LF.imagecount„4 ª DEMO.LF.group„99
    [50]  DEMO.LF.bitmap„((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))
    [51]  DEMO.LF.onClick„"Œ„'Left Hit!',STATE[ŒIO+ŒWSELF ŒWI 'value']"
    [52]  ©
    [53]  © Wait for the user to close the window
    [54]  0 0½ŒWE DEMO
         ’

### Properties

align anchors aquaadjust autodraw bitmap caption children class color data dragsource droptarget enabled events extent font group imagecount maxsize methods minsize name opened pointer properties scale self size sourceformats style targetformats tie tooltip units value visible where

### Methods

Click Clienttoscreen Close Create Delete Hide New Open Paint Resize Screentoclient Send Set Show Trigger

### Callbacks

onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onHide onMouseDown onMouseMove onMouseUp onOpen onSend onShow

Topic: APLX Help : System Classes : List of Classes : ToolButton

[ Previous | Next | Contents | Index ]