Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

Examples of an unassigned field with no icon and an assigned field with an object icon, displayed in light and dark themes
Object fields display the object icon when an object is assigned
  • The object field can be configured to receive any object type
  • Allowable objects include any type of asset such as images, audio clips, textures, terrains, and materials
  • Objects can be assigned either by drag and drop or by selecting an object using the object picker

Object fields APIs

An example of an empty object field on the left and a cube mesh object field with an object icon on the right
An empty object field and cube mesh object field with object icon

Object fields in UI Toolkit

Object field UI Builder icon
UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}
API in UI Toolkit
ObjectField
Reference for an object field
Object fields in IMGUI
API in IMGUI
EditorGUI.ObjectField
Makes a field to receive any object type

Guidance

When to use

An object field is an input field that is used when a user needs to assign an object or asset to a subject.

How to use

  • Avoid hidden or implicit behavior when the object field is unset.
  • If unsetting the object field changes its behavior, consider hiding the control behind an explicit decision that the user must make (such as a toggles or dropdowns) to make sure the user knows what to expect
  • Objects can be assigned either by drag and drop, by code or by selecting an object using the object picker
  • To use the object picker the user must first set up the object type. The object type can include images, audio clips, textures, terrains and materials

Style

Picker window headers
Example of an object picker for materials with the “Select Materials” header displayed
Object picker for materials with the header “Select Material”
  • If there is no object type defined for the object field, the object picker window header is “Select” by default
  • If an object type is defined for the object field, the picker window header refers to this type, such as “Select Material” for textures
Drag and drop highlight
Three stages of drag and drop using material for an example with the idle stage on the left, the material dragged in the center and the material assigned on the right
Dragging a material in the material object field

In addition to using the Object Field Button to assign objects, users can drag and drop objects to the object field body.

When an object is being dragged on an object field, it’s entire body will be highlighted in blue.

Object types

Allowing scene objects

Use allowSceneObjects to allow scene objects to be assigned to the object field.

Setting up object types

Users can set up the object parameter to be a Project Asset and set the type of object to be any type of asset.

Change GameObject parameter in obj, typeof(GameObject) to define different object types.

Ensure that the allowSceneObjects parameter is false if the object reference is stored as part of an asset, since assets can't store references to objects in a Scene.

Assigning an object
Two ways to assign an object, with the drag and drop method shown on the left and the object picker window on the right
Assigning a material by drag and drop (left) and using picker window (right)

Users can assign an object to the object field by;

  • Clicking on Object Field Button to open the Picker Window and choose the object
  • Dragging an object from the projects panel onto the Object Field body. Note that the object type needs to match the object field
Locating assigned objects
An animated image showing a cursor locating a material asset in the project panel by clicking on the object icon
Locating material asset in the project window by clicking the object icon

Clicking the object field body will highlight the assigned objects and their path in the Project panel.

Formatting

Anatomy and layout

Anatomy
An annotated image showing the numbered parts of an object field
Anatomy of an object field and its key parts

A numeric field can contain and be paired with the following elements:

1. Control label
2. Object icon
3. Object label
4. Object field button
5. Body (container)

1. Control label

Labels should be placed to the left of the object field and be should be simple and clear, relating to the nature of content.

2. Object icon

Icon representing the type of object picked.

3. Object label

Label of the picked object.

4. Object field button

Button to open up the picker modal.

5. Body (container)

The body of the object field is the container where content (Icons, Object Icon and Label, Object Field Button) is displayed.

Interaction states

An object field’s five interactive states in light and dark themes
An object field's interactive states
Default

Default state of an Object Field.

Hover

When hovering over an object field body the border will be highlighted.
When hovering over the object field button, both the button and border will be highlighted.

Focused

When an object field enters the Focused state its label and border will be highlighted in blue.

Accepted (drag and drop)

When an object is being dragged on an object field, it’s entire body will be highlighted in blue.

Disabled

An object field that is disabled will indicate so by having its body “greyed out” and will not accept inputs or react to hovering.

Color

An object field in light and dark themes with annotations indicating the object field background color, the object field border color and the object field button background color
1. object_field-background 2. object_field-border 3. object_field_button-background
Object Field Background
--unity-colors-object_field-background
The background color for an object field control
#EDEDED
#282828
Object Field Border
--unity-colors-object_field-border
The border color for an object field control
#B0B0B0
#202020
Object Field Border Focus
--unity-colors-object_field-border-focus
The border color for an object field control when it has focus
#1D5087
#3A79BB
Object Field Border Hover
--unity-colors-object_field-border-hover
The border color for an object field control when the mouse pointer hovers over it
#6C6C6C
#656565
Object Field Button Background
--unity-colors-object_field_button-background
The background color for the button in an object field control
#DEDEDE
#373737
Object Field Button Background Hover
--unity-colors-object_field_button-background-hover
The background color for the button in an object field control when the mouse pointer hovers over it
#CCCCCC
#4C4C4C

Code samples

UI Toolkit samples

Icon indicating this element is available in UI Builder

Go to Window > UI Toolkit > Samples, to view code samples in C# / USS / UXML.

Slider icon