BUTTON

Instructions Properties Methods Events Notes Examples

The BUTTON instruction defines an object variable for a push button. Users click BUTTON objects to begin, interrupt, or end a process. When chosen, a BUTTON appears pushed in and so is sometimes called a push button. The BUTTON face may contain text or an image. To define a BUTTON, use one of the following statement formats:

(1)	[label]	BUTTON	[%]
(2)	[label]	BUTTON	(arraysize)
(3)	[label]	BUTTON	^
(4)	[label]	BUTTON	^,{target}
(5)	[label]	BUTTON	^(arraysize)
(6)	[label]	BUTTON	^(arraysize),({target}),...,({target})

Where:

label

Optional. A Data Label.

Optional. Denotes the item as being GLOBAL.

arraysize

Required. An integer decimal constant, CONST variable, or EQUATEd value indicating the number of array items.

Optional. Denotes the item as being a POINTER.

target

Required. The name of a previously defined data item of the same type.

Flags Affected: NONE

Instructions:

Object instructions are PL/B verbs that support the graphical objects.

ACTIVATE	Makes an object visible and allows the user to interact with it.
CHECKPROP	Tests whether a property is valid.
CREATE	Creates all necessary data structures for an object.
DEACTIVATE	Hides the object from the user.
DESTROY	Release the data structures obtained for an object.
DISABLEITEM	Prevents user interaction.
DRAGITEM	Turns on or off the capability of moving object or moving an item in an object.
ENABLEITEM	Allows user interaction.
EVENTREGISTER	Associates an event with a program execution label.
EVENTSEND	Sends an event to a specified object.
GETITEM	Obtain the value of an object item.
GETPROP	Obtain the value of a specific property.
LISTDEL	Removes an object from a COLLECTION.
LISTINS	Inserts an object into a COLLECTION.
SETFOCUS	Changes the current focus.
SETITEM	Set the value of an object item.
SETPROP	Set the value of a specific property.

Properties:

Properties are attributes of an object that define the object's characteristics or its behavior.

ANCHOR	Ties an object to one or more edges of its parent object.
APPEARANCE	Defines the appearance.
BUTTONSTATE	Defines the Bootstrap 5 appearance.
BUTTONTYPE	Defines the type of button as standard, split, command link, or file input.
CANCEL	Escape key triggers a Click event.
CAUSEVALID	Focus will trigger the Validate event
CMDNOTE	Defines text associated with a command link.
CONTEXT	Defines the BootStrap 5 context style.
DEFAULT	Enter key triggers a Click event.
DOCK	Defines which borders are docked to its parent and determines how it is resized.
DROPID	Defines the object's ability to receive drop actions.
ENABLED	Defines if user interaction is allowed.
FLOATMENU	Associates a FLOATMENU object.
FONT	Identifies the text font.
HEIGHT	Defines the height of an object.
HELPID	Associates a topic number as defined in a user generated Windows help file.
HELPTOPIC	Associates a help keyword string as defined in a user generated Windows help file
HWND	Returns Windows handle for an object.
ICON	Allows use of an image in place of the text.
LEFT	Defines the left position of an object.
OBJECTID	User defined identification number.
PICTURE	Allows use of a picture in place of the text.
RUNNAME	Defines the run-time name of the object.
SHIELD	Specifies if an elevation icon should be shown.
TABID	Defines the location in the tabbing sequence.
THEME	Windows application visual style theme.
TITLE	Defines text associated with an object.
TOOLTIP	Specifies a string to be displayed in a tool tip.
TOOLTIPHWND	Returns the tool tip window handle.
TOP	Define the top position of an object.
USERDATA	Allows application data to be assigned.
VISIBLE	Specifies whether an object is visible or hidden.
WEBCLASS	Specifies a HTML class name.
WEBHEIGHT	Specifies the CSS height property.
WEBLEFT	Specifies the CSS left property.
WEBOBJECT	Specifies that an object should be created as a web object.
WEBPOSITION	Specifies the CSS position property.
WEBSTYLE	Specifies a list of CSS properties.
WEBTOP	Specifies the CSS top property.
WEBWIDTH	Specifies the CSS width property.
WIDTH	Defined the height of an object.
ZORDER	Defines the z-order of an object.

Methods:

Methods are encapsulated routines that act upon an object.

AddWebClass	Adds one or more HTML classes.
DisableJqEvent	Disable one or more jQuery events.
EnableJqEvent	Enable one or more jQuery events.
GetWebId	Obtains the HTML id attrbute.
GetWebStyle	Retrieves a specific CSS style.
RemoveWebClass	Removes one or more HTML classes.
SetWebStyle	Sets a specific CSS style.

AamCancelMode	Allow a click action to cancel an AFILE read that is active.
GetFileCount	Retrieves the number of files that have been selected
GetFileItem	Retrieves the file names that have been selected.
IOCancelMode	Allow a click action to cancel a FILE, AFILE, or IFILE READ that is active.
SetFileOptions	Sets the specific options used by the client browser File Upload selection dialog.

Events:

Events are actions recognized by an object for which you can write code to respond. Events can occur as a result of a user action or program code, or they can be triggered by the system.

Change	Occurs when the contents or value of an object is altered.
Click	Occurs when the mouse button is pressed and released over an object.
DragDrop	Occurs when a drag-and-drop operation is in progress and the mouse button is released.
DragOver	Occurs when a drag-and-drop operation is in progress and the mouse cursor is moved over an object.
GotFocus	Occurs when an object gains keyboard focus.
KeyPress	Occurs when an object has the keyboard focus and the user presses and releases a key.
LostFocus	Occurs when an object loses keyboard focus.
MouseDown	Occurs when the user presses a mouse button over an object.
MouseMove	Occurs when the user moves the mouse over an object.
MouseUp	Occurs when the user releases a mouse button over an object.
Move	Occurs when an object is relocated.
Validate	Occurs when the focus leaves an object as a result of a user action and the new focus has its CAUSEVALID property set.

Note the following:

A BUTTON contains only one item accessible through SETITEM. It is the push button.
The BUTTON is always referenced as item number zero for SETITEM and GETITEM instructions.
The text displayed on a BUTTON is specified when the button is CREATEd. Subsequently, it may be modified or retrieved using the SETITEM and GETITEM instructions. If a Null String is specified, no text is displayed on the BUTTON.
The text associated with a BUTTON may include an Alt Keyboard Sequence.
An icon or picture may be displayed on a BUTTON in place of the text. To add an icon to a BUTTON, use the ICON property. Pictures are added using the PICTURE property. Any text associated with the BUTTON is still available and any Alt Keyboard Sequence defined is still active.
To allow the user to choose a BUTTON by pressing the enter key, set the DEFAULT property to $ON. Only one button per window may be designated as the DEFAULT button.
To allow the user to choose a BUTTON by pressing the escape key, set the CANCEL property to $ON. Only one button per window may be designated as the CANCEL button.
Multi-dimension arrays of BUTTONS are supported up to a maximum of fourteen dimensions.
The ^ denotes a Pointer Variable to a BUTTON object.
Although a BUTTON may be defined as Global, it is DESTROYed during a CHAIN instruction.

Example:

*
.Define the BUTTONs and result variable
.
BUTTONS	BUTTON	(3)
RESULT	FORM	2
*
.Create the BUTTONs
.
	CREATE	BUTTONS(1)=4:5:21:30,"Button 1"
	CREATE	BUTTONS(2)=7:8:21:30,"Button 2":
		ICON=10020
	CREATE	BUTTONS(3)=16:17:35:42:
		"Exit",PICTURE="stop-up.bmp"
*
.Activate the BUTTONs
.
	ACTIVATE	BUTTONS(1),DISPM1,RESULT
	ACTIVATE	BUTTONS(2),DISPM2,RESULT
	ACTIVATE	BUTTONS(3),EXIT,RESULT
*
.Wait for an Event to Occur
.
	LOOP
	EVENTWAIT
	REPEAT
*
.Button 1 Selected
.
DISPM1
	DISPLAY	*P35:4,"Button 1 clicked!":
		W2,H=35,*EL;
	RETURN
*
.Button 2 Selected
.
DISPM2
	DISPLAY	*P35:7,"Button 2 clicked!":
		W2,H=35,*EL;
	RETURN
*
.Exit Button Selected
.
EXIT
	STOP

This example creates three BUTTONs on the screen. Button 2 is displayed containing the icon specified by resource number 10020. Button 3 is displayed containing the image specified by "stop-up.bmp". When 'Button 1' or 'Button

2' is clicked, a message is displayed on the screen. When the Button 3 is clicked, the program is terminated.