libdockapp/src/dockapp.h

   1 /*
   2  * Copyright (c) 1999-2005 Alfredo K. Kojima, Alban Hertroys
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a copy
   5  * of this software and associated documentation files (the "Software"), to deal
   6  * in the Software without restriction, including without limitation the rights
   7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   8  * copies of the Software, and to permit persons to whom the Software is
   9  * furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included in
  12  * all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  17  * AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  18  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20  *
  21  */
  22
  23 #ifndef _DOCKAPP_H_
  24 #define _DOCKAPP_H_
  25 #define DA_VERSION      20050716
  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  * It is very limited and can be only used for dockapps that open a single
  32  * appicon for process in only ibe single display, but this seems to be
  33  * enough for most, if not all, dockapps.
  34  */
  35
  36 #include <X11/Xlib.h>
  37 #include <X11/Xresource.h>
  38 #include <X11/xpm.h>
  39 #include <stdlib.h>
  40 #include <stdio.h>
  41 #include <stdarg.h>
  42 #include <unistd.h>
  43
  44
  45 /* class-name for X-resources and Window Maker attributes */
  46 #define RES_CLASSNAME "DockApp"
  47
  48
  49 /* !!! DEPRECATED !!!
  50  * This feature may be removed in the future. Use DAEventCallbacks instead.
  51  *
  52  * the callbacks for events related to the dockapp window your program wants
  53  * to handle
  54  */
  55 typedef struct {
  56         /* the dockapp window was destroyed */
  57         void (*destroy)(void);
  58         /* button pressed */
  59         void (*buttonPress)(int button, int state, int x, int y);
  60         /* button released */
  61         void (*buttonRelease)(int button, int state, int x, int y);
  62         /* pointer motion */
  63         void (*motion)(int x, int y);
  64         /* pointer entered dockapp window */
  65         void (*enter)(void);
  66         /* pointer left dockapp window */
  67         void (*leave)(void);
  68         /* timer expired */
  69         void (*timeout)(void);
  70 } DACallbacks;
  71
  72
  73 typedef struct {
  74         char        *shortForm; /* short form for option, like -w       */
  75         char        *longForm;  /* long form for option, like --withdrawn */
  76         char        *description; /* description for the option         */
  77
  78         short type;             /* type of argument                     */
  79         Bool used;              /* if the argument was passed on the cmd-line */
  80
  81         /* the following are only set if the "used" field is True               */
  82         union {
  83                 void    *ptr;   /* a ptr for the value that was passed  */
  84                 int     *integer; /* on the command line                        */
  85                 char    **string;
  86         } value;
  87 } DAProgramOption;
  88
  89
  90 typedef XRectangle DARect;
  91
  92 /*
  93  * A callback function for an event on an "action rectangle"
  94  */
  95 typedef void DARectCallback(int x, int y, DARect rect, void *data);
  96
  97 /*
  98  * The action rectangle structure
  99  */
 100 typedef struct {
 101         DARect rect;
 102         DARectCallback      *action;
 103 } DAActionRect;
 104
 105
 106 /* option argument types */
 107 enum {
 108         DONone,                 /* simple on/off flag                   */
 109         DOInteger,              /* an integer number                    */
 110         DOString,               /* a string                             */
 111         DONatural               /* positive integer number              */
 112 };
 113
 114
 115 /* Shaped pixmaps: Shapes in combination with pixmaps */
 116 typedef struct {
 117         Pixmap pixmap;
 118         Pixmap shape;                   /* needs a 1-bit plane GC (shapeGC). */
 119         GC drawGC, clearGC, shapeGC;
 120         DARect geometry;                /* position and size */
 121         DAActionRect    *triggers;
 122 } DAShapedPixmap;
 123
 124
 125
 126 extern Display  *DADisplay;
 127 extern Window DAWindow, DALeader, DAIcon;   /* see [NOTE] */
 128 extern int DADepth;
 129 extern Visual   *DAVisual;
 130 extern GC DAGC, DAClearGC;
 131 extern DARect DANoRect;
 132 extern unsigned long DAExpectedVersion;
 133
 134 /* [NOTE]
 135  * DALeader is the group-leader window, DAIcon is the icon window.
 136  * DAWindow is the one of these two that is visible. Depending on whether the
 137  * dockapp was started normally or windowed, that will be DAIcon and DALeader
 138  * respectively.
 139  * DAIcon is None if the dockapp runs in "windowed mode".
 140  */
 141
 142
 143 /*
 144  * Set the version of the library that the dockapp expects.
 145  * This is a date in the format 'yyyymmdd'. You can find this date
 146  * in NEWS.
 147  */
 148 void DASetExpectedVersion(unsigned long expectedVersion);
 149
 150
 151 /*
 152  * DAParseArguments-
 153  *      Command line arguments parser. The program is exited if there are
 154  * syntax errors.
 155  *
 156  * -h, --help and --version are automatically handled (causing the program
 157  * to exit)
 158  * -w is handled automatically as well and causes the dockapp to be run
 159  * in windowed mode.
 160  */
 161 void DAParseArguments(int argc, char **argv, DAProgramOption *options,
 162                       int count, char *programDescription, char *versionDescription);
 163
 164 /*
 165  * DAInitialize-
 166  *      Initialize the dockapp, open a connection to the X Server,
 167  * create the needed windows and set them up to become an appicon  window.
 168  * It will automatically detect if Window Maker is present and use
 169  * an appropriate window form.
 170  *
 171  * You must call this always before calling anything else (except for
 172  * DAParseArguments())
 173  *
 174  * Arguments:
 175  *      display         - the name of the display to connect to.
 176  *                      Use "" to use the default value.
 177  *      name            - the name of your dockapp, used as the instance name
 178  *                      for the WM_CLASS hint. Like wmyaclock.
 179  *                      The ClassName is set to "DockApp" on default.
 180  *      width, height   - the size of the dockapp window. 48x48 is the
 181  *                      preferred size.
 182  *      argc, argc      - the program arguments. argv[0] will be used
 183  *                      as the instance name for the WM_CLASS hint.
 184  */
 185
 186 void DAInitialize(char *display, char *name, unsigned width, unsigned height,
 187                   int argc, char **argv);
 188
 189 void DAOpenDisplay(char *display, int argc, char **argv);
 190
 191 void DACreateIcon(char *name, unsigned width, unsigned height,
 192                   int argc, char **argv);
 193
 194 void DAProposeIconSize(unsigned width, unsigned height);
 195
 196
 197 /*
 198  * Wrapper functions for global variables.
 199  */
 200
 201 /* Get/Set DADisplay value. For use with external code.
 202  * Call with NULL as only argument. Other arguments are for backward compatibility
 203  * only.
 204  * XXX: Argument list is a kludge.
 205  */
 206 Display *DAGetDisplay(char *d, ...);
 207 void DASetDisplay(Display *display);
 208
 209 /* Get program name (from argv[0]). Returns a reference. */
 210 char *DAGetProgramName();
 211
 212 /* Get/Set DAWindow and DALeader values respectively. For use with external code. */
 213 Window DAGetWindow(void);
 214 void DASetWindow(Window window);
 215
 216 Window DAGetLeader(void);
 217 void DASetLeader(Window leader);
 218
 219 Window DAGetIconWindow(void);
 220 void DASetIconWindow(Window icon_win);
 221
 222 /* Get/Set DADepth; the display depth. For use with external code. */
 223 int DAGetDepth(void);
 224 void DASetDepth(int depth);
 225
 226 /* Get/Set DAVisual; the visual type for the screen. For use with external code. */
 227 Visual *DAGetVisual(void);
 228 void DASetVisual(Visual *visual);
 229
 230
 231 /*
 232  * DASetShapeWithOffset-
 233  *      Sets the shape mask of the dockapp to the specified one. This is
 234  * optional. If you pass None as shapeMask, the dockapp will become
 235  * non-shaped.
 236  *
 237  * This is only needed if you want the dockapp to be shaped.
 238  */
 239 #define DASetShape(shapeMask) \
 240         (DASetShapeWithOffset((shapeMask), 0, 0))
 241 #define DASetShapeForWindow(window, shapeMask) \
 242         (DASetShapeWithOffsetForWindow((window), (shapeMask), 0, 0))
 243
 244 void DASetShapeWithOffset(Pixmap shapeMask, int x_ofs, int y_ofs);
 245 void DASetShapeWithOffsetForWindow(Window window, Pixmap shapeMask,
 246                                    int x_ofs, int y_ofs);
 247 /*
 248  * DASetPixmap-
 249  *      Sets the image pixmap for the dockapp. Once you set the image with it,
 250  * you don't need to handle expose events.
 251  */
 252 void DASetPixmap(Pixmap pixmap);
 253 void DASetPixmapForWindow(Window window, Pixmap pixmap);
 254
 255 /*
 256  * DAMakePixmap-
 257  *      Creates a pixmap suitable for use with DASetPixmap()
 258  */
 259 Pixmap DAMakePixmap(void);
 260
 261 /*
 262  * DAMakeShape-
 263  *      Creates a shape pixmap suitable for use with DASetShape()
 264  */
 265 Pixmap DAMakeShape(void);
 266
 267 /*
 268  * DAMakeShapeFromData-
 269  *      Creates a shape pixmap suitable for use with DASetShape() from XBM data.
 270  */
 271 Pixmap DAMakeShapeFromData(char *data, unsigned int width, unsigned int height);
 272
 273 /*
 274  * DAMakeShapeFromFile-
 275  *      Creates a shape pixmap suitable for use with DASetShape() from an
 276  *      XBM file.
 277  */
 278 Pixmap DAMakeShapeFromFile(char *filename);
 279
 280 /*
 281  * DAMakePixmapFromData-
 282  *      Creates a pixmap and mask from XPM data
 283  *      Returns true on success, false on failure.
 284  */
 285 Bool DAMakePixmapFromData(char **data, Pixmap *pixmap, Pixmap *mask,
 286                           unsigned short *width, unsigned short *height);
 287
 288 /*
 289  * DAMakePixmapFromFile-
 290  *      Creates a pixmap and mask from an XPM file
 291  *      Returns true on success, false on failure.
 292  */
 293 Bool DAMakePixmapFromFile(char *filename, Pixmap *pixmap, Pixmap *mask,
 294                           unsigned short *width, unsigned short *height);
 295
 296 /*
 297  * DAMakeShapedPixmap-
 298  *      Creates a shaped pixmap with width & height of dockapp window.
 299  */
 300 DAShapedPixmap *DAMakeShapedPixmap();
 301
 302 /*
 303  * DAMakeShapedPixmapFromData-
 304  *      Creates a shaped pixmap from XPM-data.
 305  *      Returns shaped pixmap on success, NULL on failure.
 306  */
 307 DAShapedPixmap *DAMakeShapedPixmapFromData(char **data);
 308
 309 /*
 310  * DAMakeShapedPixmapFromFile-
 311  *      Creates a shaped pixmap from an XPM file.
 312  *      Returns shaped pixmap on success, NULL on failure.
 313  */
 314 DAShapedPixmap *DAMakeShapedPixmapFromFile(char *filename);
 315
 316 /*
 317  * DAFreeShapedPixmap-
 318  *      Free memory reserved for a ShapedPixmap
 319  */
 320 void DAFreeShapedPixmap(DAShapedPixmap *dasp);
 321
 322 /*
 323  * DASPCopyArea-
 324  *      Copies shape-mask and pixmap-data from an area in one shaped pixmap
 325  * into another shaped pixmap.
 326  */
 327 void DASPCopyArea(DAShapedPixmap *src, DAShapedPixmap *dst,
 328                   int x1, int y1, int w, int h, int x2, int y2);
 329
 330 /*
 331  * DASPClear-
 332  *      Clears a shaped pixmaps contents.
 333  */
 334 void DASPClear(DAShapedPixmap *dasp);
 335
 336 /* DASPShow-
 337  *      Displays the pixmap in the dockapp-window.
 338  */
 339 void DASPSetPixmap(DAShapedPixmap *dasp);
 340 void DASPSetPixmapForWindow(Window window, DAShapedPixmap *dasp);
 341
 342 /*
 343  * DAGetColor-
 344  *      Returns an X color index.
 345  */
 346 unsigned long DAGetColor(char *colorName);
 347
 348 /*
 349  * DAShow-
 350  *      Displays the dockapp.
 351  *
 352  * Always call this function or the dockapp won't show up.
 353  */
 354 void DAShow(void);
 355
 356 /*
 357  * DAShowWindow-
 358  *      Display a window. Also displays subwindows if it is the dockapp leader
 359  *      window (DALeader).
 360  */
 361 void DAShowWindow(Window window);
 362
 363 /*
 364  * DASetCallbacks-
 365  *      Register a set of callbacks for events like mouse clicks.
 366  *
 367  * Only needed if you want to receive some event.
 368  */
 369 void DASetCallbacks(DACallbacks *callbacks);
 370
 371 /*
 372  * DASetTimeout-
 373  *      Sets a timeout for the DAEventLoop(). The timeout callback
 374  * will be called whenever the app doesn't get any events from the
 375  * X server in the specified time.
 376  */
 377 void DASetTimeout(int milliseconds);
 378
 379 /*
 380  * DANextEventOrTimeout-
 381  *      Waits until a event is received or the timeout limit has
 382  * expired. Returns True if an event was received.
 383  */
 384 Bool DANextEventOrTimeout(XEvent *event, unsigned long milliseconds);
 385
 386 /*
 387  * DAProcessEvent-
 388  *      Processes an event. Returns True if the event was handled and
 389  * False otherwise.
 390  *
 391  * Must be called from your event loop, unless you use DAEventLoop()
 392  */
 393 Bool DAProcessEvent(XEvent *event);
 394 Bool DAProcessEventForWindow(Window window, XEvent *event);
 395
 396 /*
 397  * DAEventLoop-
 398  *      Enters an event loop where events are processed until the dockapp
 399  * is closed. This function never returns.
 400  */
 401 void DAEventLoop(void);
 402 void DAEventLoopForWindow(Window window);
 403
 404 /*
 405  * DAProcessActionRects-
 406  *      Processes the current coordinates with one of the functions in
 407  * the array of action rectangles. Coordinates are converted to relative
 408  * coordinates in one of the rectangles. The last item in the array of
 409  * action rectangles must be NULL.
 410  */
 411 void DAProcessActionRects(int x, int y, DAActionRect *actionrects,
 412                           int count, void *data);
 413
 414
 415 /*
 416  * Error handling functions
 417  */
 418
 419 /* Print a warning to stderr and continue */
 420 void DAWarning(const char *fmt, ...);
 421
 422 /* Print an error to stderr and exit with 1 */
 423 void DAError(const char *fmt, ...);
 424
 425 #endif