src/motif/xmcombo/combobox.doc

   1 Welcome to the ComboBox widget for Motif 1.1 or 1.2 (maybe even 2.0...)!
   2 This is now version 1.32.
   3 THERE ARE A LOT OF NEW RESOURCES AVAILABLE SO PLEASE READ THE
   4 DOCUMENTATION (in ComboBox_eng.dvi)!!!
   5
   6 If 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
   9 This is our campus server in Aachen, Germany. From outside Europe
  10 please 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
  14 There are many local ftp servers that mirror the /contrib directory. Thus
  15 with a delay of one or two days you'll also find the source on many other
  16 ftp sites.
  17
  18 PLEASE READ THIS INFORMATION CAREFULLY. IT ALWAYS CONTAINS THE MOST
  19 RECENT INFORMATION.
  20
  21 Whats 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
  66 Well - if you never heard of ComboBoxes you'll have to figure out
  67 yourself what these strange widgets really are. The following text
  68 will only explain how to include it into your own code. (Just as a little
  69 hint: combo boxes are well known from M$ Windoze. A combo box consists
  70 of a text input field with an arrow button besides it. When you click
  71 on the arrow button the combo box pops up a list just below its input
  72 area. You can now browse in it or pop it down by pressing the arrow button
  73 again.)
  74
  75 The 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
  77 Geometrie und Praktische Mathematik, where I'm working). So you get a well
  78 tested piece of widget magic. Please feel free to report any trouble you
  79 have using the ComboBox widget. But be patient - I'm just a student. In the
  80 meantime I've received a couple of reports and hopefully the widget now can
  81 be used on many well known systems as well as with Motif 1.1 and 1.2. I've
  82 heard of people using the ComboBox widget with Motif 2.0, because they need
  83 the many features... But there seems to be problems with the subclassing
  84 mechanism, so the sanity check CheckComboBox() fails. This check is now
  85 disabled if the source detects a Motif 2.0 release.
  86
  87 BTW - I'm collecting picture postcards...if you have one with a nice picture of
  88 the place you're living in, don't hesitate... 8-)
  89
  90 1. 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
 100 2. 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
 134 3. 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
 146 4. 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
 167 5. 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
 175 6. 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
 184 42. Known bugs: you will need a german dictionary to understand all the
 185     jokes in the source and in the german documentation.
 186
 187 That's it! Enjoy using this ComboBox widget.
 188 (More than 160 downloads yet within the first 3 weeks -- seems that I've
 189 filled in a real gap in Motif. Thanks to all who encouraged me to do
 190 further work on the ComboBox widget -- especially Chris Marotz!)
 191
 192 You may also want to visit my "Motif Programming Cornor" at
 193    file://ftp.igpm.rwth-aachen.de/arc/pub/unix/html/motifcorner.html
 194 with tips & tricks about Motif.
 195
 196 I really don't understand why the folks at OSF didn't implemented
 197 something like the M$ Windoze ComboBox in Motif. Maybe they have
 198 had their moti"f"es... (Rumor has spread it that the mysterious
 199 Motif 2.0 will have one - whow! after many years, the OSF folk got it!)
 200
 201 P.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
 213 Institut fuer Geometrie und Praktische Mathematik
 214 Rheinisch-Westfaelische Technische Universitaet Aachen,
 215 D-52056 Aachen, Germany
 216 albrecht@igpm.rwth-aachen.de
 217
 218 Bad Aachen -- Die Stadt der Printe. Warum Aachen ein Kurbad ist?
 219 -- Wieso Kurbad? "Bad" heisst doch nur, dass es hier staendig regnet (wenn
 220 es eben 'mal nicht schneit...)