/libs/ObjectAL/Actions/OALAction.h

  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