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