# coyote: FSC_DROPLIST

- coyote/General Programming
- [Source code]

NAME

      FSC_DROPLIST

PURPOSE

      The purpose of this compound widget is to provide an alternative
      to the DROPLIST widget offered in the IDL distribution. What has
      always annoyed me about a droplist is that you can't get the current
      "value" of a droplist easily. This compound widget makes this and
      other tasks much easier.

AUTHOR

      FANNING SOFTWARE CONSULTING
      David Fanning, Ph.D.
      1645 Sheely Drive
      Fort Collins, CO 80526 USA
      Phone: 970-221-0438
      E-mail: david@idlcoyote.com
      Coyote's Guide to IDL Programming: http://www.idlcoyote.com/

CATEGORY

      General programming.

CALLING SEQUENCE

      droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)
      The return value of the FSC_Droplist (droplistObj in this example) is
      an object reference. Interaction with the droplist will occur through
      object methods.

INPUT PARAMETERS

      parent -- The parent widget ID of the compound widget. Required.

INPUT KEYWORDS

Any keyword that is appropriate for the Widget_Droplist function can be used.

In addition, these keywords are explicitly defined.

      EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
      EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
      FORMAT -- A format specifier for the "format" of the values in the droplist.
      INDEX -- The index number of the current selection.
      SPACES -- A two-element array that indicates the number of blank spaces to be added
                to the the beginning and end of the formatted values. If a single number
                is provided, this number of blank spaces is added to both the beginning
                and the end of the value.
      TITLE -- The title of the droplist widget.
      UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
      UVALUE -- The normal "user value" of the droplist.
      VALUE -- An array of the droplist "selections". May be any data type.

COMMON BLOCKS

      None.

EVENT STRUCTURE

      An event is returned each time the droplist value is changed. The event structure
      is defined like this:
      event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure.
                ID: 0L, $             ; The ID of the compound widget's top-level base.
                TOP: 0L, $            ; The widget ID of the top-level base of the hierarchy.
                HANDLER: 0L, $        ; The event handler ID. Filled out by IDL.
                INDEX: 0L, $          ; The index number of the current selection.
                SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
                SELF:Obj_New() }      ; The object reference of the compound widget.

PUBLIC OBJECT METHODS

      GetID -- A function with no arguments that returns the widget identifier
         of the droplist widget.
         droplistID = droplistObj->GetID()
      GetIndex -- A function with no arguments that returns the index
         number of the current droplist selection.
         currentIndex = droplistObj->GetIndex()
      GetSelection -- A function with no arguments that returns the current
         droplist selection.
         currentSelection = droplistObj->GetSelection()
      GetUValue -- A function with no arguments that returns the "user value"
         of the compound widget i.e., the value set with the UVALUE keyword).
         myUValue = droplistObj->GetUValue()
      GetValues -- A function with no arguments that returns the "values" or
         "selections" for the droplist.
         possibleSelections = droplistObj->GetValues()
      Resize -- A procedure that sets the X screen size of the droplist. It is
         defined like this:
         PRO Resize, newSize, ParentSize=parentSize
         The "newSize" keyword is the new X screen size. If this argument is
         missing, the screen X size of the compound widget's parent is used.
         The parentSize keyword is an output keyword that returns the X screen
         size of the compound widget's parent.
         droplistObj->Resize, 400
         Note that not all devices (e.g., X Windows devices) support droplist resizing.
      SetIndex -- A procedure that sets the current droplist selection based on
         the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex
         droplistObj->SetIndex, newIndex
      SetSelection -- Whereas a regular droplist widget can only be set by index
         number, this compound widget can also be set by a "selection". The new selection
         can be any data type and corresponds to one of the "values" of the droplist.
         droplistObj->SetSelection, newSelection
      SetValues -- Sets the possible selections of the droplist widget. The CurrentIndex keyword
         will allow the current index of the selection to be changed to:
         newChoices = ['dog', 'cat', 'coyote']
         droplistObj->SetValues, newChoices, CurrentIndex=2

EXAMPLE

      An example program is provided at the end of the FSC_DROPLIST code. To run it,
      type these commands:
         IDL> .Compile FSC_DROPLIST
         IDL> Example

MODIFICATION HISTORY

      Written by: David W Fanning, 17 Jan 2000. DWF.
      Added FORMAT and SPACES keywords 28 April 2000. DWF.
      Fixed a small problem with event processing when the EVENT_FUNC keyword
         was used. 29 Dec 2000. DWF.
      Attached the UNAME value to the TLB of the compound widget instead
         of to the droplist widget itself. 11 Jan 2001. DWF.
      Fixed a problem when the droplist was part of a modal widget and used the
         EVENT_PRO keyword. 27 Oct 2003. DWF.
      Added a SetValue method for setting all the values in the droplist at once. 12 Nov 2004. DWF.
      Fixed type on line 346/ 6 Feb 2008. DWF.