home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / cmd / xfe / DtWidgets / ComboBox.README < prev    next >
Encoding:
Text File  |  1998-04-08  |  11.0 KB  |  302 lines
  1. /***********************************************************
  2. Copyright 1993 Interleaf, Inc.
  3.  
  4. Permission to use, copy, modify, and distribute this software
  5. and its documentation for any purpose without fee is granted,
  6. provided that the above copyright notice appear in all copies
  7. and that both copyright notice and this permission notice appear
  8. in supporting documentation, and that the name of Interleaf not
  9. be used in advertising or publicly pertaining to distribution of
  10. the software without specific written prior permission.
  11.  
  12. Interleaf makes no representation about the suitability of this
  13. software for any purpose. It is provided "AS IS" without any
  14. express or implied warranty. 
  15. ******************************************************************/
  16.  
  17. Notes/Issues:
  18. - The list menu is posted on the select button release.  In order to
  19.   be like Windows, the menu would come up on the button press, and allow
  20.   the user to drag immediately, without letting go of the select button.
  21.   When I wrote the widget, I didn't have time to investigate getting this
  22.   drag to work.  We would have to simulate the select press inside the
  23.   list, I imagine.
  24. - No key pattern matching available.
  25. - Lack of translation table functionality.
  26.  
  27.  
  28. 1. ComboBox Widget
  29.  
  30. 1.1 Widget Class Name
  31.  
  32. ComboBox
  33.  
  34. 1.2 Synopsis
  35.  
  36.     #include "ComboBox.h"
  37.  
  38.     widget = DtCreateComboBox(parent, name, arglist, num_args);
  39.     XtManageChild(widget);
  40.  
  41. 1.3 Description
  42.  
  43. 1.4 Resources
  44.  
  45.     Property            Type        Init              Access
  46.     --------            ----        ----              ------
  47.     XmNactivateCallback     CallbackList        NULL                  CSG
  48.     XmNalignment            unsigned char       XmALIGNMENT_BEGINNING CSG
  49.     XmNarrowSpacing         Dimension           0                     CSG
  50.     XmNarrowSize            Dimension           dynamic                 G
  51.     XmNarrowType            unsigned char       XmWINDOWS             CSG
  52.     XmNcolumns              Integer             20                    CSG
  53.     XmNfocusCallback        CallbackList        NULL                  CSG
  54.     XmNitemCount            Unsigned Integer    0                     CSG
  55.     XmNitems                XmStringTable       NULL                  CSG
  56.     XmNlabelString          XmString            NULL                  CSG
  57.     XmNlist                 Widget              NULL                    G
  58.     XmNlistFontList         FontList            NULL                  CSG
  59.     XmNlistMarginHeight     Dimension           2                     CSG
  60.     XmNlistMarginWidth      Dimension           2                     CSG
  61.     XmNlistSpacing          Dimension           0                     CSG
  62.     XmNlosingFocusCallback  CallbackList        NULL                  CSG
  63.     XmNmarginHeight         Dimension           2                     CSG
  64.     XmNmarginWidth          Dimension           2                     CSG
  65.     XmNmaxLength            Unsigned Integer    MAXINT                CSG
  66.     XmNmenuPostCallback     CallbackList        NULL                  CSG
  67.     XmNorientation          unsigned char       XmRIGHT               CSG
  68.     XmNpoppedUp             Boolean             FALSE                   G
  69.     XmNrecomputeSize        Boolean             TRUE                  CSG
  70.     XmNselectedItem         XmString            NULL                  CSG
  71.     XmNselectedPosition     Unsigned Integer    0                     CSG
  72.     XmNselectionCallback    CallbackList        NULL                  CSG
  73.     XmNtextField            Widget              NULL                    G
  74.     XmNtopItemPosition      Unsigned Integer    1                     CSG
  75.     XmNtype                 unsigned char       XmDROP_DOWN_LIST_BOX  CSG
  76.     XmNupdateLabel          Boolean             TRUE                  CSG
  77.     XmNvisibleItemCount     Unsigned Integer    10                    CSG
  78.  
  79.     XmNactivateCallback:
  80.         List of callbacks called when the user does KActivate in
  81.         the text-field widget (when ComboBox is 
  82.         XmDROP_DOWN_COMBO_BOX). See also XmTextFieldWidget.
  83.         
  84.     XmNalignment:
  85.         Alignment of the text within the non-editable label.
  86.         This only gets used if XmNtype is XmDROP_DOWN_LIST_BOX.
  87.         Values are:
  88.             XmALIGNMENT_CENTER, XmALIGNMENT_BEGINNING, 
  89.             XmALIGNMENT_END
  90.         See also XmLabelWidget
  91.  
  92.     XmNarrowSpacing:
  93.         Amount of space between the arrow and the label or 
  94.         text-field (in pixels).
  95.  
  96.     XmNarrowSize:
  97.         Height/Width of arrow.  This is not a settable resource;
  98.         it is based on the height of the ComboBox (which is
  99.         related to the font used).
  100.  
  101.     XmNarrowType:
  102.         Type of down arrow displayed in the ComboBox.  The legal
  103.         values are:  XmWINDOWS, XmMOTIF
  104.  
  105.     Xmcolumns:
  106.         This resource is passed on to the text-field widget.
  107.         See also XmTextFieldWidget.
  108.  
  109.     XmNfocusCallback:
  110.         List of callbacks called when the text-field widget accepts
  111.         focus (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
  112.         See also XmTextFieldWidget.
  113.  
  114.     XmNitemCount:
  115.         Total number of items.  This value must be the number of
  116.                 items in XmNitems and must not be negative.  It is 
  117.                 automatically updated by the widget whenever an item
  118.                 is added or deleted.
  119.  
  120.     XmNitems:   
  121.         A list of xm-strings which will be displayed in the drop
  122.         down list box.
  123.  
  124.     XmNlabelString:
  125.         This is the string that will be used in the label when the 
  126.                 resource XmNupdateLabel is FALSE.  This string will remain
  127.                 in the label as long as the XmNupdateLayout resource is
  128.                 FALSE, even if the user picks a new item off the list.
  129.  
  130.     XmNlist:
  131.         List widget (which is inside the popup).  Gettable only.
  132.  
  133.     XmNlistFontList:
  134.         This resource is passed on to the XmListWidget as the
  135.         XmNfontList resource.
  136.         See also XmListWidget.
  137.  
  138.     XmNlistMarginHeight:
  139.         This resource is passed on to the XmListWidget as the
  140.         XmNlistMarginHeight resource.
  141.         See also XmListWidget.
  142.  
  143.     XmNlistMarginWidth:
  144.         This resource is passed on to the XmListWidget as the
  145.         XmNlistMarginWidth resource.
  146.         See also XmListWidget.
  147.  
  148.     XmNlistSpacing:
  149.         This resource is passed on to the XmListWidget as the
  150.         XmNlistSpacing resource.
  151.         See also XmListWidget.
  152.  
  153.     XmNlosingFocusCallback:
  154.         List of callbacks called when the text-field widget loses
  155.         focus (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
  156.         See also XmTextFieldWidget.
  157.  
  158.     XmNmarginHeight:
  159.         Vertical distance from the beginning of the widget to the
  160.                 start of the shadow.  Used for making this widget
  161.                 look like push-buttons, etc.
  162.  
  163.     XmNmarginWidth:
  164.         Horizontal distance from the beginning of the widget to 
  165.                 the start of the shadow.  Used for making this widget
  166.                 look like push-buttons, etc.
  167.  
  168.     XmNmaxLength:
  169.         Maximum length of the text string that can be entered into
  170.         a text-field widget.  This resource is passed on to the
  171.         text-field (when ComboBox is editable - XmDROP_DOWN_COMBO_BOX).
  172.         See also XmTextFieldWidget.
  173.  
  174.     XmNmenuPostCallback:
  175.         List of callbacks called right before the list menu
  176.         gets put on the screen.
  177.  
  178.     XmNorientation:
  179.         Specifies location of down arrow.  Legal values are:
  180.         XmLEFT, XmRIGHT
  181.  
  182.     XmNpoppedUp:
  183.         Returns TRUE if the list menu is mapped; otherwise, FALSE.
  184.  
  185.     XmNrecomputeSize:
  186.         If FALSE, the widget will not try to recompute a new
  187.                 size if setting some other resource would cause it
  188.                 to grow or shrink.
  189.  
  190.     XmNselectedItem:
  191.         Item currently visible in list.  Can be used to
  192.         change selected item.  User must make copy of this 
  193.         before modifying.
  194.  
  195.     XmNselectedPosition:
  196.         Position of item, within scrolling list, currently 
  197.                 visible (in label or text-field).  Can be used
  198.         to change selected item. Starts at 0.
  199.  
  200.     XmNselectionCallback:
  201.         List of callbacks called when the user selects something
  202.         off the list (the list's XmNdefaultActionCallback or
  203.         XmNbrowseSelectionCallback callbacks).
  204.         See also XmListWidget.
  205.  
  206.     XmNtextField:
  207.         text-field widget used within the ComboBox when
  208.         XmNtype is XmDROP_DOWN_COMBO_BOX.
  209.  
  210.     XmNtopItemPosition:
  211.         This resource is passed on to the XmListWidget as the
  212.         XmNtopItemPosition resource.
  213.         See also XmListWidget.
  214.  
  215.     XmNtype:
  216.         Type of combo-box create.  Legal values are:
  217.             XmDROP_DOWN_LIST_BOX (non-editable, uses label)
  218.             XmDROP_DOWN_COMBO_BOX (editable, uses text-field)
  219.  
  220.     XmNupdateLabel:
  221.             If TRUE, the contents of the label will change when the
  222.                 user picks a new item off the list.  If FALSE, the
  223.                 label will not update, and the resource XmNlabelString
  224.                 will be used as the label.
  225.  
  226.     XmNvisibleItemCount:
  227.         This resource is passed on to the XmListWidget as the
  228.         XmNvisibleItemCount resource.
  229.         See also XmListWidget.
  230.  
  231.  
  232. ========================================================================
  233.  
  234. Functions available for ComboBox widget.
  235.  
  236.     Widget
  237.     DtCreateComboBox(parent, name, args, num_args)
  238.     Widget parent;
  239.     char *name;
  240.     ArgList args;
  241.     int num_args;
  242.     {
  243.     }
  244.  
  245. Creates an instance of a ComboBox widget.
  246.  
  247.  
  248.     void
  249.     DtComboBoxAddItem(widget, item, position, unique)
  250.     DtComboBoxWidget widget;
  251.     XmString item;
  252.     int position;
  253.     Boolean unique;
  254.  
  255. Adds the given item to the list at the given position.
  256. position is an integer specifying the position of the new item in the
  257. list.  A value of 1 makes the new item the first item in the list; a value
  258. of 2 makes it the second item, and so on.  A value of 0 (zero) makes the new
  259. item the last item in the list.
  260. If the unique parameter is TRUE, the item will only be added if it doesn't
  261. already exist.  If it is FALSE, the item will always be added.
  262. See also, XmListSelectItem in the Motif reference manual.
  263.  
  264.  
  265.     void
  266.     DtComboBoxDeletePos(widget, position)
  267.     DtComboBoxWidget widget;
  268.     int position;
  269.  
  270. Deletes the item at the given position from the list.
  271. position is an integer specifying the position of the item to delete 
  272. in the list.  A value of 1 indicates that the first item in the list is
  273. to be deleted. A value of 2 indicates the second item, etc.  A value of 0
  274. indicates that the last item is to be deleted.  See also, 
  275. XmListSelectItem in the Motif reference manual.
  276.  
  277.     void
  278.     DtComboBoxSetItem(widget, item)
  279.     DtComboBoxWidget widget;
  280.     XmString item;
  281.  
  282. Puts the given item into the combo-box label or text-field (this will be the
  283. new value shown).  The given item will be positioned at the top of the
  284. list.  This may cause problems if the viewing area is larger than the
  285. number of items in the list.  The new item will not be selected (use
  286. DtComboBoxSelectItem).
  287. See also, XmListSetItem in the Motif reference manual.
  288.  
  289.  
  290.     void
  291.     DtComboBoxSelectItem(combo, item)
  292.     DtComboBoxWidget combo;
  293.     XmString item;
  294.  
  295. Puts the given item into the combo-box label or text-field (this will be the
  296. new value shown).  The currently selected item in the list will be deselected
  297. and the given item will be selected.  See also, XmListSelectItem in the Motif
  298. reference manual.
  299.  
  300. ------------------------------------------------------------------------
  301.  
  302.