Element visibilities are controlled with element attribute "eyeball". This attribute can be set per-slide for each element. See Studio: Timeline Palette.

Eyeball attribute can also be controlled in Runtime with data inputs or setAttribute API.

Eyeball attribute controls not only element visibility, but also entire element active state. Element active state determines if element participates in animations, or if it in general exists in the scene at any given moment. Thus, changing element eyeball state is more than just hiding or revealing an existing element.

Using Data Inputs to Control Active State

A boolean type data input can be bound to element "eyeball" property and used to control element active state. See Using Data Inputs for details.

Master Slide Elements versus Per-slide Elements

When a data input is used to change element eyeball property, runtime behavior depends on whether the element exists on master slide, or on a single slide.

For elements on master slide, data input control is persistent. This means that after element visibility has been changed using a data input, element is no longer affected by visibility states set in slides, and will not change visibility at slide transitions. This helps avoid - often tricky! - bugs where element visibility is controlled by several sources.

For elements existing on a single slide, data input visibility control is not persistent. Element visibility can be set using a data input, but when the slide containing the element is re-entered, element visibility will have the state that was assigned to it in Editor.

SetAttribute API Visibility Control versus Data Inputs

Q3DSElement::setAttribute API can also be used to directly set eyeball attribute. Visibility persistence does not apply to any visibility changes done using setAttribute API.

Note: Data input is the preferred method for controlling element attributes.

Note: Mixing setAttribute and data input control can lead to unexpected behavior. Due to performance optimizations, Q3DSDataInput::setValue API by default only generates a change event when the new Data Input value differs from the old one. Thus, a data input might discard value even though the underlying target element visibility has actually been changed by another controller. See Best practices for dynamic visibility control for example.

Best Practices for Dynamic Visibility Control

If an element on master slide must be controlled dynamically, consider the following approach:

• Use a single visibility controller instead of relying on a combination of slide transitions, data inputs and setAttribute calls. For example, the following sequence where element "Element" visibility is bound to data input visCtrlDI will fail and leave "Element" in non-visible state:

  visCtrlDI.setValue(true)
  Element.setAttribute("eyeball", false)
  visCtrlDI.setValue(true) // this value change will be discarded, because force=true is not set

• For data input -controlled elements, set visibility explicitly with data input at presentationReady to make sure that visibility is at a known state. This also makes sure that master slide element visibility is persistent and not affected by slide transitions. Use parameter force = true.
• Use onSlideChanged signal and data input to explicitly set element visibility at slide transition, especially for master slide elements. Do not rely on visibility state set in slide.
• To make sure that visibility change event is actually created regardless of data input current value, use force=true parameter in Q3DSdata input::setValue interface. Do not call setValue needlessly when force parameter is set to true, as this can have performance implications.

Debugging Element Visibility Issues

Element has wrong visibility after slide change, element is on master slide, and visibility (eyeball) was changed with data input before this?

Slide-based visibility states are no longer used because data input control overrides them. Make sure that you will do all visibility changes using data input.

Element visibility was changed using Q3DSElement::setAttribute, and data input visibility setting now has no effect?

Do not mix setAttribute, slide-based and data input visibility control. Use force = true parameter for Q3DSDataInput::setValue API to make sure that data input does not discard incoming value.

Element is not on master slide, and data input visibility control has no effect after slide change?

Element visibility might have been changed by slide transition. Data input is not creating change event, if the new value is not different from previously set value. Use force = true parameter to bypass this optimization. Also remember that for non-master slide elements, data input control is not persistent. Entering this slide later on will again set visibility to slide-based initial value.