Buttons
PBButton
Opaque object handle: A clickable button UI element.
This is a subclass of PBElement. You can safely cast from PBButton to PBElement. To cast from PBElement to PBButton, call PBButtonCast; this performs a runtime assertion to check the cast is possible. This function is thread-safe.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBElementRetain; to decrement the reference count, call PBElementRelease. These functions are thread-safe.
PBButtonFlags
Enumeration/bitset of type uint32_t: Flags controlling the behavior and appearance of a button.
Constants
PBButton_NO_LABEL
PBButton_NO_LABEL = 1<<0
If not set, PBButtonCreate adds a PBTextDisplay as a child to the button for use as its label with the default control text style. The button still keeps track of the passed label string regardless (for accessibility).
PBButton_NO_FOCUS
PBButton_NO_FOCUS = 1<<1
If set, the button will not mark itself as a tab stop, and it will not focus itself when pressed.
PBButton_PRIMARY
PBButton_PRIMARY = 1<<2
Display in the primary button style.
Or any of the values from PBElementFlags.
PBButtonCreate
Function: Create a button UI element.
Syntax (C/C++)
PBButtonPtr _Nullable PBButtonCreate(PBElementRef parent, PBButtonFlags flags,
ConstStr label);
Syntax (Python)
ButtonCreate(parent, flags, label) -> (button)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBButtonFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] label (referenced string): The initial label displayed in the button.
[out] button (nullable owned PBButton): The button element, or null on failure.
Discussion
Set the callback that runs when the button is clicked with PBButtonSetActionHandler. Change the label of the button after creating it with PBButtonSetLabel.
See PBElementCreate for a more detailed description of element creation.
Example (C/C++)
PBButton *button = PBButtonCreate(parent, 0, PB_STR("Push"));
PBAssert(button);
PBButtonSetActionHandler(button, PBActionHandler_Make(ButtonClicked));
PBElementRelease((PBElement *) button);
See Also
PBButtonAddWithAction
Function: Create a button that runs an action command when clicked.
Syntax (C/C++)
void PBButtonAddWithAction(PBElementRef parent, PBButtonFlags flags,
PBWindowRef _Nullable windowForCommand, PBCommandID actionCommandID,
PBCommandListItemFlags itemFlags);
Syntax (Python)
ButtonAddWithAction(parent, flags, windowForCommand, actionCommandID, itemFlags)
Parameters and Return Values
[in] parent (referenced PBElement): The parent element.
[in] flags (PBButtonFlags): Flags bitwise OR-ed together controlling the behavior and appearance of the element.
[in] windowForCommand (nullable referenced PBWindow): If non-null, this specifies the window in which the target command is registered. If null, the window containing the button is used.
[in] actionCommandID (PBCommandID): The identifier of the action command. You can register commands with PBWindowRegisterAction.
[in] itemFlags (PBCommandListItemFlags): Flags bitwise OR-ed together controlling how the command is used.
Discussion
This function does not return a pointer to the created element since it modifies various properties of the element which should not be accessed further.
The button will automatically be enabled and disabled with the command. When clicked, it will call PBWindowInvokeCommand.
See PBElementCreate for a more detailed description of element creation.
Example (C/C++)
PBButtonAddWithAction(parent, 0, NULL, COMMAND_REFRESH, 0);
See Also
PBButtonSetLabel
Function: Change the label of a button.
Syntax (C/C++)
void PBButtonSetLabel(PBButtonRef button, ConstStr contents);
Syntax (Python)
ButtonSetLabel(button, contents)
Parameters and Return Values
[in] button (referenced PBButton): The button object.
[in] contents (referenced string): The new label.
Discussion
The button is automatically redrawn after changing the label. The button maintains its own copy of the label, which will be automatically freed when the button is destroyed.
If PBButton_NO_LABEL is set, the label will only be used for reporting the label accessibility property.
Example (C/C++)
PBButtonSetLabel(button, PB_STR(playing ? "Pause" : "Play"));
See Also
PBButtonSetIcon
Function: Set the icon display in the button.
Syntax (C/C++)
void PBButtonSetIcon(PBButtonRef button, PBImageRef _Nullable image);
Syntax (Python)
ButtonSetIcon(button, image)
Parameters and Return Values
[in] button (referenced PBButton): The button object
[in] image (nullable referenced PBImage): The image to display as the icon. If null, the current icon is removed.
Discussion
Even if the button only has an icon, you should still set the label with PBButtonSetLabel to describe the button's purpose and set a tool tip.
The button maintains its own reference to the image. The button is automatically redrawn after calling this function.
See Also
PBButtonSetToolTipText
Function: Set the text displayed in a tool tip when the mouse hovers over the button for a short while.
Syntax (C/C++)
void PBButtonSetToolTipText(PBButtonRef button, ConstStr toolTipText);
Syntax (Python)
ButtonSetToolTipText(button, toolTipText)
Parameters and Return Values
[in] button (referenced PBButton): The button object.
[in] toolTipText (referenced string): The text to display.
Discussion
Calling this function does not cause a tool tip to be displayed. It merely sets the text that will be displayed when a tool tip is created for the button.
See Also
PBButtonSetActionHandler
Function: Set the callback for when a button is clicked.
Syntax (C/C++)
void PBButtonSetActionHandler(PBButtonRef button, PBActionHandler actionHandler);
Syntax (Python)
ButtonSetActionHandler(button, actionHandler)
Parameters and Return Values
[in] button (referenced PBButton): The button object.
[in] actionHandler (PBActionHandler): The callback. The window parameter will be the set to the window containing the button. The context parameter will be set to the user data of the element (see PBElementSetUserDataInt and PBElementSetUserDataPtr).
Discussion
This is the preferred method for handling button clicks, since it will also respond correctly to automation requests.
Example (C/C++)
void OnClick(PBWindow *window, PBModifierKeys modifiers, UserContext context) {
PBLogInfo("The button was clicked (%d).", (int) context.i);
}
PBElementSetUserDataInt((PBElement *) button, 50);
PBButtonSetActionHandler(button, PBActionHandler_Make(OnClick));
See Also
PBButtonSetTextStyle
Function: Sets the style of text displayed in the button.
Syntax (C/C++)
void PBButtonSetTextStyle(PBButtonRef button, PBTextStyleRef textStyle);
Syntax (Python)
ButtonSetTextStyle(button, textStyle)
Parameters and Return Values
[in] button (referenced PBButton): The button object.
[in] textStyle (referenced PBTextStyle): The new text style for the button's label. The text style's color is ignored; see the discussion.
Discussion
The button is automatically redrawn after changing the text style. The button maintains its own reference to the text style, which will be automatically freed when the button is destroyed.
This function cannot be used if PBButton_NO_LABEL is set.
The appearance of the button determines the color of its text. Therefore, regardless of the text color specified in the text style, the label's colors will be unchanged. This behavior was chosen so that the text is always readable on the button's background. However, if you really wish to change the label's text color, then you should create the button with the flag PBButton_NO_LABEL and manually add a text display to it.