==================================
``grail.widgets.gcombobox`` module
==================================
.. include:: ../../version.h
.. include:: ref.h

.. contents:: Table of Contents
   :backlinks: top

-----------
Description
-----------

Contains the :c:`GComboBox` widget. A Combobox style widget is not commonly available within the Tkinter library.

-------
Example
-------

Below is an example of using the :c:`GComboBox` widget.

.. Python::
   
    import Tkinter
    from grail.widgets import *
    from grail import rtv

    var = rtv.StringRTV(name="__test_gcombobox")
    items = ["item-%.2d" % (i) for i in range(100)]

    root = Tkinter.Tk()
    left, right = gtools.splitframe(root, 
                                    orient='vertical', 
                                    expand=1, 
                                    fill=Tkinter.X)
    Tkinter.Label(left, 
                  text="This is a test combobox: ").pack(side=Tkinter.LEFT)
    cb = GComboBox(right, entry_width=30, items=items)

    cb.pack(expand=1, fill=Tkinter.X)
    cb.select(30)
    root.title("Demo - GCombobox")
    root.focus_set()
    root.mainloop()

This will create a dialog that contains a :c:`GComboBox` widget with 100 items in it and with item 30 selected.

.. figure:: figure-gcombobox-example.gif
   :alt: Screen shot of the GComboBox widget.

   Example of the :c:`GComboBox` widget.

----------------
GComboBox Widget
----------------

The :c:`GComboBox` widget inherits from,
  * :c:`gwidget.GWidget` (grail.widgets.gwidget_)
  * :c:`objsignal.Emitter` (grail.objsignal_)

class :dc:`GComboBox([parent, **keywords])`
    Creates our own custom combobox.

    Arguments:
       :a:`parent` : :c:`Tkinter.Frame`
          Parent widget, widget we insert into.

       :a:`keywords` 
          Variable keyword list defined below.

    Keywords:
      :a:`rtv`
        A grail.rtv_ variable that you wish to associate with the
        :c:`GComboBox`.
       
      :a:`items`
        A list of valid items for this combobox. The default value
        is an empty list.

      :a:`required`
        Flags whether or not we must have a value specified within
        the combobox (i.e. something must be selected). The default
        value is 0.

      All other keywords can be applied to the :c:`GComboBox` object's
      components by prefixing the keyword with the component name.
      
    Signals:
      :d:`const.sigON_SELECT`
        Generated when the user picks an item within the textbox.
        The receiver function should receive the index as its only
        argument.  

    Components:
      entry
         The text entry box.
      arrow
         The pulldown arrow.
      listbox 
          The listbox that appears when you click the arrow.
        
    Some additional information about the :f:`cget()` and :f:`configure()`
    options,
    
      * The keyword :a:`text` will return the a string of the currently
        selected item in the combobox.
    
      * To find the index of the currently selected item do the following,
        with a combobox named :a:`cb`,

        .. Python::
    
         index = cb.find(cb.cget('text'))
         if index is None:
            print "no item selected"
         else:
            print "index of selected item is: %d" % (index)
   
      * To change the color configuration, use the entry_XXX keywords.  For
        example, :a:`entry_enablebackground` and :a:`entry_disablebackground`.
        In the future these will be mapped to the combobox proper, but for now
        prefix with entry.
    
    :df:`delete(first[, last])`
        Removes the said items from the combobox list
        
        .. Note::

           If you attempt to delete everything from a combobox that has a
           :a:`required` flag on it, then your dialog will go into an
           inconsistent state. If you have a :a:`required` flag set, then
           perfer to clear you combobox and incrementally insert.
    
    :df:`destroy()`
        Handle the Tkinter clean-up request.
    
    :df:`disable()`
        Set the combobox to ignore user events.
    
    :df:`enable()`
        Set the combobox to respond to user events.
    
    :df:`find(item)`
        Returns the index (or None) for an item in the combobox list.
    
    :df:`get(first[, last])`
        Returns a list of elements from the combobox's pulldown list, from
        :a:`first` to :a:`last`. If last is not defined it is assumed to be the
        end of the list. Forwards to the listbox's (pulldown) :f:`get()`
        method.
    
    :df:`insert(idx, *items)`
        Inserts a list of items into the pulldown box.
        
        Arguments:
          :a:`idx` : integer
            Index to the insertion. Remember you have :d:`Tkinter.END` and 0.
          :a:`items`: variable argument list
            A set of arguments that you wish to insert into the list.
       
        Some examples are,

         .. Python::

           combobox.insert(Tkinter.END, 'copper', 'gold', 'silver')
           items = ["MODEL1", "MODEL2", "MODEL3"]
           combobox.insert(Tkinter.END, *items)

        Both these examples insert items into the end of the combobox.

    :df:`select(index)`
        Takes an the indexed item and puts it into the entry.
    
    :df:`select_clear()`
        Clears the text entry box.
        
        Raises :e:`GWidgetError` for a clear request made to a combobox that
        *requires* an entry.
    
    :df:`size()`
        Returns the number of elements in the combobox's pulldown list.
        Forwards to the listbox's (pulldown) :f:`size()` method.
    
    :df:`updatevars()`
        Ensure that the entry and RTV are in sync.
        
        In this case forwards to internal entry widget.