Show
Ignore:
Timestamp:
07/23/2008 01:59:10 PM (6 months ago)
Author:
funkiedamouse
Message:

Added docstrings to all classes and functions in examplewm.py.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/examples/examplewm.py

    r215 r217  
    1919#    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
    2020 
     21''' Example PLWM window manager 
     22 
     23This example demonstrates basic window manager construction and some of the 
     24more common window manager concepts such as a mode window, multiple views, 
     25and window decorations. 
     26''' 
    2127 
    2228import sys 
    … …  
    4753               outline.XorOutlineClient, 
    4854               modestatus.ModeFocusedTitleClient): 
     55    ''' Example client class 
     56 
     57    This class adds an XOR outline for moving/resizing windows and a hook to 
     58    display the title of the currently-focused window in the mode window. It 
     59    also specifies a list of clients that should start in an iconified 
     60    (withdrawn) state and specifies default pointer positions for a couple of 
     61    programs. 
     62    ''' 
    4963 
    5064    # Put a frame around all client windows 
    … …  
    6377               views.XMW_ViewHandler, 
    6478               modestatus.ModeFocusedTitleScreen): 
     79    ''' Example screen class 
     80 
     81    This class adds support for colors(FIXME), views, and a mode window, and 
     82    adds support to the mode window for displaying status(FIXME: clarify), 
     83    movement and resizing information, the current view, and the title of the 
     84    currently-focused window. 
     85    ''' 
    6586 
    6687    view_always_visible_clients = Or(name('XClock'), 
    … …  
    6990 
    7091class WMConfig: 
     92    ''' Example window manager configuration class 
     93 
     94    Installs the BasicKeys key map into the window manager. 
     95 
     96    TODO: Why is this not included in PLWM below? Should it be moved there? 
     97    ''' 
    7198    def __wm_init__(self): 
    7299        # Install the basic key map 
    … …  
    82109           inspect.InspectServer, 
    83110           WMConfig): 
     111    ''' Example window manager class 
     112 
     113    This class sets up the configuration for the window manager, including font 
     114    support, sloppy focus, focus movement support, a clock and mail notifier 
     115    for the mode window, and inspection support. It also sets the client class 
     116    and screen class to use. 
     117    ''' 
    84118 
    85119    client_class = MyClient 
    … …  
    88122 
    89123class BasicKeys(keys.KeyHandler): 
     124    ''' Basic key bindings 
     125 
     126    This class defines all key-bindings for the example window manager. 
     127    ''' 
     128 
    90129    def F1(self, event): 
     130        ''' Find a view containing an XTerm. 
     131        ''' 
    91132        self.wm.current_screen.view_find_with_client(name('XTerm')) 
    92133 
    93134    def S_F1(self, event): 
     135        ''' Start an XTerm. 
     136        ''' 
    94137        self.wm.system('xterm -geometry 80x50+200+100') 
    95138 
    96139    def C_S_F1(self, event): 
     140        ''' Start an XTerm in a new view. 
     141        ''' 
    97142        self.wm.current_screen.view_new() 
    98143        self.wm.system('xterm -geometry 80x50+200+100') 
    99144 
    100145    def F2(self, event): 
     146        ''' Find a view containing an Emacs window. 
     147        ''' 
    101148        self.wm.current_screen.view_find_with_client(name('Emacs')) 
    102149 
    103150    def S_F2(self, event): 
     151        ''' Start Emacs. 
     152        ''' 
    104153        self.wm.system('emacs') 
    105154 
    106155    def C_S_F2(self, event): 
     156        ''' Start Emacs in a new view. 
     157        ''' 
    107158        self.wm.current_screen.view_new() 
    108159        self.wm.system('emacs') 
    109160 
    110161    def F3(self, event): 
     162        ''' Find a view containing a Netscape window. 
     163        ''' 
    111164        self.wm.current_screen.view_find_with_client(name('Netscape')) 
    112165 
    113166    def S_F3(self, event): 
     167        ''' Start Netscape. 
     168        ''' 
    114169        self.wm.system('netscape') 
    115170 
    116171    def C_S_F3(self, event): 
     172        ''' Start Netscape in a new view. 
     173        ''' 
    117174        self.wm.current_screen.view_new() 
    118175        self.wm.system('netscape') 
    119176 
    120177    def F5(self, event): 
     178        ''' Switch to the next view with the tag 'F5'. 
     179        ''' 
    121180        self.wm.current_screen.view_find_tag('F5') 
    122181 
    123182    def S_F5(self, event): 
     183        ''' Set the current view's tag to 'F5'. 
     184        ''' 
    124185        self.wm.current_screen.view_tag('F5') 
    125186 
    126187    def F6(self, event): 
     188        ''' Switch to the next view with the tag 'F6'. 
     189        ''' 
    127190        self.wm.current_screen.view_find_tag('F6') 
    128191 
    129192    def S_F6(self, event): 
     193        ''' Set the current view's tag to 'F6'. 
     194        ''' 
    130195        self.wm.current_screen.view_tag('F6') 
    131196 
    132197    def F7(self, event): 
     198        ''' Switch to the next view with the tag 'F7'. 
     199        ''' 
    133200        self.wm.current_screen.view_find_tag('F7') 
    134201 
    135202    def S_F7(self, event): 
     203        ''' Set the current view's tag to 'F7'. 
     204        ''' 
    136205        self.wm.current_screen.view_tag('F7') 
    137206 
    138207    def F8(self, event): 
     208        ''' Switch to the next view with the tag 'F8'. 
     209        ''' 
    139210        self.wm.current_screen.view_find_tag('F8') 
    140211 
    141212    def S_F8(self, event): 
     213        ''' Set the current view's tag to 'F8'. 
     214        ''' 
    142215        self.wm.current_screen.view_tag('F8') 
    143216 
    144217    # Simulate mouse clicks 
    145218    def Any_F9(self, evt): 
     219        ''' Simulate a primary (usually, left) mouse button click. 
     220        ''' 
    146221        self.wm.fake_button_click(1) 
    147222 
    148223    def Any_F10(self, evt): 
     224        ''' Simulate a secondary (usually, right) mouse button click. 
     225        ''' 
    149226        self.wm.fake_button_click(2) 
    150227 
    151228    def Any_F11(self, evt): 
     229        ''' Simulate a tertiary (usually, middle) mouse button click. 
     230        ''' 
    152231        self.wm.fake_button_click(3) 
    153232 
    154233 
    155234    def F12(self, evt): 
     235        ''' Toggle inspect mode. 
     236        ''' 
    156237        self.wm.inspect_toggle() 
    157238 
    158239    def S_F12(self, evt): 
     240        ''' Toggle inspect mode, forcing if needed. 
     241        ''' 
    159242        self.wm.inspect_toggle(force = 1) 
    160243 
    161     # Drop all keygrabs until Scroll_Lock is pressed again, to allow 
    162     # clients to recieve keys used by plwm 
    163  
    164244    def S_Pause(self, evt): 
     245        ''' Drop all keygrabs until Scroll_Lock is pressed again. 
     246 
     247        Allows clients to recieve keys used by plwm. 
     248        ''' 
    165249        wmanager.debug('keys', 'dropping keygrabs temporarily') 
    166250 
    … …  
    173257 
    174258    def KP_Begin(self, event): 
     259        ''' Start moving / resizing the current window. 
     260        ''' 
    175261        MyMoveResizeKeys(self, event) 
    176262 
    177263 
    178264    def C_Tab(self, event): 
     265        ''' Cycle through minimized windows. 
     266        ''' 
    179267        CycleUMKeys(self, event) 
    180268 
    181269    def KP_Insert(self, event): 
     270        ''' Iconify the current window. 
     271        ''' 
    182272        wmanager.debug('keys', 'Iconifying') 
    183273        if self.wm.current_client: 
    … …  
    185275 
    186276    def KP_Subtract(self, event): 
     277        ''' Switch to the previous view. 
     278        ''' 
    187279        wmanager.debug('keys', 'Prev view') 
    188280        self.wm.current_screen.view_prev() 
    189281 
    190282    def KP_Add(self, event): 
     283        ''' Switch to the next view. 
     284        ''' 
    191285        wmanager.debug('keys', 'Next view') 
    192286        self.wm.current_screen.view_next() 
    193287 
    194288    def C_KP_Add(self, event): 
     289        ''' Create a new view. 
     290        ''' 
    195291        wmanager.debug('keys', 'New view') 
    196292        self.wm.current_screen.view_new() 
    197293 
    198294    def KP_Left(self, event): 
     295        ''' Move the pointer to the left. 
     296        ''' 
    199297        self.wm.display.warp_pointer(-delta.get(event.time), 0) 
    200298 
    201299    def KP_Right(self, event): 
     300        ''' Move the pointer to the right. 
     301        ''' 
    202302        self.wm.display.warp_pointer(delta.get(event.time), 0) 
    203303 
    204304    def KP_Up(self, event): 
     305        ''' Move the pointer up. 
     306        ''' 
    205307        self.wm.display.warp_pointer(0, -delta.get(event.time)) 
    206308 
    207309    def KP_Down(self, event): 
     310        ''' Move the pointer down. 
     311        ''' 
    208312        self.wm.display.warp_pointer(0, delta.get(event.time)) 
    209313 
    210314    def KP_Home(self, event): 
     315        ''' Move the pointer up and to the left. 
     316        ''' 
    211317        d = delta.get(event.time) 
    212318        self.wm.display.warp_pointer(-d, -d) 
    213319 
    214320    def KP_End(self, event): 
     321        ''' Move the pointer down and to the left. 
     322        ''' 
    215323        d = delta.get(event.time) 
    216324        self.wm.display.warp_pointer(-d, d) 
    217325 
    218326    def KP_Prior(self, event): 
     327        ''' Move the pointer up and to the right. 
     328        ''' 
    219329        d = delta.get(event.time) 
    220330        self.wm.display.warp_pointer(d, -d) 
    221331 
    222332    def KP_Next(self, event): 
     333        ''' Move the pointer down and to the right. 
     334        ''' 
    223335        d = delta.get(event.time) 
    224336        self.wm.display.warp_pointer(d, d) 
    225337 
    226338    def KP_Enter(self, event): 
     339        ''' Raise or lower the current window. 
     340        ''' 
    227341        if self.wm.current_client: 
    228342            self.wm.current_client.raiselower() 
    … …  
    232346 
    233347    def C_KP_Subtract(self, event): 
     348        ''' Lock the screen with xlock. 
     349        ''' 
    234350        self.wm.system('xlock -mode blank') 
    235351 
    236352    def C_M_Escape(self, event): 
     353        ''' Quit the window manager. 
     354        ''' 
    237355        self.wm.quit() 
    238356 
    239357    def C_KP_Delete(self, event): 
     358        ''' Close the current window. 
     359        ''' 
    240360        if self.wm.current_client: 
    241361            self.wm.current_client.delete(1) 
    242362 
    243363    def C_S_KP_Delete(self, event): 
     364        ''' Kill the current client. 
     365        ''' 
    244366        if self.wm.current_client: 
    245367            self.wm.current_client.destroy() 
    246368 
    247369    def C_KP_Left(self, event): 
     370        ''' Focus the next window to the left of the current one. 
     371        ''' 
    248372        self.wm.move_focus(focus.MOVE_LEFT) 
    249373 
    250374    def C_KP_Right(self, event): 
     375        ''' Focus the next window to the right of the current one. 
     376        ''' 
    251377        self.wm.move_focus(focus.MOVE_RIGHT) 
    252378 
    253379    def C_KP_Up(self, event): 
     380        ''' Focus the next window above the current one. 
     381        ''' 
    254382        self.wm.move_focus(focus.MOVE_UP) 
    255383 
    256384    def C_KP_Down(self, event): 
     385        ''' Focus the next window below the current one. 
     386        ''' 
    257387        self.wm.move_focus(focus.MOVE_DOWN) 
    258388 
    259389    def C_less(self, event): 
     390        ''' Focus the next window to the left of the current one. 
     391        ''' 
    260392        self.wm.move_focus(focus.MOVE_LEFT) 
    261393 
    262394    def C_S_less(self, event): 
     395        ''' Focus the next window to the right of the current one. 
     396        ''' 
    263397        self.wm.move_focus(focus.MOVE_RIGHT) 
    264398 
    265399 
    266400class BypassHandler(keys.KeyHandler): 
     401    ''' Surrogate key handler to bypass the window manager's key bindings. 
     402 
     403    Allows clients to receive key presses normally handled by the WM. 
     404    ''' 
    267405    propagate_keys = 0 
    268406 
    … …  
    275413 
    276414    def Pause(self, evt): 
     415        ''' Restore normal key bindings. 
     416        ''' 
    277417        wmanager.debug('keys', 'reinstalling keygrabs') 
    278418 
    … …  
    294434 
    295435class MyMoveResizeKeys(MoveResizeKeys): 
     436    ''' Keys for moving and resizing the current window. 
     437    ''' 
    296438    KP_Left  = MoveResizeKeys._move_w 
    297439    KP_Right = MoveResizeKeys._move_e 
    … …  
    330472 
    331473class CycleUMKeys(CycleKeys): 
     474    ''' Keys to cycle through all iconified windows. 
     475    ''' 
    332476    _cycle_filter = iconified 
    333477