Items

Items are interactive elements (like buttons, checkboxes, and sliders) that react to cursors.

Item Overview

Capabilities

Items are provide a variety of functionality, and are extremely flexible. You can:

• Configure them for a variety of behaviors (like a checkbox or slider).
• Listen for their events to trigger changes in a scene.
• Render them with any shape, size, or visual appearance.
• Position, rotate, arrange, and animate them within any layout.
• Modify functionality or appearance in the Unity editor and at runtime.

Structure

Each item has one main GameObject with several item-specific components attached to it. These components handle the item's functionality -- data, states, events, etc. This functional portion is typically referred to simply as the item.

The item's main GameObject has a child GameObject (often a prefab reference), with its own hierarchy of objects and components. These components handle the item's visual appearance -- shape, size, colors, textures, fonts, indicator styles, animations, etc. This visual portion is typically referred to as the renderer.

Each item needs a compatible renderer (for example, the renderer provides a "hit area" for item selections). However, the item is not dependent upon any particular structure or graphics within the renderer.

Types

Each item type provides a different behavior. The item type is also reflected in the visual display provided by a renderer. The following list describes the available item types:

Type	Description	Default Renderer
Selector	A "trigger" style button with no on/off state.	Button. Shows no icon.
Sticky	A "press-and-hold" style button that stays selected until the cursor moves far enough away from it.	Button. Shows a sticky icon.
Checkbox	A button that toggles an on/off state upon selection.	Button. Shows a filled/unfilled checkbox icon.
Radio	A button that toggles on when selected directly, but toggles off when another item within its "radio group" is selected.	Button. Shows a filled/unfilled radio icon.
Slider	A "track" that represents a range of values, with a "handle" (a sub-item "Sticky" button) that moves along the track to select a value within the range.	Slider. Contains a track with segments and tick marks, and a handle that shows a slider icon.
Text	A non-selectable item.	Button. Shows no icon.

Transform

Use the item's transform (not the renderer's transform) to move and rotate the item.

Note: when items are grouped within a layout, the layout will control some aspects of the item's position and rotation.

Item Components

The following sections describe the components that are attached to the item's main GameObject.

Tree Updater

The TreeUpdater component is responsible for ensuring that the item and its components update in the correct order during each frame. This is a general-use component.

Item

The HoverItem component is responsible for selecting the item type, and maintaining the data (as much as possible) after a change to the item type.

This component has an "Item Type" property that can be changed at any time (in the Unity editor or during runtime). The item (and sometimes, its renderer) will automatically update to support the new item type.

Item Data (and Events)

Each item type has its own data component, such as HoverItemDataCheckbox and HoverItemDataSlider. These components are responsible for maintaining their item's values, and for triggering the item's events.

These components all have the same two properties, "Id" and "Label". Each component also has several type-specific properties. For example, the Checkbox item type has a boolean "Checkbox Value" property, while the Slider item type has properties for its numerical range values and number of tick marks.

These components all provide type-specific events, which you can use to trigger actions in your scene. These are in the Unity inspector's "Events" foldout. These components also provide read-only information in the Unity inspector's "Info" foldout.

Highlight State

The HoverItemHighlightState component is responsible for finding the distances between the item and each cursor, and converting those distances into a highlight (or proximity) progress.

The item-to-cursor distances are calculated by determining the nearest point, compared to each cursor, that falls within the item's "hit area". Because the renderer controls the item's size and shape, the renderer (via the "ProximityProvider" property) is responsible for calculating the nearest point.

This component has an "Interaction Settings" property, which is pre-set to the HoverInteractionSettings component within the HoverKit prefab. You may set this property to give an item different interaction-related settings (for example, the proximity distance thresholds).

This component also provides read-only information in the Unity inspector's "Item Highlight Information" foldout.

Selection State

The HoverItemSelectionState component is responsible for calculating the item's selection progress. This progress can only occur while the item has 100% highlight progress, and (unlike the highlight progress) it grows based on time duration.

This component also provides read-only information in the Unity inspector's "Item Selection Information" foldout.

Renderer Updater

The HoverItemRendererUpdater component is responsible for instantiating the item's renderer (via prefab reference), switching between renderers when the item type changes, and updating the renderer with item-related data.

This component has "Button Renderer Prefab" and "Slider Renderer Prefab" properties, which are pre-set with references to the default renderer prefabs. There are two separate renderer types here because the requirements for a "button" renderer and a "slider" renderer are very different. You can set these properties to use different prefab references. Note that the renderer prefabs also determine the item's shape (for example, there are "Rect" and "Arc" variants of all default renderer prefabs).

This component also has a "Rebuild Renderer" button. Changing the prefab properties (described above) automatically generates a rebuild action, so the primary reason for this button is to delete/overwrite any item-specific changes that were made to the renderer.