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
So thats ends our tutorial for now. Back to Tutorial Index.