README

This is a JQuery plugin for an editable combobox, built according to JQuery UI 1.5 conventions.  There are a couple existing combobox plugins, but they either weren't true comboboxes (dropdown only) or they would fail if you tried typing something non-ASCII into the text field.  This uses a different approach: the text field is real, but the drop-down is faked as a collection of spans.

### Dependencies ###

* jquery.js (1.2.6 or later)
* ui.core.js (1.5b4 or later)
* for default styling, ui.combobox.css and drop_down.png

### Usage ###

$(selector).combobox() may be called on elements of any type.  If the element is a <select> tag, the combobox will attempt to populate itself from the options of the select.  Otherwise, the options arguments must have a 'data' field that contains a list of options.  By default, those options are displayed verbatim in the drop-down list; you can customize this by providing a function for the listHTML option.

The selected element is completely replaced by a text field, drop-down list, and image to display the drop-down list.  The name, class, and id attributes are copied over from the original element to the new input field, and after the call, the JQuery collection will point to the new input field(s).  Calling combobox('destroy') will restore the original element.

The drop-down list is keyboard sensitive with the following keybindings:

* F4: Show the drop-down list 
* ESC: Hide the drop-down list
* Up: Previous option
* Down: Next option
* Enter: Select the current option

Additionally, options are auto-selected by typing within the input box.

### Options ###

* data: A list of options for the combobox
* autoShow: If true (the default), then display the drop-down whenever the input field receives focus.  Otherwise, the user must explicitly click the drop-down icon to show the list.
* matchMiddle: If true (the default), then the combobox tries to match the typed text with any portion of any of the options, instead of just the beginning.
* key: event handler called whenever a key is pressed in the input box.
* change: event handler called whenever a new option is selected on the drop-down list (eg. down/up arrows, typing in the input field).
* select: event handler called when a selection is finished (enter pressed or input field loses focus)
* arrowURL: URL of the image used for the drop-down arrow.  Used only by the default arrowHTML function; if you override that, you don't need to supply this.  Defaults to "drop_down.png"
* arrowHTML: function that should return the HTML of the element used to display the drop-down.  Defaults to an image tag.
* listContainerTag: Tag to hold the drop-down list element.
* listHTML: function that takes the option datum and index within the list and returns an HTML fragment for each option.  Default is a span of class ui-combobox-item.

All event handlers take 2 arguments: the original browser event, and an object with the following fields:

* value: the current value of the input field
* index: the index within the option list of the presently-selected value, or -1 if directly inputted.
* isCustom: true if the user has typed in an option not on the list
* inputElement: JQuery object containing the input field
* listElement: JQuery object containing the drop-down list

The event handlers are also available as custom JQuery events, following JQuery UI conventions (i.e. select = 'comboboxselect', key = 'comboboxkey', etc.)

## License

Dual-licensed under GPL and MIT licenses, same as regular JQuery.