wmii/doc/NOTES

DEVELOPMENT NOTES

Architecture;

1. Modularized design

wmii separates all concerns into different binaries.
To share code between the binaries we also got a bunch of libraries,
which are initially written for wmii, and all wmii binaries are
statically linked with those libraries.

    * libcext       (collection of useful C-API extending functions)
    * libixp        (remote interface library, obsolete)
    * libixp2       (remote interface library, 9P2000 compliant - the future)
    * liblitz       (non-wimp GUI-toolkit library)
    * libwmii       (convenience functions for wmii-tools)
    * cmd/wm/wmiiwm (core window manager)
    * cmd/wmiibar   (a generic bar)
    * cmd/wmiimenu  (a generic keyboard-driven one-line menu)
    * cmd/wmiikeys  (shortcut handler)
    * cmd/wmiifs    (libixp fileserver multiplexer, obsolete)
    * cmd/wmiir     (remote interface client for obsolete libixp)
    * cmd/wmiir2    (remote interface client for libixp2)

liblitz contains all drawing code beside some geometry code, which is used by
all tools. 

2. Remote interface

The remote interface is implemented in the libixp library, which
is independent from all other parts of wmii and provides a client/server
API for a userland memory filesystem with a similar approach as 9p
server- and clients of the plan9 operating system. Note that the old libixp is
obsolete and will be replaced by libixp2.
An IXP server provides and manages a memory file system (only the old libixp
does) which is accessed concurrently by several clients over a UNIX
socket file. wmiiwm, wmiibar, wmiimenu, wmiikeys and wmiifs are IXP servers,
wmiir is an IXP client.
An IXP server dispatches its connections with a select() based loop, it also
represents the X event loop for above components, because the
ConnectionNumber(X11) is the file descriptor of a connection to the X
server. If requested, the IXP server also selects() for file descriptors
provided by the server implementing developer and runs appropriate read()
and write() callbacks. In above components we need only a read()
callback for the ConnectionNumber, because the event handling of X is
single-directional and awakes if X writes data to that file descriptor.
The file system what the server manages, is capable to manage arbitrary
length paths, infinite files (as long as memory is available), and byte
content of files through following functions:

    * create        (creates file/path)
    * remove        (removes file/path)
    * open          (opens file)
    * read          (reads opened file)
    * write         (writes opened file)
    * close         (closes opened file)

Note above functions are obsolete, in future libixp2 provides full 9P2000
support due to following interface:

	int ixp_client_init(IXPClient * c, char *sockfile);
	void ixp_client_deinit(IXPClient * c);
	int ixp_client_remove(IXPClient * c, u32 newfid, char *filepath);
	int ixp_client_create(IXPClient * c, u32 dirfid, char *name, u32 perm, u8 mode);
	int ixp_client_walk(IXPClient * c, u32 newfid, char *filepath);
	int ixp_client_open(IXPClient * c, u32 newfid, char *filepath, u8 mode);
	u32 ixp_client_read(IXPClient * c, u32 fid, u64 offset, void *result, u32 res_len);
	u32 ixp_client_write(IXPClient * c, u32 fid, u64 offset, u32 count, u8 * data);
	int ixp_client_close(IXPClient * c, u32 fid);


Technical Details;

1. Hint management

The window management of wmii conforms to the ICCCM specification,
although client supplied icons and iconified window states are not
handled for simplicity reasons and because they don't fit well with the
tiled window management.
Apart from this, wmii conforms partly to the EWMH specification to fit
well with the requirements of more recent applications in the area of
the KDE and Gnome desktop, although to fulfill these hints are no primary
target of wmii's window management capabilities.

2. Layout interface

wmii provides an C-API interface to extend the core window manager with new layouts.
See wmii/cmd/wm/layout_*.c for samples how to implement a layout.

The interface looks like:

struct Layout {
	char *name;
	void (*init) (Area *);      /* called when layout is initialized */
	void (*deinit) (Area *);    /* called when layout is uninitialized */
	void (*arrange) (Area *);   /* called when area is resized */
	Bool (*attach) (Area *, Client *);  /* called on attach */
	void (*detach) (Area *, Client *, Bool unmap);  /* called on detach */
	void (*resize) (Frame *, XRectangle *, XPoint *);   /* called after resize */
	void (*select) (Frame *, Bool raise);   /* selection */
	Container *(*get_frames) (Area *);  /* called for drawing */
	Action *(*get_actions) (Area *); /* local action table */
};

See wmii/cmd/wm/wm.h for further details about the structs.
See wmii/libcext/cext.h for details about the Container data
structure which provides a single linked list and a stack in one
implementation (list for navigation, stack for focus history) -
which is useful for frames, clients, areas and even pages.

To store arbitrary stuff in an area, there is an Area->aux
pointer, same can be done with frames, which contain a Frame->aux pointer.
Note that each layout implementation needs to create and destroy
frames by itself (this is required because otherwise a wmi-10
alike layout which assumes tabbing, won't be possible).