/****************************************************************************
**
** 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: Toolbar
\page studio-toolbar.html
\ingroup qt3dstudio-studio

\section1 Selection Modes

\image Studio-Toolbar-Selection.png

The Selection Mode buttons control what item is selected in the timeline
palette when you click on items in the scene view. You can toggle mode with shortcut key
\c{Q}.

\list
\li
  Clicking on an item using \b{Group Select} mode will select the highest group or
  component owning the item you clicked on. This mode is useful when you
  want to move a group of items at once.
\li
  Clicking on an item using \b{Item Select} mode will select the item you clicked on. If
  the item is not present in the Timeline palette (if it is inside a
  component) then the component is selected instead.
\endlist

With either tool, if you \b{double-click} on an item in the
scene view then the item itself will be selected (changing which
component is displayed in the timeline palette as necessary).

\section1 Manipulator Modes

\image Studio-Toolbar-Transform.png

The Manipulator Mode buttons control what manipulator is shown in the
rendered scene when an item is selected, and what happens when you drag
on the selected item.

\list
\li
  The \b{Position} mode (keyboard shortcut: \c{W}) adjusts the
  position of the selected item. Left-dragging on the item will
  adjust the selected item's position in the plane of the render camera;
  right-dragging will adjust the selected item's position along the view
  axis of the camera.
\li
  The \b{Rotation} mode (keyboard shortcut: \c{E}) adjusts the
  rotation of the selected item. Left-dragging on the item will
  tumble the selected item; right-dragging rotate the item around the
  view axis of the camera.
\li
  The \b{Scale} mode (keyboard shortcut: \c{R}) adjusts the
  scale of the selected item. Left-dragging on the item will
  uniformly scale the selected item; right-dragging will adjust only the
  local Z scale of the item.
\endlist
By default the manipulators affect the local transformation of the item.
For example, selecting an unrotated cube inside a rotated group with the
Position manipulator mode active will show rotated axes. Dragging on the
red arrow of the manipulator will affect only the X position of the
item.

The \b{Local/Global Manipulators} mode (right-most icon above) changes
this behavior to affect the global transform of the selected item
instead. In global mode, the manipulators always transform with respect
to the global space. In the example above, turning on global mode will
show the red arrow for the position manipulator aligned with the screen
(assuming an unrotated camera). Dragging on the red arrow may affect two
or three of the position values for the selected item in order to move
it in global space.

\section1 Keyframing

\image Studio-Toolbar-Animation.png

The \b{Autoset Keyframes} toggle (keyboard shortcut: \c{K})
controls whether keyframes are automatically created at the current
playhead time in the timeline whenever a value with animation enabled
has its value changed.

The following example illustrates the use of this toggle:

\list 1
\li
  Create an object positioned at 0,0,0
\li
  Move the playhead to time 0.
\li
  Turn on the animation toggle for the Position property in the
  Inspector palette. A keyframe is created at time 0.
\li
  Move the playhead to a new time (e.g. 1 second).
\li
  Turn off the \c{Autoset Keyframes} toggle.
\li
  Adjust the object position to 100,200,0. The object moves in the scene view, but no keyframe is
  created.
\li
  Move the playhead to a new time (e.g.2 seconds). The object snaps back to position 0,0,0,
  since no new keyframe was created for the new position.
\li
  Turn on the \c{Autoset Keyframes} toggle.
\li
  Adjust the position to 100,200,0. As soon as you stop editing one of the position values a new
  keyframe is created. Each time you change a value at this time the keyframe is updated.
\endlist

Without the \c{Autoset Keyframes} mode on, you must set change keyframes manually by selecting
\uicontrol {Timeline > Set Changed Keyframes} from the menu (Shortcut key: \c {Ctrl + Shift + K}).
to create a new keyframe.

\section1 Edit Cameras

\image Studio-Toolbar-EditCameras.png

By default the rendered scene looks through the camera in each layer and
shows the composited result. Sometimes you want to instead move around
the 3D space of your scene without adjusting the final rendered view.
Studio calls this concept \e {Edit Cameras}, and it is controlled by the
section of the toolbar displayed above.

You can navigate in \e{Edit Camera Mode} by zooming, panning and orbiting:
\table
\header
  \li Action
  \li Shortcut keyboard
  \li Desctiption
\header
\row
  \li
  \b{Zoom}
  \li
  \c{Alt}+Right mouse button
  \li
  Clicking and dragging anywhere in the rendered view for the edit
  camera will zoom the view in/out as you drag up/down.
\row
  \li
  \b{Pan}
  \li
  \c{Alt}+Middle mouse button
  \li
  Clicking and dragging anywhere in the rendered view for the edit
  camera will slide the view around.
\row
  \li
  \b{Orbit}
  \li
  \c{Alt}+Left mouse button
  \li
  Clicking and dragging anywhere in the rendered view for the edit
  camera will rotate the view. (This is not available for the
  predefined, axis-aligned orthographic views.)
\endtable

\note When \e{Edit Camera} is in use it only makes sense to show the
contents of one layer at a time. To control which layer's items you are
viewing, select any item inside the desired layer in the timeline
palette.

\list
\li
  The \b{Edit Camera Mode} drop-down menu controls the view.
  \list
    \li
    The \b{Perspective View} and \b{Orthographic} view are
    free-form cameras that you can use to rotate around the scene.
  \li
    The
    \b{Top}/\b{Bottom}/\b{Left}/\b{Right}/\b{Front}/\b{Back}
    axis-aligned presets are orthographic cameras that may be panned and
    zoomed, but not orbited.
  \endlist
\li
  The \b{Scene Camera View} entry at the bottom of the menu
  switches out of edit camera mode and returns to displaying the final
  composited result from the cameras in each layer of the presentation.
\li
  \target fit-selected
  The \b{Fit Selected} command (keyboard
  shortcut: \c{F}) will ensure that whatever is selected fills the
  view of the active edit camera. If no item is selected, this command
  ensures that the contents of the active layer are all visible in the
  edit camera.
  \list
  \li
  \note If you want to drop your selection, but cannot find
     any empty space in the view to click on, you can click on empty
     space in the Slides palette to cause no items to be selected.
     This may seem a little weird, but it is effective.)
  \li
    When using the default \c{Scene Camera View} mode, this command will instead
    downscale the appearance of the presentation to fit within the
    available space in Studio.
  \endlist
\li
  The \b{Helper Grid} toggle (shortcut: \c{Ctrl + Shift + H}) toggles the visibility of the
  helper grid.
\li
  The \b{Shading Mode} toggle (shortcut: \c{L}) toggles a
  `headlamp' attached to your edit camera. When enabled (the default)
  items are lit by the edit camera such that they are always easy to
  see. When disabled, the lighting from the final rendering is used. If
  you have a black ambient lighting in your scene (the default) then
  objects viewed from behind may not be visible without turning on your
  headlamp.
\omit
\li
  The show or hide \b{Wireframe} toggles wireframe visibility (for tessellated meshes only).
\endomit
\endlist

\section1 Preview

\image Studio-Toolbar-Preview.png
The preview toolbar buttons are used to preview your presentation.
\list
  \li
  The \b{Filter Variants} button (keyboard shortcut: \c{F7}) will open the variant tags panel.
  Read more in the \l{Using Variant Tags} section.
  \li
  The \b{Preview with OpenGL Runtime} button (keyboard shortcut: \c{F5})
  will launch the OpenGL Runtime Viewer application and preview the
  application for the presentation.
  \li
  The \b{Remote Preview} button (keyboard shortcut: \c{F6})will launch the presentation on the
  connected remote device Qt 3D Studio Viewer application. This button is only enabled if you are
  connected to a remote device.
\endlist

\note If there is no \c{.uia} file in the folder for the presentation, then the
presentation will be previewed by itself (no sub-presentations).

*/