always adjust the frames size and position together, so there is no more weird resizi...
[mikachu/openbox.git] / doc / python / openbox.txt
1 ob.Openbox
2
3 ----
4
5 This document describes the 'Openbox' class, exposed by Openbox's 'ob' module
6 to its python scripts.
7
8 ----
9
10 Methods
11
12 ----
13
14 shutdown()
15
16 Causes Openbox to shutdown and exit.
17
18
19 ----
20
21 restart([path])
22
23 Causes Openbox to shutdown and restart. If path is specified, Openbox will
24 shutdown and attempt to run the specified executable instead of restarting
25 itself. If that fails, however, it will restart itself.
26
27         path: Optional path to replacement executable.
28
29 ----
30
31 state()
32
33 Returns Openbox's current state, this will be one of the State constants.
34
35         Returns: One of the State values representing the internal state
36                  of Openbox.
37
38 ----
39
40 desktop()
41
42 Returns the number of the currently visible desktop. This will be in the range
43 of [0, numDesktops()).
44
45         Returns: The currently visible desktop.
46
47 ----
48
49 setDesktop(desktop)
50
51 Sets the specified desktop as the visible desktop.
52
53         desktop: The desktop to make visible. Must be in the range of
54                  [0, numDesktops()) or a ValueError exception will be raised.
55
56 ----
57
58 setNextDesktop([wrap])
59
60 Sets the visible desktop to the next desktop, optionally wrapping around when
61 reaching the last.
62
63         wrap: An optional argument which, when True will cause the function to
64               wrap to the first desktop when going past the last. If it is not
65               specified, it defaults to true.
66
67 ----
68
69 setPreviousDesktop([wrap])
70
71 Sets the visible desktop to the previous desktop, optionally wrapping around
72 when reaching the first.
73
74         wrap: An optional argument which, when True will cause the function to
75               wrap to the last desktop when going past the first. If it is not
76               specified, it defaults to true.
77
78 ----
79
80 numDesktops()
81
82 Returns the number of desktops available.
83
84         Returns: The number of available desktops.
85
86 ----
87
88 setNumDesktops(num)
89
90 Sets the number of desktops available.
91
92         num: The new number of available desktops. This must be greater than 0.
93
94 ----
95
96 desktopNames()
97
98 Returns a tuple of names, containing a name for each desktop. The tuple may
99 have a length greater than numDesktops() if more names have been specified.
100
101         Returns: A tuple of names.
102
103 ----
104
105 setDesktopNames(names)
106
107 Sets the names for the desktops.
108
109         names: An iterable list of names to apply to the desktops. Can contain
110                more or less names than numDesktops(). If it contains fewer
111                names, then Openbox will give the remaining desktops a
112                placeholder name.
113
114 ----
115
116 showingDesktop()
117
118 Returns True or False, depicting if Openbox is in 'showing the desktop' mode.
119 In 'showing the desktop' mode, all normal clients are hidden and the desktop
120 is given focus if possible.
121
122         Returns: True or False describing if Openbox is in 'showing the
123                  desktop' mode.
124
125 ----
126
127 setShowingDesktop(show)
128
129 Enters or leaves 'showing the desktop' mode. See showingDesktop() for a
130 description of this mode.
131
132         show: True or False to enter or leave 'showing the desktop' mode
133               respectively.
134
135 ----
136
137 screenArea(desktop)
138
139 Returns the on-screen available area. This is the area not reserved by
140 applications' struts. Windows should be placed within this area, not within
141 the physicalSize().
142
143         desktop: The desktop for which to get the available area. 0xffffffff to
144                  get the combined area for all desktops (combined
145                  subtractively).
146
147         Returns: A tuple of form (x, y, width, height) containing the
148                  dimensions of the available on-screen area for the desktop.
149
150
151 ----
152
153 screenStrut(desktop)
154
155 Returns the combined strut which has been reserved by all applications on the
156 desktops.
157
158         desktop: The desktop for which to get the strut. 0xffffffff to get the
159                  combined strut for all desktops (combined additively).
160
161         Returns: A tuple of form (left, top, right, bottom) containing the
162                  size of the reserved strut space for the desktop.
163
164 ----
165
166 physicalSize()
167
168 Returns the physical size of the display device (in pixels).
169
170         Returns: A tuple of the form (width, height) containing the size of
171                  the display device's area.
172
173 ----
174
175 screenNumber()
176
177 Returns the number of the screen on which Openbox is running.
178
179         Returns: An integer specifying the screen on which this instance of
180                  Openbox is running.
181
182 ----
183
184 rootWindow()
185
186 Return the window id of the root window.
187
188         Returns: An integer containing the window id of the root window.
189
190 ----
191
192 clientList()
193
194 Returns a all clients currently being managed by Openbox. This list is updated
195 as clients are managed and closed/destroyed/released.
196
197         Returns: A list of Clients containing all the clients managed by
198                  Openbox.
199
200 ----
201
202 ob.State
203
204 State.Starting: Openbox is starting up and has not yet reached its
205                 main event loop.
206 State.Running:  Openbox is running normally.
207 State.Exiting:  Openbox has left its main event loop and is shutting
208                 down.