components/x11/libXaw5/src/List.h

   1 /* $XConsortium: List.h,v 1.22 94/04/17 20:12:17 kaleb Exp $ */
   2
   3 /*
   4 Copyright (c) 1989, 1994  X Consortium
   5
   6 Permission is hereby granted, free of charge, to any person obtaining a copy
   7 of this software and associated documentation files (the "Software"), to deal
   8 in the Software without restriction, including without limitation the rights
   9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10 copies of the Software, and to permit persons to whom the Software is
  11 furnished to do so, subject to the following conditions:
  12
  13 The above copyright notice and this permission notice shall be included in
  14 all copies or substantial portions of the Software.
  15
  16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
  19 X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  20 AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22
  23 Except as contained in this notice, the name of the X Consortium shall not be
  24 used in advertising or otherwise to promote the sale, use or other dealings
  25 in this Software without prior written authorization from the X Consortium.
  26 */
  27
  28 /*  This is the List widget, it is useful to display a list, without the
  29  *  overhead of having a widget for each item in the list.  It allows
  30  *  the user to select an item in a list and notifies the application through
  31  *  a callback function.
  32  *
  33  *      Created:        8/13/88
  34  *      By:             Chris D. Peterson
  35  *                      MIT X Consortium
  36  */
  37
  38 #ifndef _XawList_h
  39 #define _XawList_h
  40
  41 /***********************************************************************
  42  *
  43  * List Widget
  44  *
  45  ***********************************************************************/
  46
  47 #include <X11/Xaw/Simple.h>
  48
  49 /* Resources:
  50
  51  Name                Class              RepType         Default Value
  52  ----                -----              -------         -------------
  53  background          Background         Pixel           XtDefaultBackground
  54  border              BorderColor        Pixel           XtDefaultForeground
  55  borderWidth         BorderWidth        Dimension       1
  56  callback            Callback           XtCallbackList  NULL       **6
  57  columnSpacing       Spacing            Dimension       6
  58  cursor              Cursor             Cursor          left_ptr
  59  cursorName          Cursor             String          NULL
  60  defaultColumns      Columns            int             2          **5
  61  destroyCallback     Callback           Pointer         NULL
  62  font                Font               XFontStruct*    XtDefaultFont
  63  forceColumns        Columns            Boolean         False      **5
  64  foreground          Foreground         Pixel           XtDefaultForeground
  65  height              Height             Dimension       0          **1
  66  insensitiveBorder   Insensitive        Pixmap          Gray
  67  internalHeight      Height             Dimension       2
  68  internalWidth       Width              Dimension       4
  69  list                List               String *        NULL       **2
  70  longest             Longest            int             0          **3  **4
  71  mappedWhenManaged   MappedWhenManaged  Boolean         True
  72  numberStrings       NumberStrings      int             0          **4
  73  pasteBuffer         Boolean            Boolean         False
  74  pointerColor        Foreground         Pixel           XtDefaultForeground
  75  pointerColorBackground Background      Pixel           XtDefaultBackground
  76  rowSpacing          Spacing            Dimension       4
  77  sensitive           Sensitive          Boolean         True
  78  verticalList        Boolean            Boolean         False
  79  width               Width              Dimension       0          **1
  80  x                   Position           Position        0
  81  y                   Position           Position        0
  82
  83  **1 - If the Width or Height of the list widget is zero (0) then the value
  84        is set to the minimum size necessay to fit the entire list.
  85
  86        If both Width and Height are zero then they are adjusted to fit the
  87        entire list that is created width the number of default columns
  88        specified in the defaultColumns resource.
  89
  90  **2 - This is an array of strings the specify elements of the list.
  91        This resource must be specified.
  92        (What good is a list widget without a list??  :-)
  93
  94  **3 - Longest is the length of the widest string in pixels.
  95
  96  **4 - If either of these values are zero (0) then the list widget calculates
  97        the correct value.
  98
  99        (This allows you to make startup faster if you already have
 100         this information calculated)
 101
 102        NOTE: If the numberStrings value is zero the list must
 103              be NULL terminated.
 104
 105  **5 - By setting the List.Columns resource you can force the application to
 106        have a given number of columns.
 107
 108  **6 - This returns the name and index of the item selected in an
 109        XawListReturnStruct that is pointed to by the client_data
 110        in the CallbackProc.
 111
 112 */
 113
 114
 115 /*
 116  * Value returned when there are no highlighted objects.
 117  */
 118
 119 #define XAW_LIST_NONE -1
 120
 121 #define XtCList "List"
 122 #define XtCSpacing "Spacing"
 123 #define XtCColumns "Columns"
 124 #define XtCLongest "Longest"
 125 #define XtCNumberStrings "NumberStrings"
 126
 127 #define XtNcursor "cursor"
 128 #define XtNcolumnSpacing "columnSpacing"
 129 #define XtNdefaultColumns "defaultColumns"
 130 #define XtNforceColumns "forceColumns"
 131 #define XtNlist "list"
 132 #define XtNlongest "longest"
 133 #define XtNnumberStrings "numberStrings"
 134 #define XtNpasteBuffer "pasteBuffer"
 135 #define XtNrowSpacing "rowSpacing"
 136 #define XtNverticalList "verticalList"
 137
 138 #ifndef XtNfontSet
 139 #define XtNfontSet "fontSet"
 140 #endif
 141
 142 #ifndef XtCFontSet
 143 #define XtCFontSet "FontSet"
 144 #endif
 145
 146 /* Class record constants */
 147
 148 extern WidgetClass listWidgetClass;
 149
 150 typedef struct _ListClassRec *ListWidgetClass;
 151 typedef struct _ListRec      *ListWidget;
 152
 153 /* The list return structure. */
 154
 155 typedef struct _XawListReturnStruct {
 156   String string;
 157   int list_index;
 158 } XawListReturnStruct;
 159
 160 /******************************************************************
 161  *
 162  * Exported Functions
 163  *
 164  *****************************************************************/
 165
 166 _XFUNCPROTOBEGIN
 167
 168 /*      Function Name: XawListChange.
 169  *      Description: Changes the list being used and shown.
 170  *      Arguments: w - the list widget.
 171  *                 list - the new list.
 172  *                 nitems - the number of items in the list.
 173  *                 longest - the length (in Pixels) of the longest element
 174  *                           in the list.
 175  *                 resize - if TRUE the the list widget will
 176  *                          try to resize itself.
 177  *      Returns: none.
 178  *      NOTE:      If nitems of longest are <= 0 then they will be caluculated.
 179  *                 If nitems is <= 0 then the list needs to be NULL terminated.
 180  */
 181
 182 extern void XawListChange(
 183 #if NeedFunctionPrototypes
 184     Widget              /* w */,
 185     String*             /* list */,
 186     int                 /* nitems */,
 187     int                 /* longest */,
 188 #if NeedWidePrototypes
 189     /* Boolean */ int   /* resize */
 190 #else
 191     Boolean             /* resize */
 192 #endif
 193 #endif
 194 );
 195
 196 /*      Function Name: XawListUnhighlight
 197  *      Description: unlights the current highlighted element.
 198  *      Arguments: w - the widget.
 199  *      Returns: none.
 200  */
 201
 202 extern void XawListUnhighlight(
 203 #if NeedFunctionPrototypes
 204     Widget              /* w */
 205 #endif
 206 );
 207
 208 /*      Function Name: XawListHighlight
 209  *      Description: Highlights the given item.
 210  *      Arguments: w - the list widget.
 211  *                 item - the item to highlight.
 212  *      Returns: none.
 213  */
 214
 215 extern void XawListHighlight(
 216 #if NeedFunctionPrototypes
 217     Widget              /* w */,
 218     int                 /* item */
 219 #endif
 220 );
 221
 222
 223 /*      Function Name: XawListShowCurrent
 224  *      Description: returns the currently highlighted object.
 225  *      Arguments: w - the list widget.
 226  *      Returns: the info about the currently highlighted object.
 227  */
 228
 229 extern XawListReturnStruct * XawListShowCurrent(
 230 #if NeedFunctionPrototypes
 231     Widget              /* w */
 232 #endif
 233 );
 234
 235 _XFUNCPROTOEND
 236
 237 #endif /* _XawList_h */