The MaxGUI Beginner Tutorial Series - Tutorial 7: Listboxes, GadgetItems and Iconstrips
(c) Assari Dec 26 2005

After a slightly relaxed previous tutorial on textfields and labels, this tutorial will be about listboxes which is easy but we shall also begin exploring the world of gadget items which is a bit more complicated.

Listbox

A Listbox Gadget displays a list of items from which a user can make a selection from.

Listboxes are created using the CreateListBox function:-
Function CreateListBox:TGadget(x,y,w,h,group:TGadget,style=0)

Here is a very simple Listbox example
    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

Being so simple what we get is just a blank listbox as we have not added anything to it.

   


To add items to our listbox we need to use the AddGadgetItem function. The AddGadgetItem function requires the following syntax
Function AddGadgetItem(gadget:TGadget,text$,flags=0,icon=-1,tip$="",extra:Object=Null)

Unlike the many Create Gadget functions we have seen, the syntax for AddGadgetItem is slightly different so lets spend some time to explore the parameters in a bit more detail. Lets add a list into our listbox as be;ow (see code in bold)
    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)
AddGadgetItem ListBox, "This is my first list item"

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

We now get an item corresponding to the text we have added with the AddGadgetItem function.

   


Function AddGadgetItem(gadget:TGadget,text$,flags=0,icon=-1,tip$="",extra:Object=Null)

Now let us see what happens when we set the flags parameter to 1 (when we did not specify anything, it defaulted to zero)

    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)
AddGadgetItem ListBox, "This is my first list item",1

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

We now see that our item is now highlighted.
   


Now lets add a second item to our listbox, also with the flag set to 1 and see what happens

    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)
AddGadgetItem ListBox, "This is my first list item",1
AddGadgetItem ListBox, "This is my second list item",1

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

From the screenshot below we can see that only one item in the list can be selected (displayed as highlighted). As we can see from the above code, adding items to our listbox can be done simply by adding more AddGadgetItem statements.

   


The next optional parameter in AddGadgetItem is the icon parameter. Before we can use this we need to introduce ourselves to another MaxGUI concept called Iconstrips
 
An Iconstrip is a pixmap strip with a series of small images that can be attached to items within some gadgets, listboxes being one of them. An example of an iconstrip would be the toolbar.bmp that came with earlier versions of blitz.
   


The above iconstrip is a BMP of size 192x16, which means that it has 12 icons (192/16). You can count it yourself to see the number of icons.

Download the above picture onto your hard-disk and then we can load it in the program below
    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)

Local IconStrip:TIconStrip=LoadIconStrip("D:\My Documents on E\_Tutorials\toolbar.bmp")
SetGadgetIconStrip(ListBox, IconStrip)

AddGadgetItem ListBox, "This is my first list item",0,1
AddGadgetItem ListBox, "This is my second list item",0,9

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

Notice now we have icons next to our items in the toolbox. 

   


The actual icon appearing next to our item corresponds to the icon # that we put in the parameter list. The first item had icon# 1 and the second item icon# 9. (You can count it yourself from the above iconstrip, just remember to start from zero instead of one)
    AddGadgetItem ListBox, "This is my first list item",0,1
AddGadgetItem ListBox, "This is my second list item",0,9

The last AddGadgetItem parameter that we want to look at is the tooltip parameter. Lets place it now in our program. Note the changes in bold below:-
    SuperStrict

Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240)
Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow)

AddGadgetItem ListBox, "This is my first list item",0,-1,"ToolTip for Item 1"
AddGadgetItem ListBox, "This is my second list item",0,-1,"ToolTip for Item 2"

Repeat
  WaitEvent()
  Select EventID()
   Case EVENT_WINDOWCLOSE
     End
   End Select
Forever

Run the above program. If you hover the mouse cursor over the item in the listbox you would see the yellow tooltip appearing over the item.

Note that I have put the number zero over the flag parameter (ie no selection) and -1 for the icon parameter to denote that we don't want any icon image for this item.

The last parameter extra:Object is more advanced that the scope of this tutorial so we will not cover it here.

Summary

OK we are now ready to cover more stuff that we can do with our listbox, this we will do in our next tutorial.

To recap what we have learnt so far
 So thats ends our tutorial for now. Back to Tutorial Index.