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...) 221