UI Listbox
Entry posted by Rob McGinnis
14892 views
Written by Rich Taylor, Lead Programmer.
Whew, sorry for not finishing off the UI Objects. There's not too many left to document here before all the basic UI types should be covered, I think...
Anyway, on to UIListBox. UIListBox is a container similar to UIPane and anything listed under UIPane that makes sense for UIListBox probably does the same thing under UIListBox. So I'm going to stick to discussing the attributes that are unique to UIListBox. Refer to UIPane for the basic attributes (Like X, Y, Height, Width, etc).
There's a couple different ways list boxes are used.
A list box can be used for displaying multiple rows of objects. Things like the Feat List or the lines of text in the chat windows use it this way. This is accomplished by just adding multiple objects to the list box. Typically these objects are the same size, but that is not a requirement.
A list box can also be used for containing a single large text field and being able to scroll over that text field. This can be seen in places like the class and race descriptions on character creation. This approach is accomplished by having a single text field within the list box, making the height of the text field dynamic, and changing the text of the text field. The listbox will allow for scrolling over the large text field.
Another note, I may use the term 'control' a lot in this write up. 'Controls' in this context are the contents of the list box. These are different than 'children' of the list box, which would include every object contained by the listbox, like the scrollbar. I will try to call controls 'rows' to make it more clear, but if I slip up and call it a 'control,' I'm talking about a row. =)
xPadding
The amount of padding that the listbox should put between the edges of the listbox and the contents of the listbox. This padding is applied equally to both sides. So if the padding is 5, and the ListBox is 100 pixels wide, then the ListBox will constrain the rows to a max width of 90.
yPadding
The amoutn of padding that the list box puts between each row. This includes padding between the top row and the top of the list box and the bottom row and the bottom of the list box as well.
snaptobottom
Setting this to 'true' will make it so that any time the text field in the listbox gets resized, the listbox will snap to the bottom to show the bottom of the text. This is used mostly for situations where text keeps getting added to a text field and you want the list box to keep scrolling to the bottom to display all the text. This is not how the chat window works, BTW.
scrollsegmentsize
This is how many pixels you want the listbox to scroll for each 'scroll click' on the part of the user. The parameter is a number, the default vaule is 1.
unequalcontrols
This is a somewhat complicated attribute. If you don't have any preference, it's usually best to just set it to true. The purpose of it is to speed up performance on list boxes where each row is the same height. So if your list box will definitely have each row with the same height, then set this to false to speed up scrolling with that list box.
showpartialchild
This tells the list box if it should just clip the bottom row if it can't show the entire row. Defaults to true, parameters are 'true' or 'false.'
scrollbaronright
Setting this to true moves the scrollbar over to the right side of the list box. Setting it to false will move the scroll bar to the left side of the list box. The default behavior is 'true'.
selectonleftclick
This tells the game that you want the user to be able to click on the rows of the list box. This means that the list box is intended to contain a number of rows and you want the user to pick a row. It is false by default. If false, then clicking on a row will perform the 'LeftClick' callback if you click on a button row, or will set the text field as the focus if there is just a single large text field in the list box. If by true, clicking on the row will still execute the OnLeftClick callback for the button if there is one. It will also set that row as selected.
hidescrollbarwhennotneeded
If this is set to true, the scrollbar will be hidden unless there are enough contents within the list box to require scrolling to see them all. Defaults to false.
hidescrollbar
If this is set to true, then the scrollbar will be hidden no matter what. This is for the rare case you may want text to scroll by but don't care to have the user being able to scroll back up. Defaults to false.
If the engine finds a UIFrame nested within a ListBox while loading the XML, it treats that Frame as a border for the full size of the list box. I'm not sure if this ever saw any actual testing though, as I believe we usually just added a separate UIFrame to the Scene to act as the border.
If the engine finds a UIScrollBar nested within a ListBox while loading the XML, that scrollbar will become the scrollbar for the ListBox and be attached to the left or right depending on the attributes.
A listbox can contain the following types of UIObjects as its rows:
Button, Label, Hotbarbutton, Text, Collapsable, Pane, Grid, Icon, TextTree
If the object found has an attribute called 'prototype=true', then that object becomes the ProtoType for the list box. The prototype defines all the attributes, styles, etc., that each row that is added dynamically to the listbox should have. Unfortunately, this is something better experimented with to understand rather than me trying to explain. 
But in brief, find a listbox that has a prototype object in the game, and see what effect changing the prototype's attributes have on the way the listbox rows look in the game.
Anyway, that's all I have to write about ListBox at the moment. I thought there would be more than this to write about it, so I imagine I'm missing some stuff. As always, just ask if I've neglected to cover some topic about UIListBox.
4 Comments
Recommended Comments
Create an account or sign in to comment
You need to be a member in order to leave a comment
Create an account
Sign up for a new account in our community. It's easy!
Register a new accountSign in
Already have an account? Sign in here.
Sign In Now