1
2
3
4
5
6
7
8
9
10 """
11 The main Blender module.
12
13 B{New}: L{Run}, L{UpdateMenus}, new options to L{Get}, L{ShowHelp},
14 L{SpaceHandlers} dictionary.
15 L{UnpackModes} dictionary.
16
17 Blender
18 =======
19
20 @type bylink: bool
21 @var bylink: True if the current script is being executed as a script link.
22 @type link: Blender Object or None; integer (space handlers)
23 @var link: for normal script links, 'link' points to the linked Object (can be
24 a scene, object (mesh, camera, lamp), material or
25 world). For space handler script links, 'link' is an integer from the
26 Blender.L{SpaceHandlers} dictionary. For script not running as script
27 links, 'link' is None.
28 @type event: string or int
29 @var event: this has three possible uses: script link type or events callback
30 ascii value:
31 - for normal script links it is a string representing the link type
32 (OnLoad, FrameChanged, Redraw, etc.).
33 - for EVENT space handler script links it is the passed event.
34 - for normal L{GUI<Draw.Register>} scripts I{during the events callback},
35 it holds the ascii value of the current event, if it is a valid one.
36 Users interested in this should also check the builtin 'ord' and 'chr'
37 Python functions.
38 @type mode: string
39 @var mode: Blender's current mode:
40 - 'interactive': normal mode, with an open window answering to user input;
41 - 'background': Blender was started as 'C{blender -b <blender file>}' and
42 will exit as soon as it finishes rendering or executing a script
43 (ex: 'C{blender -b <blender file> -P <script>}'). Try 'C{blender -h}'
44 for more detailed informations.
45 @type UnpackModes: constant dictionary
46 @var UnpackModes: dictionary with available unpack modes.
47 - USE_LOCAL - use files in current directory (create when necessary)
48 - WRITE_LOCAL - write files in current directory (overwrite when necessary)
49 - USE_ORIGINAL - use files in original location (create when necessary)
50 - WRITE_ORIGINAL - write files in original location (overwrite when necessary)
51 @type SpaceHandlers: constant dictionary
52 @var SpaceHandlers: dictionary with space handler types.
53 - VIEW3D_EVENT;
54 - VIEW3D_DRAW.
55 """
56
57 -def Set (request, data):
58 """
59 Update settings in Blender.
60 @type request: string
61 @param request: The setting to change:
62 - 'curframe': the current animation frame
63 - 'compressfile' : compress file writing a blend file (Use a boolean value True/False).
64 - 'uscriptsdir': user scripts dir
65 - 'yfexportdir': yafray temp xml storage dir
66 - 'fontsdir': font dir
67 - 'texturesdir': textures dir
68 - 'seqpluginsdir': sequencer plugin dir
69 - 'renderdir': default render output dir
70 - 'soundsdir': sound dir
71 - 'tempdir': temp file storage dir
72 - 'mipmap' : Use mipmapping in the 3d view (Use a boolean value True/False).
73 @type data: int or string
74 @param data: The new value.
75 """
76
78 """
79 Retrieve settings from Blender.
80 @type request: string
81 @param request: The setting data to be returned:
82 - 'curframe': the current animation frame.
83 - 'curtime' : the current animation time.
84 - 'compressfile' : compress setting from the file menu, return 0 for false or 1 for true.
85 - 'staframe': the start frame of the animation.
86 - 'endframe': the end frame of the animation.
87 - 'rt': the value of the 'rt' button for general debugging
88 - 'filename': the name of the last file read or written.
89 - 'homedir': Blender's home directory.
90 - 'datadir' : the path to the dir where scripts should store and
91 retrieve their data files, including saved configuration (can
92 be None, if not found).
93 - 'udatadir': the path to the user defined data dir. This may not be
94 available (is None if not found), but users that define uscriptsdir
95 have a place for their own scripts and script data that won't be
96 erased when a new version of Blender is installed. For this reason
97 we recommend scripts check this dir first and use it, if available.
98 - 'scriptsdir': the path to the main dir where scripts are stored.
99 - 'uscriptsdir': the path to the user defined dir for scripts. (*)
100 - 'icondir': the path to blenders icon theme files.
101 - 'yfexportdir': the path to the user defined dir for yafray export. (*)
102 - 'fontsdir': the path to the user defined dir for fonts. (*)
103 - 'texturesdir': the path to the user defined dir for textures. (*)
104 - 'texpluginsdir': the path to the user defined dir for texture plugins. (*)
105 - 'seqpluginsdir': the path to the user defined dir for sequence plugins. (*)
106 - 'renderdir': the path to the user defined dir for render output. (*)
107 - 'soundsdir': the path to the user defined dir for sound files. (*)
108 - 'tempdir': the path to the user defined dir for storage of Blender
109 temporary files. (*)
110 - 'mipmap' : Use mipmapping in the 3d view. (*)
111 - 'version' : the Blender version number.
112 @note: (*) these can be set in Blender at the User Preferences window -> File
113 Paths tab.
114 @warn: this function returns None for requested dir paths that have not been
115 set or do not exist in the user's file system.
116 @return: The requested data or None if not found.
117 """
118
120 """
121 Returns a list of files this blend file uses: (libraries, images, sounds, fonts, sequencer movies).
122 @type absolute: bool
123 @param absolute: When true, the absolute paths of every file will be returned.
124 @return: A list for paths (strings) that this blend file uses.
125 """
126
128 """
129 Redraw all 3D windows.
130 """
131
132 -def Load (filename = None):
133 """
134 Load a Blender .blend file or any of the other supported file formats.
135
136 Supported formats:
137 - Blender's .blend;
138 - DXF;
139 - Open Inventor 1.0 ASCII;
140 - Radiogour;
141 - STL;
142 - Videoscape;
143 - VRML 1.0 asc.
144
145 @type filename: string
146 @param filename: the pathname to the desired file. If 'filename'
147 isn't given or if it contains the substring '.B.blend', the default
148 .B.blend file is loaded.
149
150 @warn: loading a new .blend file removes the current data in Blender. For
151 safety, this function saves the current data as an auto-save file in
152 the temporary dir used by Blender before loading a new Blender file.
153 @warn: after a call to Load(blendfile), current data in Blender is lost,
154 including the Python dictionaries. Any posterior references in the
155 script to previously defined data will generate a NameError. So it's
156 better to put Blender.Load as the last executed command in the script,
157 when this function is used to open .blend files.
158 @warn: if in edit mode, this function leaves it, since Blender itself
159 requires that.
160 @note: for all types except .blend files, this function only works in
161 interactive mode, not in background, following what Blender itself does.
162 """
163
164 -def Save (filename, overwrite = 0):
165 """
166 Save a Blender .blend file with the current program data or export to
167 one of the builtin file formats.
168
169 Supported formats:
170 - Blender (.blend);
171 - DXF (.dxf);
172 - STL (.stl);
173 - Videoscape (.obj);
174 - VRML 1.0 (.wrl).
175
176 @type filename: string
177 @param filename: the filename for the file to be written. It must have one
178 of the supported extensions or an error will be returned.
179 @type overwrite: int (bool)
180 @param overwrite: if non-zero, file 'filename' will be overwritten if it
181 already exists (can be checked with L{Blender.sys.exists<Sys.exists>}.
182 By default existing files are not overwritten (an error is returned).
183
184 @note: The substring ".B.blend" is not accepted inside 'filename'.
185 @note: DXF, STL and Videoscape export only B{selected} meshes.
186 """
187
189 """
190 Execute the given script.
191 @type script: string
192 @param script: the name of an available Blender Text (use L{Text.Get}() to
193 get a complete list) or the full pathname to a Python script file in the
194 system.
195 @note: the script is executed in its own context -- with its own global
196 dictionary -- as if it had been executed from the Text Editor or chosen
197 from a menu.
198 """
199
201 """
202 Show help for the given script. This is a time-saver ("code-saver") for
203 scripts that need to feature a 'help' button in their GUIs or a 'help'
204 submenu option. With proper documentation strings, calling this function is
205 enough to present a screen with help information plus link and email buttons.
206 @type script: string
207 @param script: the filename of a registered Python script.
208 @note: this function uses L{Run} and the "Scripts Help Browser" script. This
209 means that it expects proper doc strings in the script to be able to show
210 help for it (otherwise it offers to load the script source code as text).
211 The necessary information about doc strings is L{given here<API_related>}.
212 @note: 'script' doesn't need to be a full path name: "filename.py" is enough.
213 Note, though, that this function only works for properly registered
214 scripts (those that appear in menus).
215 """
216
218 """
219 Update the menus that list registered scripts. This will scan the default
220 and user defined (if available) folder(s) for scripts that have registration
221 data and will make them accessible via menus.
222 @note: only scripts that save other new scripts in the default or user
223 defined folders need to call this function.
224 """
226 """
227 Unpack all files with specified mode.
228 @param mode: The Mode for unpacking. Must be one of the modes in
229 Blender.UnpackModes dictionary.
230 @type mode: int
231 """
233 """
234 Pack all files.
235 """
236
238 """
239 Returns the number of packed files.
240 """
241
243 """
244 Exit from Blender immediately.
245 @warn: the use of this function should obviously be avoided, it is available
246 because there are some cases where it can be useful, like in automated
247 tests. For safety, a "quit.blend" file is saved (normal Blender behavior
248 upon exiting) when this function is called, so the data in Blender isn't
249 lost.
250 """
252 """
253 Sets an undo at the current state.
254 @param message: Message that appiers in the undo menu
255 @type message: string
256 """
257