wmget/dockapp/dockapp.h

   1 #ifndef I_DOCKAPP_H
   2 #define I_DOCKAPP_H
   3 /*
   4     wmget - A background download manager as a Window Maker dock app
   5     Copyright (c) 2001-2003 Aaron Trickey <aaron@amtrickey.net>
   6
   7     Permission is hereby granted, free of charge, to any person
   8     obtaining a copy of this software and associated documentation files
   9     (the "Software"), to deal in the Software without restriction,
  10     including without limitation the rights to use, copy, modify, merge,
  11     publish, distribute, sublicense, and/or sell copies of the Software,
  12     and to permit persons to whom the Software is furnished to do so,
  13     subject to the following conditions:
  14
  15     The above copyright notice and this permission notice shall be
  16     included in all copies or substantial portions of the Software.
  17
  18     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  19     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  21     NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
  22     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  23     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  24     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25
  26     ********************************************************************
  27     dockapp/dockapp.h - Public interface to the dockapp library
  28
  29     The dockapp library, distributed as part of the wmget program,
  30     provides a fairly simple way to write dockapps.  It abstracts away
  31     the actual drawing, input, and main-loop logic.
  32 */
  33
  34 #include <X11/X.h>      /* to get Button?Mask, etc. */
  35 #include <sys/poll.h>   /* to get POLLIN, POLLOUT, etc. */
  36
  37
  38 /**********************************************************************
  39  * BASIC TYPES
  40  */
  41
  42 /* RV type.  When writing a callback, you should generally return ok or
  43  * exit, to ask the dockapp to proceed or quit.
  44  */
  45 typedef enum {
  46     dockapp_ok = 0,
  47     dockapp_exit,
  48     dockapp_invalid_arg,
  49     dockapp_rv_too_many_clickregions,
  50 } dockapp_rv_t;
  51
  52
  53 /**********************************************************************
  54  * STARTUP/RUNTIME
  55  */
  56
  57 /* initializes the dockapp's X display
  58  */
  59 dockapp_rv_t dockapp_init_gui (
  60         char *appname,                  /* desired dockapp name */
  61         char *argv[],                   /* X/dockapp args */
  62         char **xpmdata);                /* XPM data */
  63
  64
  65 /* the main loop... when this returns, your program should exit
  66  */
  67 dockapp_rv_t dockapp_run (void);
  68
  69
  70 /* this asks dockapp_run() to periodically call an arbitrary function
  71  * (you can only have one of these installed at a time).  All sorts of
  72  * other things can pre-empt a periodic callback, so consider the 'msec'
  73  * parameter to be an interval floor.
  74  */
  75 void dockapp_set_periodic_callback (
  76         long msec,                      /* approx. interval */
  77         dockapp_rv_t (*cb) (void *),
  78         void *cbdata);
  79
  80 void dockapp_remove_periodic_callback (void);
  81
  82
  83 /* you can ask dockapp_run() to add an fd to an internal efficient
  84  * poll-list... see poll(2) for full documentation; the semantics here
  85  * are that you give fd and pollevents and we create a struct pollfd;
  86  * when we invoke the callback, the pollstatus arg will contain the
  87  * revents field from the struct pollfd
  88  */
  89 dockapp_rv_t dockapp_add_pollfd (
  90         int fd,                         /* the fd to poll */
  91         short pollevents,               /* see poll(2), e.g. POLLIN */
  92         dockapp_rv_t (*cb) (void *, short pollstatus),
  93         void *cbdata);
  94
  95 dockapp_rv_t dockapp_remove_pollfd (
  96         int fd);                        /* the fd to remove */
  97
  98
  99
 100 /**********************************************************************
 101  * CLICKREGIONS
 102  */
 103
 104 /* a clickregion is simply an area where the user can click to trigger a
 105  * callback
 106  * (Helpful list of buttonmask components: ShiftMask, LockMask,
 107  * ControlMask, Mod1Mask .. Mod5Mask, Button1Mask .. Button5Mask)
 108  */
 109 dockapp_rv_t dockapp_add_clickregion (
 110         int x, int y, int w, int h,
 111         int buttonmask,
 112         dockapp_rv_t (*cb) (void *, int x, int y),
 113         void *cbdata);
 114
 115
 116
 117
 118 /**********************************************************************
 119  * PIXMAP COPY/OVERLAY OPERATIONS
 120  *  Most dockapp drawing will consist of simple pixel moving from one
 121  *  part of the pixmap to another.
 122  */
 123
 124 /* copy pixels, overwriting the target
 125  */
 126 void dockapp_copy_pixmap (
 127         int source_x, int source_y,     /* copy from where */
 128         int target_x, int target_y,     /* copy to where */
 129         int w, int h);                  /* copy how much */
 130
 131 /* use an XOR raster-op to overlay the source on the target; call this
 132  * again with the same arguments to undo the first overlay
 133  */
 134 void dockapp_overlay_pixmap (
 135         int source_x, int source_y,     /* copy from where */
 136         int target_x, int target_y,     /* copy to where */
 137         int w, int h);                  /* copy how much */
 138
 139
 140
 141
 142 /**********************************************************************
 143  * X SELECTION
 144  */
 145
 146 /* request the current X selection... only non-incremental strings
 147  * supported... if there is no selection, callback gets called with
 148  * (const char *)0; otherwise, it gets called with the string (which
 149  * will still be owned by the X server, so you need to copy it if you
 150  * want to keep it)
 151  */
 152 dockapp_rv_t dockapp_request_selection_string (
 153         dockapp_rv_t (*cb) (void *, const char *),
 154         void *cbdata);
 155
 156
 157 #endif /* I_DOCKAPP_H */
 158