=IDProperties Python update=
[blender-staging.git] / source / blender / blenkernel / BKE_idprop.h
1 /**
2  * $Id: BKE_idprop.h
3  *
4  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version. The Blender
10  * Foundation also sells licenses for use in proprietary software under
11  * the Blender License.  See http://www.blender.org/BL/ for information
12  * about this.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  * GNU General Public License for more details.
18  *
19  * You should have received a copy of the GNU General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
22  *
23  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
24  * All rights reserved.
25  *
26  * Contributor(s): Joseph Eagar
27  *
28  * ***** END GPL/BL DUAL LICENSE BLOCK *****
29  */
30  
31 #ifndef _BKE_IDPROP_H
32 #define _BKE_IDPROP_H
33
34 #include "DNA_ID.h"
35
36 /*
37 these two are included for their (new :P )function
38 pointers.
39 */
40 #include "BLO_readfile.h"
41 #include "BLO_writefile.h"
42
43 struct WriteData;
44 struct FileData;
45
46 struct IDProperty;
47 struct ID;
48
49 typedef union {
50         int i;
51         float f;
52         char *str;
53         struct ID *id;
54         struct {
55                 short type;
56                 short len;
57         } array;
58         struct {
59                 int matvec_size;
60                 float *example;
61         } matrix_or_vector;
62 } IDPropertyTemplate;
63
64 /* ----------- Array Type ----------- */
65 /*this function works for strings too!*/
66 void IDP_ResizeArray(struct IDProperty *prop, int newlen);
67 void IDP_FreeArray(struct IDProperty *prop);
68 void IDP_UnlinkArray(struct IDProperty *prop);
69
70 /* ---------- String Type ------------ */
71 void IDP_AssignString(struct IDProperty *prop, char *st);
72 void IDP_ConcatStringC(struct IDProperty *prop, char *st);
73 void IDP_ConcatString(struct IDProperty *str1, struct IDProperty *append);
74 void IDP_FreeString(struct IDProperty *prop);
75
76 /*-------- ID Type -------*/
77 void IDP_LinkID(struct IDProperty *prop, ID *id);
78 void IDP_UnlinkID(struct IDProperty *prop);
79
80 /*-------- Group Functions -------*/
81 /*
82 This function has a sanity check to make sure ID properties with the same name don't
83 get added to the group.
84
85 The sanity check just means the property is not added to the group if another property
86 exists with the same name; the client code using ID properties then needs to detect this 
87 (the function that adds new properties to groups, IDP_AddToGroup, returns 0 if a property can't
88 be added to the group, and 1 if it can) and free the property.
89
90 Currently the code to free ID properties is designesd to leave the actual struct
91 you pass it un-freed, this is needed for how the system works.  This means
92 to free an ID property, you first call IDP_FreeProperty then MEM_freeN the
93 struct.  In the future this will just be IDP_FreeProperty and the code will
94 be reorganized to work properly.
95 */
96 int IDP_AddToGroup(struct IDProperty *group, struct IDProperty *prop);
97
98 /*this is the same as IDP_AddToGroup, only you pass an item
99   in the group list to be inserted after.*/
100 int IDP_InsertToGroup(struct IDProperty *group, struct IDProperty *previous, 
101                       struct IDProperty *pnew);
102
103 /*NOTE: this does not free the property!!
104
105  To free the property, you have to do:
106  IDP_FreeProperty(prop); //free all subdata
107  MEM_freeN(prop); //free property struct itself
108
109 */
110 void IDP_RemFromGroup(struct IDProperty *group, struct IDProperty *prop);
111
112 IDProperty *IDP_GetPropertyFromGroup(struct IDProperty *prop, char *name);
113
114 /*Get an iterator to iterate over the members of an id property group.
115  Note that this will automatically free the iterator once iteration is complete;
116  if you stop the iteration before hitting the end, make sure to call
117  IDP_FreeIterBeforeEnd().*/
118 void *IDP_GetGroupIterator(struct IDProperty *prop);
119
120 /*Returns the next item in the iteration.  To use, simple for a loop like the following:
121  while (IDP_GroupIterNext(iter) != NULL) {
122         . . .
123  }*/
124 IDProperty *IDP_GroupIterNext(void *vself);
125
126 /*Frees the iterator pointed to at vself, only use this if iteration is stopped early; 
127   when the iterator hits the end of the list it'll automatially free itself.*/
128 void IDP_FreeIterBeforeEnd(void *vself);
129
130 /*-------- Main Functions --------*/
131 /*Get the Group property that contains the id properties for ID id.  Set create_if_needed
132   to create the Group property and attach it to id if it doesn't exist; otherwise
133   the function will return NULL if there's no Group property attached to the ID.*/
134 struct IDProperty *IDP_GetProperties(struct ID *id, int create_if_needed);
135
136 /*
137 Allocate a new ID.
138
139 This function takes three arguments: the ID property type, a union which defines
140 it's initial value, and a name.
141
142 The union is simple to use; see the top of this header file for its definition. 
143 An example of using this function:
144
145  IDPropertyTemplate val;
146  IDProperty *group, *idgroup, *color;
147  group = IDP_New(IDP_GROUP, val, "group1"); //groups don't need a template.
148
149  val.array.len = 4
150  val.array.type = IDP_FLOAT;
151  color = IDP_New(IDP_ARRAY, val, "color1");
152
153  idgroup = IDP_GetProperties(some_id, 1);
154  IDP_AddToGroup(idgroup, color);
155  IDP_AddToGroup(idgroup, group);
156
157 Note that you MUST either attach the id property to an id property group with 
158 IDP_AddToGroup or MEM_freeN the property, doing anything else might result in
159 a memory leak.
160 */
161 struct IDProperty *IDP_New(int type, IDPropertyTemplate val, char *name);
162 \
163 /*NOTE: this will free all child properties of list arrays and groups!
164   Also, note that this does NOT unlink anything!  Plus it doesn't free
165   the actual struct IDProperty struct either.*/
166 void IDP_FreeProperty(struct IDProperty *prop);
167
168 /*Unlinks any struct IDProperty<->ID linkage that might be going on.*/
169 void IDP_UnlinkProperty(struct IDProperty *prop);
170
171 #endif /* _BKE_IDPROP_H */