]> git.saurik.com Git - wxWidgets.git/blame - src/motif/xmcombo/combobox.doc
[ 1509599 ] 'Split pickers page in widgets sample' with more icons and rebaking.
[wxWidgets.git] / src / motif / xmcombo / combobox.doc
CommitLineData
8704bf74
JS
1Welcome to the ComboBox widget for Motif 1.1 or 1.2 (maybe even 2.0...)!
2This is now version 1.32.
3THERE ARE A LOT OF NEW RESOURCES AVAILABLE SO PLEASE READ THE
4DOCUMENTATION (in ComboBox_eng.dvi)!!!
5
6If you're in doubt, the primary source of this widget is
7 ftp.informatik.rwth-aachen.de (137.226.112.172)
8 The source is in: /pub/packages/ComboBox/ComboBox.tar.gz
9This is our campus server in Aachen, Germany. From outside Europe
10please also contact:
11 ftp.x.org (198.112.44.100)
12 There you'll find the source in:
13 /contrib/widgets/motif/ComboBox/ComboBox.tar.gz
14There are many local ftp servers that mirror the /contrib directory. Thus
15with a delay of one or two days you'll also find the source on many other
16ftp sites.
17
18PLEASE READ THIS INFORMATION CAREFULLY. IT ALWAYS CONTAINS THE MOST
19RECENT INFORMATION.
20
21Whats new? (changes since the last version are marked with an asterisk)
22 * Some minor changes concerning the drop down list layout have been made in
23 order to correct some minor quirks.
24 * Updated files for VMS users (hellooooo -- where are you?!!)
25 - A real man page for use with troff/groff. It's in ComboBox.groff.
26 - Some applications like GUI development tools or TclMotif were unable to
27 get notice of these special resources because they were implemented
28 through the core's setValues method. Thus they don't appeared in the
29 resource list because there aren't any instance variables connected to
30 them. These mirror resources instead belong to child widgets. With 1.23
31 the resource list (which can be queried by XtGetResourceList()) contains
32 entries for all mirror resources although the initial value setting is
33 always zero. But this should'nt matter. You can switch off these entries
34 by setting -DDONT_LOOK_IN_THE_MIRROR when compiling ComboBox.c.
35 - The selection policies XmSINGLE_SELECT and XmBROWSE_SELECT are now
36 supported.
37 - A new resource called XmNstaticList has been added, which switches the combo
38 box into a new mode with the drop down list statically displayed.
39 - Support of XmNautomaticSelection (like the resource known from XmList).
40 - New callbacks XmNunselectionCallback, XmNdefaultActionCallback,
41 XmNmodifyVerifyCallback, XmNmotionVerifyCallback and XmNvalueChangedCallback
42 added (don't know whether I forgot to mention one...).
43 - New convenience function XmComboBoxClearItemSelection() for deselecting
44 any selection in the combo box (if XmNselectionPolicy is XmSINGLE_SELECT).
45 - New demo app called FontSel. It shows how to realize a full blown
46 font selection dialog (even for scalable fonts) using combo boxes.
47 - Some additional casting has been added to the source, so it seems
48 now really to be ANSI compliant.
49 - can be compiled with Motif 1.2. (Tested on Sun & HP yet)
50 - many new resources & a callback that is called whenever the drop down
51 list gets dropped down or hidden.
52 - corrected a few minor typos in the header files (mis-spelled function
53 prototypes) and some minor quirks in the source.
54 - A FULL-BLOWN ENGLISH DOCUMENTATION (dvi file)
55 If you can't process dvi files you can download a post script variant
56 from ftp.informatik.rwth-aachen.de (137.226.112.172) as
57 /pub/packages/ComboBox/ComboBox_eng.ps.gz
58 - The XmNitems and XmNitemCount resources can now be set at any time (not
59 only when creating the ComboBox widget).
60 - Corrected some minor memory leaks in the source as well as some typos and
61 errors in the documentation.
62 - Drag'n'Drop is now supported with Motif 1.2.
63 - fvwm's handling of FocusOut events supported.
64
65
66Well - if you never heard of ComboBoxes you'll have to figure out
67yourself what these strange widgets really are. The following text
68will only explain how to include it into your own code. (Just as a little
69hint: combo boxes are well known from M$ Windoze. A combo box consists
70of a text input field with an arrow button besides it. When you click
71on the arrow button the combo box pops up a list just below its input
72area. You can now browse in it or pop it down by pressing the arrow button
73again.)
74
75The source code is now in (wide public) use for nearly a year.
76(before this time it was tested for half a year in the Institut fuer
77Geometrie und Praktische Mathematik, where I'm working). So you get a well
78tested piece of widget magic. Please feel free to report any trouble you
79have using the ComboBox widget. But be patient - I'm just a student. In the
80meantime I've received a couple of reports and hopefully the widget now can
81be used on many well known systems as well as with Motif 1.1 and 1.2. I've
82heard of people using the ComboBox widget with Motif 2.0, because they need
83the many features... But there seems to be problems with the subclassing
84mechanism, so the sanity check CheckComboBox() fails. This check is now
85disabled if the source detects a Motif 2.0 release.
86
87BTW - I'm collecting picture postcards...if you have one with a nice picture of
88the place you're living in, don't hesitate... 8-)
89
901. To compile you will need at least Motif :-)
91 (or :-( depending on your point of view...)
92 and an *ANSI* c compiler (the code is completely ANSI -
93 no more mess with the old K&R style)!
94 To compile, try something like
95 $ cc -DFUNCPROTO -c ComboBox.c
96 this should do it's work. -DFUNCPROTO is needed because the function
97 prototypes would be K&R style without it. In addition you often need
98 to specify to the compiler that the source is ANSI. (-ansi with gcc)
99
1002. Place a
101 #include "ComboBox.h"
102 at the top of your source file and create the widget just like any
103 other ordinary widget. The class is xmComboBoxWidgetClass. There is
104 no convenience function since it's hardly ever needed with this
105 widget.
106
107 To compile the short demo:
108 $ cc -DFUNCPROTO ComboBoxDemo.c -o ComboBoxDemo ComboBox.o \
109 -lXm -lXt -lX11
110 On some machines you'll need to link additional libs (like network
111 and socket libs).
112 Or use the makefile (first edit it accordingly to your needs):
113 $ make demo
114 Run the demo with:
115 $ ./ComboBoxDemo
116
117 I don't provide a makefile for every system/compiler combination
118 because this widget is intended to be placed seamless into the
119 existing Motif widget set. Thus, compile it and if all is ok, then
120 copy the includes to the Xm directory and the object file to a
121 suitable place in your file system -- but don't even think of
122 /dev/null as a good destination ;-)
123
124 To compile the FontSel demo:
125 Edit the makefile (if you haven't already done so), then do a:
126 $ make FontSel
127 And run the Font Selector demo:
128 $ ./FontSel
129
130 If you also have the ButtonFace Library you may want to do a
131 $ make FontSelX
132 instead. This will use my pictural push buttons for okay, cancel and help.
133
1343. The ComboBox consists primarily of a XmManager descendant - the
135 widget you'll get from XtCreateWidget(). This widget contains several
136 more widgets as its childs: a XmTextField and some other widgets.
137 You *must* not modify any resources of the TextField directly - this
138 leads sooner or later to trouble. Instead all the necessary instance
139 variables of the TextField are accessible through the main widget
140 (the one XtCreateWidget() returned).
141 There are many (convenience) functions like the ones for XmTextFields
142 and XmLists to set the TextField's text, add items to the drop down
143 list and and and... please see ComboBox.h for details (you know:
144 the documentation is under work...)
145
1464. There is one special resource called "persistentDropDown". It
147 defaults to "False". Its purpose it not easy to explain since that
148 has to do with the way your window manager is set up. If you're
149 using the explicit focus methode (that is: you move the keyboard
150 focus from application to application by clicking on the top level
151 window) you're lucky - don't ever think of this resource. For all
152 those other people (like me): if the window manager is set up to
153 give the keyboard focus to the top level window the mouse cursor
154 is over you'll notice one annoying "feature". (It's really *not*
155 a bug ;-) ) If you drop down the ComboBox's list (by clicking on
156 the arrow right beside the text field) and move the mouse cursor
157 out of the window the ComboBox resides in the list immediatly
158 disappears. That happens because the ComboBox looses the keyboard
159 focus. You can try to bypass that behavior by setting
160 "persistentDropDown" to "True" if you like. In the application's
161 resource file a line like
162 *YourApp*ComboBox.persistentDropDown: True
163 should do the job. But remember: whether this will work depends
164 on the window manager you're using. I have testet this with
165 Silicon Graphics' 4dwm (a mwm clone).
166
1675. On some window managers the drop down list gets hidden as soon as
168 the user moves the mouse cursor into the list. If this happens try
169 to set the resource "twmHandlingOn" to "True". You can do this
170 on the command line:
171 ComboBoxDemo -xrm "*.twmHandlingOn: True"
172 This should do it's job with twm as well as fvwm. With olwm you shouldn't
173 need to set one of the special resources.
174
1756. The combo box has been reported to run sucessfully on:
176 Silicon Graphics, Sun, HP, IBM RS6000, PC, even VMS!
177 Linux, of course...!
178 Attention VMS folks! You'll find two files called "motif11.opt" or
179 "motif12.opt" and "vmsmake.com" in this packages. They are provided by
180 Vincent Li. You'll hopefully know what to do with these two
181 files. They are provided "as is" with no warranty. Please read the file
182 "readme.vms".
183
18442. Known bugs: you will need a german dictionary to understand all the
185 jokes in the source and in the german documentation.
186
187That's it! Enjoy using this ComboBox widget.
188(More than 160 downloads yet within the first 3 weeks -- seems that I've
189filled in a real gap in Motif. Thanks to all who encouraged me to do
190further work on the ComboBox widget -- especially Chris Marotz!)
191
192You may also want to visit my "Motif Programming Cornor" at
193 file://ftp.igpm.rwth-aachen.de/arc/pub/unix/html/motifcorner.html
194with tips & tricks about Motif.
195
196I really don't understand why the folks at OSF didn't implemented
197something like the M$ Windoze ComboBox in Motif. Maybe they have
198had their moti"f"es... (Rumor has spread it that the mysterious
199Motif 2.0 will have one - whow! after many years, the OSF folk got it!)
200
201P.S.: This software is Free Software. Please refer to the file
202 COPYING, which you should have received together this
203 file and the source code of the combo box widget.
204 However if you find this widget to be usefull, you are encouraged
205 to donate a reasonable amount to a charitable institution --
206 there are enough people out there who need help! Sometimes I got
207 the strong impression that programmers tend to get lost in their
208 own "virtual reality" - sitting in front of their screen, hacking
209 new algorithms and forget about everything around them. So please
210 don't forget about people who need help.
211
212(c) 1993, 1994 Harald Albrecht
213Institut fuer Geometrie und Praktische Mathematik
214Rheinisch-Westfaelische Technische Universitaet Aachen,
215D-52056 Aachen, Germany
216albrecht@igpm.rwth-aachen.de
217
218Bad Aachen -- Die Stadt der Printe. Warum Aachen ein Kurbad ist?
219-- Wieso Kurbad? "Bad" heisst doch nur, dass es hier staendig regnet (wenn
220es eben 'mal nicht schneit...)