Software Customisation Reference Manual
Summary of Objects, Members and Methods : Object Type Details : BUTTON Gadget
BUTTON Gadget
Members
 
Name
Type
Purpose
Background
REAL
Set/Get
Set or get Background Colour Number
Background
STRING
Set Only
Set Background Colour Name
Val
BOOLEAN
TRUE when the button is pressed
FALSE when it is not
Table 2: 22.
BUTTON Object Members
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, e.g.'!!Form.gadget'.
Name()
STRING
Get the gadget's name, e.g. '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 Colour Name.
Some gadgets do not support this property in all circumstances, e.g. gadgets which are showing a pixmap. Gadgets whose colour has not been set explicitly, may not have a colour with a known colourname. In this case an error is raised..
SetToolTip(STRING)
NO RESULT
Sets the text of the Tooltip.
Type()
STRING
Get the gadget-type as a STRING.
Table 2: 23.
BUTTON Object Methods
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, e.g. 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 colour 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.
Note:
 
1.
The Button has subtypes Normal, Toggle and Linklabel.
2.
Linklabels are Buttons and so they do cause validation of any modified text fields of the form whenever they are pressed.
3.
Linklabels:
1.
cannot have pixmaps assigned to them
2.
don't support change of background colour
3.
don't support 'pressed' and 'not pressed' value
4.
are not enclosed in a box
5.
can have popup menus (though this is not recommended)
6.
don't have Control Types e.g. OK, CANCEL etc
4.
The sub-type 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 -.
                                                  '----------------'-->
Figure 2:19.
Syntax Graph -: Creating a BUTTON Object
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.
Method syntax is:
AddPixmap( !pixmap1 is STRING )
AddPixmap( !pixmap1 is STRING, !pixmap2 is STRING )
Where: !pixmap is a string holding the file pathname of the required .png file, e.g.
%pmllib%\png\camera.png
!pixmap1 shows the Un-selected state of the gadget, and pixmap2 shows the Selected state.
Notes:
1.
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 behaviour.
2.
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 greyed-out on de-activation.
1974 to current year. AVEVA Solutions Limited and its subsidiaries. All rights reserved.
AVEVA Logo