wmsupermon/dockapp.h

   1 /*
   2  *
   3  * Copyright (c) 1999 Alfredo K. Kojima
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy
   6  * of this software and associated documentation files (the "Software"), to deal
   7  * in the Software without restriction, including without limitation the rights
   8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9  * copies of the Software, and to permit persons to whom the Software is
  10  * furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included in
  13  * all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  18  * AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  19  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  *
  22  */
  23
  24 #ifndef _DOCKAPP_H_
  25 #define _DOCKAPP_H_
  26
  27 /*
  28  * This is a simple (trivial) library for writing Window Maker dock
  29  * applications, or dockapps (those that only show up in the dock), easily.
  30  */
  31
  32 #include <X11/Xlib.h>
  33 #include <X11/xpm.h>
  34 #include <stdlib.h>
  35 #include <stdio.h>
  36
  37 extern Display *DADisplay;
  38
  39 /* the callbacks for events related to the dockapp window your program wants
  40  * to handle */
  41 typedef struct {
  42     /* the dockapp window was destroyed */
  43     void (*destroy)(Window win);
  44     /* button pressed */
  45     void (*buttonPress)(Window win, int button, int state, int x, int y);
  46     /* button released */
  47     void (*buttonRelease)(Window win, int button, int state, int x, int y);
  48     /* pointer motion */
  49     void (*motion)(Window win, int x, int y);
  50     /* pointer entered dockapp window */
  51     void (*enter)(Window win);
  52     /* pointer leaved dockapp window */
  53     void (*leave)(Window win);
  54     /* timer expired */
  55     void (*timeout)(Window win);
  56 } DACallbacks;
  57
  58 /* option argument types */
  59 enum {
  60         DONone,                        /* simple on/off flag */
  61         DOInteger,                     /* an integer number */
  62         DOString,                      /* a string */
  63         DONatural                      /* positive integer number */
  64 };
  65
  66 typedef struct {
  67     char *shortForm;                   /* short form for option, like -w */
  68     char *longForm;                    /* long form for option, like --withdrawn */
  69     char *description;                 /* description for the option */
  70
  71     short type;                        /* type of argument */
  72
  73     Bool used;                         /* if the argument was passed in the
  74                                         cmd line */
  75     /* the following are only set if the "used" field is True */
  76     union {                            /* a ptr for the value that was passed
  77                                         in the command line */
  78         void *ptr;
  79
  80         int *integer;
  81
  82         char **string;
  83     } value;
  84 } DAProgramOption;
  85
  86 /*
  87  * DAParseArguments-
  88  *      Command line argument parser. The program is exited if there are
  89  * syntax errors.
  90  *
  91  * -h, --help and --version are automatically handled (causing the program
  92  * to exit)
  93  *
  94  */
  95 void DAParseArguments(int argc, char **argv, DAProgramOption *options,
  96                       int count, char *programDescription,
  97                       char *versionDescription);
  98
  99 /*
 100  * DAInitialize-
 101  *      Initialize the dockapp, open a connection to the X server,
 102  * create the needed windows and setup them to become an appicon window.
 103  * It will automatically detect if Window Maker is present and use
 104  * an appropriate form form
 105  *
 106  * You must call this always before calling anything else (except for
 107  * DAParseArguments())
 108  *
 109  * Arguments:
 110  *      display - the name of the display to connect to. Use "" to use the
 111  *              default value
 112  *      name - the name of your dockapp, used as the class name for
 113  *              the WM_CLASS hint. Like WMYAClock
 114  *      width, height - the size of the dockapp window. 48x48 is the
 115  *              preferred size
 116  *      argc, argv - the program arguments. argv[0] will be used as the
 117  *              instance name for the WM_CLASS hint.
 118  */
 119 void
 120 DAInitialize(char *display, char *name, unsigned width, unsigned height,
 121              int argc, char **argv, Window *out);
 122
 123 /*
 124  * DASetShape-
 125  *      Sets the shape mask of the dockapp to the specified one. This is
 126  * optional. If you pass None as shapeMask, the dockapp will become
 127  * non-shaped.
 128  *
 129  * This is only needed if you want the dockapp to be shaped.
 130  */
 131 void DASetShape(Window *window, Pixmap shapeMask);
 132
 133 /*
 134  * DASetPixmap-
 135  *      Sets the image pixmap for the dockapp. Once you set the image with
 136  * it, you don't need to handle expose events.
 137  */
 138 void DASetPixmap(Window *window, Pixmap pixmap);
 139
 140 /*
 141  * DAMakePixmap-
 142  *      Creates a pixmap suitable for using with DASetPixmap()
 143  */
 144 Pixmap DAMakePixmap(Window *window);
 145
 146 /*
 147  * DAMakePixmapFromData-
 148  *      Creates a pixmap and mask from XPM data
 149  */
 150 Bool DAMakePixmapFromData(Window *window, char **data, Pixmap *pixmap,
 151                           Pixmap *mask, unsigned *width, unsigned *height);
 152
 153 /*
 154  * Returns a color.
 155  */
 156 unsigned long DAGetColor(char *colorName);
 157 /*
 158  * DAShow-
 159  *      Opens the dockapp.
 160  *
 161  * Always call this function or the dockapp won't show up.
 162  */
 163 void DAShow(Window *window);
 164
 165 /*
 166  * DASetCallbacks-
 167  *      Register a set of callbacks for events like mouse clicks.
 168  *
 169  * Only needed if you want to receive some event.
 170  */
 171 void DASetCallbacks(Window *window, DACallbacks *callbacks);
 172
 173 /*
 174  * DASetTimeout-
 175  *      Sets a timeout for the DAEventLoop(). The timeout callback
 176  * will be called whenever the app doens't get any events from the
 177  * X server in the specified time.
 178  */
 179 void DASetTimeout(int milliseconds);
 180
 181 /*
 182  * DANextEventOrTimeout-
 183  *      Waits until an event is received or the timeout limit is
 184  * expired. Returns True if an event was received.
 185  */
 186 Bool DANextEventOrTimeout(XEvent *event, unsigned long millisec);
 187
 188 /*
 189  * DAProcessEvent-
 190  *      Processes an event. Returns True if the event was handled and
 191  * False otherwise.
 192  *
 193  * Must be called from your event loop, unless you use DAEventLoop()
 194  */
 195 Bool DAProcessEvent(Window *window, XEvent *event);
 196
 197 /*
 198  * DAEventLoop-
 199  *      Enters an event loop where events are processed until the dockapp
 200  * is closed. This function never returns.
 201  */
 202 void DAEventLoop(Window *window);
 203
 204 #endif