1
2
3 """
4 The Blender.Library submodule.
5
6 Library
7 =======
8
9 This module provides access to objects stored in .blend files. With it scripts
10 can append from Blender files to the current scene, like the File->Append
11 menu entry in Blender does. It allows programmers to use .blend files as
12 data files for their scripts.
13
14 @warn: This module is being considered for deprecation. Users should
15 consider using the L{new Library<LibData>} module and stay tuned to see
16 which module is supported in the end.
17
18 Example::
19 import Blender
20 from Blender import Library
21
22 def f(name):
23 open_library(name)
24
25 def open_library(name):
26 Library.Open(name)
27 groups = Library.LinkableGroups()
28
29 for db in groups:
30 print "DATABLOCK %s:" % db
31 for obname in Library.Datablocks(db):
32 print obname
33
34 if 'Object' in groups:
35 for obname in Library.Datablocks('Object'):
36 Library.Load(obname, 'Object', 0) # note the 0...
37 Library.Update()
38
39 Library.Close()
40 b.Redraw()
41
42 b.Window.FileSelector(f, "Choose Library", "*.blend")
43
44 """
45
47 """
48 Open an existing .blend file. If there was already one open file, it is
49 closed first.
50 @type filename: string
51 @param filename: The filename of a Blender file. Filenames starting with "//" will be loaded relative to the blend file's location.
52 @rtype: bool
53 @return: 1 if successful. An IOError exception is thrown if the file cannot be opened.
54 """
55
57 """
58 Close the currently open library file, if any.
59 """
60
62 """
63 Get the filename of the currently open library file.
64 @rtype: string
65 @return: The open library filename.
66 """
67
69 """
70 Get all the linkable group names from the currently open library file. These
71 are the available groups for linking with the current scene. Ex: 'Object',
72 'Mesh', 'Material', 'Text', etc.
73 @rtype: list of strings
74 @return: the list of linkable groups.
75 """
76
78 """
79 Get all datablock objects of the given 'group' available in the currently
80 open library file.
81 @type group: string
82 @param group: datablock group, see L{LinkableGroups}.
83 """
84
85 -def Load (datablock, group, update = 1, linked = 0):
86 """
87 Load the given datablock object from the current library file
88 @type datablock: string
89 @type group: string
90 @type update: bool
91 @type linked: bool
92 @param datablock: an available object name, as returned by L{Datablocks}.
93 @param group: an available group name, as returned by L{LinkableGroups}.
94 @param update: defines if Blender should be updated after loading this
95 object. This means linking all objects and remaking all display lists,
96 so it is potentially very slow.
97 @param linked: Will keep objects linked to their source blend file, the update option or later updating will unlink the data from the original blend and make it local.
98
99 @warn: If you plan to load more than one object in sequence, it is
100 B{definitely recommended} to set 'update' to 0 in all calls to this
101 function and after them call L{Update}.
102 """
103
105 """
106 Update all links and display lists in Blender. This function should be
107 called after a series of L{Load}(datablock, group, B{0}) calls to make
108 everything behave nicely.
109 @warn: to use this function, remember to set the third L{Load} parameter to
110 zero or each loading will automatically update Blender, which will slow
111 down your script and make you look like a lousy programmer.
112 Enough warnings :)?
113 """
114