File indexing completed on 2025-02-16 05:03:12
0001 /* 0002 SPDX-FileCopyrightText: 2018 Vlad Zahorodnii <vlad.zahorodnii@kde.org> 0003 0004 SPDX-License-Identifier: GPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "kwin_export.h" 0010 0011 #include <QEasingCurve> 0012 #include <QSharedDataPointer> 0013 0014 #include <chrono> 0015 0016 namespace KWin 0017 { 0018 0019 /** 0020 * The TimeLine class is a helper for controlling animations. 0021 */ 0022 class KWIN_EXPORT TimeLine 0023 { 0024 public: 0025 /** 0026 * Direction of the timeline. 0027 * 0028 * When the direction of the timeline is Forward, the progress 0029 * value will go from 0.0 to 1.0. 0030 * 0031 * When the direction of the timeline is Backward, the progress 0032 * value will go from 1.0 to 0.0. 0033 */ 0034 enum Direction { 0035 Forward, 0036 Backward 0037 }; 0038 0039 /** 0040 * Constructs a new instance of TimeLine. 0041 * 0042 * @param duration Duration of the timeline, in milliseconds 0043 * @param direction Direction of the timeline 0044 * @since 5.14 0045 */ 0046 explicit TimeLine(std::chrono::milliseconds duration = std::chrono::milliseconds(1000), 0047 Direction direction = Forward); 0048 TimeLine(const TimeLine &other); 0049 ~TimeLine(); 0050 0051 /** 0052 * Returns the current value of the timeline. 0053 * 0054 * @since 5.14 0055 */ 0056 qreal value() const; 0057 0058 /** 0059 * Advances the timeline to the specified @a timestamp. 0060 */ 0061 void advance(std::chrono::milliseconds timestamp); 0062 0063 /** 0064 * Returns the number of elapsed milliseconds. 0065 * 0066 * @see setElapsed 0067 * @since 5.14 0068 */ 0069 std::chrono::milliseconds elapsed() const; 0070 0071 /** 0072 * Sets the number of elapsed milliseconds. 0073 * 0074 * This method overwrites previous value of elapsed milliseconds. 0075 * If the new value of elapsed milliseconds is greater or equal 0076 * to duration of the timeline, the timeline will be finished, i.e. 0077 * proceeding TimeLine::done method calls will return @c true. 0078 * Please don't use it. Instead, use TimeLine::update. 0079 * 0080 * @note The new number of elapsed milliseconds should be a non-negative 0081 * number, i.e. it should be greater or equal to 0. 0082 * 0083 * @param elapsed The new number of elapsed milliseconds 0084 * @see elapsed 0085 * @since 5.14 0086 */ 0087 void setElapsed(std::chrono::milliseconds elapsed); 0088 0089 /** 0090 * Returns the duration of the timeline. 0091 * 0092 * @returns Duration of the timeline, in milliseconds 0093 * @see setDuration 0094 * @since 5.14 0095 */ 0096 std::chrono::milliseconds duration() const; 0097 0098 /** 0099 * Sets the duration of the timeline. 0100 * 0101 * In addition to setting new value of duration, the timeline will 0102 * try to retarget the number of elapsed milliseconds to match 0103 * as close as possible old progress value. If the new duration 0104 * is much smaller than old duration, there is a big chance that 0105 * the timeline will be finished after setting new duration. 0106 * 0107 * @note The new duration should be a positive number, i.e. it 0108 * should be greater or equal to 1. 0109 * 0110 * @param duration The new duration of the timeline, in milliseconds 0111 * @see duration 0112 * @since 5.14 0113 */ 0114 void setDuration(std::chrono::milliseconds duration); 0115 0116 /** 0117 * Returns the direction of the timeline. 0118 * 0119 * @returns Direction of the timeline(TimeLine::Forward or TimeLine::Backward) 0120 * @see setDirection 0121 * @see toggleDirection 0122 * @since 5.14 0123 */ 0124 Direction direction() const; 0125 0126 /** 0127 * Sets the direction of the timeline. 0128 * 0129 * @param direction The new direction of the timeline 0130 * @see direction 0131 * @see toggleDirection 0132 * @since 5.14 0133 */ 0134 void setDirection(Direction direction); 0135 0136 /** 0137 * Toggles the direction of the timeline. 0138 * 0139 * If the direction of the timeline was TimeLine::Forward, it becomes 0140 * TimeLine::Backward, and vice verca. 0141 * 0142 * @see direction 0143 * @see setDirection 0144 * @since 5.14 0145 */ 0146 void toggleDirection(); 0147 0148 /** 0149 * Returns the easing curve of the timeline. 0150 * 0151 * @see setEasingCurve 0152 * @since 5.14 0153 */ 0154 QEasingCurve easingCurve() const; 0155 0156 /** 0157 * Sets new easing curve. 0158 * 0159 * @param easingCurve An easing curve to be set 0160 * @see easingCurve 0161 * @since 5.14 0162 */ 0163 void setEasingCurve(const QEasingCurve &easingCurve); 0164 0165 /** 0166 * Sets new easing curve by providing its type. 0167 * 0168 * @param type Type of the easing curve(e.g. QEasingCurve::InCubic, etc) 0169 * @see easingCurve 0170 * @since 5.14 0171 */ 0172 void setEasingCurve(QEasingCurve::Type type); 0173 0174 /** 0175 * Returns whether the timeline is currently in progress. 0176 * 0177 * @see done 0178 * @since 5.14 0179 */ 0180 bool running() const; 0181 0182 /** 0183 * Returns whether the timeline is finished. 0184 * 0185 * @see reset 0186 * @since 5.14 0187 */ 0188 bool done() const; 0189 0190 /** 0191 * Resets the timeline to initial state. 0192 * 0193 * @since 5.14 0194 */ 0195 void reset(); 0196 0197 enum class RedirectMode { 0198 Strict, 0199 Relaxed 0200 }; 0201 0202 /** 0203 * Returns the redirect mode for the source position. 0204 * 0205 * The redirect mode controls behavior of the timeline when its direction is 0206 * changed at the source position, e.g. what should we do when the timeline 0207 * initially goes forward and we change its direction to go backward. 0208 * 0209 * In the strict mode, the timeline will stop. 0210 * 0211 * In the relaxed mode, the timeline will go in the new direction. For example, 0212 * if the timeline goes forward(from 0 to 1), then with the new direction it 0213 * will go backward(from 1 to 0). 0214 * 0215 * The default is RedirectMode::Relaxed. 0216 * 0217 * @see targetRedirectMode 0218 * @since 5.15 0219 */ 0220 RedirectMode sourceRedirectMode() const; 0221 0222 /** 0223 * Sets the redirect mode for the source position. 0224 * 0225 * @param mode The new mode. 0226 * @since 5.15 0227 */ 0228 void setSourceRedirectMode(RedirectMode mode); 0229 0230 /** 0231 * Returns the redirect mode for the target position. 0232 * 0233 * The redirect mode controls behavior of the timeline when its direction is 0234 * changed at the target position. 0235 * 0236 * In the strict mode, subsequent update calls won't have any effect on the 0237 * current value of the timeline. 0238 * 0239 * In the relaxed mode, the timeline will go in the new direction. 0240 * 0241 * The default is RedirectMode::Strict. 0242 * 0243 * @see sourceRedirectMode 0244 * @since 5.15 0245 */ 0246 RedirectMode targetRedirectMode() const; 0247 0248 /** 0249 * Sets the redirect mode for the target position. 0250 * 0251 * @param mode The new mode. 0252 * @since 5.15 0253 */ 0254 void setTargetRedirectMode(RedirectMode mode); 0255 0256 TimeLine &operator=(const TimeLine &other); 0257 0258 /** 0259 * @returns a value between 0 and 1 defining the progress of the timeline 0260 * 0261 * @since 5.23 0262 */ 0263 qreal progress() const; 0264 0265 private: 0266 class Data; 0267 QSharedDataPointer<Data> d; 0268 }; 0269 0270 } // namespace KWin