1/****************************************************************************
2**
3** Copyright (C) 2021 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the Qt Creator documentation.
7**
8** Commercial License Usage
9** Licensees holding valid commercial Qt licenses may use this file in
10** accordance with the commercial license agreement provided with the
11** Software or, alternatively, in accordance with the terms contained in
12** a written agreement between you and The Qt Company. For licensing terms
13** and conditions see https://www.qt.io/terms-conditions. For further
14** information use the contact form at https://www.qt.io/contact-us.
15**
16** GNU Free Documentation License Usage
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of
20** this file. Please review the following information to ensure
21** the GNU Free Documentation License version 1.3 requirements
22** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
23**
24****************************************************************************/
25
26/*!
27    \page qtquick-timeline-view.html
28    \previouspage qtquick-transition-editor.html
29    \nextpage qtquick-curve-editor.html
30
31    \title Timeline
32
33    You can use the timeline and keyframe based editor in the
34    \uicontrol Timeline view to animate the properties of
35    \l{glossary_component}{components}. The view is empty until
36    you create a timeline.
37
38    \image studio-timeline-empty.png "Empty Timeline view"
39
40    Select the \inlineimage plus.png
41    (\uicontrol {Add Timeline}) button to \l{Creating Timelines}
42    {create a timeline} and specify settings for it in the
43    \uicontrol {Timeline Settings} dialog.
44
45    \image studio-timeline-settings.png "Timeline Settings dialog"
46
47    When you select \uicontrol Close, the \uicontrol Timeline view appears.
48    It now displays a \l{Timeline Toolbar}{toolbar} and a ruler but no
49    keyframe tracks.
50
51    \image studio-timeline-no-tracks.png "Timeline view without keyframe tracks"
52
53    To animate component properties in the \uicontrol Timeline view, you
54    must \l{Setting Keyframe Values}{insert keyframes} for them. In the
55    \l Properties view, select \inlineimage icons/action-icon.png
56    (\uicontrol Actions) > \uicontrol {Insert Keyframe} for a property that you
57    want to animate. A keyframe track is generated for each component that you
58    insert keyframes for.
59
60    \image studio-timeline-with-empty-tracks.png "Timeline view with a property"
61
62    You can now select \inlineimage local_record_keyframes.png
63    to \l{Setting Keyframe Values}{record changes} in component properties
64    while you \l{Navigating in Timeline}{navigate the timeline}.
65
66    The following video shows how to insert keyframes for component properties
67    and to animate them in \uicontrol Timeline:
68
69    \youtube V3Po15bNErw
70
71    \if defined(qtdesignstudio)
72    To try it yourself, follow the \l{Log In UI - Timeline} tutorial.
73    \endif
74
75
76    For more information about creating timeline animations, see
77    \l{Creating Timeline Animations}.
78
79    \section1 Navigating in Timeline
80
81    \image studio-timeline.png "Timeline view"
82
83    You can navigate the timeline in the following ways:
84
85    \list
86        \li Drag the playhead (1) to a frame.
87        \li Click on the ruler (2) to move to a frame.
88        \li Select the \uicontrol {To Start (Home)}, \uicontrol {Previous (,)},
89            \uicontrol {Next (.)}, or \uicontrol {To End (End)} buttons (3), or
90            use the keyboard shortcuts to move to the first, previous, next, or
91            last frame on the timeline.
92        \li Enter the number of a frame in the current keyframe field (4) to
93            move to that frame.
94        \li Select the \uicontrol Previous and \uicontrol Next buttons next to
95            a property name on the timeline (5) to move to the previous or next
96            keyframe for that property.
97    \endlist
98
99    \section1 Zooming in Timeline
100
101    Use the slider on the toolbar to set the zooming level in the
102    \uicontrol Timeline view. Select the \inlineimage zoom_small.png
103    and \inlineimage zoom_big.png
104    buttons to zoom out of or into the view.
105
106    \section1 Setting Keyframe Track Color
107
108    To change the color of a keyframe track, select \uicontrol {Override Color}
109    in the context menu, and then select a color in the \l{Picking Colors}
110    {color picker}. To reset the color, select \uicontrol {Reset Color}.
111
112    \image studio-timeline-keyframe-track-colors.png "Keyframe track colors in Timeline"
113
114    \section1 Timeline Toolbar
115
116    The \uicontrol Timeline toolbar contains the following buttons and fields.
117
118    \table
119    \header
120        \li Button/Field
121        \li Action
122        \li Read More
123    \row
124        \li \inlineimage animation.png
125        \li Opens the \uicontrol {Timeline Settings} dialog for editing
126            timeline settings.
127        \li \l{Creating Timelines}
128    \row
129        \li Timeline ID
130        \li Displays the ID of the current timeline.
131        \li \l{Creating Timelines}
132    \row
133        \li \inlineimage to_first_frame.png
134        \li \uicontrol {To Start (Home)} moves to the first frame on the
135            timeline.
136        \li \l{Navigating in Timeline}
137    \row
138        \li \inlineimage back_one_frame.png
139        \li \uicontrol {Previous (,)} moves to the previous frame on the
140            timeline.
141        \li \l{Navigating in Timeline}
142    \row
143        \li \inlineimage start_playback.png
144        \li \uicontrol {Play (Space)} previews the animation.
145        \li \l{Viewing the Animation}
146    \row
147        \li \inlineimage forward_one_frame.png
148        \li \uicontrol {Next (.)} moves to the next frame on the timeline.
149        \li \l{Navigating in Timeline}
150    \row
151        \li \inlineimage to_last_frame.png
152        \li \uicontrol {To End (End)} moves to the last frame on the timeline.
153        \li \l{Navigating in Timeline}
154    \row
155        \li Current Keyframe
156        \li Displays the frame that the playhead is currently on. Enter a
157            number in the field to move the playhead to the respective frame.
158        \li \l{Navigating in Timeline}
159    \row
160        \li \inlineimage global_record_keyframes.png
161        \li Records changes in keyframe values.
162        \li \l {Setting Keyframe Values}
163    \row
164        \li \inlineimage curve_editor.png
165        \li Opens \uicontrol {Easing Curve Editor} for attaching an easing
166            curve to the selected transition.
167        \li \l{Editing Easing Curves}
168    \row
169        \li Start Frame
170        \li Specifies the first frame of the timeline. Negative values are
171            allowed. The difference between the start frame and the end frame
172            determines the duration of the animation.
173        \li \l{Creating Timelines}
174    \row
175        \li \inlineimage zoom_small.png
176        \li \uicontrol {Zoom Out} (\key Ctrl+-) zooms out of the view.
177        \li \l{Zooming in Timeline}
178    \row
179        \li Slider
180        \li Sets the zooming level.
181        \li \l{Zooming in Timeline}
182    \row
183        \li \inlineimage zoom_big.png
184        \li \uicontrol {Zoom In} (\key Ctrl++) zooms into the view.
185        \li \l{Zooming in Timeline}
186    \row
187        \li End Frame
188        \li Specifies the last frame of the timeline. The difference between
189            the start frame and the end frame determines the duration of the
190            animation, so if the start frame is 0, the end frame equals the
191            duration.
192        \li \l{Creating Timelines}
193    \row
194        \li State Name
195        \li Displays the name of the current state.
196        \li \l{Binding Animations to States}
197    \endtable
198
199    \section1 Keyframe Track Icons
200
201    Each keyframe track can contain the following buttons and markers.
202
203    \table
204    \header
205        \li Button/Icon
206        \li Action
207        \li Read More
208    \row
209        \li \inlineimage previous_keyframe.png
210        \li Jumps to the previous frame on the timeline.
211        \li \l{Setting Keyframe Values}
212    \row
213        \li \inlineimage next_keyframe.png
214        \li Jumps to the next frame on the timeline.
215        \li \l{Setting Keyframe Values}
216    \row
217        \li \inlineimage local_record_keyframes.png
218        \li Records changes in keyframe values for a particular property.
219        \li \l {Setting Keyframe Values}
220    \target keyframe_marker
221    \row
222        \li \inlineimage keyframe.png
223        \li Indicates the type of easing curve attached to the keyframe.
224            When a keyframe track is selected, the keyframe markers on it turn
225            gray, and when a keyframe itself is selected, its marker turns
226            brown:
227            \list
228                \li \inlineimage keyframe_linear_inactive.png
229                    - linear easing curve
230                \li \inlineimage keyframe_manualbezier_inactive.png
231                    - manually set Bezier curve
232                \li \inlineimage keyframe_autobezier_inactive.png
233                    - automatically set Bezier curve
234                \li \inlineimage keyframe_lineartobezier_inactive.png
235                    - linear-to-Bezier curve
236            \endlist
237        \li \l {Editing Easing Curves}
238    \endtable
239
240    \section1 Timeline Context Menu
241
242    The following table summarizes the context menu items available for each
243    keyframe track for a component, property, or keyframe marker and provides
244    links to more information about them.
245
246    \table
247    \header
248        \li To Learn About
249        \li Go To
250    \row
251        \li Delete All Keyframes
252        \li \l{Deleting Keyframes}
253    \row
254        \li Add Keyframes at Current Frame
255        \li \l{Setting Keyframe Values}
256    \row
257        \li Copy All Keyframes
258        \li \l{Copying Keyframes}
259    \row
260        \li Paste Keyframes
261        \li \l{Copying Keyframes}
262    \row
263        \li Remove Property
264        \li \l{Setting Keyframe Values}
265    \row
266        \li Delete Keyframe
267        \li \l{Deleting Keyframes}
268    \row
269        \li Edit Easing Curve
270        \li \l{Editing Easing Curves}
271    \row
272        \li Edit Keyframe
273        \li \l{Editing Keyframe Values}
274    \row
275        \li Override Color
276        \li \l{Setting Keyframe Track Color}
277    \row
278        \li Reset Color
279        \li \l{Setting Keyframe Track Color}
280    \endtable
281*/
282