UserGuide

Desktop Button

From Xojo Documentation

A Button is the standard button control for the OS. Typically a user clicks on buttons to perform an action of some kind.

Push Button Library Icons

There are three button types in the Library from which to choose: Default Button, Cancel Button and Generic Button. They are primarily the same, just with different property settings and default text. They all inherit from PushButton, which is the name for the standard button control. Refer to PushButton in the Language Reference Guide details on all its events, properties and methods.

When you click a button it is highlighted giving the user feedback that they have clicked it. Buttons are typically used to take an immediate and obvious action when pressed, like printing a report or closing a window.

Below are the commonly used events and properties:

Events

Action

This event handler is called when the button has been pressed (or clicked).
If you want to call the code in the Action event handler by other means (e.g. a menu event), then you should move the code to a method and instead call the method from the Action event handler and anywhere else it is used.

Properties

Caption

The text for the button's Caption. To change the Caption in code, assign a new value:
SaveButton.Caption = "Save"

ButtonStyle (Mac-only)

This property is ignored on Windows and Linux. For Mac apps this changes the look of the Button to one of these styles: Bevel, Gradient, Help, Push, Recessed, Round, Rounded, RoundTextured, Square, Textured.

TextFont, TextSize, Bold, Italic, Underline

Font, size and style information for drawing the button's Caption.

Default, PushButton.Cancel

These are Boolean values indicating how the button appears and responses to OS-specific keystrokes. For example, when Default = True, the button Action event is called when Return is pressed. When Cancel = True, the button Action event is called when ESC is pressed. At most only one button on a Window layout should be set as the Default. At most only one button on a layout should be set to Cancel.
Note that a button can only work with keyboard commands if there are no entry fields with the focus. If a TextField or TextArea has the focus, then it will response to keyboard commands and not the button.

Methods

Push

This calls the Action event handler for the button, giving it the appearance of being pressed. As noted above for the Action event handler, you should not use this as a substitute for moving common code to its own method. Use the Push method for special cases where you want you UI to indicate the button was pressed.

Handling Focus

Buttons can have the focus on Microsoft Windows. When a button gets the focus, a rectangular outline surrounds its caption. Pressing the spacebar while the Button has the focus pushes it and calls its Action event handler.

On a window, the default button can also be “pushed” by pressing Return/Enter. The Cancel button can be pushed by pressing Esc.

On Mac, a button can only get the focus if you enable Keyboard Access in System Preferences.

Usage

You can put the code that should run when the button is pressed in the Action event handler. This code displays a simple message when a button is pressed:

MsgBox("Hello!")

If your code needs to be called from multiple places (say a button press and a menu), then put the code in its own method and then call the method from the button and menu Action event handlers.

See Also

PushButton class; UserGuide:Desktop Bevel Button, UserGuide:Desktop Segmented Control topics