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:
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
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:
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.
∇DEMO_ToolButton;NORMAL;DISABLED;CLICKED;SELECTED;X;STATE;DEMO  ⍝ Sample function demonstrating use of theTool Button object  DEMO←'⎕' ⎕NEW 'Dialog' ⋄ DEMO.scale←5 ⋄ DEMO.size←60 235  DEMO.title←'ToolButton Example'  STATE←'Unselected' 'Selected'  ⍝  ⍝ Create a simple 20 by 20 bitmap of a triange shape, which we use to make  ⍝ four images for up/down/left/right, in four colors  X←(⌽X),X←20 10↑0,2/⊃9↑¨(⍳9)⍴¨1  ⍝  ⍝ Choose some colors for our simple images.  NORMAL←256⊥0 255 0 ⍝ Green  DISABLED←256⊥160 160 255 ⍝ Pale Red  CLICKED←256⊥170 240 170 ⍝ Pale green  SELECTED←256⊥255 0 0 ⍝ Blue  ⍝  ⍝ Make four tool buttons, with triangle in different color for each state  ⍝ Style 0+4+8+16 for caption below image, 'flat', allow all up, transparent  ⍝ Create the buttons in a radio group, so only one can be down at any time.  DEMO.UP.New 'ToolButton'  DEMO.UP.tooltip←'Up direction (disabled)' ⋄ DEMO.UP.caption←'Up'  DEMO.UP.where←0 0 50 40 ⋄ DEMO.UP.style←28  DEMO.UP.imagecount←4 ⋄ DEMO.UP.group←99  DEMO.UP.bitmap←((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))  DEMO.UP.onClick←"⎕←'Up Hit!'"  ⍝ Show effect of disabling the Up button; we'll get the second (red) image  DEMO.UP.enabled←0  ⍝  ⍝  X←⊖X  DEMO.DN.New 'ToolButton'  DEMO.DN.tooltip←'Down direction' ⋄ DEMO.DN.caption←'Down'  DEMO.DN.where←0 40 50 40 ⋄ DEMO.DN.style←28  DEMO.DN.imagecount←4 ⋄ DEMO.DN.group←99  DEMO.DN.bitmap←((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))  DEMO.DN.onClick←"⎕←'Down Hit! ',STATE[⎕IO+⎕WSELF ⎕WI 'value']"  ⍝  X←⍉X  DEMO.RT.New 'ToolButton'  DEMO.RT.tooltip←'Right direction' ⋄ DEMO.RT.caption←'Right'  DEMO.RT.where←0 80 50 40 ⋄ DEMO.RT.style←28  DEMO.RT.imagecount←4 ⋄ DEMO.RT.group←99  DEMO.RT.bitmap←((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))  DEMO.RT.onClick←"⎕←'Right Hit!',STATE[⎕IO+⎕WSELF ⎕WI 'value']"  ⍝  X←⌽X  DEMO.LF.New 'ToolButton'  DEMO.LF.tooltip←'Left direction' ⋄ DEMO.LF.caption←'Left'  DEMO.LF.where←0 120 50 40 ⋄ DEMO.LF.style←28  DEMO.LF.imagecount←4 ⋄ DEMO.LF.group←99  DEMO.LF.bitmap←((X×NORMAL),(X×DISABLED),(X×CLICKED),(X×SELECTED))  DEMO.LF.onClick←"⎕←'Left Hit!',STATE[⎕IO+⎕WSELF ⎕WI 'value']"  ⍝  ⍝ Wait for the user to close the window  0 0⍴⎕WE DEMO ∇
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
Copyright © 1996-2010 MicroAPL Ltd