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