include/gadgets/ListViewClass.h

   1 #ifndef LISTVIEWCLASS_H
   2 #define LISTVIEWCLASS_H
   3 /*
   4 **      $Id: ListViewClass.h,v 1.4 2000/01/12 21:18:06 bernie Exp $
   5 **
   6 **      Copyright (C) 1996,97,99 by Bernardo Innocenti
   7 **
   8 **      ListView class built on top of the "gadgetclass".
   9 **
  10 */
  11
  12 #define LISTVIEWCLASS   "listviewclass"
  13 #define LISTVIEWVERS    1
  14
  15
  16 Class   *MakeListViewClass(void);
  17 BOOL     FreeListViewClass(Class *LVClass);
  18
  19
  20
  21 /*
  22  * New Methods
  23  */
  24
  25 /* This class does not define any new methods */
  26
  27
  28 /*
  29  * New Attributes
  30  */
  31
  32 #define LVA_Dummy                       (TAG_USER | ('L'<<16) | ('V'<<8))
  33
  34 #define LVA_Selected            (LVA_Dummy+1)
  35         /* [IGSNU] (LONG) - Selected item number. ~0 (-1) indicates that no
  36          * item is selected.
  37          */
  38
  39 #define LVA_Top                         (LVA_Dummy+2)
  40         /* [IGSNU] (LONG) - Number of top displayed item. Default is 0.
  41          */
  42
  43 #define LVA_Total                       (LVA_Dummy+3)
  44         /* [IGSN] (LONG) - Total number of items in list.
  45          * This attribute can be set when LVA_StringArray, LVA_ImageArray
  46          * or LVA_CustomList is used. If you pass -1 or omit this tag,
  47          * the ListView class will count the items in the array until it
  48          * finds a NULL entry. If you know the number of nodes in your list,
  49          * you will save some internal overhead by telling it to the
  50          * ListView with the LVA_Total tag, expecially when using the
  51          * LVA_StringList and LVA_ImageList modes. You must set LVA_Total
  52          * each time you provide a new list or array, and in the same
  53          * OM_SET call.
  54          * Be careful: no checks are made on the values you are passing!
  55          */
  56
  57 #define LVA_SelectItem          (LVA_Dummy+4)
  58         /* [SN] (LONG) - Add item specified by ti_Data to the
  59          * selection list.
  60          */
  61
  62 #define LVA_DeselectItem        (LVA_Dummy+5)
  63         /* [SN] (LONG) - Remove item specified by ti_Data from the
  64          * selection list.
  65          */
  66
  67 #define LVA_ToggleItem          (LVA_Dummy+6)
  68         /* [SN] (LONG) - Toggle item selection.
  69          */
  70
  71 #define LVA_ClearSelected       (LVA_Dummy+7)
  72         /* [SN] (LONG) - Remove the selected state to AALL items.
  73          */
  74
  75
  76 #define LVA_MakeVisible         (LVA_Dummy+8)
  77         /* [ISU] (BOOL) - Make this item visible by doing the minimum required
  78          * scrolling.
  79          */
  80
  81 #define LVA_MoveUp                      (LVA_Dummy+9)
  82 #define LVA_MoveDown            (LVA_Dummy+10)
  83 #define LVA_MoveLeft            (LVA_Dummy+11)
  84 #define LVA_MoveRight           (LVA_Dummy+12)
  85         /* [SU] - Scroll the display up/down. left/right movement is not
  86          * yet supported.
  87          */
  88
  89 #define LVA_StringList          (LVA_Dummy+13)
  90 #define LVA_StringArray         (LVA_Dummy+14)
  91 #define LVA_ImageList           (LVA_Dummy+15)
  92 #define LVA_ImageArray          (LVA_Dummy+16)
  93 #define LVA_CustomList          (LVA_Dummy+17)
  94 #define LVA_Labels                      LVA_StringList
  95         /* [ISG] - List of items to display. All structures and strings
  96          * are referenced, not copied, so they must stay in memory
  97          * while the ListView gadget displays them.
  98          *
  99          * LVA_StringList (AKA LVA_Labels) passes a pointer to a
 100          * List (or MinList) of Node structures. The strings
 101          * pointed by ln_Name will be displayed as item labels.
 102          *
 103          * LVA_StringArray specifies a pointer to an array of STRPTR which
 104          * will be used as item labels.  The array must be NULL terminated
 105          * unless the LVA_Count is set.
 106          *
 107          * LVA_ImageList passes a pointer to a List (or MinList)
 108          * of Node structures. The ln_Name field of each Node structure
 109          * must point to a normal Image structure or to an instance of
 110          * the imageclass (or a subclass of it).
 111          *
 112          * LVA_ImageArray specifies a pointer to an array of pointers to
 113          * Image structures or imageclass objects.  The array must be NULL
 114          * terminated unless the LVA_Count attribute is used.
 115          *
 116          * LVA_CustomList can be used to provide a data structure which
 117          * is neither a list nor an array.  Custom user functions will
 118          * be called to retrieve the items. The data passed with this
 119          * tag will be passed to the user functions.
 120          *
 121          * Setting one of these attributes to NULL causes the contents
 122          * of the ListView gadget to be cleared.
 123          *
 124          * Setting one of these attributes to ~0 (-1) detaches the
 125          * items from the ListView.  You must detach your list before
 126          * adding or removing items.  This isn't required when using
 127          * array oriented item lists.
 128          */
 129
 130 #define LVA_Visible                     (LVA_Dummy+18)
 131         /* [IGN] (ULONG) - Number of visible items. When this attribute is
 132          * passed on intialization, the ListView gadget will resize
 133          * itself to make the desired number of lines visible. this
 134          * feature is incompatible with GA_RelHeight. LVA_Visible at
 135          * creation time requires a valid DrawInfo passed with the
 136          * GA_DrawInfo tag.
 137          */
 138
 139 #define LVA_SelectedPtr         (LVA_Dummy+19)
 140         /* [GN] (APTR) - Selected item pointer or NULL when no
 141          * items are selected.
 142          */
 143
 144 #define LVA_SelectArray         (LVA_Dummy+20)
 145         /* [ISGNU] (ULONG *) - This array of ULONGs is only used in
 146          * LVA_#?Array modes, when multiple selection is active. It will
 147          * hold the selection status of all items in the list. Each
 148          * element will be 0 if the related item is unselected, and
 149          * it will indicate the selection order when the item is
 150          * selected.
 151          */
 152
 153 #define LVA_CallBack            (LVA_Dummy+21)
 154         /* [I] (struct Hook *) - Callback hook for various listview operations.
 155          * The call back hook is called with:
 156          *              A0 - struct Hook *
 157          *              A1 - struct LVDrawMsg *
 158          *              A2 - struct Node *
 159          * The callback hook *must* check the lvdm_MethodID field of the
 160          * message and only do processing if it is known. If any other
 161          * value is passed, the callback hook must return LVCB_UNKNOWN.
 162          */
 163
 164 #define LVA_ShowSelected        (LVA_Dummy+23)
 165         /* [I] (BOOL) - Enable highlighting selected items (default is TRUE).
 166          * Note that this is different from the GadTools ListView default,
 167          * which is not displaying the selected item.
 168          */
 169
 170 #define LVA_Clipped                     (LVA_Dummy+24)
 171         /* [I] (BOOL) - When this attribute is set, the ListView gadget
 172          * installs a ClipRegion in its Layer whenever it redraws its items.
 173          * (defaults is FALSE).
 174          */
 175
 176 #define LVA_DoMultiSelect       (LVA_Dummy+25)
 177         /* [I] (BOOL) - Allows picking multiple items from the list
 178          * (default is FALSE).
 179          * When MultiSelect mode is active and a List structure is used,
 180          * the ListView gadget keeps track of which items are selected
 181          * by setting/clearing the ln_Type field of the Node structure.
 182          * When items are passed with an array, you must also provide
 183          * a second array for storing selection information (LVA_SelectArray).
 184          * When item number n is selected, then the n-th BOOL of this array
 185          * is set with its selection order.
 186          */
 187
 188 #define LVA_ItemHeight          (LVA_Dummy+27)
 189         /* [I] (ULONG) - Exact height of an item. Defaults to be the Y size
 190          * of the font used to draw the text labels. The listview will ask
 191          * the height to its Image items if not explicitly given.
 192          */
 193
 194 #define LVA_MaxPen                      (LVA_Dummy+28)
 195         /* [I] (LONG) - The maximum pen number used by rendering in a custom
 196          * rendering callback hook. This is used to optimize the
 197          * rendering and scrolling of the listview display (default is
 198          * the maximum pen number used by all of TEXTPEN, BACKGROUNDPEN,
 199          * FILLPEN, TEXTFILLPEN and BLOCKPEN).
 200          */
 201
 202 #define LVA_TextFont            (LVA_Dummy+29)
 203         /* [I] (struct TextFont *) - Font to be used for rendering texts.
 204          * Defaults to the default screen font.
 205          */
 206
 207 #define LVA_DoubleClick         (LVA_Dummy+30)
 208         /* [N] (ULONG) - The item specified by ti_Data has been double clicked.
 209          */
 210
 211 #define LVA_MaxSelect           (LVA_Dummy+31)
 212         /* [IS] (ULONG) - Maximum number of selected items to allow in multiselect
 213          * mode. If you later set this tag with a more restrictive condition, the
 214          * listview will NOT deselect any of the currently selected items to
 215          * satisfy your request. Default is unlimited (~0).
 216          */
 217
 218 #define LVA_PixelTop            (LVA_Dummy+32)
 219         /* [ISGNU] (ULONG) - Offset from top of list in pixel units. Useful for
 220          * scrollers.
 221          */
 222
 223 #define LVA_PixelHeight         (LVA_Dummy+33)
 224         /* [N] (LONG) - Total height of list in pixel units. Useful for scrollers.
 225          */
 226
 227 #define LVA_PixelVVisible       (LVA_Dummy+34)
 228         /* [N] (LONG) - Number of vertical visible pixels. Useful for scrollers.
 229          */
 230
 231 #define LVA_PixelLeft           (LVA_Dummy+35)
 232         /* [ISNU] (LONG) - Offset from left of list in pixel units. Useful for scrollers.
 233          */
 234
 235 #define LVA_PixelWidth          (LVA_Dummy+36)
 236         /* [ISNG] (LONG) - Total width of list in pixel units. Useful for scrollers.
 237          */
 238
 239 #define LVA_PixelHVisible       (LVA_Dummy+37)
 240         /* [N] (LONG) - Number of horizontal visible pixels. Useful for scrollers.
 241          */
 242
 243 #define LVA_Title                       (LVA_Dummy+38)
 244         /* [IS] - Listview title item. This item will be drawn on the top line of
 245          * the list and will not scroll. ti_Data points to an item in the same
 246          * format of the items list (e.g.: If it is LVA_StringArray, then it will
 247          * be a Node * with ln_Name pointing to a text string. The item will be
 248          * passed to the custom item drawing hook. (TODO)
 249          */
 250
 251 #define LVA_Columns                     (LVA_Dummy+39)
 252         /* [I] (LONG) - Number of columns to be displayed. Default is 1. If set
 253          * to ~0, the listview will precheck all items to calculate this number
 254          * automatically. (TODO)
 255          */
 256
 257 #define LVA_ColumnSpacing       (LVA_Dummy+40)
 258         /* [I] (ULONG) - Spacing between columns in pixel units.
 259          * Default is 4 pixels. (TODO)
 260          */
 261
 262 #define LVA_ColumnWidths        (LVA_Dummy+41)
 263         /* [IGS] (ULONG *) - Points to an array of ULONGs containing the width of
 264          * each column expressed in pixel units.  A value of -1 causes the
 265          * ListView to automatically calculate the width of the column, by
 266          * asking the width to all items. (TODO)
 267          */
 268
 269 #define LVA_ColumnSeparator     (LVA_Dummy+42)
 270         /* [I] (UBYTE) - When the listview is in multicolumn mode, the
 271          * internal text label routines will scan the string for this
 272          * character, as a separator for the column labels. This defaults
 273          * to '\t', so a label for a three column list view would look
 274          * like this: "One\tTwo\tThree". (TODO)
 275          */
 276
 277 #define LVA_ResizeColumns       (LVA_Dummy+43)
 278         /* [IS] (BOOL) - Allows the user to resize the columns by dragging
 279          * on the listview title line. (TODO)
 280          */
 281
 282 #define LVA_SelectTick          (LVA_Dummy+44)
 283         /* [I] When user selects an item, show a checkmark on the left
 284          * instead of rendering the item in selected state. (TODO)
 285          */
 286
 287 #define LVA_ScrollInertia       (LVA_Dummy+45)
 288         /* [IS] (ULONG) - Sets the scrolling inertia of the listview.
 289          * Defaults to 4 for LVA_Clipped mode, 0 for a non-clipped listview.
 290          * (TODO)
 291          */
 292
 293 #define LVA_ScrollRatio         (LVA_Dummy+46)
 294         /* [IS] (ULONG) - If you ask the listview to scroll more than
 295          * LVA_Visible / LVA_ScrollRatio lines, all the listview contents
 296          * will be redrawn instead.  The minimum value of 1 will trigger a
 297          * full redraw only when ALL the listview visible part is scrolled away.
 298          * The default value is 2, which is a good compromise for items which
 299          * can redraw themselves relatively quickly, such as simple text
 300          * labels or bitmap images.
 301          */
 302
 303 /* Public flags */
 304 #define LVB_READONLY            0       /* Do not allow item selection                          */
 305 #define LVB_CLIPPED                     1       /* Clip item drawing inside their boxes         */
 306 #define LVB_SHOWSELECTED        2       /* Hilights the selected item                           */
 307 #define LVB_DOMULTISELECT       3       /* Allows user to pick more than one item       */
 308 #define LVB_SMOOTHSCROLLING     4       /* Scoll pixel by pixel                                         */
 309 #define LVB_RESIZECOLUMNS       5       /* Allow user to resize the columns                     */
 310
 311 /* Internal flags - DO NOT USE */
 312 #define LVB_CLOSEFONT           27      /* Close the font when disposing the object     */
 313 #define LVB_LIST                        28      /* Using an exec List                                           */
 314 #define LVB_DONTDRAW            29      /* Do not perform any drawing operations        */
 315 #define LVB_SCROLLING           30      /* User scrolling with middle mouse button      */
 316 #define LVB_DRAGGING            31      /* User dragging selection with LMB                     */
 317
 318
 319 #define LVF_READONLY            (1<<LVB_READONLY)
 320 #define LVF_CLIPPED                     (1<<LVB_CLIPPED)
 321 #define LVF_SHOWSELECTED        (1<<LVB_SHOWSELECTED)
 322 #define LVF_DOMULTISELECT       (1<<LVB_DOMULTISELECT)
 323 #define LVF_SMOOTHSCROLLING     (1<<LVB_SMOOTHSCROLLING)
 324 #define LVF_RESIZECOLUMNS       (1<<LVB_RESIZECOLUMNS)
 325
 326 #define LVF_CLOSEFONT           (1<<LVB_CLOSEFONT)
 327 #define LVF_LIST                        (1<<LVB_LIST)
 328 #define LVF_DONTDRAW            (1<<LVB_DONTDRAW)
 329 #define LVF_SCROLLING           (1<<LVB_SCROLLING)
 330 #define LVF_DRAGGING            (1<<LVB_DRAGGING)
 331
 332
 333
 334 /*
 335  * Changed attributes:
 336  *
 337  * GA_ToggleSelect
 338  *      [I] (BOOL) - When TRUE, the listview gadget will allow deselecting items
 339  *      by clicking on them.
 340  *
 341  * GA_Image
 342  *      [IS] (struct Image *), (Object *) - Specifies a framing boopsi image
 343  *      which will be rendered around the gadget. This attribute works much
 344  *      like in the frbuttonclass. (the default is a frameless gadget).
 345  *
 346  * GA_SelectRender
 347  *      [IS] (struct Image *) - Specifies an imageclass object to be used as
 348  *      cursor/selection.  The image will be drawn in IDS_SELECTED state
 349  *      for the selected item and IDS_NORMAL for all all other highlighted
 350  *      items. (TODO)
 351  *
 352  * GA_Immediate
 353  *      [I] (BOOL) - Sends interim notifications when the selected item changes.
 354  *
 355  * GA_TextAttr
 356  *      [I] (struct TextAttr *) - Font to be used for rendering texts.
 357  *      Defaults to the default screen font. See also LVA_TextFont.
 358  *
 359  * GA_ReadOnly
 360  *      [I] (BOOL) - Prevent selection of items (default is FALSE).
 361  *
 362  * LAYOUTA_Spacing
 363  *      [I] (UWORD) - Extra space to place between the items of the listview
 364  *      (defaults to 0).
 365  *
 366  */
 367
 368 /* FIX: Define here the attributes that not present
 369  * before V42 of <intuition/gadgetclass.h>.
 370  */
 371 #ifndef GA_ReadOnly
 372         #define GA_ReadOnly (GA_Dummy+41)
 373 #endif
 374 #ifndef GA_TextAttr
 375         #define GA_TextAttr (GA_Dummy+40)
 376 #endif
 377
 378
 379 /* Do not define these if <libraries/gadtools.h> will be included too */
 380
 381 #ifdef LV_GADTOOLS_STUFF
 382
 383 /* The different types of messages that a listview callback hook can see */
 384 #define LV_DRAW         0x202L          /* draw yourself, with state    */
 385
 386 /* Possible return values from a callback hook */
 387 #define LVCB_OK                 0               /* callback understands this message type               */
 388 #define LVCB_UNKNOWN    1               /* callback does not understand this message    */
 389
 390 /* states for LVDrawMsg.lvdm_State */
 391 #define LVR_NORMAL                              0       /* the usual                            */
 392 #define LVR_SELECTED                    1       /* for selected gadgets         */
 393 #define LVR_NORMALDISABLED              2       /* for disabled gadgets         */
 394 #define LVR_SELECTEDDISABLED    8       /* disabled and selected        */
 395
 396 #endif /* LV_GADTOOLS_STUFF */
 397
 398 #define LVR_TITLE                               16      /* ListView title item          */
 399
 400
 401 /* More callback hook methods */
 402
 403 #define LV_GETNEXT              0x203L  /* gimme next item in list              */
 404 #define LV_GETPREV              0x204L  /* gimme previous item in list  */
 405 #define LV_GETITEM              0x205L  /* gimme item handle by number  */
 406
 407 /* These two methods can be used to optimize listview rendering
 408  * operations.  You can safely assume that the rastport attributes
 409  * you set inside LV_DRAWBEGIN will remain unchanged for all
 410  * subsequent calls to LV_DRAW, until an LV_DRAWEND is issued.
 411  * They do also provide a way to lock/unlock the list of items
 412  * if the access to its item needs to be arbitrated by a semaphore.
 413  */
 414 #define LV_DRAWBEGIN    0x206L  /* prepare to draw items                */
 415 #define LV_DRAWEND              0x207L  /* items drawing completed              */
 416
 417
 418
 419 /* More messages */
 420
 421 struct lvDrawItem
 422 {
 423         ULONG                           lvdi_MethodID;  /* LV_DRAW                                              */
 424         LONG                            lvdi_Current;   /* Current item number                  */
 425         APTR                            lvdi_Items;             /* Pointer to List, array, etc. */
 426         struct RastPort         *lvdi_RastPort; /* where to render to                   */
 427         struct DrawInfo         *lvdi_DrawInfo; /* useful to have around                */
 428         struct Rectangle        lvdi_Bounds;    /* limits of where to render    */
 429         ULONG                           lvdi_State;             /* how to render                                */
 430         ULONG                           lvdi_Flags;             /* Current LVF_#? flags                 */
 431 };
 432
 433 struct lvGetItem
 434 {
 435         ULONG   lvgi_MethodID;  /* LV_GETITEM                                   */
 436         ULONG   lvgi_Number;    /* Number of item to get                */
 437         APTR    lvgi_Items;             /* Pointer to List, array, etc. */
 438 };
 439
 440 #define lvGetNext       lvGetItem
 441 #define lvGetPrev       lvGetItem
 442 #define lvDrawBegin     lvGetItem       /* lvgi_Number has no useful meaning    */
 443 #define lvDrawEnd       lvGetItem       /* lvgi_Number has no useful meaning    */
 444
 445 #endif /* !LISTVIEWCLASS_H */