Widget listbox

listbox , 📚 🚧

listbox:

A rectangle with headers at he top and containing a list of strings from which the user can select. This widget can contain a list of categories, with in turn contain a list of items.

category:

A category is a text which can be selected, checked and expanded to show the items of that category. nana::listbox creates the category 0 by default. This is an special category, which stays hidden, not showing any text, only the associated items. The member functions without the categ parameter operate the items that belong to this default category. This way, if you are not interested in classifying the items in categories, you can ignore categories and work always with the default and hidden category 0. Any "user" defined category will have an index 1 or higher. A proxy to a category (cat_proxy 📚 ) can be acces by a simple index.

The listbox::assoc() function is used to access a category through specified key.

item:

An item is formed by column-fields, each corresponding to one of the headers. An item can be selected and checked (both features are optional and controllable programmatically). Optionaly, each item can have attached an object of any type. This attached object is called the "value" of that item. A proxy to an item (item_proxy) can be acces by a duplex index (index_pair).

cell:

Each item-column-field is drawn in a "cell", which offers some possibilities of individual formatting, for example in correspondence to the cell content. It can also contains inline widgets.

header:

The user can drag the header to resize it or to reorganize its. By clicking on a header the item of the list get reordered, first up, and then down, alternatively.

resolver:

A resolver can be used to resolute some object of an specified type into a listbox item and back.

sort:

The final user can sort the list: click the header of the column to sort the list. Click again and it will be sorted in the other direction. Like in file explorer in windows. Programmatically use the listbox function sort_col(col_index, reverse). This by default sort as normal text. For more control on the sorting we need to set first our own function. Set that function with: set_sort_compare(col_index, your_function); after that it will get called when need. A sort compare is used for sorting the items. It is a strict weak ordering comparer that must meet the requirement:

	Irreflexivity (comp(x, x) returns false) 

and

	antisymmetry(comp(a, b) != comp(b, a) returns true)

In a simple example we use directly the string printed in that column. This is the default behavior.

	bool sort_compare( const nana::string& s1, nana::any*, 
			  const nana::string& s2, nana::any*, bool reverse)
	{
		return (reverse ? s1 > s2 : s1 < s2);
	}

	listbox.set_sort_compare(0, sort_compare);

The listbox supports attaching a customer's object to each item. The items can then be sorted by comparing these customer's object. Lets assume that most items have an object of type int attached to it:

	bool sort_compare( const nana::string&, nana::any* o1, 
		           const nana::string&, nana::any* o2, bool reverse)
	{
		if(o1 && o2) 	//some items may not attach a customer object.
		{
			int * i1 = o1->get<int>();
			int * i2 = o2->get<int>();
			return (i1 && i2 && (reverse ? *i1 > *i2 : *i1 < *i2));
						; //some types may not be int.
		}
		return false;
	}

In this simple example you will get an exception if the type of the object attached to one of the items is not int.

color and geometrical scheme

Define many characteristics of the listbox and its components. You can acces and modify this characteristics using the function scheme() which listbox inherit from widget.

inline widgets

We can "attach" inline widgets to each item in the list, but we do not do that directly. Instead, the list itself generates a limited number of widgets and in each moment "inlines" one of those widgets to each and only to each of the visible items. In order to do that the list need to know how to create the widgets and how to "update" it for each item, as well as how the widget responds to the different possibles events, and how to update back the corresponding item.

This is achieved by attaching to one column of one of the categories of the list a "factory" of objects that implement the virtual interface listbox::inline_notifier_interface. This is where you use the function of the listbox category:

void nana::listbox::cat_proxy::inline_factory (size_type column,                    
           pat::cloneable<pat::abstract_factory<inline_notifier_interface>> factory);

Using STL container

An STL container can be attached to a category using the template function template<typename T> void nana::listbox::cat_proxy::append_model(const T& value); to automatically generate the items.

Listbox associative category

export:

Items can be exported. In particular, the final user can select some items and export it: for example, by selecting items and then copy them to the clipboard. By pasting them to a document it will result in a tab-separated text table containing the headers and each of the selected items in the same order as visualized at the moment of copying.

\todo doc: actualize this example listbox.at(0)...

\example listbox_Resolver.cpp