components/x11/libXaw4/src/Xaw3_1List.h

   1 /*
   2  * $XConsortium: List.h,v 1.15 89/12/11 15:08:59 kit Exp $
   3  *
   4  * Copyright 1989 Massachusetts Institute of Technology
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of M.I.T. not be used in advertising or
  11  * publicity pertaining to distribution of the software without specific,
  12  * written prior permission.  M.I.T. makes no representations about the
  13  * suitability of this software for any purpose.  It is provided "as is"
  14  * without express or implied warranty.
  15  *
  16  * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
  18  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  19  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  20  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  21  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  22  */
  23
  24 /*  This is the List widget, it is useful to display a list, without the
  25  *  overhead of having a widget for each item in the list.  It allows
  26  *  the user to select an item in a list and notifies the application through
  27  *  a callback function.
  28  *
  29  *      Created:        8/13/88
  30  *      By:             Chris D. Peterson
  31  *                      MIT X Consortium
  32  */
  33
  34 #ifndef _XawList_h
  35 #define _XawList_h
  36
  37 /***********************************************************************
  38  *
  39  * List Widget
  40  *
  41  ***********************************************************************/
  42
  43 #include <./Xaw3_1Simple.h>
  44
  45 /* Resources:
  46
  47  Name                Class              RepType         Default Value
  48  ----                -----              -------         -------------
  49  background          Background         Pixel           XtDefaultBackground
  50  border              BorderColor        Pixel           XtDefaultForeground
  51  borderWidth         BorderWidth        Dimension       1
  52  callback            Callback           XtCallbackList  NULL       **6
  53  columnSpacing       Spacing            Dimension       6
  54  cursor              Cursor             Cursor          left_ptr
  55  defaultColumns      Columns            int             2          **5
  56  destroyCallback     Callback           Pointer         NULL
  57  font                Font               XFontStruct*    XtDefaultFont
  58  forceColumns        Columns            Boolean         False      **5
  59  foreground          Foreground         Pixel           XtDefaultForeground
  60  height              Height             Dimension       0          **1
  61  insensitiveBorder   Insensitive        Pixmap          Gray
  62  internalHeight      Height             Dimension       2
  63  internalWidth       Width              Dimension       4
  64  list                List               String *        NULL       **2
  65  longest             Longest            int             0          **3  **4
  66  mappedWhenManaged   MappedWhenManaged  Boolean         True
  67  numberStrings       NumberStrings      int             0          **4
  68  pasteBuffer         Boolean            Boolean         False
  69  rowSpacing          Spacing            Dimension       4
  70  sensitive           Sensitive          Boolean         True
  71  verticalList        Boolean            Boolean         False
  72  width               Width              Dimension       0          **1
  73  x                   Position           Position        0
  74  y                   Position           Position        0
  75
  76  **1 - If the Width or Height of the list widget is zero (0) then the value
  77        is set to the minimum size necessay to fit the entire list.
  78
  79        If both Width and Height are zero then they are adjusted to fit the
  80        entire list that is created width the number of default columns
  81        specified in the defaultColumns resource.
  82
  83  **2 - This is an array of strings the specify elements of the list.
  84        This resource must be specified.
  85        (What good is a list widget without a list??  :-)
  86
  87  **3 - Longest is the length of the widest string in pixels.
  88
  89  **4 - If either of these values are zero (0) then the list widget calculates
  90        the correct value.
  91
  92        (This allows you to make startup faster if you already have
  93         this information calculated)
  94
  95        NOTE: If the numberStrings value is zero the list must
  96              be NULL terminated.
  97
  98  **5 - By setting the List.Columns resource you can force the application to
  99        have a given number of columns.
 100
 101  **6 - This returns the name and index of the item selected in an
 102        XawListReturnStruct that is pointed to by the client_data
 103        in the CallbackProc.
 104
 105 */
 106
 107
 108 /*
 109  * Value returned when there are no highlighted objects.
 110  */
 111
 112 #define XAW_LIST_NONE -1
 113
 114 #define XtCList "List"
 115 #define XtCSpacing "Spacing"
 116 #define XtCColumns "Columns"
 117 #define XtCLongest "Longest"
 118 #define XtCNumberStrings "NumberStrings"
 119
 120 #define XtNcursor "cursor"
 121 #define XtNcolumnSpacing "columnSpacing"
 122 #define XtNdefaultColumns "defaultColumns"
 123 #define XtNforceColumns "forceColumns"
 124 #define XtNlist "list"
 125 #define XtNlongest "longest"
 126 #define XtNnumberStrings "numberStrings"
 127 #define XtNpasteBuffer "pasteBuffer"
 128 #define XtNrowSpacing "rowSpacing"
 129 #define XtNverticalList "verticalList"
 130
 131 /* Class record constants */
 132
 133 extern WidgetClass listWidgetClass;
 134
 135 typedef struct _ListClassRec *ListWidgetClass;
 136 typedef struct _ListRec      *ListWidget;
 137
 138 /* The list return structure. */
 139
 140 typedef struct _XawListReturnStruct {
 141   String string;
 142   int list_index;
 143 } XawListReturnStruct;
 144 #ifdef XAW_BC
 145 /*************************************************************
 146  * For Compatibility only.                                   */
 147
 148 #define XtListReturnStruct   XawListReturnStruct
 149
 150 #define XT_LIST_NONE         XAW_LIST_NONE
 151
 152 #define XtListChange         XawListChange
 153 #define XtListUnhighlight    XawListUnhighlight
 154 #define XtListHighlight      XawListHighlight
 155 #define XtListShowCurrent    XawListShowCurrent
 156
 157 /*************************************************************/
 158 #endif /* XAW_BC */
 159
 160 /******************************************************************
 161  *
 162  * Exported Functions
 163  *
 164  *****************************************************************/
 165
 166 /*      Function Name: XawListChange.
 167  *      Description: Changes the list being used and shown.
 168  *      Arguments: w - the list widget.
 169  *                 list - the new list.
 170  *                 nitems - the number of items in the list.
 171  *                 longest - the length (in Pixels) of the longest element
 172  *                           in the list.
 173  *                 resize - if TRUE the the list widget will
 174  *                          try to resize itself.
 175  *      Returns: none.
 176  *      NOTE:      If nitems of longest are <= 0 then they will be caluculated.
 177  *                 If nitems is <= 0 then the list needs to be NULL terminated.
 178  */
 179
 180 extern void XawListChange(); /* w, list, nitems, longest, resize */
 181
 182 /*      Function Name: XawListUnhighlight
 183  *      Description: unlights the current highlighted element.
 184  *      Arguments: w - the widget.
 185  *      Returns: none.
 186  */
 187
 188 extern void XawListUnhighlight(); /* w */
 189
 190 /*      Function Name: XawListHighlight
 191  *      Description: Highlights the given item.
 192  *      Arguments: w - the list widget.
 193  *                 item - the item to hightlight.
 194  *      Returns: none.
 195  */
 196
 197 extern void XawListHighlight(); /* w, item */
 198
 199
 200 /*      Function Name: XawListShowCurrent
 201  *      Description: returns the currently highlighted object.
 202  *      Arguments: w - the list widget.
 203  *      Returns: the info about the currently highlighted object.
 204  */
 205
 206 extern XawListReturnStruct * XawListShowCurrent(); /* w */
 207
 208 #endif /* _XawList_h */
 209 /* DON'T ADD STUFF AFTER THIS #endif */