Patch by Matt Ebb: upgraded usablitiy of text button.
[blender.git] / source / blender / python / api2_2x / doc / Theme.py
1 # Blender.Window.Theme submodule and the Theme PyType object
2
3 """
4 The Blender.Window.Theme submodule.
5
6 Theme
7 =====
8
9 This module provides access to B{Theme} objects in Blender.
10
11 Example::
12   # this is a simplified version of the save_theme.py script
13   # shipped with Blender:
14   import Blender
15   from Blender.Window import Theme, FileSelector
16
17   theme = Theme.Get()[0] # get current theme
18
19   def write_theme(filename):
20     "Write the current theme as a BPython script"
21
22     f = file(filename, "w")
23
24     f.write("import Blender")
25     f.write("from Blender.Window import Theme")
26     f.write("theme = Theme.New('%s')" % theme.name)
27
28     for tsp in theme.get(): # write each theme space
29       command = "\\n%s = theme.get('%s')" % (tsp, tsp)
30       f.write(command + "\\n")
31       exec(command)
32       exec("vars = dir(%s)" % tsp)
33       vars.remove('theme')
34
35       for var in vars: # write each variable from each theme space
36         v = "%s.%s" % (tsp, var)
37         exec("value = %s" % v)
38         f.write("%s = %s\\n" % (v, value))
39
40     f.write('\\nBlender.Redraw(-1)') # redraw to update the screen
41     f.close()
42
43   FileSelector(write_theme, "Save Current Theme", default_fname)
44 """
45
46 def New (name = "New Theme", theme = '<default>'):
47   """
48   Create a new Theme object.
49   @type name: string
50   @param name: The name of the new theme.
51   @type theme: Blender Theme
52   @param theme: a base theme to copy all data from.  It defaults to the current
53       one.
54   @rtype:  Blender Theme
55   @return: A new Blender Theme object.
56   """
57
58 def Get (name = None):
59   """
60   Get the Theme object(s) from Blender.
61   @type name: string
62   @param name: The name of the Theme object.
63   @rtype: Blender Theme or a list of Blender Themes
64   @return: It depends on the I{name} parameter:
65       - (name): The Theme object called I{name}, None if not found;
66       - (): A list with all Theme objects currently in Blender.
67   """
68
69
70 class Theme:
71   """
72   The Theme object
73   ================
74     This object gives access to Themes in Blender.  Each Theme object is
75     composed of one UI (Use Interface) theme and many Space themes
76     (3d view, Text Editor, Buttons window, etc).
77   @ivar name: The name of this Theme object.
78   """
79
80   def getName():
81     """
82     Get the name of this Theme object.
83     @rtype: string
84     @return: the name of this Theme object.
85     """
86
87   def setName(s):
88     """
89     Rename this theme.
90     @type s: string
91     @param s: the new name.
92     """
93
94   def get(t = None):
95     """
96     Get a space or the ui (sub)theme from this Theme.
97     @type t: string, int or None
98     @param t: the wanted sub-theme as either:
99         - int: -1 for UI or the types in L{Window.Types<Window.Types>} for the others;
100         - string: use get() to know them (they are case insensitive);
101         - nothing: as written above, get() returns a list of names.
102     @rtype: Blender ThemeSpace or ThemeUI or list of sub-theme types as strings.
103     @return: It depends on the given parameter:
104       - (): a list with all available types, as strings;
105       - (type): the chosen sub-theme.
106     """
107
108   class ThemeUI:
109     """
110     The User Interface sub-theme
111     ============================
112       This can be accessed with theme.get(t), where t can be 'ui' or -1.
113       The available variables follow the internal (C coded) ThemeUI struct in
114       Blender.  Most of them represent rgba (red, green, blue, alpha) colors,
115       with each component in the range [0, 255].  There is more than one way to
116       access them.
117
118       Examples::
119         print outline.R
120         outline.r = 180 # it's case insensitive
121         outline[0] = 94 # 0 for red, 1 for green, ...
122         outline = [200, 200, 200, 255] # setting all components at once
123     @type theme: string
124     @ivar theme: the parent Theme for this object.
125     @ivar outline: theme rgba var.
126     @ivar neutral: theme rgba var.
127     @ivar action: theme rgba var.
128     @ivar setting: theme rgba var.
129     @ivar setting1: theme rgba var.
130     @ivar setting2: theme rgba var.
131     @ivar num: theme rgba var.
132     @ivar textfield: theme rgba var.
133         @ivar textfield_hi: theme rgba var.
134     @ivar popup: theme rgba var.
135     @ivar text: theme rgba var.
136     @ivar text_hi: theme rgba var.
137     @ivar menu_back: theme rgba var.
138     @ivar menu_item: theme rgba var.
139     @ivar menu_hilite: theme rgba var.
140     @ivar menu_text: theme rgba var.
141     @ivar menu_text_hi: theme rgba var.
142     @type drawType: int
143     @ivar drawType: the draw type (minimal, rounded, etc) in the range [1, 4].
144     """
145
146   class ThemeSpace:
147     """
148     The Space sub-themes
149     ====================
150       There is a sub-theme for each space in Blender (except for the Scripts
151       window, but it will be added soon).  Please read the information about
152       L{Theme.ThemeUI}, since it is also relevant here.  In Blender,
153       all theme spaces share the same C structure.  For this reason, all of
154       them here share the same variables, event though some spaces only use
155       a few of them.  This lower-level access is acceptable because generally
156       users will prefer to use the interface to change single theme options
157       and only use scripting to save or restore themes.  But anyway, checking
158       the Themes tab in the User Preferences space in Blender and using the
159       bundled "Save current theme" script (or its simplified version written
160       on the top of this page) can help you finding out any specific info you
161       may need.
162     @type theme: string
163     @ivar theme: the parent Theme for this object.
164     @ivar back: theme rgba var.
165     @ivar text: theme rgba var.
166     @ivar text_hi: theme rgba var.
167     @ivar header: theme rgba var.
168     @ivar panel: theme rgba var.
169     @ivar shade1: theme rgba var.
170     @ivar shade2: theme rgba var.
171     @ivar hilite: theme rgba var.
172     @ivar grid: theme rgba var.
173     @ivar wire: theme rgba var.
174     @ivar select: theme rgba var.
175     @ivar active: theme rgba var.
176     @ivar transform: theme rgba var.
177     @ivar vertex: theme rgba var.
178     @ivar vertex_select: theme rgba var.
179     @ivar edge: theme rgba var.
180     @ivar edge_select: theme rgba var.
181     @ivar edge_seam: theme rgba var.
182     @ivar edge_facesel: theme rgba var.
183     @ivar face: theme rgba var.
184     @ivar face_select: theme rgba var.
185     @ivar face_dot: theme rgba var.
186     @ivar normal: theme rgba var.
187     @ivar syntaxl: theme rgba var.
188     @ivar syntaxn: theme rgba var.
189     @ivar syntaxb: theme rgba var.
190     @ivar syntaxv: theme rgba var.
191     @ivar syntaxc: theme rgba var.
192     @type vertex_size: int
193     @ivar vertex_size: size of the vertices dots on screen in the range [1, 10].
194     @type facedot_size: int
195     @ivar facedot_size: size of the face dots on screen in the range [1, 10].
196     """
197