BUTTON Gadget

Software Customisation Reference Manual

Summary of Objects, Members and Methods : Object Type Details : BUTTON Gadget


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

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.

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:

The Button has 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

don't support change of background colour

don't support 'pressed' and 'not pressed' value

are not enclosed in a box

can have popup menus (though this is not recommended)

don't have Control Types e.g. OK, CANCEL etc

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 -. '----------------'-->

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:

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.