Back to index

plt-scheme  4.2.1
xwMultiList.h
Go to the documentation of this file.
00001 /****************************************************************************
00002 
00003        MultiList.h
00004 
00005        This file is the public header file for the MultiList widget, an
00006        extension to the Athena List widget.
00007 
00008        This code is loosely based on the Athena List source which
00009        is why the MIT copyright notice appears below.
00010 
00011        The code was changed substantially in V3.4 to change the
00012        action/callback interface which was unnecessarily ugly.  Code
00013        using some features of the old interface may need to be changed.
00014        Hope the changes don't make people's lives too miserable.
00015 
00016  ****************************************************************************/
00017 
00018 /*
00019  * Author:
00020  *     Brian Totty
00021  *     Department of Computer Science
00022  *     University Of Illinois at Urbana-Champaign
00023  *     1304 West Springfield Avenue
00024  *     Urbana, IL 61801
00025  * 
00026  *     totty@cs.uiuc.edu
00027  *     
00028  */ 
00029 
00030 /*
00031  * Copyright 2004-2009 PLT Scheme Inc.
00032  * Copyright 1989 Massachusetts Institute of Technology
00033  *
00034  * Permission to use, copy, modify, distribute, and sell this software and its
00035  * documentation for any purpose is hereby granted without fee, provided that
00036  * the above copyright notice appear in all copies and that both that
00037  * copyright notice and this permission notice appear in supporting
00038  * documentation, and that the name of M.I.T. not be used in advertising or
00039  * publicity pertaining to distribution of the software without specific,
00040  * written prior permission.  M.I.T. makes no representations about the
00041  * suitability of this software for any purpose.  It is provided "as is"
00042  * without express or implied warranty.
00043  *
00044  * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
00045  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
00046  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
00047  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
00048  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 
00049  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
00050  *
00051  * Original Athena Author:  Chris D. Peterson, MIT X Consortium
00052  */
00053 
00054 #ifndef _MULTILIST_H_
00055 #define _MULTILIST_H_
00056 
00057 #include <X11/Xaw/Simple.h>
00058 #ifdef WX_USE_XFT
00059 # include <X11/Xft/Xft.h>
00060 #endif
00061 
00062 /*---------------------------------------------------------------------------*
00063 
00064       R E S O U R C E    D E S C R I P T I O N S    A N D    N O T E S
00065 
00066  *---------------------------------------------------------------------------*/
00067 
00068 /*
00069 
00070  Name              Class           RepType              Default Value
00071  ----              -----           -------              -------------
00072  background        Background             Pixel         XtDefaultBackground
00073  border                   BorderColor     Pixel         XtDefaultForeground
00074  borderWidth       BorderWidth     Dimension     1
00075  callback            Callback           XtCallbackList  NULL                *1
00076  columnWidth         Width              Dimension       0                   *9
00077  columnSpacing       Spacing            Dimension       8
00078  cursor                   Cursor          Cursor        left_ptr
00079  defaultColumns      Columns            int             1                   *2
00080  destroyCallback     Callback             Pointer              NULL 
00081  font              Font            XFontStruct*  XtDefaultFont
00082  forceColumns        Columns            Boolean         False               *2
00083  foreground        Foreground             Pixel         XtDefaultForeground
00084  height                   Height          Dimension     0                   *3
00085  highlightBackground HBackground   Pixel         XtDefaultForeground *4
00086  highlightForeground HForeground   Pixel         XtDefaultBackground *4
00087  insensitiveBorder   Insensitive   Pixmap        Gray
00088  list                List               String *        NULL                *5
00089  longest             Longest            int             0                   *6
00090  mappedWhenManaged   MappedWhenManaged    Boolean              True
00091  maxSelectable       Value              int             1                   *7
00092  numberStrings       NumberStrings      int             0                   *5
00093  pasteBuffer         Boolean            Boolean         False
00094  rowHeight           Height             Dimension       0                   *9
00095  rowSpacing          Spacing            Dimension       2
00096  sensitive         Sensitive              Boolean              True
00097  sensitiveArray      List               Boolean *       NULL                *8
00098  shadeSurplus      Boolean         Boolean              True              *10
00099  verticalList        Boolean            Boolean         False
00100  width             Width           Dimension     0
00101  x                 Position        Position      0
00102  y                 Position        Position      0
00103 
00104  *1 -  The callback functions are called whenever a highlight or unhighlight
00105        takes place.  More precisely, a callback occurs whenever the Notify()
00106        action is triggered.  By default, this occurs when the mouse button is
00107        lifted after a selection or deselection occurred.  The callback returns
00108        an XfwfMultiListReturnStruct data structure which contains numerous
00109        fields describing the selection state.  The most important fields
00110        indicate the total number of items selected, and a list of those items.
00111 
00112  *2 -  The defaultColumns resource is used in two cases.  If forceColumns
00113        is true, the widget will set the number of columns to the value of
00114        default columns.  If the widget width is unconstrained by the parent
00115        widgets, the defaultColumns is also used to determine the number of
00116        columns and the resulting width.  Otherwise, the number of columns
00117        will be calcultaed based on the current width and will be changed to
00118        an appropriate value.
00119 
00120  *3 -  If the width or height is set to zero (0), which is the default case,
00121        then the widget will calculate the size of that dimension to be just
00122        large enough to hold the contents of the widget.
00123 
00124  *4 -  The highlightForeground and highlightBackground colors specify the
00125        colors used to highlight the text (foreground) and the surrounding
00126        background space of a list item when it is selected (highlighted).
00127        The default is the reverse of the default foreground and background
00128        colors.
00129 
00130  *5 -  The list resource is an array of strings (char * array) which tell
00131        the names of each item of the list.  The number of elements of this
00132        array are indicated by the resource numberStrings.  If numberStrings
00133        is set to 0 (the default), then the MultiList widget will count the
00134        number of strings in the list.  This requires that the list be
00135        NULL terminated.  If list is NULL, then the widget treats it as an
00136        empty list.  Once the list is set the list resource is set to NULL,
00137        so you won't be able to read back the list after it has been set.  The
00138        widgets copies the strings internally, so the user can free the list
00139        storage after setting it.
00140 
00141  *6 -  This resource represent the longest string in pixels.  If this
00142        resource is zero (0), which is the default and probably the value
00143        most people should use, the longest string length is calculated
00144        and the resource is updated.
00145 
00146  *7 -  The maxSelectable resource indicates the maximum number of items
00147        which can be selected at any one time.  In the original Athena
00148        widget, you could have at most one item selected at a time.  In
00149        this widget, you can choose how many will be selected at a time.
00150 
00151  *8 -  Each item in the MultiList can be made insensitive, so it is printed in
00152        gray shading and can not be highlighted.  This can be done by
00153        setting the sensitivity list, which is an array of Booleans which
00154        indicate whether or not the corresponding item is sensitive (can be
00155        selected).  If sensitivity list is NULL, all items are sensitive.  The
00156        widget copies the sensitivity information, so the user can delete the
00157        sensitivity array storage after setting it.  The widget sets the
00158        resource to NULL after it has been set, so the user cannot read the
00159        old list back.
00160 
00161  *9 -  These values are intended for reading only.  They indicate the pixel
00162        width/height of the column/row.
00163 
00164  *10 - If the list height is made larger than the sum of the list entry
00165        heights, the surplus space is shaded in the background color if
00166        shadeSurplus is False, or in a gray stipple pattern if shadeSurplus
00167        is True.       
00168 
00169 */
00170 
00171 /*---------------------------------------------------------------------------*
00172 
00173                     S T R I N G    D E F I N I T I O N S
00174 
00175  *---------------------------------------------------------------------------*/
00176 
00177 #define XtCMLXftFont          "XftFont"
00178 #define XtNmlXftFont          "xftFont"
00179 
00180 #define XtCList                    "List"
00181 #define XtCSpacing          "Spacing"
00182 #define XtCColumns          "Columns"
00183 #define XtCLongest          "Longest"
00184 #define XtCNumberStrings    "NumberStrings"
00185 #define       XtCHForeground              "HForeground"
00186 #define       XtCHBackground              "HBackground"
00187 
00188 #ifndef XtNcursor
00189 #define XtNcursor           "cursor"
00190 #endif
00191 
00192 #define XtNoffset           "offset"
00193 
00194 #define       XtNhighlightForeground      "highlightForeground"
00195 #define       XtNhighlightBackground      "highlightBackground"
00196 #define XtNcolumnSpacing    "columnSpacing"
00197 #define XtNrowSpacing              "rowSpacing"
00198 #define XtNdefaultColumns   "defaultColumns"
00199 #define XtNforceColumns            "forceColumns"
00200 #define XtNpasteBuffer             "pasteBuffer"
00201 #define XtNverticalList            "verticalList"
00202 #define XtNlongest          "longest"
00203 #define XtNnumberStrings    "numberStrings"
00204 #define XtNlist                    "list"
00205 #define       XtNsensitiveArray    "sensitiveArray"
00206 #define       XtNmaxSelectable     "maxSelectable"
00207 #define       XtNshadeSurplus             "shadeSurplus"
00208 #define XtNclickExtends         "clickExtends"
00209 #define XtNdrawgray             "drawgray"
00210 
00211 #define       XtNrowHeight         "rowHeight"
00212 #define       XtNcolumnWidth              "columnWidth"
00213  
00214 #ifndef XtNtablist
00215 #define XtNtablist "tablist"
00216 #endif
00217 #ifndef XtCTablist
00218 #define XtCTablist "Tablist"
00219 #endif
00220 
00221        /* Class Record Constants */
00222 
00223 extern WidgetClass xfwfMultiListWidgetClass;
00224 
00225 typedef struct _XfwfMultiListClassRec *XfwfMultiListWidgetClass;
00226 typedef struct _XfwfMultiListRec      *XfwfMultiListWidget;
00227 
00228 /*---------------------------------------------------------------------------*
00229 
00230                      R E T U R N    S T R U C T U R E
00231 
00232  *---------------------------------------------------------------------------*/
00233 
00234 #define       XfwfMultiListActionNothing         0
00235 #define       XfwfMultiListActionHighlight              1
00236 #define       XfwfMultiListActionUnhighlight            2
00237 #define       XfwfMultiListActionStatus          3
00238 #define       XfwfMultiListActionDClick          4
00239 
00240 typedef struct _XfwfMultiListReturnStruct
00241 {
00242        int num_selected;           /* Number Of Items Now Selected */
00243        int *selected_items;        /* Indexes Of Selected Items */
00244 
00245        int action;                 /* Last Action Performed */
00246        int item;                   /* Last Item Index Modified */
00247        String string;                     /* String Of Last Index Modified */
00248 } XfwfMultiListReturnStruct;
00249 
00250 /*---------------------------------------------------------------------------*
00251 
00252                      U T I L I T Y    R O U T I N E S
00253 
00254  *---------------------------------------------------------------------------*/
00255 
00256 _XFUNCPROTOBEGIN
00257 
00258 #if (!NeedFunctionPrototypes)
00259 
00260 extern Boolean              XfwfMultiListHighlightItem();
00261 extern void          XfwfMultiListHighlightAll();
00262 extern void          XfwfMultiListUnhighlightItem();
00263 extern void          XfwfMultiListUnhighlightAll();
00264 extern int           XfwfMultiListToggleItem();
00265 extern XfwfMultiListReturnStruct *
00266                      XfwfMultiListGetHighlighted();
00267 extern Boolean              XfwfMultiListIsHighlighted();
00268 extern Boolean              XfwfMultiListGetItemInfo();
00269 extern void          XfwfMultiListSetNewData();
00270 
00271 #else
00272 
00273 extern Boolean              XfwfMultiListHighlightItem(XfwfMultiListWidget mlw,
00274                             int item_index);
00275 extern void          XfwfMultiListHighlightAll(XfwfMultiListWidget mlw);
00276 extern void          XfwfMultiListUnhighlightItem(XfwfMultiListWidget mlw,
00277                             int item_index);
00278 extern void          XfwfMultiListUnhighlightAll(XfwfMultiListWidget mlw);
00279 extern int           XfwfMultiListToggleItem(XfwfMultiListWidget mlw,
00280                             int item_index);
00281 extern XfwfMultiListReturnStruct *
00282                      XfwfMultiListGetHighlighted(XfwfMultiListWidget mlw);
00283 extern Boolean              XfwfMultiListIsHighlighted(XfwfMultiListWidget mlw,
00284                             int item_index);
00285 extern Boolean              XfwfMultiListGetItemInfo(XfwfMultiListWidget mlw,
00286                             int item_index, String *str_ptr,
00287                             Boolean *h_ptr, Boolean *s_ptr);
00288 extern void          XfwfMultiListSetNewData(XfwfMultiListWidget mlw,
00289                             String *list, int nitems, int longest,
00290                             Boolean resize, Boolean *sensitivity_array);
00291 
00292 #endif
00293 
00294 _XFUNCPROTOEND
00295 
00296 #endif