This is a library which was extracted from a pretty much dead pywmdockapps project, and is meant to help with writing Window Maker dockapps in Python.

Installation

The installation from source expect there is a C compiler around, as well as X and Python headers/dev packages. It might be installed using virtualenv, or system wide:

Note, that you'll need C compiler and Xorg dev package to build the C extension.

Usage

There is a base class, a foundation for building custom dockapps. Simplest possible usage would be:

import wmdocklib

app = wmdocklib.DockApp()
app.run()

this will run dockapp, which doesn't do anything, it just displays black background with 3 pixel wide border.

To build something useful, there will be a need for adding implementation, and optionally bitmaps in XPM format for additional graphical elements, like fonts, buttons, app mask and so on.

To create an application, it simple as:

• create a class inherited from DockApp,

• implement run() and main_loop() methods,

• optionally, add graphics (like bitmap charset), command line options handling, and possibly configuration file.

So below is the example for displaying random number:

 1 import random
 2 import time
 3 
 4 import wmdocklib
 5 
 6 
 7 FONTS = '''\
 8 /* XPM */
 9 static char *square_[] = {
10 "156 8 2 1",
11 "  c black",
12 "% c gray100",
13 "        %    % %   % %          % %                                                          %  %%%%%   %   %%%%% %%%%% %   % %%%%% %%%%% %%%%% %%%%% %%%%% ",
14 "        %    % %   % %            %                                                          %  %   %  %%       %     % %   % %     %         % %   % %   % ",
15 "        %    % %  %%%%%          %%                                                         %%  %   %   %       %     % %   % %     %         % %   % %   % ",
16 "        %          % %           %                                            %%%%%         %   %   %   %   %%%%%  %%%% %%%%% %%%%% %%%%%     % %%%%% %%%%% ",
17 "                  %%%%%         %%                                        %%               %%   %   %   %   %         %     %     % %   %     % %   %     % ",
18 "                   % %          %                                         %%          %%   %    %   %   %   %         %     %     % %   %     % %   %     % ",
19 "        %          % %          % %                                        %          %%   %    %%%%%  %%%  %%%%% %%%%%     % %%%%% %%%%%     % %%%%% %%%%% ",
20 "                                                                          %                                                                                 ",
21 };
22 '''
23 
24 class MyDockApp(wmdocklib.DockApp):
25 
26     font_dimentions = (6, 8)
27 
28     def __init__(self):
29         super().__init__()
30         self.fonts = [wmdocklib.BitmapFonts(FONTS, self.dimensions)]
31 
32     def run(self):
33         self.prepare_pixmaps()
34         self.open_xwindow()
35         self.main_loop()
36 
37     def main_loop(self):
38         while True:
39             self.fonts[0].add_string(f'{random.randint(0, 999):3}', 1, 1)
40             self.redraw()
41             time.sleep(0.1)
42 
43 
44 app = MyDockApp()
45 app.run()

In this simple application, there is (partial) charset defined (lines 7-22), which is assigned to the self.font (this attribute can be either a string with XPM data like above, or just a filename), by which it will be indicated that font data will be used.

Than, class MyDockApp is defined, with overriden methods run() and main_loop().

As for method run() it is kind of initialization of the object and window. By calling prepare_pixmaps there will be prepared combined bitmaps of background, pattern and (optionally) fonts, coordinates for the charset, it's width and heigh, and finally load prepared pixmap to memory.

Function open_xwindow will create and show the window. And than main loop is called, which iterate endlessly calling add_string() method for display string on the dockapp. Note, that add_string() method (and underlying add_char()) assuming, that fonts in bitmap are ordered just like ord() will do.

Method redraw() will trigger entire window to be refreshed.

Lowlevel module

There is a C module called pywmgeneral, which exposes couple of functions, which are useful building custom dockapps.

• open_xwindow - this function is responsible for creating an application window, with all the wm hints set to appropriate values, so that we can get docked app in Window Maker or borderless window in most of other window managers. This method should be run after include_pixmap is called, since (any) bitmap is expected to be a part of the app. It accepts four arguments - argcount - number of arguments in next argument list - argument list - there are two arguments which can be passed to this

  System Message: ERROR/3 (<string>, line 138)

  Unexpected indentation.

  function -geometry and -disply. All the rest will be ignored, so it's safe to pass len(sys.argv) and sys.argv as a argcount and argument list respectively.

  System Message: WARNING/2 (<string>, line 141)

  Block quote ends without a blank line; unexpected unindent.

  • width - application width, whatever value is accepted. By default 64.

  • height - application height, whatever value is accepted. By default 64.

• include_pixmap - function which loads and picture in XPM format as a string. The only argument here is a list of lines of the XPM image.

• redraw_window - repaint the window content.

• redraw_window_xy - repaint the window region counting from the provided coordinates (x and y) to the end of the application width and height.

• add_mouse_region - define a region for checking mouse events. This function may be repeated with definition for several regions using index. Arguments: - index - simple region integer identifier - left, top, right, bottom - coordinates for the area

• check_mouse_region - function for check if certain defined mouse region has any event. It returns id of the mouse region, or -1 if there were no events within provided coordinates.

• copy_xpm_area - copy XPM area from provided coordinates to new location. Arguments: - source x, source y - coordinate of the area to be copied from - source width, source height - dimension of the block to be copied - target x, targed y - destination coordinates.

• check_for_events - check for events. Return None if there is no events, or dictionary with information about type of the event. Currently supported events are as follows: - keypress - buttonpress - buttonrelease - destroynotify

License

This work is licensed under (L)GPL license.