================================= ``grail.widgets.glistbox`` module ================================= .. include:: ../../version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- Contains the :c:`GListBox` widget. This widget provides the user with the ability to associate a run-time variable (RTV) from the grail.rtv_ module with an item picked in the :c:`GListBox` widget. Whenever the user modifies the :c:`GListBox`, the appropriate RTV will be modified. Because there is *only* a one to one relationship between the contents of the :c:`GListBox` and the RTV, the :c:`GListBox` is only a single selection listbox. Finally, to make life simpler the Tkinter scrollbar logic has been automatically wrapped into this widget for easier use. ------- Example ------- The follow example illustrates working with the :c:`GListBox` .. Python:: from grail.widgets import * from grail import rtv def onselect(index): print "selected: %s (%d)" % (lb.get(index), index) def ondoubleclick(index): print "double-clicked: %s (%d)" % (lb.get(index), index) def onenabledisable(): if btn['text'] == 'disable': btn['text'] = 'enable' lb.disable() else: btn['text'] = 'disable' lb.enable() root = gwidgetinit() variable = rtv.StringRTV(name="glistboxtestrtv", value="b") lb = GListBox(root, items=["a", "b", "c"], rtv=variable) btn = Tkinter.Button(root, text="disable", command=onenabledisable) lb.pack(expand=1, fill='both') btn.pack(expand=1, fill='x') objsignal.listen(lb, const.sigON_SELECT, None, onselect) objsignal.listen(lb, const.sigON_DOUBLE_CLICK, None, ondoubleclick) variable.fromstring("c") root.title("Demo - GListBox") root.geometry("%dx%d+%d+%d" % (200, 200, 100, 100)) root.mainloop() Notice, that for simplicity, we mixed in a :c:`Tkinter.Button` into our dialog. This also illustrates that one can use both the MineSightŪ Grail and the Tkinter widgets side-by-side. The example script above will generate a Tkinter window that appears as follows, .. figure:: figure-glistbox-example.gif :alt: Screen shot of the GListbox widget. Example of the :c:`GListBox` widget. --------------- GListBox Widget --------------- The :c:`GListBox` widget inherits from, * :c:`gwidget.GWidget` (grail.widgets.gwidget_) * :c:`objsignal.Emitter` (grail.objsignal_) class :dc:`GListBox([parent, **keywords])` Creates a single pick list box that can be associated with a run-time variable (see grail.rtv_). In addition the scrollbar logic is wrapped into this widget for easier use. This listbox incorporates variables as well as wraps the scrollbar logic directly into the same widget. .. Note:: A few remarks on using :c:`GListBox`, * If you have multiple listboxes within the same frame you may see that the "selection" behavior will be only apparent in the last listbox selected. To avoid this behavior ensure you set the keyword exportselect is set to 1 (the default is 0). * The double-click behavior will generate both a sigON_SELECT and a sigON_DOUBLE_CLICK signal. The first signal is to indicate that the something was selected, the second is to indicate that the user double-clicked on their selection. .. Arguments: :a:`parent` : :c:`Tkinter.Frame` Parent widget, widget we insert into. :a:`keywords` Variable keyword list defined below. Keywords: All keywords usable with the :c:`Tkinter.ListBox` [#tkinter-listbox]_ widget are usable with the :c:`GListBox` widget. However, the :a:`selectmode` is always set to :d:`Tkinter.SINGLE`. :a:`items` : list List of strings to display within the listbox. :a:`rtv` : :c:`StringRTV` A variable to associate with listbox. :a:`disabledbackground` : string A HEX representation of the RGB color to use when the listbox is disabled. Components: None. Signals: :d:`const.sigON_SELECT` Generated when the user picks an item in the list, this also transmits the index of the picked item. :d:`const.sigON_DOUBLE_CLICK` Generated when the user double clicks on a list item, this also transmits the index of the picked item. :df:`delete(first[, last])` Delete elements from :a:`first` to :a:`last` indices. If :a:`last` index is not specified it will remove only the index specified in :a:`first`. :df:`destroy()` Handles Tkinter de-allocation. :df:`disable()` Set the listbox to ignore user events. :df:`enable()` Set the listbox to respond to user events. :df:`selectedindex()` Returns the index of the selected item. Since only single is allowed I thought this little convenience function may come in handy for the :c:`GListBox`. The Python :a:`None` is returned if no items are selected. :df:`selection_clear()` Clears the selected item. :df:`selection_set(index)` Sets the selected item to the one indicated in the index. :df:`updatevars()` Forces a synchronization with the user interface and any internal run-time variable. ---- .. [#tkinter-listbox] John W. Shipman. "The Label widget." *Tkinter Reference: a GUI for Python*. 2004 June 6. 2004 June 18.