Essence » Wiki » Buttons

UI Elements > Controls > Buttons


Push Buttons

An image of a push button, in its normal state.

Push buttons are used to allow the user to either perform an action, such as saving a document, or cause some modification to the GUI, such as opening a find dialog.

When a push button has keyboard focus, it can be invoked by pressing the space key. When a push button has mouse hover, it can be invoked by a single left click.

A push button's label should be in sentence case. If the action requires further information, such as selecting a filename, then the label should have a trailing ellipsis. The label should contain a brief description of the action it will perform, such as "Open..." or "Zoom in".

In a dialog box, one push button can be selected as the default button. This allows it to be invoked by pressing the enter key. This implicitly also gives it keyboard focus. If the keyboard focus changes to another push button, then that push button can be invoked with the enter key instead. This special type of focus is called button focus.

If the push button causes a destructive, irreversible action to occur, then it should be marked as dangerous.

Avoid including an icon on a push button, unless it specifically helps to convey the meaning of the action. However, a push button must always have a label.

Do not use a push button to toggle between two states. Use a checkbox or checkable toolbar button instead.

Push buttons should remain at their default height. If the label is long, then the button can be expanded horizontally to make it fit.

Push buttons can be placed in the following grid styles:

  • Group boxes
  • Containers
  • Tab pane content

Custom push button styles should be used with caution. Do not use a push button as an opportunity to brand your program.

Creating a button

Here is an example of creating a button and its command, and adding it to a container.


[command doSomething]
label = "Do something";


OSObject button = OSButtonCreate(commandGroup + doSomething, OS_BUTTON_STYLE_NORMAL);
OSGridAddElement(myContainer, 0 /*column*/, 0 /*row*/, button, OS_CELL_CENTER);



A button can be created using the OSButtonCreate subroutine.

OSObject OSButtonCreate(OSCommand *command, OSButtonStyle *style);

The command is optional. If provided, the button will inherit its label, icon, danger marker, checked state, disabled state, and notification callback. It will then be added to the command's list of connected controls.

The style can be one of the following default values, or manually configured:

  • OS_BUTTON_STYLE_NORMAL: infer the button type based on the command; push button by default
  • OS_BUTTON_STYLE_REPEAT: enables the button's command to be repeatedly triggered when held down
  • OS_BUTTON_STYLE_TOOLBAR: the button can be placed in a toolbar
  • OS_BUTTON_STYLE_TOOLBAR_ICON_ONLY: the button can be placed in a toolbar; the label is hidden

When the button is invoked, a OS_NOTIFICATION_COMMAND notification will be sent to its notification callback.


struct OSButtonStyle {
    uint32_t flags, textColor,
        horizontalMargin, verticalMargin, 
        preferredWidth, preferredHeight, textAlign;
    OSUIImage **backgrounds, *icon;

flags is a combination of:

  • OS_BUTTON_FLAG_TEXT_SHADOW: the label should have a shadow
  • OS_BUTTON_FLAG_TEXT_SHADOW_BLUR: the label's shadow should be blurred
  • OS_BUTTON_FLAG_TEXT_BOLD: the label's text is bold
  • OS_BUTTON_FLAG_CENTER_ICONS: the icon should be centered in the button
  • OS_BUTTON_FLAG_FOCUSABLE: the button can receive keyboard focus
  • OS_BUTTON_FLAG_TAB_STOP: the button can be focused using tab navigation
  • OS_BUTTON_FLAG_USE_CLICKED_REPEAT: when the button is held, it will be repeatedly invoked

textColor is the color of the label's text. horizontal/verticalMargin is the size of the gap between the border of the button and its label in pixels. preferredWidth/Height is the default size of the button in pixels. textAlign is the alignment of the label. See OS_DRAW_STRING_*. icon is the button's icon.

backgrounds is an array of the button's backgrounds. The order of images is as follows:

  • The normal state, when the button has neither mouse hover nor keyboard focus
  • The disabled state, entered using OSControlDisable.
  • The hover state, when the mouse is within the bounds of the button
  • The pressed state, when the button is being invoked.
  • The focused state, when the button has keyboard focus.

The focused image should only be present if the flag OS_BUTTON_FLAG_HAS_FOCUSED_BACKGROUND is given. If the flag OS_BUTTON_FLAG_HAS_CHECKED_BACKGROUNDS is passed, the array should be immediately duplicated with the checked variants of each backgrounds.

Therefore the following background orders are valid:

  • normal, disabled, hover, pressed
  • OS_BUTTON_FLAG_HAS_FOCUSED_BACKGROUND: normal, disabled, hover, pressed, focused
  • OS_BUTTON_FLAG_HAS_CHECKED_BACKGROUNDS: normal, disabled, hover, pressed, normal and checked, disabled and checked, hover and checked, pressed and checked
  • OS_BUTTON_FLAG_HAS_FOCUSED_BACKGROUND | OS_BUTTON_FLAG_HAS_CHECKED_BACKGROUNDS: normal, disabled, hover, pressed, focused, normal and checked, disabled and checked, hover and checked, pressed and checked, focused and checked


A button can be created in the UI markup language with the button instruction, which takes a single argument, the command.

For example, to add right-aligned button:

[right] button "instance->commands + commandMatchCase"


The button handles the following messages, in additional to standard control message processing:

  • OS_MESSAGE_CLICKED: invoking a button's command when clicked
  • OS_MESSAGE_START_FOCUS: giving a button in a dialog button focus
  • OS_MESSAGE_KEY_PRESSED: invoking a button's command using the keyboard
  • OS_MESSAGE_KEY_RELEASED: invoking a button's command using the keyboard

See Also

A button inherits from a control, which inherits from a UI element, which in turn inherits from an API object.