vegUI Tutorial 10 - The List Widget

A live example of this tutorial can be found here

This tutorial is a follow-up article to vegUI Tutorial 09 - The Content Box Widget.

The graphics used in this tutorial and the other vegUI tutorials can be downloaded here.


The vegUI list allows you to have a list of items in a scroll-able environment. The list itself can be built in three different modes, the first and default mode is the standard mode. The second mode is the drop-down mode which builds a list that can be collapsed and expanded. The third mode is the multi-select mode, which is similar to the first mode with the difference that the user is able to select more than 1 item using ctrl left-click or by simply selecting items with the mouse.

The list itself extends the Content Box element that we discussed in the previous tutorial. Therefor it inherits all the properties, children and methods of the Content Box. That also means we can use the content box from the last tutorial and all the more or less tedious work we did setting up the scroll-bars and clone our list from it, isn't that sweet?!

So before we start take the stuff of the previous tutorial and remove all the stuff we do not need, that is everything that comes after we build the CBox and the statement that builds the CBox as well. I know i've stated this before but i will do it again, the reason we remove the Manager.build_element(CBox); line is so we can use the CBox as a template for our list. A vegUI element is only considered a template when it is in its unbuilt form.

Okay! Lets start by creating our List element and cloning our CBox into it.



The reason we do not use Manager.get_clone() is because get_clone() always creates an item of the same type as the template, which would make myList a content box instead of a list. So we create the list manually using the manager's get_new() method and then call the clone() method directly.

Make sure to always call clone() before you do the set() stuff as cloning will overwrite any colliding settings.

Next thing we need to do is setting up our list. We do this by using it's set() or set_list() method.



The first two arguments are width and height, parameter 3 and 4 are position x and y, parameter 5 is the default item height of the list, if you submit this at null or 0 then the item height will be dynamic. The last parameter in the statement above is the row space between items, in our case 0 pixels.

The vegUI List supports item states for, normal, hovering and selected items. With normal items i mean items that are neither being touched by the mouse pointer nor selected. Hovering items are items that are touched by the mouse pointer and selected items are ... well .. selected items.

So we need to define three separate css classes, one for each state.



Only thing left to do is to assign the css classes



Oh, almost forgot, we gave the Content element of our CBox a padding of 5 pixels in the previous tutorial. This is still active if you have copied over all the code as i told you to ;). This will look weird on our list so lets give it a padding of 1 pixels instead´.



That's it, only thing left to do: building the list



Hrm... its empty , isn't it. Lets fix this by adding some items to it :). There are three predefined methods to add items to a list. The basic method is add_item(), which can append an existing HTML node to the list. Then there is the add_item_txt() method which is a wrapper method to add text node to the list. Lastly there is the add_item_imgtxt() method, another wrapper method which adds an image and some text as the item to list.

Definition: VegUIList.add_item
Definition: VegUIList.add_item_txt
Definition: VegUIList.add_item_imgtxt

We will be using add_item_txt() for our example. The second argument submitted should be a unique value (numeric or string) that will represent the value of the item.

The Dropdown List

Okay, lets do a dropdown list too, just for the fun of it and because there are certain things you need to do specific to the dropdown list. First off we want to use myList as a template so add the following code pieces before the Manager.build_element(myList); snippet ;)



We can skip width, height, row-height and row space in this set() call as they are already set to the properties of myList. There is an additional 7th parameter though which defines the list type of myDDList. As i said there are three different list types



Additionally there are two child elements i have not told you about yet as they can be ignored for the other two list types. The BtnOpen child and SelItemLabel child. BtnOpen is a button that allows the user to expand or collapse the dropdown list. SelItemLabel holds the currently selected item to the left side of the BtnOpen element.

As always child elements can be accessed directly as a property of the list or over the list's C property

Let's start by setting up our button, we do this as we would set up any other vegUI button element, except that we can ignore its position as it will be aligned automatically by the list.



The CSS classes btn_scroll_down_0 and btn_scroll_down_1 should be set if you copied over all the code from the content box tutorial.

For the SelItemLabel we will create a new css class that sports a border.





Okay now we can build both lists, and we also modify our add item loop to add items to our drop down list, so make the changes accordingly:



If you load the page now there should be two lists, a normal one to the left and a dropdown one to the right each holding 20 items.

Responding to Selection

In order to handle selection changes in the list you need to utilize the list's onchange event. The onchange event gets fired every time an item is selected in the list. The current selection value is held in the sValue property of the list. The currently selected item is stored as an object in the sItem property in the list (normal List), i will explain how multi-select lists work further down.

The list itself has several functions to work with items, for example drop_item() drops the item of the specified index. And find() returns the index of the item with the specified value. You can find a list of all the list's methods in the vegUI API documentation.

Since our lists should hold identical items, value-wise, lets have it so that if an item is selected in our drop-down list it's counterpart in the normal list is removed.

The multi-select list

Selection response in the multi-select list is a bit different than in the other two lists, as multiple items can be selected at the same time. The sValue property of the multi-select list holds the value of the most recently selected item and is thereby not very useful.

The sItems (notice the plural form) property of the multi-select list is an array that holds all the sItem objects of the currently selected items. An sItem object is an object with two properties:

1. itemValue , the value of the item


2. node, the HTML node of the item

So in order to get all the selected items you would need to loop through the sItems array of the multi-select list and collect the itemValue of every object in it.

However the list itself provides the to_string() method which creates a string of all the currently selected values in the list separated by a separator string that can be set to anything (default is ',').



Update: 2.0.6

Headers

You can also use the add_item() method to add an item as a header. Header's use different css classes than normal items and wont be selectable.

To define the css class for the header item set the mHeader property.



To add an item as a header simply submit a fourth argument to the add_item functions. If the fourth argument (asHeader) is true the item will be added as a header item to the list.

And again we've reached the end of a tutorial. Next up: The dropdown menu

Related Posts

• vegUI Tutorial 09 - The Content Box Widget
• vegUI Tutorial 11 - The Popup Menu

---

Your Comment

name:*
email-address:
Are you human?

Comments

No comments yet.

---