The MaxGUI Beginner Tutorial Series - Tutorial 8: More Listboxes, GadgetItems
(c) Assari Dec 26 2005

In this tutorial we are going to look at the additional GadgetItem functions that MaxGUI has to help us manipulate Listboxes. One of the use of listboxes is to present list of choices to users so that they can act on them.

The helpfile lists the following relevant functions:- AddGadgetItems, ClearGadgetItems, ModifyGadgetItems, SelectGadgetItems, SelectedGadgetItems and RemoveGadgetItems

Before we start, lets take a look at how to quickly populate our ListBox

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End    End Select Forever

Notice how I have added a For/Next loop to quickly add numbers into our ListBox. Notice also our ListBox now has a scroll bar as the number of items in the list exceeds the height of our listbox.


Now that we have a longer list, lets start manipulating them

Lets start with SelectedGadgetItem

SelectedGadgetItem has the following syntax

Function SelectedGadgetItem(gadget:TGadget)

We would use this function as follows:-

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End   Case EVENT_GADGETACTION      SetStatusText MyWindow, "Item Selected="+SelectedGadgetItem(ListBox)     End Select Forever

Notice how when we click on an item in the listbox, the index of the item appears in the statusbar not the item that we selected


To get the item itself, we need another MaxGUI function, GadgetItemText which has the following syntax

Function GadgetItemText$( gadget:TGadget,index )

We would then use this function as follows:-

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next Local s:String Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End   Case EVENT_GADGETACTION      s=GadgetItemText(ListBox,SelectedGadgetItem(ListBox))      SetStatusText MyWindow, SelectedGadgetItem(ListBox) + ":" + s    End Select Forever

Notice we now can see the item itself. So remember that SelectedGadgetItem just gives you the index (ie its location in the list) and you will need to use the GadgetItemText function to get the actual item.


The next function we want to look at is RemoveGadgetItem, which has the following syntax:-

Function RemoveGadgetItem( gadget:TGadget,index )

We can either specify the item to be removed programatically or get the user to select. Let's look at both method.

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next RemoveGadgetItem Listbox,3 Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End    End Select Forever

Notice that item 1003 is now missing from the list below.


To remove an item by user action, we can do the following

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End   Case EVENT_GADGETACTION       RemoveGadgetItem(Listbox,SelectedGadgetItem(ListBox))    End Select    SetStatusText MyWindow, "Total items in list="+CountGadgetItems(ListBox) Forever

From the screenshot below we can see that I have removed 3 items, leaving only 48 items in the list. (Note that we had 51 items to start with, 0-50).


The line which deleted our item is the following, as we saw from the example before this, the RemoveGadgetItem function needs to know which item to delete. In this example, we use the SelectedGadgetItem function to supply the item to be deleted.

RemoveGadgetItem(Listbox,SelectedGadgetItem(ListBox))

 I have also introduced another useful Gadget function called CountGadgetItems which as the name implies, gives us the number of items in the current list.

SetStatusText MyWindow, "Total items in list="+CountGadgetItems(ListBox)

SelectGadgetItem (which is different from SelectedGadgetItem, note the smal difference in tense there) simply allows you to programmatically select an item in the index, nothing spectacular there. You would use it as follows:- 

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next SelectGadgetItem ListBox,3 Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End    End Select Forever

Notice now our 3rd item is selected (see highlight 1003)


The next function ClearGadgetItems is simplicity in itself, but can be dangerous if not handled carefully.

SuperStrict Local MyWindow:TGadget=CreateWindow("ListBox Example", 200,200,320,240) Local ListBox:TGadget=CreateListBox(10,10,200,100,MyWindow) For Local i:Int=1000 To 1050   AddGadgetItem ListBox,i Next Repeat   WaitEvent()   Select EventID()   Case EVENT_WINDOWCLOSE      End   Case EVENT_GADGETACTION      ClearGadgetItems(Listbox)    End Select Forever

With one click, the whole list is gone. 



Summary

This ListBox gagdet has a lot to offer and thus needs three tutorials to cover the subject. We will look at two more relevant functions in the next tutorial. The topics we are covering though will be relevant to other gadgets as well.

To recap what we have learnt so far

• We can add items onto list using for/next loops rather than individual AddGadgetItem statements. 
• We've learnt how to use AddGadgetItem, ClearGadgetItems, SelectGadgetItem, SelectedGadgetItem and RemoveGadgetItem to manage items in our listbox
  
  

So thats ends our tutorial for now. Back to Tutorial Index.