/****************************************************************************
**
** Copyright (C) 1993-2009 NVIDIA Corporation.
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qt 3D Studio.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!

\title Studio: Timeline Palette
\page studio-timeline-palette.html
\ingroup qt3dstudio-studio

\image Studio-Timeline-Overview.png

The timeline palette is second-only to the
\l{studio-inspector-palette.html}{inspector palette} in frequency of
use when editing a presentation. The timeline palette provides direct
access to all elements in your scene, including those not producing a
visible result, and also gives you control over the animation and
timing within a slide.

The palette is comprised of two connected sections: the scene graph (on
the left side) and the animation portion (on the right).

\section1 Scene Graph

\image Studio-Timeline-SceneGraph.png

The left half of the timeline palette shows all elements in your
presentation for the current slide (chosen in the
\l{studio-slide-palette.html}{slide palette}). The root of your
presentation is the scene, to which are attached one or more layers (and
possibly additional presentation behaviors).

\section2 Name Color Indicates Slide

The name of an item in the scene graph is colored based on its presence
on the master slide. Elements that are present on the master slide have
a green name, while elements that are only present on the current slide
have a light gray name.

The same holds true for animated properties. Properties that are
animated the same on all slides show with green text, while properties
that have a custom animation on this slide are shown with light gray text.

\section2 Element Hierarchy

Within each layer is a camera, usually a light, and the elements
rendered for the layer. These elements are arranged hierarchically.
Placing one element as a child of another causes:

\list
\li
  The child element to inherit the transform of the parent. When the
  parent moves or rotates, so do its children.
\li
  The child element to inherit the opacity from the parent. As the
  parent becomes less opaque, so do its children.
\li
  The child element to inherit the active state from the parent. If
  the parent is eyeballed off on this slide, so are all its children.
\li
  Events to bubble from the child to the parent. An
  \c{onPressureDown} event on a child element may also be handled
  by the parent element.
\endlist

\section2 Rearranging Elements

It is possible to rearrange elements by dragging and dropping them within the scene graph. This way
you can change positions of objects or alter parent/child relationships.

When dragging an element, a yellow line will indicate where it will be dropped, while a
yellow frame indicates under which parent element it will be dropped.
Additionally, a slightly yellow background indicates which element is being dragged.

A collapsed element will automatically expand if you drag and hold another element over it.

\image scene-graph-rearranging.png

\section2 Action Indicators

The left-most column of the timeline palette is used to show which
elements have actions on them.

\list
\li
  A row with \inlineimage Studio-Timeline-ActionBadge.png on it
  indicates that the element has one or more actions on it.
\li
  A row with a down-triangle in this column indicates that one or more
  descendant elements have actions on them.
\li
  A row with a right-triangle in this column indicates that the
  component on this row has one or more actions inside it.
\endlist

Elsewhere in the interface, a green item indicates an action on the
master slide, while a light gray item indicates an action specific to
this slide.

When an object has \c{onActivate} or \c{onDeactivate} timeline actions
on it, those are indicated with markers at the beginning and at the
end of the time bar. These actions are usually used with
\l{studio-basic-objects-palette.html#Signal}{Signal} objects.

\image Studio-Timeline-SignalAction.png

\section2 Editing Components

Components are somewhat like mini scenes. A component has its own set of
slides and independent time. Consequently the contents inside a
component cannot sensibly be shown and edited at the same time as items
outside a component. To see and edit the contents of a component, either
double-click the component or right-click on it and choose
\uicontrol{Edit Component}. The timeline and slide palettes will both switch to
show the contents of the component.

When you enter a component, a breadcrumb is shown at the top of the
Timeline palette.

\image Studio-Timeline-Breadcrumb.png

To leave the component and return to the scene, click on the scene in the beginning
of the breadcrumb.

Alternatively, double-click on an element outside the component in the
rendered scene view; this will switch the timeline palette as necessary
to select and show that item.

\section2 Hiding Irrelevant Elements

As your scene graph grows in elements you may find yourself annoyed by
the presence of elements that you almost never edit. The first column
after the name allows you to mark an element as shy, indicated by
\inlineimage Studio-Timeline-Shy.png
Clicking the button at the top of this column will toggle the visibility
of all element rows marked as shy.

\note This is only an editing convenience within the timeline
palette, and has no effect on the visibility of elements rendered in the
scene at runtime.

\section2 Per-Slide Element Visibility

If you have an element that should only appear on one slide, you should
create the element as a non-master element on the correct slide. If
you have an element that should appear on every slide, you should create
the element on the master slide. But what if you have an element that
should appear on a few slides, but not all?

The second column after the name has eyeballs
\inlineimage Studio-Timeline-Eyeball.png which are used
to control the active state of an element and all its descendants. To
cause an element to not appear on only certain slides, place your
element on the master slide and then eyeball it off on slides where it
should not be present.

\note The visible property is disabled on the master slide, it can only be controlled
on a per-slide basis.

The active state of an element controls more than just visibility.
Elements that are not active do not receive update notifications each
frame. which is particularly important for presentation behaviors.

Similar to the other columns, clicking the eyeball at the top of the
column will hide the rows for elements that are eyeballed off on the
current slide.

\note Unlike the shy and lock columns, the presence or
absence of the eyeball changes the runtime behavior of your
presentation. You may wish to use the eyeball to temporarily hide an
element during editing, but be sure to re-enable the element if it is
supposed to be present on this slide.

\section2 Locking an Element

Once you have perfected a particular element you may wish to lock it. To
lock the element, click the lock icon
\inlineimage Studio-Timeline-Lock.png in the third column. Locking an
element prevents its properties from being edited, and even prevents it
from being selected.

Similar to the other columns, clicking the lock at the top of the column
will hide the rows for elements that are locked. Unlike the other
columns, which take effect per slide, an element that is locked is
locked on every slide.

\note This is only an editing convenience, and has no effect
on interaction with elements at runtime.

\section2 Copying Object Path

The path to an element is used both in presentation behaviors as well
as by an application's
\l{file-formats-uia.html#visual-actions}{Visual Actions}. While you could
type out the name of each ancestor of the element, a more convenient
option is available.

Right-click on the name of any element and choose \uicontrol {Copy Object Path}
from the context menu. This will put a string on your clipboard like
\c{Scene.Overlays.Dialogs.Content.preloader}, ready for pasting
elsewhere.
\note For visual actions you need to prefix this
path with the \c{id} of the
\c{<presentation>} asset in order to
differentiate it from other possible presentations.

\section2 Layers

A layer represents a 3D scene that gets rendered into a 2D image and
placed somewhere on the screen. Just as a Photoshop file may have
multiple 2D layers drawn on top of one another, a Studio presentation
may have multiple layers composited together.

Layers also provide a target where
\l{best-practices-effects.html}{post-processing effects} may be applied.

There must be at least one layer on each slide in the presentation. Studio will not let
you delete the last layer unless you first add a new layer on the slide to replace it.

To create a new layer, do one of the following:
\list
  \li Click the layer icon
  \inlineimage Studio-Timeline-NewLayer.png
  in the bottom part of the scene graph.
  \li Right-click the scene element in the scene graph and select \uicontrol {Add Layer} from the
  context menu.
  \li Press \c{Ctrl + L}.
\endlist

Creating a new layer in your scene will add both a camera and a light to that new layer.

To remove a layer, first select it in the scene graph, then do one of the following:
\list
  \li Click the delete icon
  \inlineimage Studio-Timeline-DeleteLayer.png
  in the bottom part of the scene graph.
  \li Right-click it and select \uicontrol{Delete Object} from the context menu.
  \li Press \c{Del}.
\endlist

\section2 Data Input

You can \l {Using Data Inputs}{use a data input} to control the timeline animation. You can set up
a data input to control the timeline by clicking the
\inlineimage datainput-to-timeline-icon-inactive.png
icon.

Orange color indicates which data input is currently connected to the timeline. Click the
\inlineimage datainput-to-timeline-icon-active.png
and select \uicontrol None to remove the data input.

\image timeline-datainput.png

\section1 Animation Portion

\image Studio-Timeline-Animation.png

To the right of the scene graph in the timeline palette is the actual
timeline. The time bars for each element control element lifespan. The
keyframe markers control the timing of animation. The playhead (in red)
allows the preview of animation effects. The time measure across the top
coordinates the timing of it all.

\section2 Zooming In and Out

When working with fast animations you may wish to zoom in to see the
contents better. It is possible to zoom the timeline both horizontally and vertically.
To zoom the timeline horizontally, do one of the following:
\list
  \li Press \c{Alt + mouse right click} and drag the mouse left/right to zoom in/out.
  \li Press \c{+} or \c{-} on the keyboard to zoom in/out.
  \li Use the slider located in the bottom of the timeline palette
\endlist

To zoom the timeline vertically, hold down the Alt key and use the mouse scroll wheel.

\note Vertical zooming only applies to expanded property graphs.

\section2 Setting Playhead Time

Drag the playhead by the red knob over the time measure to adjust the
time. (You can actually just click and drag on the time measure and the
playhead will teleport to your mouse.) This is used to set the time for
a new keyframe, and the effects of dragging the playhead back and forth
will also preview the effects in the rendered scene view in real time.

To prevent keyframes from being misaligned, you may
wish to ensure that the playhead is exactly at a particular time.
Holding down the \c{Shift} key while dragging the playhead will
cause it to snap to keyframe markers as well as certain notches on the
time measure.

Use the \c{Timeline Snapping Grid} setting in the
\l{studio-menu.html#edit}{Application Preferences} to control what level
of notches it snaps to.

As you adjust the time for the playhead you will see the exact time
displayed below the scene graph portion of the
palette. Clicking on these numbers will open the Go To Time palette,
where you may type in an exact time, down to milliseconds, to set
the playhead to.

\section2 Working with Animations

For more information on how to work with animations, see the \l Animations documentation.

\section2 Adjusting Time Bars

The colored bars displayed for each element control the lifespan during
which the element is active. Whenever the playhead (in Studio, or the
virtual playhead active at runtime) is outside the time bar for an
element, that element becomes inactive: it no longer renders, nor does
it receive update events each frame.

Drag the ends of a time bar to adjust its duration. As with the dragging
the playhead, holding down the shift key will snap the time to
appropriate boundaries during dragging.

Alternatively, double-click on a time bar to open the Set Time Bar
Start/End Time dialog, where you may enter specific values.

To set the start or end time for many time bars at once:

\list 1
\li
  Select an element.
\li
  Set the playhead to the desired time.
\li
  Press the \c{[} key to set the start time to the playhead time,
  or the \c{]} key to set the end time to the playhead.
\endlist

All descendant elements will also have their start or end time set to
the same value. It is thus common when entering a new slide for the
first time to select the scene or active component, set the playhead
to a particular time, and then press \c{]} to crop the entire
slide to that duration.

\section2 Customizing Time Bars

To help you keep track of your assets, Studio allows you to apply custom
colors and text to time bars.

\section3 Custom Color

To apply a custom color, right-click on a time bar and choose \uicontrol {Change Time Bar Color}
from the context menu.

\section3 Custom Text

To apply a custom text, first do one of the following:
\list
  \li
    Right-click anywhere in the timeline palette and select
    \uicontrol {Toggle Timebars Text Visibility} from the context menu.
  \li
    Click the
    \inlineimage timeline-texts-icon.png
    icon in the bottom of the scene graph.
\endlist

Now, the timeline is in comment mode. Click a time bar to add or edit a text.

\image timeline-text-edit.png

\section2 Playback Control

\image Studio-Toolbar-Playback.png

These commands control the playhead, making it easier to preview
animations and slide transitions without leaving Studio.

\list
\li
  The \uicontrol{Rewind} command sets the playhead to time 0.
\li
  The \uicontrol{Play} command starts advancing the playhead in realtime,
  previewing animations on elements. The \uicontrol{Play Mode} for the
  current slide is honored, possibly looping or ping-ponging playback,
  or causing Studio to switch to an new slide when the end time for the
  current slide is reached.
\li
  The \uicontrol{Stop} command stops any playback. \uicontrol{Stop} replaces \uicontrol{Play}
  when animation is playing.
\li
  The \uicontrol{Fast-forward} command sets the playhead to the timeline end.
\li
  Holding down the space bar temporarily enables playback while held
  down. Releasing the spacebar returns the playhead to its previous
  time, allowing you to repeatedly hold down space to preview an
  animation.
\li
  Pressing the Enter key will start playback. Press Enter again to stop
  playback.
\endlist
*/