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

   1 /*
   2  * ListBox
   3  *  Provides handling for list boxes
   4  *
   5  * v. 1.00 (27 July 1991)
   6  *
   7  * © 1991-1998 Straylight
   8  */
   9
  10 /*----- Licensing note ----------------------------------------------------*
  11  *
  12  * This file is part of Straylight's Steel library.
  13  *
  14  * Steel is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2, or (at your option)
  17  * any later version.
  18  *
  19  * Steel is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with Steel.  If not, write to the Free Software Foundation,
  26  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 #ifndef __listbox_h
  30 #define __listbox_h
  31
  32 #ifndef __wimp_h
  33 #include "wimp.h"
  34 #endif
  35
  36 /*
  37  * Abstract listbox handle
  38  */
  39 typedef struct list__liststr *list;
  40
  41 #ifndef __pane_h
  42 #include "pane.h"
  43 #endif
  44
  45 /*
  46  * An abstraction for list items
  47  */
  48 typedef struct list__item *list_item;
  49
  50 #define list_NOITEM ((list_item)0)
  51 #define list_CLOSE ((list_item)-2)
  52 #define list_HELP ((list_item)-3)
  53
  54 typedef void (*list_eventhandler)(list l,list_item item,void *handle);
  55 typedef BOOL (*list_raweventhandler)(list l,wimp_eventstr *e,void *handle);
  56 typedef void (*list_redrawhandler)(list l,
  57                                    list_item i,
  58                                    wimp_redrawstr *r,
  59                                    wimp_box *b,
  60                                    char *text,
  61                                    BOOL selected,
  62                                    void *handle);
  63
  64 typedef enum
  65 {
  66   list_RESETSTATE,
  67   list_SETSTATE,
  68   list_READSTATE,
  69   list_TOGGLESTATE
  70 }
  71 list_action;
  72
  73 /*
  74  * void list_isPane(list l,pane p)
  75  *
  76  * Use
  77  *  This routine is part of the private interface between the listbox and
  78  *  pane segments.  Do *NOT* try to call it in your own code.
  79  */
  80
  81 void list_isPane(list l,pane p);
  82
  83 /*
  84  * list list_create(char *name,BOOL alterSize)
  85  *
  86  * Use
  87  *  Creates a new list box window, and returns a handle to it.  Initially,
  88  *  there are no items, and the list box is not shown.  The function returns
  89  *  0 if the call fails for one reason or another (not enough windows or
  90  *  memory).
  91  *
  92  * Parameters
  93  *  char *name == the name to match in the template file
  94  *  BOOL alterSize == TRUE if we are allowed to change the box's visible
  95  *    size.
  96  *
  97  * Returns
  98  *  An abstract handle for the list box.
  99  */
 100
 101 list list_create(char *name,BOOL alterSize);
 102
 103 /*
 104  * void list_selectItem(list l,list_item item)
 105  *
 106  * Use
 107  *  Makes the item the currently selected one.
 108  *
 109  * Parameters
 110  *  list l == the list handle
 111  *  list_item item == the item number
 112  */
 113
 114 void list_selectItem(list l,list_item item);
 115
 116 /*
 117  * list_item list_selected(list l)
 118  *
 119  * Use
 120  *  Returns the currently selected item of the list.
 121  *
 122  * Parameters
 123  *  list l == the list handle
 124  *
 125  * Returns
 126  *  The item number of the currently selected item.
 127  */
 128
 129 list_item list_selected(list l);
 130
 131 /*
 132  * char *list_itemData(list l,list_item i)
 133  *
 134  * Use
 135  *  Returns the string for an item
 136  *
 137  * Parameters
 138  *  list l == the list handle
 139  *  list_item i == the item's handle
 140  *
 141  * Returns
 142  *  A pointer to the item's data
 143  */
 144
 145 char *list_itemData(list l,list_item i);
 146
 147 /*
 148  * list_item list_addItem(list l,char *data,BOOL inOrder)
 149  *
 150  * Use
 151  *  Adds a new piece of data into the list.
 152  *
 153  * Parameters
 154  *  list l == the list handle
 155  *  char *data == the data (as a char *, because most of the time you'll
 156  *    want to be using character strings).
 157  *
 158  * Returns
 159  *  A handle for the list item.
 160  */
 161
 162 list_item list_addItem(list l,char *data,BOOL inOrder);
 163
 164 /*
 165  * list_item list_findItem(list l,char *data)
 166  *
 167  * Use
 168  *  Searches through a list and returns the item number of the item whose
 169  *  data matches that given in the function.
 170  *
 171  * Parameters
 172  *  list l == the list handle
 173  *  char *data == the data to compare with
 174  *
 175  * Returns
 176  *  The item number of the item, or list_NOITEM if no match.
 177  */
 178
 179 list_item list_findItem(list l,char *data);
 180
 181 /*
 182  * void list_removeItem(list l,list_item i)
 183  *
 184  * Use
 185  *  Removes an item from the list.
 186  *
 187  * Parameters
 188  *  list l == the list's handle
 189  *  list_item i == the item number
 190  */
 191
 192 void list_removeItem(list l,list_item i);
 193
 194 /*
 195  * void list_delete(list l)
 196  *
 197  * Use
 198  *  Destroys a list totally.
 199  *
 200  * Parameters
 201  *  list l == the list handle
 202  */
 203
 204 void list_delete(list l);
 205
 206 /*
 207  * void list_updatePosition(list l)
 208  *
 209  * Use
 210  *  Writes the position of the listbox back into the template, so any new
 211  *  list boxes created from the template open at that position.
 212  *
 213  * Parameters
 214  *  list l == the list handle
 215  */
 216
 217 void list_updatePosition(list l);
 218
 219 /*
 220  * BOOL list_link(list l)
 221  *
 222  * Use
 223  *  Links a list box to a WIMP window.  If the list is already linked,
 224  *  nothing happens.  The list box is not displayed.
 225  *
 226  * Parameters
 227  *  list l == the list handle
 228  *
 229  * Returns
 230  *  TRUE if the link succeeded (may run out of windows!)
 231  */
 232
 233 BOOL list_link(list l);
 234
 235 /*
 236  * void list_unlink(list l)
 237  *
 238  * Use
 239  *  Unlinks the list box from its window and deletes the window.
 240  *
 241  * Parameters
 242  *  list l == the list handle
 243  */
 244
 245 void list_unlink(list l);
 246
 247 /*
 248  * void list_unlinkNoUpdate(list l)
 249  *
 250  * Use
 251  *  Unlinks a list from its window without storing its final position  back
 252  *  in memory.  Note that list_delete() calls list_unlink(), so make sure
 253  *  you call this routine before deleting the listbox it you want to prevent
 254  *  the position being written back.
 255  *
 256  * Parameters
 257  *  list l == the list handle
 258  */
 259
 260 void list_unlinkNoUpdate(list l);
 261
 262 /*
 263  * void list_update(list l,BOOL really)
 264  *
 265  * Use
 266  *  Enables or disables list updating (i.e. whether the listbox resizes and
 267  *  redraws itself between every operation).  If you're going to do some
 268  *  lengthy operation, it would be a good idea to turn update off first,
 269  *  and then turn it on again afterwards.
 270  *
 271  *  Note that this is an all-or-nothing thing -- no counter is kept.
 272  *
 273  * Parameters
 274  *  list l == the listbox which we're messing about with
 275  *  BOOL really == whether to turn the update on or off
 276  */
 277
 278 void list_update(list l,BOOL really);
 279
 280 /*
 281  * void list_display(list l)
 282  *
 283  * Use
 284  *  Displays a list box on-screen
 285  *
 286  * Parameters
 287  *  list l == the list
 288  */
 289
 290 void list_display(list l);
 291
 292 /*
 293  * void list_openDisplaced(list l)
 294  *
 295  * Use
 296  *  Opens the listbox on-screen displaced from its previous position by
 297  *  the normal 48 OS units.  It must be unlinked using list_unlinkNoUpdate()
 298  *  before deletion.
 299  *
 300  * Parameters
 301  *  list l == the list handle.
 302  */
 303
 304 void list_openDisplaced(list l);
 305
 306 /*
 307  * void list_hide(list l)
 308  *
 309  * Use
 310  *  Stops the list box being displayed
 311  *
 312  * Parameters
 313  *  list l == the list handle
 314  */
 315
 316 void list_hide(list l);
 317
 318 /*
 319  * wimp_w list_syshandle(list l)
 320  *
 321  * Use
 322  *  Returns the WIMP window handle being used for the list box.
 323  *
 324  * Parameters
 325  *  list l == the list
 326  *
 327  * Returns
 328  *  The window handle (a wimp_w).
 329  */
 330
 331 wimp_w list_syshandle(list l);
 332
 333
 334 /*
 335  * void list_eventHandler(list l,list_eventhandler proc,void *handle)
 336  *
 337  * Use
 338  *  Attaches an event handler to the list box.  Most won't actually need
 339  *  this, just the stand-alone ones, or ones that do clever-dick things.
 340  *
 341  * Parameters
 342  *  list l == the list handle
 343  *  list_eventhandler proc == the procedure to handle events
 344  *  void *handle == the jolly olde pointer to the user-defined data
 345  */
 346
 347 void list_eventHandler(list l,list_eventhandler proc,void *handle);
 348
 349 /*
 350  * void list_rawEventHandler(list l,list_raweventhandler proc,void *handle)
 351  *
 352  * Use
 353  *  Attaches the raw event handler procedure to the list box.  You can then
 354  *  vet any events coming into the list box and have your wicked way with
 355  *  them.
 356  *
 357  * Parameters
 358  *  list l == the list handle
 359  *  list_raweventhandler proc == the raw event handler routine
 360  *  void *handle == the (now-famous) caller defined handle.
 361  */
 362
 363 void list_rawEventHandler(list l,list_raweventhandler proc,void *handle);
 364
 365 /*
 366  * void list_redrawHandler(list l,list_redrawhandler rdr,void *handle)
 367  *
 368  * Use
 369  *  Attaches a replacement redraw handler to the list box.  The new handler
 370  *  redraws individual items in the list.  It must fill in the box it is
 371  *  passed, because the WIMP does not fill in the background.  The part of
 372  *  the list box not populated by items is filled in the window background
 373  *  colour automatically.  Using this, you can achieve quite a pleasing
 374  *  effect by making the background grey (colour 1) and the actual item
 375  *  backgrounds white (colour 0), indicating clearly the bottom of the list.
 376  *
 377  *  You can also implement other things like items being shaded etc.
 378  *
 379  * Parameters
 380  *  list l == the list to which the redraw handler is to be attached
 381  *  list_redrawhandler == the replacement redraw routine (or 0 to cancel)
 382  *  void *handle == a pointer to pass the redraw routine
 383  */
 384
 385 void list_redrawHandler(list l,list_redrawhandler rdr,void *handle);
 386
 387 /*
 388  * void list_widthAdd(list l,int extra)
 389  *
 390  * Use
 391  *  Since redraw handlers can basically do whatever they want to for each
 392  *  items, the list manager no longer really has any idea about how wide an
 393  *  item is.  Since the main thing displayed in lists is text, it is assumed
 394  *  that the width of an item is the width of the longest piece of text plus
 395  *  a constant (e.g. for a sprite on the side).  If this is not so, I'll
 396  *  have to rethink this bit...
 397  *
 398  * Parameters
 399  *  list l == the list we're setting the width of
 400  *  int extra == the constant to add to each item
 401  */
 402
 403 void list_widthAdd(list l,int extra);
 404
 405 /*
 406  * void list_setItemHeight(list l,int height)
 407  *
 408  * Use
 409  *  Sets the height of items in the specified list box.  By default, the
 410  *  height is 44 OS units (the height of menu items).  This should be
 411  *  sufficient for most purposes.
 412  *
 413  * Parameters
 414  *  list l == the list to set
 415  *  int height == the new height of each item, in OS units
 416  */
 417
 418 void list_setItemHeight(list l,int height);
 419
 420 /*
 421  * int list_items(list l)
 422  *
 423  * Use
 424  *  Informs the caller how many items there are in a list
 425  *
 426  * Parameters
 427  *  list l == the list handle
 428  *
 429  * Returns
 430  *  The number of items in a list
 431  */
 432
 433 int list_items(list l);
 434
 435 /*
 436  * void list_doForItems
 437  * (
 438  *   list l,
 439  *   void (*proc)(list l,list_item i,void *handle),
 440  *   void *handle
 441  * )
 442  *
 443  * Use
 444  *  Performs an operation on all of the items in a list box.
 445  *
 446  * Parameters
 447  *  list l == the list handle
 448  *  void (*proc)(list l,list_item i,void *handle) == the procedure to use
 449  *  void *handle == a handle to pass to the procedure.
 450  */
 451
 452 void list_doForItems
 453 (
 454   list l,
 455   void (*proc)(list l,list_item i,void *handle),
 456   void *handle
 457 );
 458
 459 /*
 460  * void list_attachData(list l,list_item i,void *data)
 461  *
 462  * Use
 463  *  Attaches a data structure to a list item.  This is a bit of an
 464  *  afterthought really.
 465  *
 466  * Parameters
 467  *  list l == the list
 468  *  list_item i == the list item
 469  *  void *data == a pointer to the data structure
 470  */
 471
 472 void list_attachData(list l,list_item i,void *data);
 473
 474 /*
 475  * void *list_getData(list l,list_item i)
 476  *
 477  * Use
 478  *  Returns the data attached to a list item.  The item number
 479  *  may have changed etc. with items deleted and added.
 480  *
 481  * Parameters
 482  *  list l == the list
 483  *  list_item i == the list item number
 484  *
 485  * Returns
 486  *  A pointer to the data structure attached using list_attachData().
 487  */
 488
 489 void *list_getData(list l,list_item i);
 490
 491 /*
 492  * void list_multipleSelection(list l)
 493  *
 494  * Use
 495  *  Makes a list able to handle a multiple selection.
 496  *
 497  * Parameters
 498  *  list l == the list handle
 499  */
 500
 501 void list_multipleSelection(list l);
 502
 503 /*
 504  * BOOL list_addToSelection(list l,list_item i,list_action a)
 505  *
 506  * Use
 507  *  Adds an item to the current selection.
 508  *
 509  * Parameters
 510  *  list l == the list
 511  *  list_item i == the list item
 512  *  list_action a == what to do with the state
 513  *
 514  * Returns
 515  *  The previous state of the item
 516  */
 517
 518 BOOL list_addToSelection(list l,list_item i,list_action a);
 519
 520 /*
 521  * void list_doForSelected
 522  * (
 523  *   list l,
 524  *   void (*proc)(list l,list_item i,void *handle),
 525  *   void *handle
 526  * )
 527  *
 528  * Use
 529  *  Performs a user-specified action for each selected list item.
 530  *
 531  * Parameters
 532  *  list l == the list box
 533  *  void (*proc)(list l,list_item i,void *handle) == the procedure to do the
 534  *    thing
 535  *  void *handle == a handle to pass to the routine.
 536  */
 537
 538 void list_doForSelected
 539 (
 540   list l,
 541   void (*proc)(list l,list_item i,void *handle),
 542   void *handle
 543 );
 544
 545
 546 /*
 547  * void list_selectAll(list l,list_action a)
 548  *
 549  * Use
 550  *  Selects all the items in a list.
 551  *
 552  * Parameters
 553  *  list l == the list
 554  *  list_action a == what to do with the icons (list_READSTATE ain't all
 555  *    that useful, and list_TOGGLESTATE is downright wierd).
 556  */
 557
 558 void list_selectAll(list l,list_action a);
 559
 560 /*
 561  * int list_numSelected(list l)
 562  *
 563  * Use
 564  *  Informs the caller how many items are selected.
 565  *
 566  * Parameters
 567  *  list l == the list handle
 568  *
 569  * Returns
 570  *  An integer indicating the number of selected items
 571  */
 572
 573 int list_numSelected(list l);
 574
 575 /*
 576  * int list_itemToIndex(list l,list_item i)
 577  *
 578  * Use
 579  *  Translates a list_item into the index of the item.  This avoids
 580  *  assumptions about the mapping of indices to item numbers.  In the
 581  *  future, for example, the list_item data type may be used as a pointer to
 582  *  the list item data structure in memory.  Most of the time this will be
 583  *  irrelevant anyway.
 584  *
 585  * Parameters
 586  *  list l == the list handle
 587  *  list_item i == the list item to translate
 588  *
 589  * Returns
 590  *  An integer giving the index of the item.  The first item has index 0, as
 591  *  for C arrays.
 592  */
 593
 594 int list_itemToIndex(list l,list_item i);
 595
 596 /*
 597  * list_item list_indexToItem(list l,int index)
 598  *
 599  * Use
 600  *  Performs the reverse operation to the previous routine.  It will
 601  *  translate an index to a list_item.
 602  *
 603  * Parameters
 604  *  list l == the list handle
 605  *  int index == the index of the item required
 606  *
 607  * Returns
 608  *  The equivalent list_item for the item.
 609  */
 610
 611 list_item list_indexToItem(list l,int index);
 612
 613 /*
 614  * list_item list_helpItem(list l)
 615  *
 616  * Use
 617  *  Returns the item that Help is interested in.
 618  *
 619  * Parameters
 620  *  list l == the list's handle
 621  *
 622  * Returns
 623  *  A list_item
 624  */
 625
 626 list_item list_helpItem(list l);
 627
 628 #endif