chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/ibicon

   1 /*
   2  * ibicon
   3  *  proper icon bar mangement (multiple icons, etc.)
   4  *
   5  * © 1992-1998 Straylight
   6  */
   7
   8 /*----- Licensing note ----------------------------------------------------*
   9  *
  10  * This file is part of Straylight's Steel library.
  11  *
  12  * Steel is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2, or (at your option)
  15  * any later version.
  16  *
  17  * Steel is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with Steel.  If not, write to the Free Software Foundation,
  24  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25  */
  26
  27 #ifndef __ibicon_h
  28 #define __ibicon_h
  29
  30 #ifndef __sprite_h
  31   #include "sprite.h"
  32 #endif
  33
  34 #ifndef __wimp_h
  35   #include "wimp.h"
  36 #endif
  37
  38 #ifndef __event_h
  39   #include "event.h"
  40 #endif
  41
  42 #ifndef __menu_h
  43   #include "menu.h"
  44 #endif
  45
  46 /*-----------------------------------------------------
  47
  48   DOs and DON'Ts
  49
  50   DO...
  51
  52   + only use the functions provided for manipulating your icons
  53
  54   DON'T...
  55
  56   + try and use event_attachmenu() or win_register_event_handler()
  57     like you do for baricon.
  58   + delete icons without these functions
  59
  60   baricon will be retained for compatibility, but it will use these
  61   routines rather than going it alone.
  62
  63 -----------------------------------------------------*/
  64
  65 typedef struct ibicon__ibiconstr *ibicon;
  66
  67 typedef enum
  68 {
  69   ibicon_NOTHING,          /* Nothing interesting.  This is for use by     */
  70                            /* ibicon, and will NOT be passed to handlers   */
  71   ibicon_LEFTCLICK,        /* Click with left button                       */
  72   ibicon_RIGHTCLICK,       /* Click with right button                      */
  73   ibicon_LOAD,             /* Attempt to load file from disk               */
  74   ibicon_SAVE,             /* Attempt to import file                       */
  75   ibicon_HELP              /* Request for help about the icon              */
  76 }
  77 ibicon_eventType;
  78
  79 typedef void (*ibicon_handler)(ibicon i,ibicon_eventType e,void *handle);
  80 typedef BOOL (*ibicon_rawHandler)(ibicon i,wimp_eventstr *e,void *handle);
  81
  82 /* These are places you can put your icon */
  83
  84 #define ibicon_LEFT -2     /* Show icon on left side (device)              */
  85 #define ibicon_RIGHT -1    /* Show icon on right side (application)        */
  86 #define ibicon_LEFTSEARCHLEFT -5
  87 #define ibicon_LEFTSEARCHRIGHT -6
  88 #define ibicon_RIGHTSEARCHLEFT -7
  89 #define ibicon_RIGHTSEARCHRIGHT -8
  90
  91 /* A couple of ways of specifying odd sprite areas */
  92
  93 #define ibicon_WIMPAREA ((sprite_area *)1)
  94 #define ibicon_SYSTEMAREA ((sprite_area *)0)
  95
  96 /*
  97  * ibicon ibicon_find(wimp_i icon)
  98  *
  99  * Use
 100  *  Return the ibicon handle of an icon.
 101  *
 102  * Parameters
 103  *  wimp_i icon == the icon to find
 104  */
 105
 106 ibicon ibicon_find(wimp_i icon);
 107
 108
 109 /*
 110  * wimp_i ibicon_syshandle(ibicon i)
 111  *
 112  * Use
 113  *  Returns the low-level WIMP handle for the icon concerned.
 114  *
 115  * Parameters
 116  *  ibicon i == the icon whose handle is desired
 117  *
 118  * Returns
 119  *  The WIMP icon handle for the icon
 120  */
 121
 122 wimp_i ibicon_syshandle(ibicon i);
 123
 124 /*
 125  * void ibicon_setPriority(int priority)
 126  *
 127  * Use
 128  *  Sets the priority with which to create icons under RISC OS 3.
 129  *
 130  * Parameters
 131  *  int priority == the new setting
 132  */
 133
 134 void ibicon_setPriority(int priority);
 135
 136 /*
 137  * ibicon ibicon_create
 138  * (
 139  *   int where,
 140  *   char *spritename,
 141  *   sprite_area *sprarea,
 142  *   char *text,
 143  *   int maxtext
 144  * )
 145  *
 146  * Use
 147  *  Creates an icon in the icon bar.  Where is up to you.  Specify a
 148  *  sprite-only icon by passing 0 for text.  Use the macros to define where
 149  *  and what area you want the sprite from.
 150  *
 151  * Parameters
 152  *  int where == what part of the icon bar you want to put the icon in.
 153  *    Macros are defined for the RISC OS 2 possibilities.  Wait for the
 154  *    RISC OS 3 macros, or just pass a window handle.
 155  *  char *spritename == the name of the sprite to display
 156  *  sprite_area *sprarea == the area from which the sprite area comes.  Use
 157  *    the macros provided for odd things like the WIMP area.  If you have
 158  *    text as well, then this will be ignored anyway.
 159  *  char *text == the text for the icon.  May be a NULL pointer, for no
 160  *    text.
 161  *  int maxtext == the max length the text entry can be.  If 0 then the
 162  *    length of the text given will be used.
 163  *
 164  * Returns
 165  *  A handle to the icon if successful, or 0 if not.
 166  */
 167
 168 ibicon ibicon_create
 169 (
 170   int where,
 171   char *spritename,
 172   sprite_area *sprarea,
 173   char *text,
 174   int maxtext
 175 );
 176
 177 /*
 178  * void ibicon_changeSprite(ibicon i,char *newsprite)
 179  *
 180  * Use
 181  *  Chnage the sprite displayed in an icon
 182  *
 183  * Parameters
 184  *  ibicon i == the icon to change
 185  *  char *newsprite == the new name
 186  */
 187
 188 void ibicon_changeSprite(ibicon i,char *newsprite);
 189
 190 /*
 191  * void ibicon_changeText(ibicon i,char *newtext)
 192  *
 193  * Use
 194  *  Change the text of an icon.
 195  *
 196  * Parameters
 197  *  ibicon i == the icon to change
 198  *  char *text == the new text to display
 199  */
 200
 201 void ibicon_changeText(ibicon i,char *newtext);
 202
 203 /*
 204  * void ibicon_attachMenu
 205  * (
 206  *   ibicon i,
 207  *   menu m,
 208  *   menu_selectProc sel,
 209  *   menu_helpProc help,
 210  *   void *handle
 211  * )
 212  *
 213  * Use
 214  *  Attaches a menu to an icon in the icon bar
 215  *
 216  * Parameters
 217  *  ibicon i == the icon to attach to
 218  *  menu m == the menu to attach
 219  *  menu_selectProc sel == a handler function for the menu
 220  *  menu_helpProc help == a help processor for the menu
 221  *  void *handle == a handle passed to the handler
 222  */
 223
 224 void ibicon_attachMenu
 225 (
 226   ibicon i,
 227   menu m,
 228   menu_selectProc sel,
 229   menu_helpProc help,
 230   void *handle
 231 );
 232
 233
 234 /*
 235  * void ibicon_attachMenuMaker
 236  * (
 237  *   ibicon i,
 238  *   event_menu_maker m,
 239  *   menu_selectProc sel,
 240  *   menu_helpProc help,
 241  *   void *handle
 242  * )
 243  *
 244  * Use
 245  *  Attaches a menu maker to an icon in the icon bar
 246  *
 247  * Parameters
 248  *  ibicon i == the icon to attach to
 249  *  event_menu_maker m == the menu maker to attach
 250  *  menu_selectProc sel == a handler function for the menu
 251  *  menu_helpProc help == a help processor for the menu
 252  *  void *handle == a handle passed to the handler
 253  */
 254
 255 void ibicon_attachMenuMaker
 256 (
 257   ibicon i,
 258   event_menu_maker m,
 259   menu_selectProc sel,
 260   menu_helpProc help,
 261   void *handle
 262 );
 263
 264 /*
 265  * void ibicon_removeIcon(ibicon i)
 266  *
 267  * Use
 268  *  Removes an icon totally from the icon bar.
 269  *
 270  * Parameters
 271  *  ibicon i == the icon to vape
 272  */
 273
 274 void ibicon_removeIcon(ibicon i);
 275
 276 /*
 277  * void ibicon_eventHandler(ibicon i,ibicon_handler p,void *handle)
 278  *
 279  * Use
 280  *  Attaches the handler to an icon.
 281  *
 282  * Parameters
 283  *  ibicon i == the icon to attach
 284  *  ibicon_handler p == the handler
 285  *  void *handle == a pointer to pass to the handler
 286  */
 287
 288 void ibicon_eventHandler(ibicon i,ibicon_handler p,void *handle);
 289
 290 /*
 291  * void ibicon_rawEventHandler(ibicon i,ibicon_rawHandler p,void *handle)
 292  *
 293  * Use
 294  *  Attaches a raw event handler.  This can 'vet' events before ibicon gets
 295  *  it mucky mits on them.
 296  *
 297  * Parameters
 298  *  ibicon i == the icon to attach
 299  *  ibicon_rawHandler p == the handler
 300  *  void *handle == a pointer to pass to the handler
 301  */
 302
 303 void ibicon_rawEventHandler(ibicon i,ibicon_rawHandler p,void *handle);
 304
 305 #endif