make python config variables very visible by making them all capitals. cleaner nicer documentation in the py modules. make public functions more visible.

8 files changed, 168 insertions, 165 deletions

diff --git a/scripts/callbacks.py b/scripts/callbacks.py
index 7f7be663..8c220e64 100644
--- a/scripts/callbacks.py
+++ b/scripts/callbacks.py
@@ -6,8 +6,14 @@ import ob
 import otk
 
 StateRemove = 0
+"""For the state_* callbacks. Indicates the state should be removed from the
+   window."""
 StateAdd = 1
+"""For the state_* callbacks. Indicates the state should be add to the
+   window."""
 StateToggle = 2
+"""For the state_* callbacks. Indicates the state should be toggled on the
+   window."""
 
 def state_above(data, add=StateAdd):
     """Toggles, adds or removes the 'above' state on a window.
diff --git a/scripts/config.py b/scripts/config.py
index 823d9d3f..e27b8d6f 100644
--- a/scripts/config.py
+++ b/scripts/config.py
@@ -1,34 +1,36 @@
 #############################################################################
-### Options that can be defined on startup that affect the behavior of    ###
-### openbox.                                                              ###
+### Options that can be changed to adjust the behavior of Openbox.        ###
 #############################################################################
 
-# theme - the theme used to decorate everything.
-theme = "/usr/local/share/openbox/styles/fieron2"
-
-# titlebar_layout - the layout of the buttons/label on client titlebars, can be
-#                   made up of the following:
-#                   I - iconify button, L - text label, M - maximize button,
-#                   D - all-desktops button, C - close button
-#                   If no 'L' is included in the string, one will be added to
-#                   the end by Openbox.
-titlebar_layout = "DILMC"
-
-# double_click_delay - the number of milliseconds in which 2 clicks are
-#                      perceived as a double-click.
-double_click_delay = 300
-
-# drag_threshold - the amount of pixels that you have to drag the mouse before
-#                  motion events will start occuring.
-drag_threshold = 3
-
-# desktop_names - the name of each desktop
-desktop_names = ["one", "two", "three", "four", "five", "six", "seven", \
+THEME = "/usr/local/share/openbox/styles/fieron2"
+"""The theme used to decorate everything."""
+
+TITLEBAR_LAYOUT = "DILMC"
+"""The layout of the buttons/label on client titlebars, can be made up of the
+following:
+    I - iconify button
+    L - text label
+    M - maximize button,
+    D - all-desktops button
+    C - close button
+If no 'L' is included in the string, one will be added to the end by
+Openbox."""
+
+DOUBLE_CLICK_DELAY = 300
+"""The number of milliseconds in which 2 clicks are perceived as a
+double-click."""
+
+DRAG_THRESHOLD = 3
+"""The amount of pixels that you have to drag the mouse before motion events
+will start occuring."""
+
+DESKTOP_NAMES = ["one", "two", "three", "four", "five", "six", "seven", \
                  "eight", "nine", "ten", "eleven", "twelve"]
+"""The name of each desktop."""
 
-# number_of_desktops - the number of desktops/workspaces which can be scrolled
-#                      between.
-number_of_desktops = 4
+NUMBER_OF_DESKTOPS = 4
+"""The number of desktops/workspaces which can be scrolled between."""
 
+#############################################################################
 
 print "Loaded config.py"
diff --git a/scripts/defaults.py b/scripts/defaults.py
index fa66329b..6467cf8e 100644
--- a/scripts/defaults.py
+++ b/scripts/defaults.py
@@ -6,7 +6,7 @@ import windowplacement # use a routine in here to place windows
 import historyplacement # history window placement
 
 # try focus something when nothing is focused
-focus.fallback = 1
+focus.FALLBACK = 1
 
 # choose a default focus model
 focusmodel.setup_click_focus() # use focusmodel.setup_sloppy_focus() instead to
@@ -23,7 +23,7 @@ ob.ebind(ob.EventAction.PlaceWindow, historyplacement.place)
 def histplace(data):
     if data.client.appClass() == "XTerm": return 0
     return 1
-historyplacement.confirm_callback = histplace
+historyplacement.CONFIRM_CALLBACK = histplace
 
 
 # run xterm from root clicks
@@ -40,7 +40,7 @@ ob.kbind(["A-S-Tab"], ob.KeyContext.All, stackedcycle.previous
 # if you want linear cycling instead of stacked cycling, comment out the focus
 # bindings above, and use these instead.
 #import focuscycle
-#focuscycle.raise_window = 0 # don't raise windows when they're activated
+#focuscycle.RAISE_WINDOW = 0 # don't raise windows when they're activated
 #ob.kbind(["A-Tab"], ob.KeyContext.All, focuscycle.next)
 #ob.kbind(["A-S-Tab"], ob.KeyContext.All, focuscycle.previous)
 
diff --git a/scripts/focus.py b/scripts/focus.py
index 97030013..b1b169e1 100644
--- a/scripts/focus.py
+++ b/scripts/focus.py
@@ -5,11 +5,11 @@
 ###########################################################################
 ###         Options that affect the behavior of the focus module.       ###
 ###########################################################################
-avoid_skip_taskbar = 1
+AVOID_SKIP_TASKBAR = 1
 """Don't focus windows which have requested to not be displayed in taskbars.
    You will still be able to focus the windows, but not through cycling, and
    they won't be focused as a fallback if 'fallback' is enabled."""
-fallback = 0
+FALLBACK = 0
 """Send focus somewhere when nothing is left with the focus, if possible."""
 ###########################################################################
 
@@ -29,7 +29,7 @@ _disable = 0
 def _focusable(client, desktop):
     if not client.normal(): return 0
     if not (client.canFocus() or client.focusNotify()): return 0
-    if avoid_skip_taskbar and client.skipTaskbar(): return 0
+    if AVOID_SKIP_TASKBAR and client.skipTaskbar(): return 0
 
     desk = client.desktop()
     if not (desk == 0xffffffff or desk == desktop): return 0
@@ -46,7 +46,7 @@ def _focused(data):
         # move it to the top
         _clients.remove(win)
         _clients.insert(0, win)
-    elif fallback:
+    elif FALLBACK:
         # pass around focus
         desktop = ob.openbox.screen(data.screen).desktop()
         for w in _clients:
diff --git a/scripts/focuscycle.py b/scripts/focuscycle.py
index 36354af2..770bbfb3 100644
--- a/scripts/focuscycle.py
+++ b/scripts/focuscycle.py
@@ -5,7 +5,7 @@
 ###########################################################################
 ###     Options that affect the behavior of the focuscycle module.      ###
 ###########################################################################
-raise_window = 1
+RAISE_WINDOW = 1
 """When cycling focus, raise the window chosen as well as focusing it. This
    does not affect fallback focusing behavior."""
 # See focus.avoid_skip_taskbar
@@ -58,7 +58,7 @@ def _cycle(data, num, forward):
         while 1:
             client = screen.client(t)
             if client and focus._focusable(client, desktop) and client.focus():
-                if raise_window:
+                if RAISE_WINDOW:
                     screen.raiseWindow(client)
                 return
             if forward:
diff --git a/scripts/historyplacement.py b/scripts/historyplacement.py
index 237fcb71..d4e7d465 100644
--- a/scripts/historyplacement.py
+++ b/scripts/historyplacement.py
@@ -6,33 +6,36 @@
 import windowplacement # fallback routines
 
 ##############################################################################
-### Options for the historyplacement module (Options in the                ###
-### windowplacement module also apply!):                                   ###
-###                                                                        ###
-# ignore_requested_positions - When true, the placement algorithm will     ###
-###                            attempt to place windows even when they     ###
-###                            request a position (like XMMS).             ###
-###                            Note this only applies to normal windows,   ###
-###                            not to special cases like desktops and      ###
-###                            docks.                                      ###
-ignore_requested_positions = 0                                             ###
-###                                                                        ###
-# fallback - The window placement algorithm that will be used when history ###
-###          placement does not have a place for the window.               ###
-fallback = windowplacement.random                                          ###
-###                                                                        ###
-# confirm_callback - set this to a function to have the function called    ###
-###                  before attempting to place a window via history. If   ###
-###                  the function returns 'true' then an attempt will be   ###
-###                  made to place the window. If it returns 'false', the  ###
-###                  fallback method will be directly applied instead.     ###
-confirm_callback = 0                                                       ###
-###                                                                        ###
-# filename - The name of the file where history data will be stored. The   ###
-###          number of the screen is appended onto this filename.          ###
-filename = 'historydb'                                                     ###
-###                                                                        ###
+###       Options for the historyplacement module (Options in the          ###
+###                windowplacement module also apply!)                     ###
 ##############################################################################
+IGNORE_REQUESTED_POSITIONS = 0
+"""When true, the placement algorithm will attempt to place windows even
+   when they request a position (like XMMS). Note this only applies to
+   normal windows, not to special cases like desktops and docks."""
+FALLBACK = windowplacement.random
+"""The window placement algorithm that will be used when history placement
+   does not have a place for the window."""
+CONFIRM_CALLBACK = 0
+"""Set this to a function to have the function called before attempting to
+   place a window via history. If the function returns a non-zero, then an
+   attempt will be made to place the window. If it returns zero, the
+   fallback method will be directly applied instead."""
+FILENAME = 'historydb'
+"""The name of the file where history data will be stored. The number of
+   the screen is appended onto this filename."""
+##############################################################################
+
+def place(data):
+    """Place a window usingthe history placement algorithm."""
+    _place(data)
+
+###########################################################################
+###########################################################################
+
+###########################################################################
+###      Internal stuff, should not be accessed outside the module.     ###
+###########################################################################
 
 import otk
 import ob
@@ -57,7 +60,7 @@ class _state:
 
 def _load(data):
     global _data
-    file = open(os.environ['HOME']+'/.openbox/'+filename+"."+str(data.screen),
+    file = open(os.environ['HOME']+'/.openbox/'+FILENAME+"."+str(data.screen),
                 'r')
     if file:
         # read data
@@ -80,7 +83,7 @@ def _load(data):
 
 def _save(data):
     global _data
-    file = open(os.environ['HOME']+'/.openbox/'+filename+"."+str(data.screen),
+    file = open(os.environ['HOME']+'/.openbox/'+FILENAME+"."+str(data.screen),
                 'w')
     if file:
         while len(_data)-1 < data.screen:
@@ -110,14 +113,14 @@ def _find(screen, state):
             _data.append([])
         return _find(screen, state) # try again
 
-def place(data):
+def _place(data):
     global _data
     if data.client:
-        if not (ignore_requested_positions and data.client.normal()):
+        if not (IGNORE_REQUESTED_POSITIONS and data.client.normal()):
             if data.client.positionRequested(): return
         state = _create_state(data)
         try:
-            if not confirm_callback or confirm_callback(data):
+            if not CONFIRM_CALLBACK or CONFIRM_CALLBACK(data):
                 print "looking for : " + state.appname +  " : " + \
                       state.appclass + " : " + state.role
 
@@ -132,7 +135,7 @@ def place(data):
                     print "No match in history"
         except TypeError:
             pass
-    if fallback: fallback(data)
+    if FALLBACK: FALLBACK(data)
 
 def _save_window(data):
     global _data
diff --git a/scripts/motion.py b/scripts/motion.py
index 03546b84..8cc89050 100644
--- a/scripts/motion.py
+++ b/scripts/motion.py
@@ -4,50 +4,54 @@
 ############################################################################
 
 #############################################################################
-### Options that can be modified to change the functions' behaviors.      ###
-###                                                                       ###
-# edge_resistance - the amount of resistance to provide to moving a       ###
-###                 window past a screen boundary. Specify a value of 0   ###
-###                 to disable edge resistance.                           ###
-edge_resistance = 10                                                      ###
-###                                                                       ###
-# move_popup - display a coordinates popup when moving windows.           ###
-move_popup = 1                                                            ###
-###                                                                       ###
-# NOT IMPLEMENTED (yet?)                                                  ###
-# move_rubberband - display an outline while moving instead of moving the ###
-###                 actual window, until the move is completed. Good for  ###
-###                 slower systems.                                       ###
-move_rubberband = 0                                                       ###
-###                                                                       ###
-# resize_popup - display a size popup when resizing windows.              ###
-resize_popup = 1                                                          ###
-###                                                                       ###
-# NOT IMPLEMENTED (yet?)                                                  ###
-# resize_rubberband - display an outline while resizing instead of        ###
-###                   resizing the actual window, until the resize is     ###
-###                   completed. Good for slower systems.                 ###
-resize_rubberband = 0                                                     ###
-###                                                                       ###
-# resize_nearest - 1 to resize from the corner nearest where the mouse    ###
-###                is, 0 to resize always from the bottom right corner.   ###
-resize_nearest = 1                                                        ###
-###                                                                       ###
-###                                                                       ###
-# Provides:                                                               ###
-# def move(data):                                                         ###
-#     """Moves the window interactively. This should only be used with    ###
-#        MouseMotion events. If move_popup or move_rubberband is enabled, ###
-#        then the end_move function needs to be bound as well."""         ###
-# def end_move(data):                                                     ###
-#     """Complete the interactive move of a window."""                    ###
-# def resize(data):                                                       ###
-#     """Resizes the window interactively. This should only be used with  ###
-#        MouseMotion events"""                                            ###
-# def end_resize(data):                                                   ###
-#     """Complete the interactive resize of a window."""                  ###
-###                                                                       ###
+###   Options that can be modified to change the functions' behaviors.    ###
 #############################################################################
+EDGE_RESISTANCE = 10
+"""The amount of resistance to provide to moving a window past a screen
+   boundary. Specify a value of 0 to disable edge resistance."""
+MOVE_POPUP = 1
+"""Display a coordinates popup when moving windows."
+MOVE_RUBBERBAND = 0
+"""NOT IMPLEMENTED (yet?)
+   Display an outline while moving instead of moving the actual window,
+   until the move is completed. Good for slower systems."""
+RESIZE_POPUP = 1
+"""Display a size popup when resizing windows."""
+RESIZE_RUBBERBAND = 0
+"""NOT IMPLEMENTED (yet?)
+   Display an outline while resizing instead of resizing the actual
+   window, until the resize is completed. Good for slower systems."""
+RESIZE_NEAREST = 1
+"""Non-zero to resize from the corner nearest where the mouse is, 0 to
+   resize always from the bottom right corner."""
+#############################################################################
+
+def move(data):
+    """Moves the window interactively. This should only be used with
+       MouseAction.Motion events. If MOVE_POPUP or MOVE_RUBBERBAND is enabled,
+       then the end_move function needs to be bound as well."""
+    _move(data)
+
+def end_move(data):
+    """Complete the interactive move of a window."""
+    _end_move(data)
+
+def resize(data):
+    """Resizes the window interactively. This should only be used with
+       MouseMotion events. If RESIZE_POPUP or RESIZE_RUBBERBAND is enabled,
+       then the end_resize function needs to be bound as well."""
+    _resize(data)
+
+def end_resize(data):
+    """Complete the interactive resize of a window."""
+    _end_resize(data)
+
+###########################################################################
+###########################################################################
+
+###########################################################################
+###      Internal stuff, should not be accessed outside the module.     ###
+###########################################################################
 
 import ob
 import otk
@@ -80,9 +84,9 @@ def _motion_grab(data):
         # have all the modifiers this started with been released?
         if not _motion_mask & data.state:
             if _inmove:
-                end_move(data)
+                _end_move(data)
             elif _inresize:
-                end_resize(data)
+                _end_resize(data)
             else:
                 raise RuntimeError
 
@@ -96,9 +100,8 @@ def _do_move():
     x = _cx + _dx + _client.frame.rect().x() - _client.area().x()
     y = _cy + _dy + _client.frame.rect().y() - _client.area().y()
 
-    global edge_resistance
     global _last_x, _last_y
-    if edge_resistance:
+    if EDGE_RESISTANCE:
         fs = _client.frame.size()
         w = _client.area().width() + fs.left + fs.right
         h = _client.area().height() + fs.top + fs.bottom
@@ -109,16 +112,16 @@ def _do_move():
         t = area.top()
         b = area.bottom() - h + 1
         # left screen edge
-        if _last_x > x and x < l and x >= l - edge_resistance:
+        if _last_x > x and x < l and x >= l - EDGE_RESISTANCE:
             x = l
         # right screen edge
-        if _last_x < x and x > r and x <= r + edge_resistance:
+        if _last_x < x and x > r and x <= r + EDGE_RESISTANCE:
             x = r
         # top screen edge
-        if _last_y > y and y < t and y >= t - edge_resistance:
+        if _last_y > y and y < t and y >= t - EDGE_RESISTANCE:
             y = t
         # right screen edge
-        if _last_y < y and y > b and y <= b + edge_resistance:
+        if _last_y < y and y > b and y <= b + EDGE_RESISTANCE:
             y = b
 
     global _inmove
@@ -129,15 +132,13 @@ def _do_move():
         _last_x = x
         _last_y = y
 
-    global move_rubberband
-    if move_rubberband:
+    if MOVE_RUBBERBAND:
         # draw the outline ...
         f=0
     else:
         _client.move(x, y)
 
-    global move_popup
-    if move_popup:
+    if MOVE_POPUP:
         global _popwidget, _poplabel
         style = ob.openbox.screen(_screen).style()
         font = style.labelFont()
@@ -160,10 +161,7 @@ def _do_move():
                                     _popwidget.height()) / 2)
         _popwidget.show(1)
 
-def move(data):
-    """Moves the window interactively. This should only be used with
-       MouseMotion events. If move_popup or move_rubberband is enabled, then
-       the end_move function needs to be bound as well."""
+def _move(data):
     if not data.client: return
 
     # not-normal windows dont get moved
@@ -182,15 +180,14 @@ def move(data):
         ob.kgrab(_screen, _motion_grab)
         _inmove = 1
 
-def end_move(data):
-    """Complete the interactive move of a window."""
-    global move_rubberband, _inmove
-    global _popwidget, _poplabel
+def _end_move(data):
+    global MOVE_RUBBERBAND
+    global _inmove, _popwidget, _poplabel
     if _inmove:
-        r = move_rubberband
-        move_rubberband = 0
+        r = MOVE_RUBBERBAND
+        MOVE_RUBBERBAND = 0
         _do_move()
-        move_rubberband = r
+        MOVE_RUBBERBAND = r
         _inmove = 0
     _poplabel = 0
     _popwidget = 0
@@ -203,7 +200,7 @@ def _do_resize():
     dy = _dy
     
     # pick a corner to anchor
-    if not (resize_nearest or _context == ob.MouseContext.Grip):
+    if not (RESIZE_NEAREST or _context == ob.MouseContext.Grip):
         corner = ob.Client.TopLeft
     else:
         x = _px - _cx
@@ -225,15 +222,13 @@ def _do_resize():
     w = _cw + dx
     h = _ch + dy
 
-    global resize_popup
-    if resize_rubberband:
+    if RESIZE_RUBBERBAND:
         # draw the outline ...
         f=0
     else:
         _client.resize(corner, w, h)
 
-    global resize_popup
-    if resize_popup:
+    if RESIZE_POPUP:
         global _popwidget, _poplabel
         style = ob.openbox.screen(_screen).style()
         ls = _client.logicalSize()
@@ -255,9 +250,7 @@ def _do_resize():
                                     _popwidget.height()) / 2)
         _popwidget.show(1)
 
-def resize(data):
-    """Resizes the window interactively. This should only be used with
-       MouseMotion events"""
+def _resize(data):
     if not data.client: return
 
     # not-normal windows dont get resized
@@ -280,15 +273,14 @@ def resize(data):
         ob.kgrab(_screen, _motion_grab)
         _inresize = 1
 
-def end_resize(data):
-    """Complete the interactive resize of a window."""
-    global resize_rubberband, _inresize
+def _end_resize(data):
+    global RESIZE_RUBBERBAND, _inresize
     global _popwidget, _poplabel
     if _inresize:
-        r = resize_rubberband
-        resize_rubberband = 0
+        r = RESIZE_RUBBERBAND
+        RESIZE_RUBBERBAND = 0
         _do_resize()
-        resize_rubberband = r
+        RESIZE_RUBBERBAND = r
         _inresize = 0
     _poplabel = 0
     _popwidget = 0
diff --git a/scripts/stackedcycle.py b/scripts/stackedcycle.py
index 9cfa051c..9c60c1b9 100644
--- a/scripts/stackedcycle.py
+++ b/scripts/stackedcycle.py
@@ -5,24 +5,24 @@
 ###########################################################################
 ###    Options that affect the behavior of the stackedcycle module.     ###
 ###########################################################################
-include_all_desktops = 0
+INCLUDE_ALL_DESKTOPS = 0
 """If this is non-zero then windows from all desktops will be included in
    the stacking list."""
-include_icons = 1
+INCLUDE_ICONS = 1
 """If this is non-zero then windows which are iconified will be included
    in the stacking list."""
-include_omnipresent = 1
+INCLUDE_OMNIPRESENT = 1
 """If this is non-zero then windows which are on all-desktops at once will
    be included."""
-title_size_limit = 80
+TITLE_SIZE_LIMIT = 80
 """This specifies a rough limit of characters for the cycling list titles.
    Titles which are larger will be chopped with an elipsis in their
    center."""
-activate_while_cycling = 1
+ACTIVATE_WHILE_CYCLING = 1
 """If this is non-zero then windows will be activated as they are
    highlighted in the cycling list (except iconified windows)."""
-# See focus.avoid_skip_taskbar
-# See focuscycle.raise_window
+# See focus.AVOID_SKIP_TASKBAR
+# See focuscycle.RAISE_WINDOW
 ###########################################################################
 
 def next(data):
@@ -51,7 +51,7 @@ import ob
 import focus
 import focuscycle
 
-class cycledata:
+class _cycledata:
     def __init__(self):
         self.cycling = 0
 
@@ -72,11 +72,11 @@ class cycledata:
 
         if not client.normal(): return 0
         if not (client.canFocus() or client.focusNotify()): return 0
-        if focus.avoid_skip_taskbar and client.skipTaskbar(): return 0
+        if focus.AVOID_SKIP_TASKBAR and client.skipTaskbar(): return 0
 
-        if include_icons and client.iconic(): return 1
-        if include_omnipresent and desk == 0xffffffff: return 1
-        if include_all_desktops: return 1
+        if INCLUDE_ICONS and client.iconic(): return 1
+        if INCLUDE_OMNIPRESENT and desk == 0xffffffff: return 1
+        if INCLUDE_ALL_DESKTOPS: return 1
         if desk == curdesk: return 1
 
         return 0
@@ -127,9 +127,9 @@ class cycledata:
 
             if c.iconic(): t = c.iconTitle()
             else: t = c.title()
-            if len(t) > title_size_limit: # limit the length of titles
-                t = t[:title_size_limit / 2 - 2] + "..." + \
-                    t[0 - title_size_limit / 2 - 2:]
+            if len(t) > TITLE_SIZE_LIMIT: # limit the length of titles
+                t = t[:TITLE_SIZE_LIMIT / 2 - 2] + "..." + \
+                    t[0 - TITLE_SIZE_LIMIT / 2 - 2:]
             length = font.measureString(t)
             if length > longest: longest = length
             w.setText(t)
@@ -172,7 +172,7 @@ class cycledata:
         
         # send a net_active_window message for the target
         if final or not client.iconic():
-            if final: r = focuscycle.raise_window
+            if final: r = focuscycle.RAISE_WINDOW
             else: r = 0
             ob.send_client_msg(self.screeninfo.rootWindow(),
                                otk.Property_atoms().openbox_active_window,
@@ -207,7 +207,7 @@ class cycledata:
         if self.menupos < 0: self.menupos = len(self.clients) - 1
         elif self.menupos >= len(self.clients): self.menupos = 0
         self.menuwidgets[self.menupos].focus()
-        if activate_while_cycling:
+        if ACTIVATE_WHILE_CYCLING:
             self.activatetarget(0) # activate, but dont deiconify/unshade/raise
 
     def grabfunc(self, data):
@@ -245,6 +245,6 @@ def _grabfunc(data):
 ob.ebind(ob.EventAction.NewWindow, _newwindow)
 ob.ebind(ob.EventAction.CloseWindow, _closewindow)
 
-_o = cycledata()
+_o = _cycledata()
 
 print "Loaded stackedcycle.py"