svn merge ^/trunk/blender -r43436:43443
[blender.git] / source / blender / blenkernel / BKE_idprop.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
19  * All rights reserved.
20  *
21  * Contributor(s): Joseph Eagar
22  *
23  * ***** END GPL LICENSE BLOCK *****
24  */
25  
26 #ifndef _BKE_IDPROP_H
27 #define _BKE_IDPROP_H
28
29 /** \file BKE_idprop.h
30  *  \ingroup bke
31  *  \author Joseph Eagar
32  */
33
34 #include "DNA_ID.h"
35
36 struct IDProperty;
37 struct ID;
38
39 typedef union IDPropertyTemplate {
40         int i;
41         float f;
42         double d;
43         struct {
44                 char *str;
45                 short len;
46                 char subtype;
47         } string;
48         struct ID *id;
49         struct {
50                 short type;
51                 short len;
52         } array;
53         struct {
54                 int matvec_size;
55                 float *example;
56         } matrix_or_vector;
57 } IDPropertyTemplate;
58
59 /* ----------- Property Array Type ---------- */
60
61 /*note: as a start to move away from the stupid IDP_New function, this type
62   has it's own allocation function.*/
63 IDProperty *IDP_NewIDPArray(const char *name);
64 IDProperty *IDP_CopyIDPArray(IDProperty *array);
65
66 void IDP_FreeIDPArray(IDProperty *prop);
67
68 /* shallow copies item */
69 void IDP_SetIndexArray(struct IDProperty *prop, int index, struct IDProperty *item);
70 struct IDProperty *IDP_GetIndexArray(struct IDProperty *prop, int index);
71 struct IDProperty *IDP_AppendArray(struct IDProperty *prop, struct IDProperty *item);
72 void IDP_ResizeIDPArray(struct IDProperty *prop, int len);
73
74 /* ----------- Numeric Array Type ----------- */
75 /*this function works for strings too!*/
76 void IDP_ResizeArray(struct IDProperty *prop, int newlen);
77 void IDP_FreeArray(struct IDProperty *prop);
78 void IDP_UnlinkArray(struct IDProperty *prop);
79
80 /* ---------- String Type ------------ */
81 IDProperty *IDP_NewString(const char *st, const char *name, int maxlen);/* maxlen excludes '\0' */
82 void IDP_AssignString(struct IDProperty *prop, const char *st, int maxlen);     /* maxlen excludes '\0' */
83 void IDP_ConcatStringC(struct IDProperty *prop, const char *st);
84 void IDP_ConcatString(struct IDProperty *str1, struct IDProperty *append);
85 void IDP_FreeString(struct IDProperty *prop);
86
87 /*-------- ID Type -------*/
88 void IDP_LinkID(struct IDProperty *prop, ID *id);
89 void IDP_UnlinkID(struct IDProperty *prop);
90
91 /*-------- Group Functions -------*/
92
93 /** Sync values from one group to another, only where they match */
94 void IDP_SyncGroupValues(struct IDProperty *dest, struct IDProperty *src);
95
96 /**
97  replaces all properties with the same name in a destination group from a source group.
98 */
99 void IDP_ReplaceGroupInGroup(struct IDProperty *dest, struct IDProperty *src);
100
101 /** checks if a property with the same name as prop exists, and if so replaces it.
102   Use this to preserve order!*/
103 void IDP_ReplaceInGroup(struct IDProperty *group, struct IDProperty *prop);
104
105 /**
106 This function has a sanity check to make sure ID properties with the same name don't
107 get added to the group.
108
109 The sanity check just means the property is not added to the group if another property
110 exists with the same name; the client code using ID properties then needs to detect this 
111 (the function that adds new properties to groups, IDP_AddToGroup, returns 0 if a property can't
112 be added to the group, and 1 if it can) and free the property.
113
114 Currently the code to free ID properties is designesd to leave the actual struct
115 you pass it un-freed, this is needed for how the system works.  This means
116 to free an ID property, you first call IDP_FreeProperty then MEM_freeN the
117 struct.  In the future this will just be IDP_FreeProperty and the code will
118 be reorganized to work properly.
119 */
120 int IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop);
121
122 /** this is the same as IDP_AddToGroup, only you pass an item
123   in the group list to be inserted after.*/
124 int IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, 
125                                           struct IDProperty *pnew);
126
127 /** \note this does not free the property!!
128
129  To free the property, you have to do:
130  IDP_FreeProperty(prop); //free all subdata
131  MEM_freeN(prop); //free property struct itself
132
133 */
134 void IDP_RemFromGroup(struct IDProperty *group, struct IDProperty *prop);
135
136 IDProperty *IDP_GetPropertyFromGroup(struct IDProperty *prop, const char *name);
137 /** same as above but ensure type match */
138 IDProperty *IDP_GetPropertyTypeFromGroup(struct IDProperty *prop, const char *name, const char type);
139
140 /** Get an iterator to iterate over the members of an id property group.
141  Note that this will automatically free the iterator once iteration is complete;
142  if you stop the iteration before hitting the end, make sure to call
143  IDP_FreeIterBeforeEnd().*/
144 void *IDP_GetGroupIterator(struct IDProperty *prop);
145
146 /** Returns the next item in the iteration.  To use, simple for a loop like the following:
147  while (IDP_GroupIterNext(iter) != NULL) {
148         . . .
149  }*/
150 IDProperty *IDP_GroupIterNext(void *vself);
151
152 /** Frees the iterator pointed to at vself, only use this if iteration is stopped early; 
153   when the iterator hits the end of the list it'll automatially free itself.*/
154 void IDP_FreeIterBeforeEnd(void *vself);
155
156 /*-------- Main Functions --------*/
157 /** Get the Group property that contains the id properties for ID id.  Set create_if_needed
158   to create the Group property and attach it to id if it doesn't exist; otherwise
159   the function will return NULL if there's no Group property attached to the ID.*/
160 struct IDProperty *IDP_GetProperties(struct ID *id, int create_if_needed);
161 struct IDProperty *IDP_CopyProperty(struct IDProperty *prop);
162
163 int IDP_EqualsProperties(struct IDProperty *prop1, struct IDProperty *prop2);
164
165 /**
166 Allocate a new ID.
167
168 This function takes three arguments: the ID property type, a union which defines
169 it's initial value, and a name.
170
171 The union is simple to use; see the top of this header file for its definition. 
172 An example of using this function:
173
174  IDPropertyTemplate val;
175  IDProperty *group, *idgroup, *color;
176  group = IDP_New(IDP_GROUP, val, "group1"); //groups don't need a template.
177
178  val.array.len = 4
179  val.array.type = IDP_FLOAT;
180  color = IDP_New(IDP_ARRAY, val, "color1");
181
182  idgroup = IDP_GetProperties(some_id, 1);
183  IDP_AddToGroup(idgroup, color);
184  IDP_AddToGroup(idgroup, group);
185
186 Note that you MUST either attach the id property to an id property group with 
187 IDP_AddToGroup or MEM_freeN the property, doing anything else might result in
188 a memory leak.
189 */
190 struct IDProperty *IDP_New(const int type, const IDPropertyTemplate *val, const char *name);
191
192 /** \note this will free all child properties of list arrays and groups!
193   Also, note that this does NOT unlink anything!  Plus it doesn't free
194   the actual struct IDProperty struct either.*/
195 void IDP_FreeProperty(struct IDProperty *prop);
196
197 /** Unlinks any struct IDProperty<->ID linkage that might be going on.*/
198 void IDP_UnlinkProperty(struct IDProperty *prop);
199
200 #define IDP_Int(prop) ((prop)->data.val)
201 #define IDP_Float(prop) (*(float*)&(prop)->data.val)
202 #define IDP_String(prop) ((char*)(prop)->data.pointer)
203 #define IDP_Array(prop) ((prop)->data.pointer)
204 #define IDP_IDPArray(prop) ((IDProperty*)(prop)->data.pointer)
205 #define IDP_Double(prop) (*(double*)&(prop)->data.val)
206
207 #endif /* _BKE_IDPROP_H */