BUTTON Gadget
- Last UpdatedNov 07, 2024
- 4 minute read
Members
|
Name |
Type |
Purpose |
|---|---|---|
|
Background |
REAL Set/Get |
Set or Get Background Color Number. |
|
Background |
STRING Set Only |
Set Background Color Name. |
|
Val |
BOOLEAN |
TRUE when the button is pressed. FALSE when it is not. |
Methods
|
Name |
Result |
Purpose |
|---|---|---|
|
AddPixmap(STRING file1, STRING file2, STRING file3 ) AddPixmap(STRING file1, STRING file2) AddPixmap(STRING file ) |
NO RESULT |
Adds pixmaps to be used for the unselected, selected and inactive states. The last two are optional. |
|
FullName() |
STRING |
Get the full gadget name, for example, !!Form.gadget. |
|
Name() |
STRING |
Get the gadget's name, for example, 'gadget'. |
|
Owner() |
FORM |
Get owning form. |
|
SetPopup(MENU menu) |
NO RESULT |
Links the given menu with the gadget as a popup. |
|
RemovePopup(MENU menu) |
NO RESULT |
Removes the given popup menu from the gadget. |
|
GetPickedPopup() |
MENU |
Returns the name of the menu picked from a popup. |
|
Shown() |
BOOLEAN |
Get shown status. |
|
SetFocus() |
NO RESULT |
Move keyboard focus to this gadget. |
|
Refresh() |
NO RESULT |
Refresh display of gadget. |
|
Background() |
STRING |
Get Background Color Name. Some gadgets do not support this property in all circumstances, for example, gadgets
which are showing a pixmap. |
|
SetToolTip(STRING) |
NO RESULT |
Sets the text of the Tooltip. |
|
Type() |
STRING |
Get the gadget-type as a STRING. |
Command
The BUTTON command defines a button, and specifies its position, tag, or pixmap, callback text, and control attribute.
You can define the button to be either PML-controlled, or core-code-controlled, using the gadget qualifier attribute control type, with values "PML" or "CORE".
The files defining any pixmaps should be specified in the form's default constructor method using the gadget's AddPixmap() method. Refer to Icons from Resource Files for further information..
A button type 'Linklabel' provides a purely textual button presentation, often used to indicate a link to some application item, for example, a hyperlink to a file, a link to an associated form. An example of the Linklabel gadget is shown on the example form in Fold up Gadget Link Example Form with Fold-up panels, NumericInput and Linklabel gadgets.
The tag text is shown in a different color to all other gadget's tag text. The link label gadget highlights by underlining when the mouse cursor passes over it. Pressing it causes a SELECT event to be raised and runs any associated call back.
Button Gadget
The Button has the subtypes Normal, Toggle, and Linklabel.
Linklabels are Buttons and so they do cause validation of any modified text fields of the form whenever they are pressed.
Linklabels:
-
cannot have pixmaps assigned to them.
-
do not support change of background color.
-
do not support 'pressed' and 'not pressed' value.
-
are not enclosed in a box.
-
can have pop-up menus (though this is not recommended).
-
do not have Control Types, for example, 'OK', 'CANCEL'.
The subtype of a Button gadget can be queried using the Button's subtype method.
.--------<-------.
/ |
>-BUTTON gname -+- LINKLabel -+-- tagtext -------|
| +-- <fgpos> -------|
| +-- CALLback text -|
| +-- TOOLTIP text --|
| +-- <fganch> ------|
| +-- <fgdock> ------|
| +-- CORE ---------* Core managed gadget
| | .------<-----.
| |/ |
| +- FORM fname -|
| +- <vshap> ----*
| |
| +- TOOLTIP text -.
| '----------------'-->
|
| .--------<----------.
+-- TOGGLE -./ |
'-----------+- tagtext -----------|
+- <fgpos> -----------|
+- CALLback text -----|
+- TOOLTIP text ------|
+- <fganch> ----------|
+- <fgdock> ----------|
+- CORE --------------| Core managed gadget
+- BACKGround <colno>-|
+- PIXMAP <vshap> ----*
| .------<-----.
|/ |
+- FORM fname -|
+- <vshap> ----*
|
+- OK -----.
+- APPLY --|
+- CANCEL -|
+- RESET --|
+- HELP ---|
'----------+- TOOLTIP text -.
'----------------'-->
Note:
It is bad practice to place one gadget on top of another. This may lead to gadgets
being obscured.
|
Defaults: |
If no tag is specified, the tag defaults to the gadget’s gname. The control attribute is unset unless you specifically enter OK, APPLY, HELP, CANCEL, or RESET. The default values for anchoring is ANCHOR = Left + Top. |
The pixmaps associated with button gadgets can be changed after the gadgets have been displayed on a form.
The method syntax is:
AddPixmap( !pixmap1 is STRING )
AddPixmap( !pixmap1 is STRING, !pixmap2 is STRING )
Here, "!pixmap" is a string holding the file pathname of the required .png file, for example, "%pmllib%\png\camera.png".
"!pixmap1" shows the unselected state of the gadget, and "!pixmap2" shows the selected state.
Note:
It is recommended that when you define the gadget you set its size to encompass the
largest pixmap which you will later add. Failure to do this may give rise to unexpected
behavior.
Note:
Historically, you could add a third pixmap which was used when the gadget was de-activated.
This practice is no longer necessary as the gadget pixmapped is automatically grayed-out
on de-activation.