======================================================================
This is the README for stph, the Sawmill-inspired Taskbar & Pager
Helper.
======================================================================

[This README is for developers using stph.  End-users who just want to
use timbar need only read INSTALL.]

---------- General Info ----------

stph is designed to make it easy to create taskbars and pagers without
needing to understand anything about X events etc.  It provides a
callback mechanism for task-related events (creation; deletion;
iconification; movement; focus; etc) as well as a way of easily
examining the state of a task and the root window (how many workspaces
and viewports there are; which one you're on...)  
Convenience functions for manipulating tasks (closing, focusing,
iconifying etc) are also provided.  

It only works with Gnome-compliant WM's, but Gnome need not be running
or even installed since stph is written purely with Xlib.  It may be
used with C or Python.  

---------- Contact Info ----------

I, Rob Hodges <s323140@student.uq.edu.au>, am to blame for stph.  I
accept full responsibility.  But I was drunk, your honour. 

IF YOU USE THIS PACKAGE, PLEASE DROP ME A MESSAGE TO SAY SO.  

Otherwise I might make incompatible changes, thinking it won't affect
anyone.

Bug reports are very welcome; as are feature requests (within
reason :).  

---------- Compilation ----------

./configure
make tester [for the C example]
make stphmodule.so [for the Python module]

---------- Usage ----------

There are 2 ways to create an app that uses stph: write your app in C,
#include stph.h and link it with stph.c, or compile stphmodule.c which
provides support for Python.  Either way, the overall picture is about
the same:

1. #include stph.h [or in Python, import stph]
2. Connect your callbacks with stph_connect().
3. Run stph_initialise() -- this will run callbacks to let you know
   about what viewport and workspace you're on, and how many viewports
   and workspaces there are.  It will then add all the tasks that are
   already present and run your add-task callback for each.
4. Call stph_mainiteration() as part of your main event loop (usually
   this will mean calling it with a timer from whatever GUI toolkit
   you're using).  
5. Start your main event loop.  That's it.

Now for the gritty details... 

In C, stph_connect() takes 3 arguments: the ID of the callback (these
are all #define'd near the top of stph.h), the function you want to
connect to that callback, and a pointer to any data you want passed to
that function as its second argument (or NULL if you don't want
a second argument passed to it).

In Python, stph.connect() is more or less the same, except the
callback IDs have "STPH_" removed from the start, since you'll be
prefixing them with "stph." anyhow.  [Similarly, stph_initialise()
becomes stph.initialise() and so on]. The third argument is optional;
if present it should be a tuple containing the arguments (as many as
you like) that the callback accepts.

You don't have to connect to any callbacks you're not interested in.  

In C, task-related callbacks are called with a pointer to a struct
StphTask as their first argument; viewport/workspace-related callbacks
get a pointer to a struct StphRoot.  See stph.h.

There are also convenience functions for giving a task focus,
iconifying and uniconifying, etc -- again, see stph.h.  

In Python, you get an objectified version of the above -- a task
object or a root object, which have data members and (in the case of
task objects) member functions.  See the definitions of task_getattr,
task_methods and root_getattr in stphmodule.c for details.  

---------- Examples ----------

timbar.py is provided for those using Python, and tester.c for those
using C.  Examine the source of these and watch them run if you're
unsure how anything works.  If that doesn't help, you're welcome to
email me: <s323140@student.uq.edu.au>.  

