/libs/ObjectAL/Actions/OALAction.h
C Header | 310 lines | 123 code | 59 blank | 128 comment | 1 complexity | ae9318176f3e8c9bdd45a3fd0973096a MD5 | raw file
Possible License(s): Apache-2.0
1// 2// OALAction.h 3// ObjectAL 4// 5// Created by Karl Stenerud on 10-09-18. 6// 7// Copyright 2009 Karl Stenerud 8// 9// Licensed under the Apache License, Version 2.0 (the "License"); 10// you may not use this file except in compliance with the License. 11// You may obtain a copy of the License at 12// 13// http://www.apache.org/licenses/LICENSE-2.0 14// 15// Unless required by applicable law or agreed to in writing, software 16// distributed under the License is distributed on an "AS IS" BASIS, 17// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18// See the License for the specific language governing permissions and 19// limitations under the License. 20// 21// Note: You are NOT required to make the license available from within your 22// iOS application. Including it in your project is sufficient. 23// 24// Attribution is not required, but appreciated :) 25// 26 27#import <Foundation/Foundation.h> 28#import "OALFunction.h" 29#import "ObjectALConfig.h" 30 31 32#if OBJECTAL_USE_COCOS2D_ACTIONS 33 34#pragma mark Cocos2d Subclassing 35 36#import "cocos2d.h" 37 38/** Generates common code required to subclass from a cocos2d action 39 * while maintaining the functionality of an OALAction. 40 */ 41#define COCOS2D_SUBCLASS_HEADER(CLASS_A,CLASS_B) \ 42@interface CLASS_A: CLASS_B \ 43{ \ 44 bool started; \ 45} \ 46 \ 47@property(readonly,nonatomic) bool running; \ 48- (void) runWithTarget:(id) target; \ 49- (void) prepareWithTarget:(id) target; \ 50- (void) stopAction; \ 51- (void) updateCompletion:(float) proportionComplete; \ 52 \ 53@end 54 55 56 57/** Generates common code required to subclass from a cocos2d action 58 * while maintaining the functionality of an OALAction. 59 */ 60#define COCOS2D_SUBCLASS(CLASS_A) \ 61@implementation CLASS_A \ 62 \ 63- (id) init \ 64{ \ 65 return [self initWithDuration:0]; \ 66} \ 67 \ 68-(void) startWithTarget:(id) targetIn \ 69{ \ 70 [super startWithTarget:targetIn]; \ 71 [self prepareWithTarget:targetIn]; \ 72 started = YES; \ 73 [self runWithTarget:targetIn]; \ 74} \ 75 \ 76- (void) update:(float) proportionComplete \ 77{ \ 78 [super update:proportionComplete]; \ 79 [self updateCompletion:proportionComplete]; \ 80} \ 81 \ 82- (bool) running \ 83{ \ 84 return !self.isDone; \ 85} \ 86 \ 87- (void) runWithTarget:(id) targetIn \ 88{ \ 89 if(!started) \ 90 { \ 91 [[CCActionManager sharedManager] addAction:self target:targetIn paused:NO]; \ 92 } \ 93} \ 94 \ 95- (void) stopAction \ 96{ \ 97 [[CCActionManager sharedManager] removeAction:self]; \ 98} \ 99 100#endif /* OBJECTAL_USE_COCOS2D_ACTIONS */ 101 102 103 104/* There are two versions of the actions which can be used: ObjectAL and Cocos2d. 105 * It's usually more convenient when using Cocos2d to have all actions as part of 106 * the Cocos2d action system. You can set this in ObjectALConfig.h 107 */ 108#if !OBJECTAL_USE_COCOS2D_ACTIONS 109 110#pragma mark - 111#pragma mark OALAction (ObjectAL version) 112 113/** 114 * Represents an action that can be performed on an object. 115 */ 116@interface OALAction : NSObject 117{ 118 /** The target to perform the action on */ 119 id target; 120 float duration; 121 float elapsed; 122 bool running; 123 124 /** If TRUE, this action is running via OALActionManager. */ 125 bool runningInManager; 126} 127 128 129#pragma mark Properties 130 131/** The target to perform the action on. WEAK REFERENCE. */ 132@property(readonly,nonatomic) id target; 133 134/** The duration of the action, in seconds. */ 135@property(readonly,nonatomic) float duration; 136 137/** The amount of time that has elapsed for this action, in seconds. */ 138@property(readwrite,nonatomic) float elapsed; 139 140/** If true, the action is currently running. */ 141@property(readonly,nonatomic) bool running; 142 143 144#pragma mark Object Management 145 146/** Initialize an action. 147 * 148 * @param duration The duration of this action in seconds. 149 * @return The initialized action. 150 */ 151- (id) initWithDuration:(float) duration; 152 153 154#pragma mark Functions 155 156/** Run this action on a target. 157 * 158 * @param target The target to run the action on. 159 */ 160- (void) runWithTarget:(id) target; 161 162/** Called by runWithTraget to do any final preparations before running. 163 * Subclasses must ensure that duration is valid when this method returns. 164 * 165 * @param target The target to run the action on. 166 */ 167- (void) prepareWithTarget:(id) target; 168 169 170/** Called by runWithTarget to start the action running. 171 */ 172- (void) startAction; 173 174/** Called by OALActionManager to update this action's progress. 175 * 176 * @param proportionComplete The proportion of this action's duration that has elapsed. 177 */ 178- (void) updateCompletion:(float) proportionComplete; 179 180/** Stop this action. 181 */ 182- (void) stopAction; 183 184@end 185 186 187#else /* !OBJECTAL_USE_COCOS2D_ACTIONS */ 188 189COCOS2D_SUBCLASS_HEADER(OALAction, CCIntervalAction); 190 191#endif /* !OBJECTAL_USE_COCOS2D_ACTIONS */ 192 193 194#pragma mark - 195#pragma mark OALFunctionAction 196 197/** 198 * An action that applies a function to the proportionComplete parameter in 199 * [update] before applying the result to the target. 200 * This allows things like exponential and s-curve functions when applying gain 201 * transitions, for example. 202 */ 203@interface OALFunctionAction: OALAction 204{ 205 float startValue; 206 float endValue; 207 /** The lowest value that will ever be set over the course of this function. */ 208 float lowValue; 209 /** The difference between the lowest and highest value. */ 210 float delta; 211 id<OALFunction,NSObject> function; 212 /** The reverse function, if any. When this is not null, the reverse function is used. */ 213 OALReverseFunction* reverseFunction; 214 /** The basic function that will be applied normally, or reversed. */ 215 id<OALFunction,NSObject> realFunction; 216} 217 218 219#pragma mark Properties 220 221/** The function that will be applied. */ 222@property(readwrite,retain,nonatomic) id<OALFunction,NSObject> function; 223 224/** The value that the property in the target will hold at the start of the action. */ 225@property(readwrite,assign,nonatomic) float startValue; 226 227/** The value that the property in the target will hold at the end of the action. */ 228@property(readwrite,assign,nonatomic) float endValue; 229 230 231#pragma mark Object Management 232 233/** Create a new action using the default function. 234 * The start value will be the current value of the target this action is applied to. 235 * 236 * @param duration The duration of this action in seconds. 237 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 238 * @return A new action. 239 */ 240+ (id) actionWithDuration:(float) duration endValue:(float) endValue; 241 242/** Create a new action. 243 * The start value will be the current value of the target this action is applied to. 244 * 245 * @param duration The duration of this action in seconds. 246 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 247 * @param function The function to apply in this action's update method. 248 * @return A new action. 249 */ 250+ (id) actionWithDuration:(float) duration 251 endValue:(float) endValue 252 function:(id<OALFunction,NSObject>) function; 253 254/** Create a new action. 255 * 256 * @param duration The duration of this action in seconds. 257 * @param startValue The "starting" value that this action will diverge from when setting the target's 258 * property. If NAN, use the current value from the target. 259 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 260 * @param function The function to apply in this action's update method. 261 * @return A new action. 262 */ 263+ (id) actionWithDuration:(float) duration 264 startValue:(float) startValue 265 endValue:(float) endValue 266 function:(id<OALFunction,NSObject>) function; 267 268/** Initialize an action using the default function. 269 * The start value will be the current value of the target this action is applied to. 270 * 271 * @param duration The duration of this action in seconds. 272 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 273 * @return The initialized action. 274 */ 275- (id) initWithDuration:(float) duration endValue:(float) endValue; 276 277/** Initialize an action. 278 * The start value will be the current value of the target this action is applied to. 279 * 280 * @param duration The duration of this action in seconds. 281 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 282 * @param function The function to apply in this action's update method. 283 * @return The initialized action. 284 */ 285- (id) initWithDuration:(float) duration 286 endValue:(float) endValue 287 function:(id<OALFunction,NSObject>) function; 288 289/** Initialize an action. 290 * 291 * @param duration The duration of this action in seconds. 292 * @param startValue The "starting" value that this action will diverge from when setting the target's 293 * property. If NAN, use the current value from the target. 294 * @param endValue The "ending" value that this action will converge upon when setting the target's property. 295 * @param function The function to apply in this action's update method. 296 * @return The initialized action. 297 */ 298- (id) initWithDuration:(float) duration 299 startValue:(float) startValue 300 endValue:(float) endValue 301 function:(id<OALFunction,NSObject>) function; 302 303 304#pragma mark Utility 305 306/** Get the function that this action would use by default if none was specified. */ 307+ (id<OALFunction,NSObject>) defaultFunction; 308 309 310@end