===Python API===
[blender.git] / source / blender / python / api2_2x / doc / Modifier.py
1 # Blender.Modifier module and the Modifier PyType object
2
3 """
4 The Blender.Modifier submodule
5
6 B{New}: 
7   -  provides access to Blender's modifier stack
8
9 This module provides access to the Modifier Data in Blender.
10
11 Example::
12   from Blender import *
13
14   ob = Object.Get('Cube')        # retrieve an object
15   mods = ob.modifiers            # get the object's modifiers
16   for mod in mods:
17     print mod,mod.name           # print each modifier and its name
18   mod = mods.append(Modifier.Type.SUBSURF) # add a new subsurf modifier
19   mod[Modifier.Settings.LEVELS] = 3     # set subsurf subdivision levels to 3
20   
21 @type Type: readonly dictionary
22 @var Type: Constant Modifier dict used for  L{ModSeq.append()} to a modifier sequence and comparing with L{Modifier.type}:
23     - ARMATURE - type value for Armature modifiers
24     - BOOLEAN - type value for Boolean modifiers
25     - BUILD - type value for Build modifiers
26     - CURVE - type value for Curve modifiers
27     - DECIMATE - type value for Decimate modifiers
28     - LATTICE - type value for Lattice modifiers
29     - SUBSURF - type value for Subsurf modifiers
30     - WAVE - type value for Wave modifiers
31
32 @type Settings: readonly dictionary
33 @var Settings: Constant Modifier dict used for changing modifier settings.
34         - RENDER - Used for all modifiers
35         - REALTIME - Used for all modifiers
36         - EDITMODE - Used for all modifiers
37         - ONCAGE - Used for all modifiers
38
39         - OBJECT - Used for Armature, Lattice, Curve, Boolean and Array
40         - VERTGROUP - Used for Armature, Lattice and Curve
41         - LIMIT - Array and Mirror
42         - FLAG - Mirror and Wave
43         - COUNT - Decimator and Array
44         
45         - TYPES - Used for Subsurf only
46         - LEVELS - Used for Subsurf only 
47         - RENDLEVELS - Used for Subsurf only
48         - OPTIMAL - Used for Subsurf only
49         - UV - Used for Subsurf only
50
51
52         - ENVELOPES - Used for Armature only
53         
54         - START - Used for Build only
55         - LENGTH - Used for Build only
56         - SEED - Used for Build only
57         - RANDOMIZE - Used for Build only
58
59         - AXIS - Used for Mirror only
60
61         - RATIO - Used for Decimate only
62         
63         - STARTX - Used for Wave only
64         - STARTY - Used for Wave only
65         - HEIGHT - Used for Wave only
66         - WIDTH - Used for Wave only
67         - NARROW - Used for Wave only
68         - SPEED - Used for Wave only
69         - DAMP - Used for Wave only
70         - LIFETIME - Used for Wave only
71         - TIMEOFFS - Used for Wave only
72         - OPERATION - Used for Wave only
73 """
74
75 class ModSeq:
76   """
77   The ModSeq object
78   =================
79   This object provides access to list of L{modifiers<Modifier.Modifier>} for a particular object.
80   Only accessed from L{Object.Object.modifiers}.
81   """
82
83   def __getitem__(index):
84     """
85     This operator returns one of the object's modifiers.
86     @type index: int
87     @return: an Modifier object
88     @rtype: Modifier
89     @raise KeyError: index was out of range
90     """
91
92   def __len__():
93     """
94     Returns the number of modifiers in the object's modifier stack.
95     @return: number of Modifiers
96     @rtype: int
97     """
98
99   def append(type):
100     """
101     Appends a new modifier to the end of the object's modifier stack.
102     @type type: a constant specifying the type of modifier to create. as from L{Type}
103     @rtype: Modifier
104     @return: the new Modifier
105     """
106
107   def remove(modifier):
108     """
109     Remove a modifier from this objects modifier sequence.
110     @type modifier: a modifier from this sequence to remove.
111     @note: Accessing attributes of the modifier after removing will raise an error.
112     """
113
114 class Modifier:
115   """
116   The Modifier object
117   ===================
118   This object provides access to a modifier for a particular object accessed from L{ModSeq}.
119   @ivar name: The name of this modifier. 31 chars max.
120   @type name: string
121   @ivar type: The type of this modifier. Read-only.  The returned value
122   matches the types in L{Type}.
123   @type type: int
124   """  
125
126   def __getitem__(key):
127     """
128     This operator returns one of the modifier's data attributes.
129     @type key: value from modifier's L{Modifier.Settings} constant
130     @return: the requested data
131     @rtype: varies
132     @raise KeyError: the key does not exist for the modifier
133     """
134
135   def __setitem__(key):
136     """
137     This operator modifiers one of the modifier's data attributes.
138     @type key: value from modifier's L{Modifier.Settings} constant
139     @raise KeyError: the key does not exist for the modifier
140     """
141
142   def up():
143     """
144     Moves the modifier up in the object's modifier stack.
145     @rtype: PyNone
146     @raise RuntimeError: request to move above another modifier requiring
147     original data
148     """
149
150   def down():
151     """
152     Moves the modifier down in the object's modifier stack.
153     @rtype: PyNone
154     @raise RuntimeError: request to move modifier beyond a non-deforming
155     modifier
156     """
157
158