/**
 * Widget module.
 *
 * License:
 *     MIT. See LICENSE for full details.
 */
module tkd.widget.combobox;

/**
 * Imports.
 */
import std.conv;
import tkd.element.element;
import tkd.element.uielement;
import tkd.widget.common.boundingbox;
import tkd.widget.common.cursor;
import tkd.widget.common.data;
import tkd.widget.common.delete_;
import tkd.widget.common.exportselection;
import tkd.widget.common.height;
import tkd.widget.common.index;
import tkd.widget.common.insert;
import tkd.widget.common.justify;
import tkd.widget.common.postcommand;
import tkd.widget.common.selection;
import tkd.widget.common.value;
import tkd.widget.common.width;
import tkd.widget.common.xscrollcommand;
import tkd.widget.common.xview;
import tkd.widget.widget;

/**
 * A combobox combines a text field with a pop-down list of values; the user 
 * may select the value of the text field from among the values in the list.
 *
 * This widget has two types of values that can be set. First, a list of values 
 * can be set to populate the drop-down list which can then be selected via a 
 * mouse. Second, the value can be set independently and in addition to the 
 * value list. See the below widget specific and common commands for an 
 * overview of how this works.
 *
 * Example:
 * ---
 * auto data = ["foo", "bar", "baz", "qux"];
 *
 * auto comboBox = new ComboBox()
 * 	.setData(data);
 * 	.setValue(data[0])
 * 	.pack();
 * ---
 *
 * Common_Commands:
 *     These are injected common commands that can also be used with this widget.
 *     $(P
 *         $(LINK2 ./common/boundingbox.html, BoundingBox) $(BR)
 *         $(LINK2 ./common/cursor.html, Cursor) $(BR)
 *         $(LINK2 ./common/data.html, Data) $(BR)
 *         $(LINK2 ./common/delete_.html, Delete) $(BR)
 *         $(LINK2 ./common/exportselection.html, Exportselection) $(BR)
 *         $(LINK2 ./common/height.html, Height) $(BR)
 *         $(LINK2 ./common/index.html, Index) $(BR)
 *         $(LINK2 ./common/insert.html, Insert) $(BR)
 *         $(LINK2 ./common/justify.html, Justify) $(BR)
 *         $(LINK2 ./common/postcommand.html, PostCommand) $(BR)
 *         $(LINK2 ./common/selection.html, Selection) $(BR)
 *         $(LINK2 ./common/value.html, Value) $(BR)
 *         $(LINK2 ./common/width.html, Width) $(BR)
 *         $(LINK2 ./common/xscrollcommand.html, XScrollCommand) $(BR)
 *         $(LINK2 ./common/xview.html, XView) $(BR)
 *     )
 *
 * Additional_Events:
 *     Additional events that can also be bound to using the $(LINK2 ../element/uielement.html#UiElement.bind, bind) method.
 *     $(P
 *         <<Clear>>,
 *         <<Copy>>,
 *         <<Cut>>,
 *         <<Paste>>,
 *         <<PasteSelection>>,
 *         <<PrevWindow>>,
 *         <<TraverseIn>>,
 *         <Alt-Key>,
 *         <B1-Enter>,
 *         <B1-Leave>,
 *         <B1-Motion>,
 *         <B2-Motion>,
 *         <Button-1>,
 *         <Button-2>,
 *         <Button-4>,
 *         <Button-5>,
 *         <ButtonRelease-1>,
 *         <ButtonRelease-2>,
 *         <Control-Button-1>,
 *         <Control-Key-Left>,
 *         <Control-Key-Right>,
 *         <Control-Key-a>,
 *         <Control-Key-b>,
 *         <Control-Key-backslash>,
 *         <Control-Key-d>,
 *         <Control-Key-e>,
 *         <Control-Key-f>,
 *         <Control-Key-h>,
 *         <Control-Key-k>,
 *         <Control-Key-slash>,
 *         <Control-Key>,
 *         <Control-Shift-Key-Left>,
 *         <Control-Shift-Key-Right>,
 *         <Double-Button-1>,
 *         <Key-BackSpace>,
 *         <Key-Delete>,
 *         <Key-Down>,
 *         <Key-End>,
 *         <Key-Escape>,
 *         <Key-F10>,
 *         <Key-Home>,
 *         <Key-KP_Enter>,
 *         <Key-Left>,
 *         <Key-Return>,
 *         <Key-Right>,
 *         <Key-Tab>,
 *         <Key-Up>,
 *         <Key>,
 *         <Meta-Key>,
 *         <Motion>,
 *         <Shift-Button-1>,
 *         <Shift-Key-End>,
 *         <Shift-Key-Home>,
 *         <Shift-Key-Left>,
 *         <Shift-Key-Right>,
 *         <Triple-Button-1>,
 *     )
 *
 * See_Also:
 *     $(LINK2 ./widget.html, tkd.widget.widget)
 */
class ComboBox : Widget, IXScrollable!(ComboBox)
{
	/**
	 * The name of the variable that contains the widget's value.
	 */
	private string _valueVariable;

	/**
	 * Construct the widget.
	 *
	 * Params:
	 *     parent = The parent of this widget.
	 *
	 * See_Also:
	 *     $(LINK2 ../element/uielement.html, tkd.element.uielement) $(BR)
	 */
	this(UiElement parent = null)
	{
		super(parent);
		this._elementId = "combobox";
		this._valueVariable = format("variable-%s", this.generateHash(this.id));

		this._tk.eval("ttk::combobox %s -textvariable %s", this.id, this._valueVariable);

		this.setState(["readonly"]);

		this.bind("<<ComboboxSelected>>", delegate(CommandArgs args){
			this.deselectText();
		});
	}

	/**
	 * Get the index of the selected value from the current widget's list values.
	 *
	 * Returns:
	 *     The index of the selected list value.
	 *     Indexes start at 0 and -1 is returned if the current value does not appear in the list.
	 */
	public int getSelected()
	{
		this._tk.eval("%s current", this.id);
		return this._tk.getResult!(int);
	}

	/**
	 * Select the value at a particular index in the value list.
	 *
	 * Params:
	 *     index = The index of the value to select.
	 *
	 * Returns:
	 *     This widget to aid method chaining.
	 */
	public auto select(this T)(int index)
	{
		this._tk.eval("%s current %s", this.id, index);

		return cast(T) this;
	}

	/**
	 * Mixin common commands.
	 */
	mixin BoundingBox;
	mixin Cursor;
	mixin Data;
	mixin Delete_;
	mixin ExportSelection;
	mixin Height;
	mixin Index;
	mixin Insert;
	mixin Justify;
	mixin PostCommand;
	mixin Selection;
	mixin Value!(this._valueVariable, string);
	mixin Width;
	mixin XScrollCommand!(ComboBox);
	mixin XView;
}