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.