source/blender/blenkernel/BKE_idprop.h

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