diff --git a/doc/qtcreator/images/extraimages/images/V3Po15bNErw.jpg b/doc/qtcreator/images/extraimages/images/V3Po15bNErw.jpg new file mode 100644 index 00000000000..b3f27ff426e Binary files /dev/null and b/doc/qtcreator/images/extraimages/images/V3Po15bNErw.jpg differ diff --git a/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf b/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf index b689825fc30..5eacc4d3118 100644 --- a/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf +++ b/doc/qtcreator/images/extraimages/qtcreator-extraimages.qdocconf @@ -6,4 +6,5 @@ images/Ed8WS03C-Vk.jpg \ images/UfvA04CIXv0.jpg \ images/FzmLuRHQXaw.jpg \ - images/pEETxSxYazg.jpg + images/pEETxSxYazg.jpg \ + images/V3Po15bNErw.jpg diff --git a/doc/qtcreator/images/extraimages/qtdesignstudio-extraimages.qdocconf b/doc/qtcreator/images/extraimages/qtdesignstudio-extraimages.qdocconf index a09c5566a21..c0f64117d24 100644 --- a/doc/qtcreator/images/extraimages/qtdesignstudio-extraimages.qdocconf +++ b/doc/qtcreator/images/extraimages/qtdesignstudio-extraimages.qdocconf @@ -11,4 +11,5 @@ images/UfvA04CIXv0.jpg \ images/FzmLuRHQXaw.jpg \ images/w1yhDl93YI0.jpg \ - images/pEETxSxYazg.jpg + images/pEETxSxYazg.jpg \ + images/V3Po15bNErw.jpg diff --git a/doc/qtcreator/images/icons/easing-curve-linear-icon.png b/doc/qtcreator/images/icons/easing-curve-linear-icon.png new file mode 100644 index 00000000000..1e97dccc7ed Binary files /dev/null and b/doc/qtcreator/images/icons/easing-curve-linear-icon.png differ diff --git a/doc/qtcreator/images/icons/easing-curve-spline-icon.png b/doc/qtcreator/images/icons/easing-curve-spline-icon.png new file mode 100644 index 00000000000..3a4bc695fc9 Binary files /dev/null and b/doc/qtcreator/images/icons/easing-curve-spline-icon.png differ diff --git a/doc/qtcreator/images/icons/easing-curve-step-icon.png b/doc/qtcreator/images/icons/easing-curve-step-icon.png new file mode 100644 index 00000000000..ce1ec8917aa Binary files /dev/null and b/doc/qtcreator/images/icons/easing-curve-step-icon.png differ diff --git a/doc/qtcreator/images/icons/lockoff.png b/doc/qtcreator/images/icons/lockoff.png new file mode 100644 index 00000000000..e88792bc6e2 Binary files /dev/null and b/doc/qtcreator/images/icons/lockoff.png differ diff --git a/doc/qtcreator/images/icons/pin.png b/doc/qtcreator/images/icons/pin.png new file mode 100644 index 00000000000..ac65f66815e Binary files /dev/null and b/doc/qtcreator/images/icons/pin.png differ diff --git a/doc/qtcreator/images/studio-curve-editor.png b/doc/qtcreator/images/studio-curve-editor.png index ee44e74cc0a..01cd7f5ab4f 100644 Binary files a/doc/qtcreator/images/studio-curve-editor.png and b/doc/qtcreator/images/studio-curve-editor.png differ diff --git a/doc/qtcreator/images/studio-edit-keyframe.png b/doc/qtcreator/images/studio-edit-keyframe.png index 446187d1414..f2bcc891a58 100644 Binary files a/doc/qtcreator/images/studio-edit-keyframe.png and b/doc/qtcreator/images/studio-edit-keyframe.png differ diff --git a/doc/qtcreator/images/studio-timeline-empty.png b/doc/qtcreator/images/studio-timeline-empty.png new file mode 100644 index 00000000000..861a1021bba Binary files /dev/null and b/doc/qtcreator/images/studio-timeline-empty.png differ diff --git a/doc/qtcreator/images/studio-timeline-keyframe-track-colors.png b/doc/qtcreator/images/studio-timeline-keyframe-track-colors.png new file mode 100644 index 00000000000..3bea1a7a6b0 Binary files /dev/null and b/doc/qtcreator/images/studio-timeline-keyframe-track-colors.png differ diff --git a/doc/qtcreator/images/studio-timeline-no-tracks.png b/doc/qtcreator/images/studio-timeline-no-tracks.png new file mode 100644 index 00000000000..85a03a00b0a Binary files /dev/null and b/doc/qtcreator/images/studio-timeline-no-tracks.png differ diff --git a/doc/qtcreator/images/studio-timeline-settings.png b/doc/qtcreator/images/studio-timeline-settings.png index eefbc561cd9..cd6ed4c8a8b 100644 Binary files a/doc/qtcreator/images/studio-timeline-settings.png and b/doc/qtcreator/images/studio-timeline-settings.png differ diff --git a/doc/qtcreator/images/studio-timeline-with-empty-tracks.png b/doc/qtcreator/images/studio-timeline-with-empty-tracks.png new file mode 100644 index 00000000000..d116d43e366 Binary files /dev/null and b/doc/qtcreator/images/studio-timeline-with-empty-tracks.png differ diff --git a/doc/qtcreator/images/studio-timeline-with-tracks.png b/doc/qtcreator/images/studio-timeline-with-tracks.png new file mode 100644 index 00000000000..060db8aa2bd Binary files /dev/null and b/doc/qtcreator/images/studio-timeline-with-tracks.png differ diff --git a/doc/qtcreator/images/studio-timeline.png b/doc/qtcreator/images/studio-timeline.png index 49557eeaaed..18e85ca5c18 100644 Binary files a/doc/qtcreator/images/studio-timeline.png and b/doc/qtcreator/images/studio-timeline.png differ diff --git a/doc/qtcreator/src/howto/creator-workspaces.qdoc b/doc/qtcreator/src/howto/creator-workspaces.qdoc index 704a221e6b1..20eacc48047 100644 --- a/doc/qtcreator/src/howto/creator-workspaces.qdoc +++ b/doc/qtcreator/src/howto/creator-workspaces.qdoc @@ -26,7 +26,7 @@ /*! \page creator-project-managing-workspaces.html \if defined(qtdesignstudio) - \previouspage creator-using-qt-quick-designer.html + \previouspage qtquick-curve-editor.html \nextpage creator-project-managing-sessions.html \else \previouspage creator-sidebars.html diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 4ea17f3dd78..8bee7c96012 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -97,6 +97,8 @@ \li \l{Navigator} \li \l{Properties} \li \l{Transition Editor} + \li \l{Timeline} + \li \l{Curve Editor} \endlist \li \l {Creating UIs} \list @@ -121,6 +123,9 @@ \li \l {Adding Dynamics} \list \li \l{Creating Animations} + \list + \li \l{Editing Easing Curves} + \endlist \li \l{Adding Connections} \list \li \l{Connecting Objects to Signals} diff --git a/doc/qtcreator/src/qtquick/qtquick-connection-editor.qdoc b/doc/qtcreator/src/qtquick/qtquick-connection-editor.qdoc index 395327e1bce..732ae2beee6 100644 --- a/doc/qtcreator/src/qtquick/qtquick-connection-editor.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-connection-editor.qdoc @@ -24,7 +24,7 @@ ****************************************************************************/ /*! - \previouspage studio-timeline.html + \previouspage qtquick-editing-easing-curves.html \page qmldesigner-connections.html \nextpage quick-signals.html diff --git a/doc/qtcreator/src/qtquick/qtquick-curve-editor.qdoc b/doc/qtcreator/src/qtquick/qtquick-curve-editor.qdoc new file mode 100644 index 00000000000..c56cea247cc --- /dev/null +++ b/doc/qtcreator/src/qtquick/qtquick-curve-editor.qdoc @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +****************************************************************************/ + +/*! + \page qtquick-curve-editor.html + \previouspage qtquick-timeline-view.html + \nextpage creator-project-managing-workspaces.html + + \title Curve Editor + + \uicontrol {Curve Editor} shows the interpolated values of an animated + property over the animation range. + + \image studio-curve-editor.png "Curve Editor" + + When you edit an animation curve, you implicitly edit the + \l{Editing Easing Curves}{easing curves} that the underlying system uses + to define an animation. The animation curve is an extension to visualize + both the value of a keyframe and the interpolation between keyframes + simultaneously. + + You can use the toolbar buttons to add \uicontrol Linear, \uicontrol Step, + or \uicontrol Spline interpolation between two keyframes. + + When you set interpolation to \uicontrol Spline, handles appear in + \uicontrol {Curve Editor} that you can use to modify the curve. Select + \uicontrol Unify to lock the handle on the left of a keyframe to the one + on the right of it so that moving the left handle also moves the right + handle. + + If the component that contains the animated property has been locked + in \l Navigator, you can select \inlineimage icons/lockon.png + to unlock it. You can also lock individual easing curves for editing. + + To lock an animation curve, hover the mouse over the keyframe in the list, + and then select \inlineimage icons/lockoff.png + . + + To pin an animation curve, hover the mouse over the keyframe in the list, + and then select \inlineimage icons/pin.png + . + + \section1 Curve Editor Toolbar + + The \uicontrol {Curve Editor} toolbar contains the following buttons and + fields. + + \table + \header + \li Button/Field + \li Action + \row + \li \inlineimage icons/easing-curve-linear-icon.png + \li \uicontrol Linear specifies that the interpolation between + keyframes is linear. + \row + \li \inlineimage icons/easing-curve-step-icon.png + \li \uicontrol Step uses steps for interpolation between keyframes. + \row + \li \inlineimage icons/easing-curve-spline-icon.png + \li \uicontrol Spline uses bezier spline curves for interpolation + between keyframes and displays handles for managing them. + \row + \li \uicontrol {Set Default} + \li Currently not used. + \row + \li \uicontrol Unify + \li For \uicontrol Spline curves, locks the handle on the left of a + keyframe to the one on the right. + \row + \li Start Frame + \li Specifies the first frame of the curve. + \row + \li End Frame + \li Specifies the last frame of the curve. + \row + \li Current Frame + \li Displays the frame that the playhead is currently on. Enter a + number in the field to move the playhead to the respective frame. + \endtable + + \section1 Editing Animation Curves + + To edit animation curves: + + \list 1 + \li In the \l Timeline view, animate at least one property value by + \l{Managing Keyframes}{inserting keyframes} for it. + \li Select \uicontrol View > \uicontrol Views > + \uicontrol {Curve Editor} to open the animation curve editor. + \li Right-click in \uicontrol {Curve Editor}, and select + \uicontrol {Insert Keyframe} to add a keyframe. + \li Select keyframes to display the easing curves attached to them. + To select multiple keyframes, press and hold \key Ctrl. + \endlist + + Your changes are automatically saved when you close the view. + + \section1 Deleting Keyframes in Curve Editor + + To delete the selected keyframe, select \uicontrol {Delete All Keyframes} + in the context menu. +*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-designer.qdoc b/doc/qtcreator/src/qtquick/qtquick-designer.qdoc index 43966d926c9..cab0701dfd5 100644 --- a/doc/qtcreator/src/qtquick/qtquick-designer.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-designer.qdoc @@ -106,16 +106,15 @@ the changes between states. \li \l{Animating Transitions Between States} \row - \li \l{Creating Animations}{Timeline} + \li \l Timeline \li Provides a timeline and keyframe based editor for animating the properties of components. \li \l{Creating Animations} \row - \li \l{Editing Animation Curves}{Curve Editor} + \li \l{Curve Editor} \li Enables you to view and modify the whole animation curve by inserting keyframes to the curve and dragging them and the point - handlers to modify the curve. You can modify the appearance of - the curve in the style editor. + handlers to modify the curve. \li \l {Editing Animation Curves} \row \li \l{Working in Edit Mode}{Text Editor} diff --git a/doc/qtcreator/src/qtquick/qtquick-easing-curve-editor.qdoc b/doc/qtcreator/src/qtquick/qtquick-easing-curve-editor.qdoc new file mode 100644 index 00000000000..04e03ac5a0b --- /dev/null +++ b/doc/qtcreator/src/qtquick/qtquick-easing-curve-editor.qdoc @@ -0,0 +1,106 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +****************************************************************************/ + +/*! + \page qtquick-editing-easing-curves.html + \previouspage studio-timeline.html + \nextpage qmldesigner-connections.html + + \title Editing Easing Curves + + You can use \uicontrol {Easing Curve Editor} to edit the easing curve + between two keyframes. + + \image studio-easing-curve-editor.png "Easing Curve Editor" + + You can use the preset curves or modify them by dragging the curve handles + around. You can add points to the curve and drag them and the point handles + to modify the curve. When you are happy with the curve, you can save it as + a custom curve. For more information about easing curve types, see the + technical documentation for \l [QML] {PropertyAnimation}{easing curves}. + + To zoom into and out of the easing curve editor, use the mouse + roller. To reset the zoom factor, right-click in the picker and + select \uicontrol {Reset Zoom}. + + You can also use the more advanced \l {Curve Editor} that + shows the interpolated values of an animated property over + the \l{Creating Animations}{animation} range. + + The animation curves present a more readable view of the animation by + showing the effective values of the animated properties over the animation + range. In order to do so, they need to be converted to and from easing + curves. This comes with the following side effects: + + \list + \li Interpolation between identical current and previous keyframe values + is meaningless regardless of what the easing curve looks like. + \li Some easing curves are not trivially mappable to animation curves + and are therefore painted in a different color and without handles. + \endlist + + \section1 Attaching Easing Curves to Keyframes + + To attach easing curves to keyframes: + + \list 1 + \li Right-click a keyframe in \l Timeline and select + \uicontrol {Easing Curve Editor} in the context menu. + \li Select an easing curve in the \uicontrol Presets tab. + \li In the \uicontrol {Duration (ms)} field, select the + duration of the easing function in milliseconds. + \li Select \uicontrol Preview to preview the curve. + \li Select \uicontrol OK to attach the easing curve to the + keyframe, close \uicontrol {Easing Curve Editor}, and + return to \l Timeline. + \endlist + + When you attach easing curves to keyframes, the shape of the + \l{keyframe_marker}{keyframe marker} on a keyframe track in + \l Timeline changes from \inlineimage keyframe_linear_inactive.png + to a marker that describes the type of the selected easing curve. + + \section1 Customizing Easing Curves + + To customize easing curves: + + \list 1 + \li In \uicontrol {Easing Curve Editor}, select an easing curve in + the \uicontrol Presets tab. + \li Drag the curve handles to modify the curve. + \li Right-click in the editor, and select \uicontrol {Add Point} to add + points to the curve. + \li Drag the points or the point handles to modify the curve. If the + curve becomes invalid, it turns red in the editor and the + \uicontrol Save button is disabled. + \li Select \uicontrol Save to save your changes to the curve. + \li In the \uicontrol Name field, enter a name for the custom curve, + and then select \uicontrol OK to save the curve in the + \uicontrol Custom tab. + \endlist + + To paste easing curve definitions to \uicontrol {Easing Curve Editor} as + text, select the \uicontrol Text tab. +*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-timeline-view.qdoc b/doc/qtcreator/src/qtquick/qtquick-timeline-view.qdoc new file mode 100644 index 00000000000..a9fd2855058 --- /dev/null +++ b/doc/qtcreator/src/qtquick/qtquick-timeline-view.qdoc @@ -0,0 +1,281 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Creator documentation. +** +** 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. +** +****************************************************************************/ + +/*! + \page qtquick-timeline-view.html + \previouspage qtquick-transition-editor.html + \nextpage qtquick-curve-editor.html + + \title Timeline + + You can use the timeline and keyframe based editor in the + \uicontrol Timeline view to animate the properties of + \l{glossary_component}{components}. The view is empty until + you create a timeline. + + \image studio-timeline-empty.png "Empty Timeline view" + + Select the \inlineimage plus.png + (\uicontrol {Add Timeline (A)}) button, or press \key {A} to + \l{Creating Timelines}{create a timeline} and specify settings + for it in the \uicontrol {Timeline Settings} dialog. + + \image studio-timeline-settings.png "Timeline Settings dialog" + + When you select \uicontrol Close, the \uicontrol Timeline view appears. + It now displays a \l{Timeline Toolbar}{toolbar} and a ruler but no + keyframe tracks. + + \image studio-timeline-no-tracks.png "Timeline view without keyframe tracks" + + To animate component properties in the \uicontrol Timeline view, you + must \l{Setting Keyframe Values}{insert keyframes} for them. In the + \l Properties view, select \uicontrol Settings > + \uicontrol {Insert Keyframe} for a property that you want to animate. + A keyframe track is generated for each component that you insert keyframes + for. + + \image studio-timeline-with-empty-tracks.png "Timeline view with a property" + + You can now select \inlineimage local_record_keyframes.png + to \l{Setting Keyframe Values}{record changes} in component properties + while you \l{Navigating in Timeline}{navigate the timeline}. + + The following video shows how to insert keyframes for component properties + and to animate them in \uicontrol Timeline: + + \youtube V3Po15bNErw + + \if defined(qtdesignstudio) + To try it yourself, follow the \l{Log In UI - Part 4} tutorial. + \endif + + + For more information about creating timeline animations, see + \l{Creating Animations}. + + \section1 Navigating in Timeline + + \image studio-timeline.png "Timeline view" + + You can navigate the timeline in the following ways: + + \list + \li Drag the playhead (1) to a frame. + \li Click on the ruler (2) to move to a frame. + \li Select the \uicontrol {To Start (Home)}, \uicontrol {Previous (,)}, + \uicontrol {Next (.)}, or \uicontrol {To End (End)} buttons (3), or + use the keyboard shortcuts to move to the first, previous, next, or + last frame on the timeline. + \li Enter the number of a frame in the current keyframe field (4) to + move to that frame. + \li Select the \uicontrol Previous and \uicontrol Next buttons next to + a property name on the timeline (5) to move to the previous or next + keyframe for that property. + \endlist + + \section1 Zooming in Timeline + + Use the slider on the toolbar to set the zooming level in the + \uicontrol Timeline view. Select the \inlineimage zoom_small.png + and \inlineimage zoom_big.png + buttons to zoom out of or into the view. + + \section1 Setting Keyframe Track Color + + To change the color of a keyframe track, select \uicontrol {Override Color} + in the context menu, and then select a color in the \l{Picking Colors} + {color picker}. To reset the color, select \uicontrol {Reset Color}. + + \image studio-timeline-keyframe-track-colors.png "Keyframe track colors in Timeline" + + \section1 Timeline Toolbar + + The \uicontrol Timeline toolbar contains the following buttons and fields. + + \table + \header + \li Button/Field + \li Action + \li Read More + \row + \li \inlineimage animation.png + \li Opens the \uicontrol {Timeline Settings} dialog for editing + timeline settings. + \li \l{Creating Timelines} + \row + \li Timeline ID + \li Displays the ID of the current timeline. + \li \l{Creating Timelines} + \row + \li \inlineimage to_first_frame.png + \li \uicontrol {To Start (Home)} moves to the first frame on the + timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage back_one_frame.png + \li \uicontrol {Previous (,)} moves to the previous frame on the + timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage start_playback.png + \li \uicontrol {Play (Space)} previews the animation. + \li \l{Viewing the Animation} + \row + \li \inlineimage forward_one_frame.png + \li \uicontrol {Next (.)} moves to the next frame on the timeline. + \li \l{Navigating in Timeline} + \row + \li \inlineimage to_last_frame.png + \li \uicontrol {To End (End)} moves to the last frame on the timeline. + \li \l{Navigating in Timeline} + \row + \li Current Keyframe + \li Displays the frame that the playhead is currently on. Enter a + number in the field to move the playhead to the respective frame. + \li \l{Navigating in Timeline} + \row + \li \inlineimage global_record_keyframes.png + \li Records changes in keyframe values. + \li \l {Setting Keyframe Values} + \row + \li \inlineimage curve_editor.png + \li Opens \uicontrol {Easing Curve Editor} for attaching an easing + curve to the selected transition. + \li \l{Editing Easing Curves} + \row + \li Start Frame + \li Specifies the first frame of the timeline. Negative values are + allowed. The difference between the start frame and the end frame + determines the duration of the animation. + \li \l{Creating Timelines} + \row + \li \inlineimage zoom_small.png + \li \uicontrol {Zoom Out} (\key Ctrl+-) zooms out of the view. + \li \l{Zooming in Timeline} + \row + \li Slider + \li Sets the zooming level. + \li \l{Zooming in Timeline} + \row + \li \inlineimage zoom_big.png + \li \uicontrol {Zoom In} (\key Ctrl++) zooms into the view. + \li \l{Zooming in Timeline} + \row + \li End Frame + \li Specifies the last frame of the timeline. The difference between + the start frame and the end frame determines the duration of the + animation, so if the start frame is 0, the end frame equals the + duration. + \li \l{Creating Timelines} + \row + \li State Name + \li Displays the name of the current state. + \li \l{Binding Animations to States} + \endtable + + \section1 Keyframe Track Icons + + Each keyframe track can contain the following buttons and markers. + + \table + \header + \li Button/Icon + \li Action + \li Read More + \row + \li \inlineimage previous_keyframe.png + \li Jumps to the previous frame on the timeline. + \li \l{Setting Keyframe Values} + \row + \li \inlineimage next_keyframe.png + \li Jumps to the next frame on the timeline. + \li \l{Setting Keyframe Values} + \row + \li \inlineimage local_record_keyframes.png + \li Records changes in keyframe values for a particular property. + \li \l {Setting Keyframe Values} + \target keyframe_marker + \row + \li \inlineimage keyframe.png + \li Indicates the type of easing curve attached to the keyframe. + When a keyframe track is selected, the keyframe markers on it turn + gray, and when a keyframe itself is selected, its marker turns + brown: + \list + \li \inlineimage keyframe_linear_inactive.png + - linear easing curve + \li \inlineimage keyframe_manualbezier_inactive.png + - manually set Bezier curve + \li \inlineimage keyframe_autobezier_inactive.png + - automatically set Bezier curve + \li \inlineimage keyframe_lineartobezier_inactive.png + - linear-to-Bezier curve + \endlist + \li \l {Editing Easing Curves} + \endtable + + \section1 Timeline Context Menu + + The following table summarizes the context menu items available for each + keyframe track for a component, property, or keyframe marker and provides + links to more information about them. + + \table + \header + \li To Learn About + \li Go To + \row + \li Delete All Keyframes + \li \l{Deleting Keyframes} + \row + \li Add Keyframes at Current Frame + \li \l{Setting Keyframe Values} + \row + \li Copy All Keyframes + \li \l{Copying Keyframes} + \row + \li Paste Keyframes + \li \l{Copying Keyframes} + \row + \li Remove Property + \li \l{Setting Keyframe Values} + \row + \li Delete Keyframe + \li \l{Deleting Keyframes} + \row + \li Edit Easing Curve + \li \l{Editing Easing Curves} + \row + \li Edit Keyframe + \li \l{Editing Keyframe Values} + \row + \li Override Color + \li \l{Setting Keyframe Track Color} + \row + \li Reset Color + \li \l{Setting Keyframe Track Color} + \endtable +*/ diff --git a/doc/qtcreator/src/qtquick/qtquick-timeline.qdoc b/doc/qtcreator/src/qtquick/qtquick-timeline.qdoc index dca62b7fc98..418a68cad63 100644 --- a/doc/qtcreator/src/qtquick/qtquick-timeline.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-timeline.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. +** Copyright (C) 2021 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Creator documentation. @@ -30,21 +30,39 @@ \title Creating Animations - You can use the timeline and keyframe based editor in the - \uicontrol Timeline view to animate the properties of UI components. + Animation is based on \e keyframes. In \QC, keyframes determine the value + of the property of a \l{glossary_component}{component} at a certain time. Animating properties enables their values to move through intermediate - values instead of immediately changing to the target value. For example, - to move an item in a scene, you can animate the properties that control - the item's position, x and y, so that the item's position changes at - keyframes on the way to the target position. Similarly, you could change - the color and scale properties of the item at keyframes to make it appear - to move closer or farther away. + values instead of immediately changing to the target value. - Qt Quick allows you to declare various UI states in \l State objects. - These states are comprised of property changes from a base state, and - can be a useful way of organizing your UI logic. Transitions are objects - you can associate with an item to define how its properties will animate - when they change due to a state change. + For example, you can set the y position property of a rectangle to 0 at the + start of your animation and to 100 at the end of the animation. When the + animation is run, the rectangle moves from position 0 to 100 on the y axis. + In the middle of the animation, the y property has the value of 50 since + keyframes are interpolated linearly by default. + + Sometimes you don't want linear movement but would rather like the rectangle + to move faster at the beginning and slower at the end of the animation. + To achieve this effect, you could insert a lot keyframes between the start + frame and the end frame. To avoid this effort, you can use the + \l{Editing Easing Curves}{Easing Curve Editor} to specify \e {easing curves} + for nonlinear interpolation between keyframes. The easing curves can make + components appear to pick up speed, slow down, or bounce back at the end of + the animation. + + While easing curves work well for most simple UI animations, more complex + 3D animations require several keyframes so it becomes necessary to visualize + the value and the interpolation of a keyframe simultaneously. The + \l {Curve Editor} visualizes the whole animation of a property at once and + shows the effective values of a keyframe together with the interpolation + between keyframes. It can also show animations of different properties + simultaneously so that you can see the animation for the x position + side-by-side with the animation of the y position. + + You can declare various UI states as \l{Adding States}{states}, which + are specified as changes from a base state and can be a useful way of + organizing your UI logic. You can \l{Binding Animations to States} + {bind animations to states} to run an animation when a state is applied. Each component in a scene or a project can have its own timeline and its own set of states. We recommend that you place your timelines inside the @@ -55,9 +73,10 @@ timelines to your components will increase the file size and runtime memory requirements of your UI. - You can find a video tutorial about creating timelines and adding keyframes - \l{https://resources.qt.io/development-topic-ui-design/qtdesignstudio-clustertutorial-parttwo} - {here}. + The following video shows how to animate component properties using the + timeline and keyframe based editor in the \l Timeline view: + + \youtube V3Po15bNErw \if defined(qtcreator) To be able to create timelines, you also need the \l {Qt Quick Timeline} @@ -76,26 +95,28 @@ To create a timeline to animate a UI component: \list 1 - \li In the \uicontrol Navigator, select the item to animate. - \li In the \uicontrol Timeline view, select the \inlineimage plus.png + \li In the \l Timeline view, select the \inlineimage plus.png (\uicontrol {Add Timeline (A)}) button, or press \key {A} to specify settings for the timeline and running the animation in the \uicontrol {Timeline Settings} dialog. - \li In the \uicontrol {Timeline ID} field, enter a name that describes - the animated item. - \li In the \uicontrol {End frame} field, set the duration of the - animation. + \li In the \uicontrol {Timeline ID} field, enter an ID that describes + the animated component. + \li In the \uicontrol {Start frame} field, set the first frame of the + timeline. Negative values are allowed. + \li In the \uicontrol {End frame} field, set the last frame of the + timeline. \li To use bindings to specify the properties, select the \uicontrol {Expression binding} radio button and enter the binding in the \uicontrol {Expression binding} field. For more information about property binding, see \l{Setting Bindings}. \li To create a timeline animation, select the \uicontrol Animation radio button. - \li In the \uicontrol timelineAnimation tab, \uicontrol {Animation ID} - field, enter a name for the animation. - \li Select the \uicontrol {Running in Base State} check box to use the - settings in this tab when previewing the UI. Deselect the check box - to use the default settings. + \li In the \uicontrol {Animation ID} field, enter an ID for the + animation. + \li Select the \uicontrol {Running in Base State} check box to run the + animation when the base state is applied. Deselect the check box + if you want to run the animation when some other state is applied. + For more information, see \l{Binding Animations to States}. \li In the \uicontrol {Start frame} field, set the first frame of the animation. \li In the \uicontrol {End frame} field, set the last frame of the @@ -111,25 +132,26 @@ means that you must restart the animation to see it again \li Select the \uicontrol {Ping pong} check box to play the animation backwards back to the beginning when it reaches the end. - \li In the \uicontrol {Transitions to states} field, select the state - to switch to when the animation finishes. + \li In the \uicontrol Finished field, select the state + to apply when the animation finishes. \li Select \uicontrol Close to close the dialog and save the settings. \endlist To create additional timelines, select the \inlineimage plus.png - (\uicontrol {Add Timeline}) button next to the \uicontrol timeline tab. + (\uicontrol {Add Timeline}) button next to the + \uicontrol {Timeline Settings} tab. - To specify settings for running the timeline animations, select the + To specify settings for running timeline animations, select the \inlineimage plus.png (\uicontrol {Add Animation}) button next to the - \uicontrol {Animation Settings} group. For example, you could create + \uicontrol {Animation Settings} tab. For example, you could create settings for running a part of the timeline animation between specified frames or for running the animation backwards from the last frame to the first. To modify the settings, select the \inlineimage animation.png - (\uicontrol {Timeline Settings (S)}) button on the toolbar - (or press \key S) in the \uicontrol Timeline view. + (\uicontrol {Timeline Settings (S)}) button on the \l{Timeline Toolbar} + {toolbar} (or press \key S) in the \l Timeline view. \section2 Binding Animations to States @@ -141,38 +163,21 @@ \section1 Managing Keyframes - To animate components in the \uicontrol Timeline view, move to a frame + To animate components in the \l Timeline view, move to a frame on the timeline and specify changes in the values of a property. \QC - automatically adds keyframes between two keyframes, and sets their values + automatically adds keyframes between two keyframes and sets their values evenly to create an appearance of movement or transformation. - \section2 Navigating the Timeline - - \image studio-timeline.png "Timeline view" - - You can navigate the timeline in the following ways: - - \list - \li Drag the playhead (1) to a frame. - \li Click on the ruler (2) to move to a frame. - \li Select the \uicontrol {To Start (Home)}, \uicontrol {Previous (,)}, - or \uicontrol {Next (.)} buttons (3), or use the keyboard shortcuts - to move to the first, previous, or next frame on the timeline. - \li Enter the number of a frame in the current keyframe field (4) to - move to that frame. - \li Select the \uicontrol Previous and \uicontrol Next buttons next to - a property name on the timeline (5) to move to the previous or next - keyframe for that property. - \endlist + \image studio-timeline-with-tracks.png "Timeline view" \section2 Setting Keyframe Values You can insert keyframes for all the properties of all the components that you want to animate first, and then record the changes in their values by - selecting the \inlineimage recordfill.png + selecting the \inlineimage local_record_keyframes.png (\uicontrol {Per Property Recording}) button for one property at a time. - For example, you can hide and show items by turning their visibility off and - on or by setting their opacity to 0 or 1. + For example, you can hide and show components by turning their visibility + off and on or by setting their opacity to 0 or 1. You can also select the \uicontrol {Auto Key (K)} button (or press \key K) to record changes in property values, but you need to be more careful about @@ -181,17 +186,19 @@ To record the changes of property values: \list 1 - \li In the \uicontrol Navigator, select the item to animate. - \li In the \uicontrol Properties view, select \uicontrol Settings > + \li In the \l Navigator view, select the component to animate. + \li In the \l Properties view, select \uicontrol Settings > \uicontrol {Insert Keyframe} for the property that you want to animate. - \li Select the \uicontrol {Per Property Recording} button to start - recording property changes. + \li In the \l Timeline view, select the + \uicontrol {Per Property Recording} button + to start recording property changes. \li Check that the playhead is in frame 0 and enter the value of the property in the field next to the property name on the timeline. Press \key Enter to save the value. \li Move the playhead to another frame on the timeline and specify - the value at that frame. + the value at that frame. For more information, see + \l{Navigating in Timeline}. \li When you have specified as many values as you need, select \uicontrol {Per Property Recording} again to stop recording. \endlist @@ -199,32 +206,42 @@ To remove all the changes you recorded for a property, right-click the property name on the timeline and select \uicontrol {Remove Property}. - Keyframes are marked on the timeline by using markers of different colors and - shapes, depending on whether they are active or inactive or whether you have - applied easing curves to them, for example. + To add keyframes to the keyframe track of a component at the current + position of the playhead, select \uicontrol {Add Keyframes at Current Frame}. - To edit the value of a keyframe, double-click a keyframe marker or select - \uicontrol {Edit Keyframe} in the context menu. In the \uicontrol Frame - field, you can set the frame and the value: + Keyframes are marked on the timeline by using \l{keyframe_marker}{markers} + of different colors and shapes, depending on whether they are active or + inactive or whether you have applied \l{Editing Easing Curves} + {easing curves} to them. + + \section2 Editing Keyframe Values + + To fine-tune the value of a keyframe, double-click a keyframe marker or + select \uicontrol {Edit Keyframe} in the context menu. + + The \uicontrol {Edit Keyframe} dialog displays the name of the property + you are animating and its current value at the frame specified in the + \uicontrol Frame field. You can change both the keyframe and its value. \image studio-edit-keyframe.png "Edit Keyframe dialog" - You can copy the keyframes from the keyframe track for an item and - paste them to the keyframe track of another item. To copy all - keyframes from one item to another one, select an item, and then - select \uicontrol {Copy All Keyframes} in the context menu. Then - select the other item and select \uicontrol {Paste Keyframes} in - the context menu. + \section2 Copying Keyframes + + You can copy the keyframes from the keyframe track for a component and + paste them to the keyframe track of another component. To copy all + keyframes from one track to another one, first right-click the component ID + and select \uicontrol {Copy All Keyframes} in the context menu. + Then right-click the other component ID, and select + \uicontrol {Paste Keyframes} in the context menu. + + \section2 Deleting Keyframes To delete the selected keyframe, select \uicontrol {Delete Keyframe} in the context menu. - To delete all keyframes from the selected item, select + To delete all keyframes from the selected component, select \uicontrol {Delete All Keyframes} in the context menu. - To add keyframes to the keyframe track of an item at the current position - of the playhead select \uicontrol {Add Keyframes at Current Frame}. - \section1 Viewing the Animation You can view the animation on the canvas by moving the playhead along the @@ -236,109 +253,11 @@ (\uicontrol {Show Live Preview}) button on the canvas toolbar or press \key {Alt+P}. - \section1 Editing Easing Curves - - \e Easing specifies the rate of a property value over time, so that - components can appear to pick up speed, slow down, or bounce back at the - end of the animation. By default, the animations you specify on the - timeline are \e linear, which means that they move from the beginning to - the end at a constant speed. You can use the \uicontrol {Easing Curve Editor} - to edit the easing curve between two keyframes. You can also use the more - advanced \uicontrol {Curve Editor} to edit the curves for the whole - animation. - - \section2 Attaching Easing Curves to Keyframes - - \image studio-easing-curve-editor.png "Easing Curve Editor" - - You can use the preset curves or modify them by dragging the curve handlers - around. You can add points to the curve and drag them and the point handlers - to modify the curve. When you are happy with the curve, you can save it as a - custom curve. For more information about easing curve types, see the - documentation for \l [QML] {PropertyAnimation}{easing curves}. - - To zoom into and out of the easing curve editor, use the mouse roller. To - reset the zoom factor, right-click in the picker and select - \uicontrol {Reset Zoom}. - - To attach easing curves to keyframes: - - \list 1 - \li Right-click a keyframe on the timeline and select - \uicontrol {Easing Curve Editor} in the context menu. - \li Select an easing curve in the \uicontrol Presets tab. - \li In the \uicontrol {Duration (ms)} field, select the duration of the - easing function in milliseconds. - \li Select \uicontrol Preview to preview the curve. - \li Select \uicontrol OK to attach the easing curve to the keyframe - and to close the easing curve editor. - \endlist - - When you attach easing curves to keyframes, the shape of the keyframe - marker changes from \inlineimage keyframe_linear_inactive.png - to \inlineimage keyframe_manualbezier_inactive.png - . - - \section2 Customizing Easing Curves - - To customize easing curves: - - \list 1 - \li In \uicontrol {Easing Curve Editor}, select an easing curve in - the \uicontrol Presets tab. - \li Drag the curve handlers to modify the curve. - \li Right-click in the editor, and select \uicontrol {Add Point} to add - points to the curve. - \li Drag the points or the point handlers to modify the curve. If the - curve becomes invalid, it turns red in the editor and the - \uicontrol Save button is disabled. - \li Select \uicontrol Save to save your changes to the curve. - \li In the \uicontrol Name field, enter a name for the custom curve, - and then select \uicontrol OK to save the curve in the - \uicontrol Custom tab. - \endlist - - To paste easing curve definitions to \uicontrol {Easing Curve Editor} as - text, select the \uicontrol Text tab. - - \section1 Editing Animation Curves - - In \uicontrol {Curve Editor}, you can view and modify the whole animation - curve. You can insert keyframes to the curve and drag them and the point - handlers to modify the curve. You can modify the appearance of the curve - in the style editor. - - You can also edit easing curves that you added in - \uicontrol {Easing Curve Editor}. If the item that - contains the easing curves has been locked in - \uicontrol Navigator, you can select \inlineimage icons/lockon.png - to unlock it. You can also lock individual easing curves for editing. - - \image studio-curve-editor.png "Curve Editor" - - To edit animation curves: - - \list 1 - \li In the \uicontrol Timeline view, insert at least one keyframe. - \li Select \uicontrol View > \uicontrol Views > - \uicontrol {Curve Editor} to open the animation curve editor. - \li Right-click in the animation curve editor, and select - \uicontrol {Insert Keyframe} to add a keyframe. - \li Select keyframes to display the easing curves attached to them. - To select multiple keyframes, press and hold \key Ctrl. - \li To lock an easing curve, hover the mouse over the keyframe in the - list, and then select the lock icon. - \li To pin an easing curve, hover the mouse over the keyframe in the - list, and then select the pin icon. - \endlist - - Your changes are automatically saved when you close the view. - - \section1 Rotating Items + \section1 Animating Rotation To animate components that rotate around a central point, you can use the - \l {basic-item}{Item} QML type as a parent for the rotating component. Then - create a timeline for the Item and set the rotation property for the start + \l {basic-item}{Item} component as a parent for the rotating component. Then + create a timeline for the Item, and set the rotation property for the start and end keyframes. \if defined(qtdesignstudio) diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index 3fad0989341..fd69a3c30bb 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -63,6 +63,8 @@ \li \l{Navigator} \li \l{Properties} \li \l{Transition Editor} + \li \l{Timeline} + \li \l{Curve Editor} \endlist \li \l{Managing Workspaces} \li \l{Managing Sessions} @@ -110,6 +112,9 @@ \li \l {Adding Dynamics} \list \li \l{Creating Animations} + \list + \li \l{Editing Easing Curves} + \endlist \li \l{Adding Connections} \list \li\l{Connecting Objects to Signals}