PUSH

A PUSH button is a graphical, square button with the label inside of the button itself. Alternately, the button can display an image.

A user can move the mouse pointer over the button and press (and hold down) the mouse button. The button will visually depress as if the mouse pointer were a finger pushing down upon the button. When the user releases the mouse button, so too does the mouse release the push button. Alternately, pressing the SPACE BAR will activate the button which currently has the focus (ie, is highlighted).


Uses

Push buttons are usually used to launch operations, such as to begin a file save or load, or initiate an action such as to create another window.


Styles

Shortcut The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut.

A Push button must be created with one of the following 3 styles:

Text Displays a label (text) inside of the button.
Bitmap Displays a bitmap inside of a button that the user can click upon.
Icon Displays an icon inside of a button that the user can click upon.

When you choose Text style, then the button can have a label (ie, caption). If you choose Bitmap or Icon styles, then you instead must choose some Bitmap or Icon resource you have already added to your Window Layout script. This image will be displayed in the button.

A PUSH button may additionally have any, all, or none of the following styles:

Flat Flat appearance.
Default The default push button. Has a thicker border, and is automatically pressed when the user presses the ENTER key.
Owner Draw (OWNER) An owner-drawn button. The Window Layout script's WM_MEASUREITEM subroutine is called when the button is created and the WM_DRAWITEM subroutine is called when a visual aspect of the button has changed. The script must draw the contents of the button using various Gui graphics primitive functions.
Multiline (MULTI) Wraps the label (text) to multiple lines if the text is too long to fit on a single line inside the button.
Notify Causes the Window Layout's DBLCLK, FOCUS, and UNFOCUS subroutines to be called when the button is double-clicked, loses the focus, or gains the focus, respectively. Note that you can always add a function to handle a button's CLICK event regardless of this style.
No Sibling (NOSIBLING) Prevents this control from drawing into any overlapping controls.
Group Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins).
Tabstop The user can move to this control using the TAB key.
Disabled Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement.
Hide Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement.

In addition to the above styles, a PUSH button may have one of the following 3 horizontal alignment styles:

Left Left-justifies the label, icon, or bitmap.
Right Right-justifies the label, icon, or bitmap.
Center The label, icon, or bitmap is horizontally centered.

In addition to the above styles, a PUSH button may have one of the following 3 vertical alignment styles:

Top The label, icon, or bitmap is positioned at the top of the button.
Bottom The label, icon, or bitmap is positioned at the bottom of the button.
Center (VCENTER) The label, icon, or bitmap is vertically centered.


Extra styles

A PUSH button can have any, all, or none of the following extra styles:

Result When clicked, it causes all of the controls in the window to set the values of their associated REXX variables in the script sleeping in GuiGetMsg().
Quiet Do not report any events for this control.
Modal Frame (MODALFRAME) Has a double border.
Static Edge (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input.
Client Edge (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge.
Accept files (FILES) Accepts drag-and-drop files (ie, the DROPFILES event).
Align text right (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties).
Read right-to-left (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right).
Transparent The control is to be transparent. Any controls that are beneath this one are not obscured.

In addition to the above styles, a PUSH button may have one of the following 2 extra styles:

All When clicked, it selects all of the items in a MULT LIST box, or group of CHECK controls (ie, all having the same REXX variable name) that are associated with the same variable name as this PUSH button.
None When clicked, it deselects all of the items in a MULT LIST box, or group of CHECK controls (ie, all having the same REXX variable name) that are associated with the same variable name as this PUSH button.


Events

A PUSH button generates the following events:

Event name When it occurs
CLICK The user has clicked the button. Note: A disabled button does not cause a CLICK event.
DBLCLK The user has double-clicked the button. Note: A disabled button does not cause a DBLCLK event. This event also does not occur if the NOTIFY style is not specified for the button.
FOCUS The user has made the control activated, and therefore may be prepared to operate it. This event does not occur if the NOTIFY style is not specified for the button.
UNFOCUS The user has selected another control or some other window, and therefore the button is deactivated. This event does not occur if the NOTIFY style is not specified for the button.
HILITE The user has clicked on the button, but not yet released it. (ie, User is pressing down on the button).
UNHILITE The user has stopped pressing down on the button.


REXX Variable

A PUSH button must have a REXX variable associated with it. You do not need to initialize the variable before opening the window which contains the push button.

For an ALL or NONE style button, the REXX variable name should be the same as the LIST, or first CHECK control in a GROUP, which the PUSH button affects.


Dynamically add/remove a PUSH button

You can dynamically add a PUSH button to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:

PUSH X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, Label
X and Y is the position of the top left corner of the control, relative to the window's top left corner.

Width and Height are the size of the control, in pixels.

Styles and ExtraStyles are those listed above, with each style separated by a | character.

VariableName is the variable name to be associated with the control.

Accelerator is the keyboard shortcut that causes the button to be "pushed".

Label is the (text) label for the control. You can use the two characters \t to represent a TAB character. You can also include multiple lines by using the characters \n to mark the end of a line. If you want to put a \ character in the text, then you must double it up as \\.

If the button has the ICON or BITMAP style, then Label will instead be either the name of a file containing the icon/bitmap image, or the image number if the image is embedded inside of an EXE you created with the Window Editor. In this case, you do not need to initialize the associated REXX variable before calling GuiAddCtl.

For example, here we add a PUSH button at an X Y position of 10, 10, with a width and height of 40 and 20, with the styles VCENTER and CENTER, extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MyPushButton, and a label of Click me:

error = GuiAddCtl("PUSH 10,10,40,20, VCENTER|CENTER, CLIENTEDGE|QUIET, MyPushButton,, Click me")

You can dynamically remove a PUSH button by calling GuiRemoveCtl. Here we remove the above button:

error = GuiRemoveCtl("MyPushButton")
Note: For an ALL or NONE style button, the REXX variable name you pass to GuiRemoveCtl should have a space and an asterick (ie " *") appended to it. For example, if the REXX variable name you used to create the button was "MyList1", then the REXX variable name you use to remove the button is "MyList1 *".


Change a PUSH button's label.

If the button has the TEXT style, you can dynamically change its label by calling GuiAddCtlText. You pass the REXX variable name for the button, and the new label. Here we change the above button's label to Don't click me:

error = GuiAddCtlText("MyPushButton", "Don't click me")


Change a PUSH button's image.

If the button has the ICON or BITMAP style, you can dynamically change its image by calling GuiAddCtlText. You pass the REXX variable name for the button, and either the filename of the icon/bitmap, or the image number if the image is embedded in an EXE you created with the Window Editor. Here we change the above button's image to the image in the file named C:/MyIcon.ico:

error = GuiAddCtlText("MyPushButton", "C:/MyIcon.ico")
Note: Use forward (not back) slashes to separate the directory names.