struct + doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

1 files changed, 46 insertions, 3 deletions

diff --git a/src/x.py b/src/x.py
index f82a943..94437f5 100644
--- a/src/x.py
+++ b/src/x.py
@@ -22,11 +22,27 @@ import Xlib.display, Xlib.Xatom, Xlib.ext.randr, Xlib.X
 
 
 display = None
+'''
+The connection the X display
+'''
+
 screen = None
+'''
+The screen the panel is placed in
+'''
+
 screen_i = None
+'''
+The index of the screen `screen`
+'''
 
 
 def open_x(screen_no = None):
+    '''
+    Open connection the X and select screen
+    
+    @param  screen_no:int?  The index of the screen to use, `None` for default
+    '''
     global display, screen, screen_i
     display = Xlib.display.Display()
     screen_i = screen_no if screen_no is not None else display.get_default_screen()
@@ -34,6 +50,13 @@ def open_x(screen_no = None):
 
 
 def get_monitors():
+    '''
+    Returns the pixel size and position of the monitors in the screen
+    
+    @return  :list<(width:int, height:int, left:int, top:int)>
+             The width, height, left position and top position of each
+             monitor, starting with the primary output
+    '''
     global screen_i
     p = subprocess.Popen(['xrandr'], stdout = subprocess.PIPE)
     p = p.communicate()[0].decode('utf-8', 'replace')
@@ -60,18 +83,35 @@ def get_monitors():
 
 
 def get_display():
+    '''
+    Returns the X display
+    '''
     global display
     return display
 
 
 def get_screen():
+    '''
+    Returns the X screen
+    '''
     global screen
     return screen
 
 
-def create_panel(width, height, left, top, panel_height, at_top):
+def create_panel(width, height, left, ypos, panel_height, at_top):
+    '''
+    Create a docked panel, not mapped yet
+    
+    @param   width:int         The width of the output
+    @param   height:int        The height of the output
+    @param   left:int          The left position of the output
+    @param   ypos:int          The position of the panel in relation the either the top or bottom edge of the output
+    @param   panel_height:int  The height of the panel
+    @param   at_top:bool       Whether the panel is to be docked to the top of the output, otherwise to the bottom
+    @return                    The window
+    '''
     global display, screen
-    ypos = top if at_top else (height - top - panel_height)
+    ypos = ypos if at_top else (height - ypos - panel_height)
     window = screen.root.create_window(left, ypos, width, panel_height, 0, screen.root_depth,
                                        Xlib.X.InputOutput, Xlib.X.CopyFromParent,
                                        event_mask = (
@@ -89,7 +129,7 @@ def create_panel(width, height, left, top, panel_height, at_top):
     
     _CARD = display.intern_atom("CARDINAL")
     _PSTRUT = display.intern_atom("_NET_WM_STRUT_PARTIAL")
-    window.change_property(_PSTRUT, _CARD, 32, (top_ if at_top else bottom_)(left, top, width, panel_height))
+    window.change_property(_PSTRUT, _CARD, 32, (top_ if at_top else bottom_)(left, ypos, width, panel_height))
     
     _ATOM = display.intern_atom("ATOM")
     _TYPE = display.intern_atom("_NET_WM_WINDOW_TYPE")
@@ -100,6 +140,9 @@ def create_panel(width, height, left, top, panel_height, at_top):
 
 
 def close_x():
+    '''
+    Closes the connection to X, but flushes it first
+    '''
     global display
     display.flush()
     display.close()