Stacks API

Come build with us.
Stacks API v11 for Stacks 4.0


Button — button

This content is open source. You can edit it and submit a pull request on GitHub.
This page is generated from this file.

© . YourHead Software all rights reserved.

Button — button

Available: Stacks API v7

A Button has all the properties of a checkbox. It represents a boolean value that is either true (pushed in) or false (default). Like checkboxes the output value of a button can be set to any specific value by using the True Value and False Value properties.

Radio Mode

Checkboxes arrays can be used where only one of the group is allowed to be checked at a time. To use checkboxes in this mode use one of the array types (see below) and enable the Radio property.

Button Array

Button controls can be used in arrays. Each has its own icon, subtitle, trueValue, falseValue, and default, all other values are shared. Button types are:

NB: trueValue/falseValue arrays requires Stacks API v8 (Stacks v3.1+).

Button Icons

A checkbox can also display an Icon. All the icons from the Stacks UI, including your custom buttons, come from the Font Awesome library package. This gives Stacks a single unified cohesive UI even while allowing a significant amount of customization.

You can choose from over 500 custom icons on the Font Awesome Icons page. Set the icons property of your button to the Unicode value of the icon you would like to display. Stacks will take care of rendering the icon for all the needed button states for Mac OS X.

The icons labeled “cube” and “cubes” are reserved for Stacks internal use.

Hint: To find the Unicode value of a Font Awesome icon click through to the icon’s page (e.g. Birthday Cake icon). The Unicode value is listed below the icon previews. (e.g. Unicode f1fd for Birthday Cake). You can enter this value directly into a PList editor as a hex value, just enter 0x before the listed value (e.g. type “0xf1fd” in the Xcode PList editor). You can also convert that hex value to a regular integer using (e.g. f1fd = 61949).


An array of Unicode values (integers) of Font Awesome icons. If using a button array, provide one value for each button. See description above for Font Awesome details.

Radio Buttons

Radio buttons will allow only one button in the group to be pushed.

True Value

When the button is pressed this value will be used in replacement templates. In arrays, this may be an arrof of strings.

False Value

When the button is unpressed this value will be used in replacement templates. In arrays, this may be an arrof of strings.

Default Value

When the stack is placed onto the page the default value will be used. If no default is provided, 0 will be used.


The ID for this control. This ID must be unique within this stack. The ID is used to refer to control’s property. IDs should be alpha-numeric (dashes and underscores are allowed), but should not contain special characters.


The title displayed next to the control. Long titles will be truncated, so keep it short.


Hide or show the control based on the value of another property.

Enables allow a stack to show only the controls needed by the user to achieve a specific task.

The enable dictionary defines the ID of another control and the value that other control must equal. When the other control’s value is not equal to the provided value, this control is hidden.

Enable Dictionary

Enable Operations

Warning: creating infinite loops in enable dependencies has undefined behavior. It will likely result in a RapidWeaver crash.

NB: macOS does not specify the wildcard characters available or how they function. * and ? clearly work as they do in a UNIX shell. you’ll just have to guess at the rest.

Tool Tip

The tooltip value is used to display hints for the user on the use of each control. If the function of the control is obvious, then a tooltip should be avoided. Simply re-displaying redundant information like the title has no value to the user.


Subtitles are displayed under the control. Subtitles are unique for each item in a control array. You should provide one for each item in the control array. In the plist the subtitles should be an array of Subtitle strings. Note that some controls have very little space, so only very short subtitles can be used.



The scope of a property can be set to bind to the page instead of each stack. Binding a property to the page-scope means that the values set by this control will be shared between all stack-instances on the page.



Inheritance allows one stack to pull in the controls and properties of another stack. All of the controls from the specified stack are pulled in to the current stack. The inherited controls will be ordered as if they were they were first in the plist customItems array. The value should be the ID of the stack to inherit from.

© . YourHead Software all rights reserved.