ListViewClass.h

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