Replaced old fly mode for a fly mode that works in all 3 view types - ortho, perspect...
[blender-staging.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 bone_solid: theme rgba var.
188   @ivar bon_pose: theme rgba var.
189   @ivar strip: theme rgba var.
190   @ivar strip_select: theme rgba var.
191   @ivar syntaxl: theme rgba var.
192   @ivar syntaxn: theme rgba var.
193   @ivar syntaxb: theme rgba var.
194   @ivar syntaxv: theme rgba var.
195   @ivar syntaxc: theme rgba var.
196   @type vertex_size: int
197   @ivar vertex_size: size of the vertices dots on screen in the range [1, 10].
198   @type facedot_size: int
199   @ivar facedot_size: size of the face dots on screen in the range [1, 10].
200   """
201