wmdocklib/README.rst

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.font = FONTS
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.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.

License

This work is licensed under (L)GPL license.