Initial revision
[blender.git] / intern / action / ACT_ActionC-Api.h
1 /**
2  * $Id$
3  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License
7  * as published by the Free Software Foundation; either version 2
8  * of the License, or (at your option) any later version. The Blender
9  * Foundation also sells licenses for use in proprietary software under
10  * the Blender License.  See http://www.blender.org/BL/ for information
11  * about this.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
21  *
22  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
23  * All rights reserved.
24  *
25  * The Original Code is: all of this file.
26  *
27  * Contributor(s): none yet.
28  *
29  * ***** END GPL/BL DUAL LICENSE BLOCK *****
30  */
31
32 /**
33
34  * $Id$
35  * Copyright (C) 2001 NaN Technologies B.V.
36  * Interface for C access to actions.
37  * @author      Maarten Gribnau
38  * @date        April, 25, 2001
39  */
40
41 #ifndef _H_ACT_ACTION_C_API
42 #define _H_ACT_ACTION_C_API
43
44 #include "MEM_RefCountedC-Api.h"
45
46 /** A pointer to an action object. */
47 typedef MEM_TRefCountedObjectPtr ACT_ActionPtr;
48 /** A pointer to an action stack object. */
49 typedef MEM_TObjectPtr ACT_ActionStackPtr;
50
51
52 /** A pointer to user data passed by the callbacks. */
53 typedef void* ACT_ActionUserDataPtr;
54
55 /**
56  * An action apply callback routine.
57  * @param action The action that should be applied.
58  * @param userData The pointer to the user data provided when the action was created.
59  */
60 typedef void (*ACT_ActionApplyProcPtr)(ACT_ActionPtr action, ACT_ActionUserDataPtr userData);
61
62 /**
63  * An action undo callback routine.
64  * @param action The action that should be undone.
65  * @param userData The pointer to the user data provided when the action was created.
66  */
67 typedef void (*ACT_ActionUndoProcPtr)(ACT_ActionPtr action, ACT_ActionUserDataPtr userData);
68
69 /**
70  * An action dispose callback routine.
71  * @param action The action that is disposed.
72  * @param userData The pointer to the user data provided when the action was created.
73  */
74 typedef void (*ACT_ActionDisposeProcPtr)(ACT_ActionPtr action, ACT_ActionUserDataPtr userData);
75
76
77 #ifdef __cplusplus
78 extern "C" {
79 #endif
80
81 /**
82  * An action is a shared object that can be applied or undone.
83  */
84
85 /**
86  * Creates a new action.
87  * This is an action that calls the given callbacks when it needs to be applied or undone.
88  * @param name The name of the action.
89  * @param isApplied Indication as to whether the action is already applied (0 = not applied).
90  * @param userData Pointer passed to the apply/undo callbacks.
91  * @param applyProc Pointer to the callback invoked when the action needs to be applied.
92  * @param undoProc Pointer to the callback invoked when the action needs to be undone.
93  * @return      The new action (null in case of error).
94  */
95 extern ACT_ActionPtr ACT_ActionCreate(
96                                                 char* name,
97                                                 int isApplied,
98                                                 ACT_ActionUserDataPtr userData,
99                                                 ACT_ActionApplyProcPtr applyProc,
100                                                 ACT_ActionUndoProcPtr undoProc,
101                                                 ACT_ActionDisposeProcPtr disposeProc);
102
103 /**
104  * Returns the name of an action.
105  * @return      The name of the action (null in case of error).
106  */
107 extern char* ACT_ActionGetName(ACT_ActionPtr action);
108
109
110
111 /**
112  * An action stack stores actions and implements undo/redo functionality.
113  */
114
115 /**
116  * Creates a new action stack.
117  * @param stackSize The maximum number of actions on the stack.
118  * @return The new stack (or NULL in case of error).
119  */
120 extern ACT_ActionStackPtr ACT_ActionStackCreate(unsigned int stackSize);
121
122 /**
123  * Disposes an action stack.
124  * @param stack The appropriate stack.
125  */
126 extern void     ACT_ActionStackDispose(ACT_ActionStackPtr stack);
127
128 /**
129  * Returns the current depth of the stack.
130  * @param stack The appropriate stack.
131  * @return the current stack depth.
132  */
133 extern unsigned int ACT_ActionStackGetStackDepth(ACT_ActionStackPtr stack);
134
135 /**
136  * Returns the current maximum depth of the stack.
137  * @param stack The appropriate stack.
138  * @return the maximum stack depth.
139  */
140 extern unsigned int ACT_ActionStackGetMaxStackDepth(ACT_ActionStackPtr stack);
141
142 /**
143  * Sets new maximum depth of the stack.
144  * @param stack The appropriate stack.
145  * @param maxStackDepth The new stack depth.
146  */
147 extern void ACT_ActionStackSetMaxStackDepth(ACT_ActionStackPtr stack, unsigned int maxStackDepth);
148
149 /**
150  * Pushes an action on the stack.
151  * If the action has not been applied yet, it will be applied here.
152  * This will increase the reference count of the action.
153  * If there is not enough capacity, the action at the bottom of the stack is removed (and its reference count decreased).
154  * @param stack The appropriate stack.
155  * @param action        the action that is pushed onto the stack.
156  */
157 extern void     ACT_ActionStackPush(ACT_ActionStackPtr stack, ACT_ActionPtr action);
158
159 /**
160  * Returns pointer to the current undo item.
161  * @param stack The appropriate stack.
162  * @return The action scheduled for undo (0 if there is none).
163  */
164 extern ACT_ActionStackPtr ACT_ActionStackPeekUndo(ACT_ActionStackPtr stack);
165
166 /**
167  * Returns pointer to the current redo item.
168  * @param stack The appropriate stack.
169  * @return The action scheduled for redo (0 if there is none).
170  */
171 extern ACT_ActionStackPtr ACT_ActionStackPeekRedo(ACT_ActionStackPtr stack);
172
173 /**
174  * Undos the current action.
175  * @param stack The appropriate stack.
176  * This will move the current undo index down (if the stack depth allows it).
177  */
178 extern void     ACT_ActionStackUndo(ACT_ActionStackPtr stack);
179
180 /**
181  * Redos the current action.
182  * @param stack The appropriate stack.
183  * This will move the action index up (if the stack depth allows it).
184  */
185 extern void     ACT_ActionStackRedo(ACT_ActionStackPtr stack);
186
187
188 #ifdef __cplusplus
189 }
190 #endif
191
192 #endif // _H_ACT_ACTION_C_API