1 /* 2 NSAnimation.h 3 4 Created by Dr. H. Nikolaus Schaller on Sat Jan 07 2006. 5 Copyright (c) 2007 Free Software Foundation, Inc. 6 7 Author: Xavier Glattard (xgl) <xavier.glattard@online.fr> 8 9 This file used to be part of the mySTEP Library. 10 This file now is part of the GNUstep GUI Library. 11 12 This library is free software; you can redistribute it and/or 13 modify it under the terms of the GNU Lesser General Public 14 License as published by the Free Software Foundation; either 15 version 2 of the License, or (at your option) any later version. 16 17 This library is distributed in the hope that it will be useful, 18 but WITHOUT ANY WARRANTY; without even the implied warranty of 19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 Lesser General Public License for more details. 21 22 You should have received a copy of the GNU Lesser General Public 23 License along with this library; see the file COPYING.LIB. 24 If not, see <http://www.gnu.org/licenses/> or write to the 25 Free Software Foundation, 51 Franklin Street, Fifth Floor, 26 Boston, MA 02110-1301, USA. 27 */ 28 29 #ifndef _GNUstep_H_NSAnimation_ 30 #define _GNUstep_H_NSAnimation_ 31 32 #import <GNUstepBase/GSVersionMacros.h> 33 34 #if OS_API_VERSION(MAC_OS_X_VERSION_10_4, GS_API_LATEST) 35 36 #import <Foundation/NSObject.h> 37 #import <AppKit/AppKitDefines.h> 38 #import <GNUstepGUI/GSAnimator.h> 39 40 @class NSString; 41 @class NSArray; 42 @class NSMutableArray; 43 @class NSNumber; 44 @class NSRecursiveLock; 45 46 /** These constants describe the curve of an animation, 47 that is, the relative speed of an animation from start to finish. */ 48 enum _NSAnimationCurve 49 { 50 NSAnimationEaseInOut = 0, // default 51 NSAnimationEaseIn, 52 NSAnimationEaseOut, 53 NSAnimationLinear, 54 NSAnimationSpeedInOut // GNUstep only 55 }; 56 typedef NSUInteger NSAnimationCurve; 57 58 /** These constants indicate the blocking mode of an NSAnimation object when it is running. */ 59 enum _NSAnimationBlockingMode 60 { 61 NSAnimationBlocking, 62 NSAnimationNonblocking, 63 NSAnimationNonblockingThreaded 64 }; 65 typedef NSUInteger NSAnimationBlockingMode; 66 67 typedef float NSAnimationProgress; 68 69 // Bezier curve parameters 70 typedef struct __GSBezierDesc 71 { 72 float p[4]; // control points 73 BOOL areCoefficientsComputed; 74 float a[4]; // coefficients 75 } _GSBezierDesc; 76 77 // Rational Bezier curve parameters 78 typedef struct __GSRationalBezierDesc 79 { 80 float w[4]; // weights 81 float p[4]; // control points 82 BOOL areBezierDescComputed; 83 _GSBezierDesc n; // numerator 84 _GSBezierDesc d; // denumerator 85 } _GSRationalBezierDesc; 86 87 // Animation curve parameters 88 typedef struct __NSAnimationCurveDesc 89 { 90 float s,e; // start & end values 91 float sg,eg; // start & end gradients 92 _GSRationalBezierDesc rb; 93 BOOL isRBezierComputed; 94 } _NSAnimationCurveDesc; 95 96 /** Posted when the current progress of a running animation reaches one of its progress marks. */ 97 APPKIT_EXPORT NSString *NSAnimationProgressMarkNotification; 98 99 /** Key used in the [NSNotification-userInfo] disctionary to access the current progress mark. */ 100 APPKIT_EXPORT NSString *NSAnimationProgressMark; 101 102 APPKIT_EXPORT NSString *NSAnimationTriggerOrderIn; 103 APPKIT_EXPORT NSString *NSAnimationTriggerOrderOut; 104 105 /** 106 * Objects of the NSAnimation class manage the timing and progress of 107 * animations in the user interface. The class also lets you link together 108 * multiple animations so that when one animation ends another one starts. 109 * It does not provide any drawing support for animation and does not directly 110 * deal with views, targets, or actions. 111 */ 112 @interface NSAnimation : NSObject < NSCopying, NSCoding, GSAnimation > 113 { 114 // FIXME ... all these ivars should be hidden inside a pointer to an 115 // FIXME ... opaque data structure, so that layout etc can be changed 116 // FIXME ... without breaking binary compatibility. 117 NSTimeInterval _duration; // Duration of the animation 118 float _frameRate; // Wanted frame rate 119 NSAnimationCurve _curve; // Id of progres->value function 120 _NSAnimationCurveDesc _curveDesc; // The curve as a rat. Bezier 121 NSAnimationProgress _curveProgressShift;// Shift used for switching 122 // from a curve to an other 123 NSAnimationProgress _currentProgress; // Progress of the animation 124 125 /* GSIArray<NSAnimationProgress> */ void *_progressMarks; // Array 126 unsigned int _nextMark; // The next mark to be reached 127 // = count if no next mark 128 __strong NSNumber **_cachedProgressMarkNumbers; // Cached values used by 129 unsigned _cachedProgressMarkNumberCount;// [-progressMarks] 130 BOOL _isCachedProgressMarkNumbersValid; 131 132 NSAnimation *_startAnimation, *_stopAnimation; // Animations used as 133 NSAnimationProgress _startMark, _stopMark; // trigger, and marks 134 135 NSAnimationBlockingMode _blockingMode; // Blocking mode 136 GSAnimator *_animator; // The animator 137 BOOL _isANewAnimatorNeeded; // Some parameters have changed... 138 139 id _delegate; // The delegate, and the cached delegation methods... 140 void (*_delegate_animationDidReachProgressMark)(id,SEL,NSAnimation*,NSAnimationProgress); 141 float (*_delegate_animationValueForProgress )(id,SEL,NSAnimation*,NSAnimationProgress); 142 void (*_delegate_animationDidEnd )(id,SEL,NSAnimation*); 143 void (*_delegate_animationDidStop )(id,SEL,NSAnimation*); 144 BOOL (*_delegate_animationShouldStart )(id,SEL,NSAnimation*); 145 id _currentDelegate; // The delegate when the animation is running 146 147 BOOL _isThreaded; 148 NSRecursiveLock *_isAnimatingLock; 149 } 150 151 /** Adds the progress mark to the receiver. */ 152 - (void) addProgressMark: (NSAnimationProgress)progress; 153 154 /** Returns the blocking mode the receiver is next scheduled to run under. */ 155 - (NSAnimationBlockingMode) animationBlockingMode; 156 157 /** Returns the animation curve the receiver is running under. */ 158 - (NSAnimationCurve) animationCurve; 159 160 /** Clears linkage to another animation that causes the receiver to start. */ 161 - (void) clearStartAnimation; 162 163 /** Clears linkage to another animation that causes the receiver to stop. */ 164 - (void) clearStopAnimation; 165 166 /** Returns the current progress of the receiver. */ 167 - (NSAnimationProgress) currentProgress; 168 169 /** Returns the current value of the effect based on the current progress. */ 170 - (float) currentValue; 171 172 /** Returns the delegate of the receiver. */ 173 - (id) delegate; 174 175 /** Returns the duration of the animation, in seconds. */ 176 - (NSTimeInterval) duration; 177 178 /** Returns the frame rate of the animation. */ 179 - (float) frameRate; 180 181 /** Returns an NSAnimation object initialized with the specified duration and animation-curve values. */ 182 - (id) initWithDuration: (NSTimeInterval)duration 183 animationCurve: (NSAnimationCurve)curve; 184 185 /** Returns a Boolean value that indicates whether the receiver is currently animating. */ 186 - (BOOL) isAnimating; 187 188 /** Returns the receiver's progress marks. */ 189 - (NSArray*) progressMarks; 190 191 /** Removes a progress mark from the receiver. 192 A value that does not correspond to a progress mark is ignored.*/ 193 - (void) removeProgressMark: (NSAnimationProgress)progress; 194 195 /** Overridden to return the run-loop modes that the receiver uses to run the 196 animation timer in. */ 197 - (NSArray*) runLoopModesForAnimating; 198 199 /** Sets the blocking mode of the receiver. 200 The new blocking mode takes effect the next time the receiver is started. */ 201 - (void) setAnimationBlockingMode: (NSAnimationBlockingMode)mode; 202 203 /** Sets the receiver's animation curve. 204 The new value affects the animation already in progress : the actual 205 curve smoothly changes from the old curve to the new one. */ 206 - (void) setAnimationCurve: (NSAnimationCurve)curve; 207 208 /** Sets the current progress of the receiver. 209 In the case of a forward jump the marks between the previous progress value 210 and the new (excluded) progress value are ignored. In the case of a 211 backward jump (rewind) the marks will be reached again. */ 212 - (void) setCurrentProgress: (NSAnimationProgress)progress; 213 214 /** Sets the delegate of the receiver. 215 The new delegate takes effect the next time the receiver is started. */ 216 - (void) setDelegate: (id)delegate; 217 218 /** Sets the duration of the animation to a specified number of seconds. 219 If the duration is changed while the animation is running the <i>speed</i> 220 of the animation is not changed but the current progress value is 221 (see [-setCurrentprogress]). The new value takes effect at the next 222 frame. */ 223 - (void) setDuration: (NSTimeInterval)duration; 224 225 /** Sets the frame rate of the receiver. 226 The new frame rate takes effect at the next frame. */ 227 - (void) setFrameRate: (float)fps; 228 229 /** Sets the receiver's progress marks to the values specified in the 230 passed-in array. The new marks are t*/ 231 - (void) setProgressMarks: (NSArray*)progress; 232 233 /** Starts the animation represented by the receiver. 234 If the animation is already running the method has no effect.*/ 235 - (void) startAnimation; 236 237 /** Starts running the animation represented by the receiver when another 238 animation reaches a specific progress mark. */ 239 - (void) startWhenAnimation: (NSAnimation*)animation 240 reachesProgress: (NSAnimationProgress)start; 241 242 /** Stops the animation represented by the receiver. 243 If the animation is not running the method has no effect.*/ 244 - (void) stopAnimation; 245 246 /** Stops running the animation represented by the receiver when another 247 animation reaches a specific progress mark. */ 248 - (void) stopWhenAnimation: (NSAnimation*)animation 249 reachesProgress: (NSAnimationProgress)stop; 250 251 @end 252 253 @interface NSAnimation (GNUstep) 254 255 /** Returns the current value of the frame counter */ 256 - (unsigned int) frameCount; 257 258 /** Resets all stats */ 259 - (void) resetCounters; 260 261 /** Returns the current the actual (mesured) frame rate value */ 262 - (float) actualFrameRate; 263 264 @end 265 266 @protocol NSAnimationDelegate <NSObject> 267 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6, GS_API_LATEST) && GS_PROTOCOLS_HAVE_OPTIONAL 268 @optional 269 #else 270 @end 271 @interface NSObject (NSAnimation) 272 #endif 273 274 /** NSAnimation delegate method. 275 * Sent to the delegate when an animation reaches a specific progress mark. */ 276 - (void) animation: (NSAnimation*)animation 277 didReachProgressMark: (NSAnimationProgress)progress; 278 279 /** NSAnimation delegate method. 280 * Requests a custom curve value for the current progress value. */ 281 - (float) animation: (NSAnimation*)animation 282 valueForProgress: (NSAnimationProgress)progress; 283 284 /** NSAnimation delegate method. 285 * Sent to the delegate when the specified animation completes its run. */ 286 - (void) animationDidEnd: (NSAnimation*)animation; 287 288 /** NSAnimation delegate method. 289 * Sent to the delegate when the specified animation is stopped before it completes its run. */ 290 - (void) animationDidStop: (NSAnimation*)animation; 291 292 /** NSAnimation delegate method. 293 * Sent to the delegate just after an animation is started. */ 294 - (BOOL) animationShouldStart: (NSAnimation*)animation; 295 296 @end 297 298 APPKIT_EXPORT NSString *NSViewAnimationTargetKey; 299 APPKIT_EXPORT NSString *NSViewAnimationStartFrameKey; 300 APPKIT_EXPORT NSString *NSViewAnimationEndFrameKey; 301 APPKIT_EXPORT NSString *NSViewAnimationEffectKey; 302 303 APPKIT_EXPORT NSString *NSViewAnimationFadeInEffect; 304 APPKIT_EXPORT NSString *NSViewAnimationFadeOutEffect; 305 306 /** 307 * The NSViewAnimation class, a public subclass of NSAnimation, 308 * offers a convenient way to animate multiple views and windows. 309 * The animation effects you can achieve are limited to changes in 310 * frame location and size, and to fade-in and fade-out effects. 311 */ 312 @interface NSViewAnimation : NSAnimation 313 { 314 NSArray *_viewAnimations; 315 NSMutableArray *_viewAnimationDesc; 316 } 317 318 /** Returns an NSViewAnimation object initialized with the supplied information. */ 319 - (id) initWithViewAnimations: (NSArray*)animations; 320 321 /** Sets the dictionaries defining the objects to animate. */ 322 - (void) setViewAnimations: (NSArray*)animations; 323 324 /** Returns the array of dictionaries defining the objects to animate. */ 325 - (NSArray*) viewAnimations; 326 327 @end 328 329 #endif /* OS_API_VERSION */ 330 331 #endif /* _GNUstep_H_NSAnimation_ */ 332 333