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

   1 /*
   2  * tearoff.h
   3  *
   4  * Tearoff menu handling
   5  *
   6  * © 1994-1998 Straylight
   7  */
   8
   9 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 #ifndef __tearoff_h
  29 #define __tearoff_h
  30
  31 /*----- Constants and exported types --------------------------------------*/
  32
  33 /* --- Event type codes --- */
  34
  35 typedef enum
  36 {
  37   tearoff_SELECTION,
  38   tearoff_CLOSE,
  39   tearoff_SUBMENU,
  40   tearoff_HELP
  41 }
  42 tearoff_message;
  43
  44 /* --- Left-side adornments for menu items --- */
  45
  46 typedef enum
  47 {
  48   tearoff_NONE,
  49   tearoff_TICKED,
  50   tearoff_RADIOED
  51 } tearoff_selectType;
  52
  53 /* --- Event handler interface --- */
  54
  55 typedef void (*tearoff_selectProc)(tearoff_message m,int hit,void *handle);
  56
  57 /* --- What a tearoff menu looks like --- */
  58
  59 typedef struct tearoff__str *tearoff;
  60
  61 /*----- Exported functions ------------------------------------------------*/
  62
  63 /* --- tearoff_create --- *
  64  *
  65  * Arguments
  66  *
  67  * char *title == title for the menu
  68  * char *items == text and properties of the menu items.  See above for
  69  *                syntax.
  70  * BOOL tearoff == whether to display the tearoff bar along the top
  71  * tearoff_selectProc proc == an event handler for the menu
  72  * int max == maximum height of the menu (OS units) or 0 for no maximum
  73  * void *handle == a `this' pointer for the event handler.
  74  *
  75  * Return value
  76  *
  77  * A handle to the newly created menu, or 0 if it failed.
  78  */
  79
  80 tearoff tearoff_create(char *title,char *items,BOOL tearoff,
  81                        tearoff_selectProc proc, int max, void *handle);
  82
  83 /* --- tearoff_attachSubMenu --- *
  84  *
  85  * Arguments
  86  *
  87  * tearoff to == a handle for the tearoff to which we must attach the submenu
  88  * int itm == the index (numbered from 1) of the item to attach to.  The item
  89  *            must exist in tearoff to.
  90  * tearoff sub == a handle to the (to be) submenu
  91  */
  92
  93 void tearoff_attachSubMenu(tearoff to,int itm,tearoff sub);
  94
  95 /* --- tearoff_destroy --- *
  96  *
  97  * Arguments
  98  *
  99  * tearoff t == handle to a tearoff to get rid of. This call does
 100  *              not recursively destroy sub menus.
 101  */
 102
 103 void tearoff_destroy(tearoff t);
 104
 105 /* --- tearoff_displayMenu --- *
 106  *
 107  * Arguments
 108  *
 109  * tearoff t == handle to the tearoff to display on the screen. It
 110  *              is opened as a sub menu if one is expected.
 111  * void *handle == Handle to be returned to handler function. If
 112  *                 it is 0 then the old value is used.
 113  */
 114
 115 BOOL tearoff_displayMenu(tearoff t,void *handle);
 116
 117 /* --- tearoff_init --- *
 118  *
 119  * Make sure you call this before any of the other tearoff functions.  The
 120  * results are undefined in the traditional manner if you don't.
 121  */
 122
 123 void tearoff_init(void);
 124
 125 /* --- tearoff_selectItem --- *
 126  *
 127  * Arguments
 128  *
 129  * tearoff t == the tearoff containing the item to select
 130  * int item == the item (indexed from 1) to select (or not)
 131  * tearoff_selectType type == how to select the item
 132  */
 133
 134 void tearoff_selectItem(tearoff t, int item, tearoff_selectType type);
 135
 136 /* --- tearoff_shadeItem --- *
 137  *
 138  * Arguments
 139  *
 140  * tearoff t == the menu
 141  * int item == the item to (un)shade
 142  * BOOL shaded == whether to shade the item or not
 143  */
 144
 145 void tearoff_shadeItem(tearoff t, int item, BOOL shaded);
 146
 147 /* --- tearoff_closeMenu --- *
 148  *
 149  * Arguments
 150  *
 151  * tearoff t == the tearoff to close
 152  */
 153
 154 void tearoff_closeMenu(tearoff t);
 155
 156 /* --- tearoff_changeItemText --- *
 157  *
 158  * Arguments
 159  *
 160  * tearoff t == the tearoff menu
 161  * int item == the item to change (indexed from 1)
 162  * char *text == the new text message. Control key shortcuts must be
 163                  regiven if they are still wanted.
 164  */
 165
 166 void tearoff_changeItemText(tearoff t,int item,char *text);
 167
 168 /* --- tearoff_extendMenu --- *
 169  *
 170  * Arguments
 171  *
 172  * tearoff t == the menu to extend
 173  * char *items == the items to add in the same syntax as for tearoff_create.
 174  *                The results are unpleasent if the menu is open
 175  *
 176  * Return Value
 177  *
 178  * A new pointer to the tearoff menu, or NULL if it could not be extended.
 179  */
 180
 181 tearoff tearoff_extendMenu(tearoff t,char *items);
 182
 183 /* --- tearoff_changeTitle --- *
 184  *
 185  * Arguments
 186  *
 187  * tearoff t == the tearoff menu
 188  * char *title == the new title - the menu changes size if nessesary
 189  */
 190
 191 void tearoff_changeTitle(tearoff t,char *title);
 192
 193 /* --- tearoff_displayAt --- *
 194  *
 195  * Arguments
 196  *
 197  * tearoff t == the menu to open
 198  * void *handle == Handle to be returned to handler function. If
 199  *                 it is 0 then the old value is used
 200  * int x == the x coordinate to open left of menu
 201  * int y == the y coordinate to open top of menu
 202  */
 203
 204 void tearoff_displayAt(tearoff t,void *handle,int x,int y);
 205
 206 /* --- tearoff_height --- *
 207  *
 208  * Arguments
 209  *
 210  * tearoff t == the tearoff menu to find height of
 211  *
 212  * Return value
 213  *
 214  * The height of the menu - not including the title bar
 215  */
 216
 217 int tearoff_height(tearoff t);
 218
 219 /* --- tearoff_attachMenu --- *
 220  *
 221  * Arguments
 222  *
 223  * wimp_w w == the window the attach menu to
 224  * tearoff t == the menu to attach
 225  * void *handle == the handle to pass to the handler function,
 226  *                 if it is 0 then the old value is used.
 227  *
 228  * Return value
 229  *
 230  * TRUE if successful
 231  */
 232
 233 BOOL tearoff_attachMenu(wimp_w w,tearoff t,void *handle);
 234
 235 /* --- tearoff__isShaded --- *
 236  *
 237  * Arguments
 238  *
 239  * tearoff t == the tearoff in question
 240  * int item == the item to be questioned
 241  *
 242  * Return value
 243  *
 244  * TRUE if the item is shaded
 245  */
 246
 247 BOOL tearoff_isShaded(tearoff t,int item);
 248
 249 /* --- tearoff_howSelected --- *
 250  *
 251  * Arguments
 252  *
 253  * tearoff t == the tearoff in question
 254  * int item == the item to be questioned
 255  *
 256  * Return value
 257  *
 258  * How the item has been selected
 259  */
 260
 261 tearoff_selectType tearoff_howSelected(tearoff t,int item);
 262
 263 #endif