a5757b0dbef880119836da4bd744e7d793ee8a7b
[blender.git] / source / blender / python / api2_2x / doc / Library.py
1 # Blender.Library submodule
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 is a new, still experimental module.
15
16 Example::
17   import Blender
18   from Blender import Library
19
20   def f(name):
21     open_library(name)
22
23   def open_library(name):
24     Library.Open(name)
25     groups = Library.LinkableGroups()
26
27     for db in groups:
28       print "DATABLOCK %s:" % db
29       for obname in Library.Datablocks(db):
30         print obname
31  
32     if 'Object' in groups:
33       for obname in Library.Datablocks('Object'):
34         Library.Load(obname, 'Object', 0) # note the 0...
35       Library.Update()
36
37     Library.Close()
38     b.Redraw()
39
40   b.Window.FileSelector(f, "Choose Library", "*.blend")
41
42 """
43
44 def Open (filename):
45   """
46   Open an existing .blend file.  If there was already one open file, it is
47   closed first.
48   @type filename: string
49   @param filename: The filename of a Blender file.
50   @rtype: bool
51   @return: 1 if succesful, 0 otherwise.
52   """
53
54 def Close ():
55   """
56   Close the currently open library file, if any.
57   """
58
59 def getName ():
60   """
61   Get the filename of the currently open library file.
62   @rtype: string
63   @return: The open library filename.
64   """
65
66 def LinkableGroups ():
67   """
68   Get all the linkable group names from the currently open library file.  These
69   are the available groups for linking with the current scene.  Ex: 'Object',
70   'Mesh', 'Material', 'Text', etc.
71   @rtype: list of strings
72   @return: the list of linkable groups.
73   """
74
75 def Datablocks (group):
76   """
77   Get all datablock objects of the given 'group' available in the currently
78   open library file.
79   @type group: string
80   @param group: datablock group, see L{LinkableGroups}.
81   """
82
83 def Load (datablock, group, update = 1):
84   """
85   Load the given datablock object from the current library file
86   @type datablock: string
87   @type group: string
88   @type update: bool
89   @param datablock: an available object name, as returned by L{Datablocks}.
90   @param group: an available group name, as returned by L{LinkableGroups}.
91   @param update: defines if Blender should be updated after loading this
92       object.  This means linking all objects and remaking all display lists,
93       so it is potentially very slow.
94
95   @warn: If you plan to load more than one object in sequence, it is
96      B{definitely recommended} to set 'update' to 0 in all calls to this
97      function and after them call L{Update}.
98   """
99
100 def Update ():
101   """
102   Update all links and display lists in Blender.  This function should be
103   called after a series of L{Load}(datablock, group, B{0}) calls to make
104   everything behave nicely.
105   @warn: to use this function, remember to set the third L{Load} parameter to
106      zero or each loading will automatically update Blender, which will slow
107      down your script and make you look like a lousy programmer.
108      Enough warnings :)?
109   """
110