/***********************************************************
Copyright 1993 Interleaf, Inc.

Permission to use, copy, modify, and distribute this software
and its documentation for any purpose without fee is granted,
provided that the above copyright notice appear in all copies
and that both copyright notice and this permission notice appear
in supporting documentation, and that the name of Interleaf not
be used in advertising or publicly pertaining to distribution of
the software without specific written prior permission.

Interleaf makes no representation about the suitability of this
software for any purpose. It is provided "AS IS" without any
express or implied warranty. 
******************************************************************/

Notes/Issues:
- The list menu is posted on the select button release.  In order to
  be like Windows, the menu would come up on the button press, and allow
  the user to drag immediately, without letting go of the select button.
  When I wrote the widget, I didn't have time to investigate getting this
  drag to work.  We would have to simulate the select press inside the
  list, I imagine.
- No key pattern matching available.
- Lack of translation table functionality.


1. ComboBox Widget

1.1 Widget Class Name

ComboBox

1.2 Synopsis

    #include "ComboBox.h"

    widget = DtCreateComboBox(parent, name, arglist, num_args);
    XtManageChild(widget);

1.3 Description

1.4 Resources

    Property		    Type		Init		      Access
    --------		    ----		----		      ------
    XmNactivateCallback     CallbackList        NULL                  CSG
    XmNalignment            unsigned char       XmALIGNMENT_BEGINNING CSG
    XmNarrowSpacing         Dimension           0                     CSG
    XmNarrowSize            Dimension           dynamic                 G
    XmNarrowType            unsigned char       XmWINDOWS             CSG
    XmNcolumns              Integer             20                    CSG
    XmNfocusCallback        CallbackList        NULL                  CSG
    XmNitemCount            Unsigned Integer    0                     CSG
    XmNitems                XmStringTable       NULL                  CSG
    XmNlabelString          XmString            NULL                  CSG
    XmNlist                 Widget              NULL                    G
    XmNlistFontList         FontList            NULL                  CSG
    XmNlistMarginHeight     Dimension           2                     CSG
    XmNlistMarginWidth      Dimension           2                     CSG
    XmNlistSpacing          Dimension           0                     CSG
    XmNlosingFocusCallback  CallbackList        NULL                  CSG
    XmNmarginHeight         Dimension           2                     CSG
    XmNmarginWidth          Dimension           2                     CSG
    XmNmaxLength            Unsigned Integer    MAXINT                CSG
    XmNmenuPostCallback     CallbackList        NULL                  CSG
    XmNorientation          unsigned char       XmRIGHT               CSG
    XmNpoppedUp             Boolean             FALSE                   G
    XmNrecomputeSize        Boolean             TRUE                  CSG
    XmNselectedItem         XmString            NULL                  CSG
    XmNselectedPosition     Unsigned Integer    0                     CSG
    XmNselectionCallback    CallbackList        NULL                  CSG
    XmNtextField            Widget              NULL                    G
    XmNtopItemPosition      Unsigned Integer    1                     CSG
    XmNtype                 unsigned char       XmDROP_DOWN_LIST_BOX  CSG
    XmNupdateLabel          Boolean             TRUE                  CSG
    XmNvisibleItemCount     Unsigned Integer    10                    CSG

    XmNactivateCallback:
		List of callbacks called when the user does KActivate in
		the text-field widget (when ComboBox is 
		XmDROP_DOWN_COMBO_BOX). See also XmTextFieldWidget.
		
    XmNalignment:
		Alignment of the text within the non-editable label.
		This only gets used if XmNtype is XmDROP_DOWN_LIST_BOX.
		Values are:
			XmALIGNMENT_CENTER, XmALIGNMENT_BEGINNING, 
			XmALIGNMENT_END
		See also XmLabelWidget

    XmNarrowSpacing:
		Amount of space between the arrow and the label or 
		text-field (in pixels).

    XmNarrowSize:
		Height/Width of arrow.  This is not a settable resource;
		it is based on the height of the ComboBox (which is
		related to the font used).

    XmNarrowType:
		Type of down arrow displayed in the ComboBox.  The legal
		values are:  XmWINDOWS, XmMOTIF

    Xmcolumns:
		This resource is passed on to the text-field widget.
		See also XmTextFieldWidget.

    XmNfocusCallback:
		List of callbacks called when the text-field widget accepts
		focus (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
		See also XmTextFieldWidget.

    XmNitemCount:
		Total number of items.  This value must be the number of
                items in XmNitems and must not be negative.  It is 
                automatically updated by the widget whenever an item
                is added or deleted.

    XmNitems:   
		A list of xm-strings which will be displayed in the drop
		down list box.

    XmNlabelString:
		This is the string that will be used in the label when the 
                resource XmNupdateLabel is FALSE.  This string will remain
                in the label as long as the XmNupdateLayout resource is
                FALSE, even if the user picks a new item off the list.

    XmNlist:
		List widget (which is inside the popup).  Gettable only.

    XmNlistFontList:
		This resource is passed on to the XmListWidget as the
		XmNfontList resource.
		See also XmListWidget.

    XmNlistMarginHeight:
		This resource is passed on to the XmListWidget as the
		XmNlistMarginHeight resource.
		See also XmListWidget.

    XmNlistMarginWidth:
		This resource is passed on to the XmListWidget as the
		XmNlistMarginWidth resource.
		See also XmListWidget.

    XmNlistSpacing:
		This resource is passed on to the XmListWidget as the
		XmNlistSpacing resource.
		See also XmListWidget.

    XmNlosingFocusCallback:
		List of callbacks called when the text-field widget loses
		focus (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
		See also XmTextFieldWidget.

    XmNmarginHeight:
		Vertical distance from the beginning of the widget to the
                start of the shadow.  Used for making this widget
                look like push-buttons, etc.

    XmNmarginWidth:
		Horizontal distance from the beginning of the widget to 
                the start of the shadow.  Used for making this widget
                look like push-buttons, etc.

    XmNmaxLength:
		Maximum length of the text string that can be entered into
		a text-field widget.  This resource is passed on to the
		text-field (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
		See also XmTextFieldWidget.

    XmNmenuPostCallback:
		List of callbacks called right before the list menu
		gets put on the screen.

    XmNorientation:
		Specifies location of down arrow.  Legal values are:
		XmLEFT, XmRIGHT

    XmNpoppedUp:
		Returns TRUE if the list menu is mapped; otherwise, FALSE.

    XmNrecomputeSize:
		If FALSE, the widget will not try to recompute a new
                size if setting some other resource would cause it
                to grow or shrink.

    XmNselectedItem:
		Item currently visible in list.  Can be used to
		change selected item.  User must make copy of this 
		before modifying.

    XmNselectedPosition:
		Position of item, within scrolling list, currently 
                visible (in label or text-field).  Can be used
		to change selected item. Starts at 0.

    XmNselectionCallback:
		List of callbacks called when the user selects something
		off the list (the list's XmNdefaultActionCallback or
		XmNbrowseSelectionCallback callbacks).
		See also XmListWidget.

    XmNtextField:
		text-field widget used within the ComboBox when
		XmNtype is XmDROP_DOWN_COMBO_BOX.

    XmNtopItemPosition:
		This resource is passed on to the XmListWidget as the
		XmNtopItemPosition resource.
		See also XmListWidget.

    XmNtype:
		Type of combo-box create.  Legal values are:
			XmDROP_DOWN_LIST_BOX (non-editable, uses label)
			XmDROP_DOWN_COMBO_BOX (editable, uses text-field)

    XmNupdateLabel:
    		If TRUE, the contents of the label will change when the
                user picks a new item off the list.  If FALSE, the
                label will not update, and the resource XmNlabelString
                will be used as the label.

    XmNvisibleItemCount:
		This resource is passed on to the XmListWidget as the
		XmNvisibleItemCount resource.
		See also XmListWidget.


========================================================================

Functions available for ComboBox widget.

	Widget
	DtCreateComboBox(parent, name, args, num_args)
	Widget parent;
	char *name;
	ArgList args;
	int num_args;
	{
	}

Creates an instance of a ComboBox widget.


	void
	DtComboBoxAddItem(widget, item, position, unique)
	DtComboBoxWidget widget;
	XmString item;
	int position;
	Boolean unique;

Adds the given item to the list at the given position.
position is an integer specifying the position of the new item in the
list.  A value of 1 makes the new item the first item in the list; a value
of 2 makes it the second item, and so on.  A value of 0 (zero) makes the new
item the last item in the list.
If the unique parameter is TRUE, the item will only be added if it doesn't
already exist.  If it is FALSE, the item will always be added.
See also, XmListSelectItem in the Motif reference manual.


	void
	DtComboBoxDeletePos(widget, position)
	DtComboBoxWidget widget;
	int position;

Deletes the item at the given position from the list.
position is an integer specifying the position of the item to delete 
in the list.  A value of 1 indicates that the first item in the list is
to be deleted. A value of 2 indicates the second item, etc.  A value of 0
indicates that the last item is to be deleted.  See also, 
XmListSelectItem in the Motif reference manual.

	void
	DtComboBoxSetItem(widget, item)
	DtComboBoxWidget widget;
	XmString item;

Puts the given item into the combo-box label or text-field (this will be the
new value shown).  The given item will be positioned at the top of the
list.  This may cause problems if the viewing area is larger than the
number of items in the list.  The new item will not be selected (use
DtComboBoxSelectItem).
See also, XmListSetItem in the Motif reference manual.


	void
	DtComboBoxSelectItem(combo, item)
	DtComboBoxWidget combo;
	XmString item;

Puts the given item into the combo-box label or text-field (this will be the
new value shown).  The currently selected item in the list will be deselected
and the given item will be selected.  See also, XmListSelectItem in the Motif
reference manual.

------------------------------------------------------------------------

