Implementation references
Scripting API and implementation references.
UI Toolkit
IMGUI
Overview
Index
The Editor includes these variations of buttons:
When to use
- Buttons are interaction elements that initialize actions, indicate choices, and control interfaces.
While buttons can have a variety of styles and purposes they all function similarly. - Buttons contain text or icons that should always clearly indicate the action they perform
- Buttons can be clustered together as single buttons or as a button group to create larger design patterns or components
Button variations
Basic button
When to use
The basic button initiates a specific action once selected. Once basic button actions are performed their task is complete.
APIs in UI Toolkit
APIs in IMGUI
When to use
- Independent toggle buttons are used for properties that are not dependent on each other but grouped together thematically (e.g. in TextMeshPro)
- It is possible to select multiple independent toggle buttons
APIs in IMGUI
Base styles
Group styles
When to use
- Dependent toggle buttons are used for properties that are dependent on each other and are tied together functionally (e.g. in Scene Toolbar)
- It is not possible to select multiple independent toggle buttons
APIs in IMGUI
Base styles
Group styles
.Toolbar
Guidance
Button order
Button order in the Editor
In the Editor, destructive buttons are aligned on the left, and secondary / primary buttons are aligned on the right hand side of the panel they are displayed in.
Button order in dialogs
Editor API for dialogs display the native operating system dialog.
Scripting API
DisplayDialog
DisplayDialogComplex
- On macOS 12, button order is; ok / alt / cancel
- On macOS 11, button order is; alt / cancel / ok
- On Windows, button order is; ok / alt / cancel
Style
Size parameters in IMGUI
Buttons come in three sizes in the IMGUI framework:
1. Default button: .Button
2. Large button: .LargeButton
3. Mini button: .minibutton
Grouped buttons in IMGUI
When grouping toggle buttons in the IMGUI framework, use these parameters to adjust left / right borders and margins:
1. Leftmost button: .ButtonLeft
2. Middle button: .ButtonMid
3. Rightmost button: .ButtonRight
Labels
- Button labels are horizontally and vertically centered
- When labeling, make sure to highlight the action that the button performs
- If the button performs an action use an active verb to indicate the user initiates the action
- If the button is for navigation then indicate the endpoint
- If the button is to select a tool then use the established icon for its tool type.
For more information go to Foundations > Iconography - For confirmation buttons restate the action being performed or a suggested action relating to the dialog
- For actions that have additional inputs or open windows following the initial choice, use an ellipses (...) after the action text. This indicates that the action offers more options or requires additional specification.
Label text
Buttons use labels to indicate their function and can be either a basic button or toggle button. Text buttons rely on words to express concepts that cannot be easily conveyed by icons or glyphs in an accessible manner. Buttons have text labels that should clearly and concisely indicate what action they perform.
- Button labels are limited to a single line of text
- Use sentence case for capitalization, making sure text conforms to our writing Style Guide
- Be concise by avoiding too many words
- Be clear by using simple, common and specific words; avoid jargon or wording that is vague or obscure
Behavior
Buttons visually communicate their interaction, by changing their state to convey that an action is being performed or is completed.
Because some buttons can relate to an action or process that can be performed multiple times, a button may return to its default state after it is pressed but will still play an animation to convey it has been used.
Formatting
Anatomy and layout
Anatomy
A button can contain the following elements:
1. Label
2. Icon
3. Container
Layout and specs
Height and padding specs for three sizes:
1. Mini Button: height is 18px, padding is 2 px
2. Default Button: height is 20px, padding is 3px
3. Large Button: height is 24px, padding is 5px
Interaction states
Default
The default state is the pre-interaction state.
Hover
When the cursor is over the button element.
Active
When the interaction is occurring or active, such as a menu being open or toggling a property.
Active focused
When the user has highlighted the active button element.
Focused
When the user has highlighted the default button element.
Hover focused
When the cursor is over the focused button element.
Disabled
When the interaction is not available to the user.
A button's state will vary depending on the state of the action it is performing and whether the action is available or not.
Color
Basic button color variables
1. button-background
2. button-border
3. button-text
Toggle button color variables
1. button-background
2. button-border
3. icon
Toolbar button color variables
toolbar container
1. toolbar_button-border
2. toolbar_button-background
3. toolbar_button-text
Code samples
UI Toolkit samples
Go to Window > UI Toolkit > Samples to view code samples in C# / USS / UXML.
Code references
Scripting references for
IMGUI
Unity - Scripting API:
GUI.Button
UnityEngine.GUI.Toggle (+styles)
UnityEngine.GUILayout.
Toolbar (+styles)
Resources and related
