Tutorial 9: Modify and Insert GadgetItems

The MaxGUI Beginner Tutorial Series - Tutorial 9: Listboxes, Modify and Insert GadgetItems
(c) Assari Dec 28 2005

In this tutorial we are going to look at the final MaxGUI functions related to ListBoxes. It's good that we are spending a bit more time on these functions as the concepts of managing gadgets that we have seen so far applies not only to Listboxes but also other list based gadgets as well.

The ModifyGadgetItem and InsertGadgetItem functions are very similar in its functionality to the AddGadgetItem function which we have covered extensively in previous tutorials.

The syntax:-

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

The extra parameter for this function over the AddGadgetItem function is the index parameter. As we can imagine, the AddGadgetItem simply tack on an item onto the end of the list whereas the insert function needs to know where in the list to insert an item and the Modify function needs to know which item to modify.

Let us see how to modify an item in a 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
Case EVENT_GADGETACTION
ModifyGadgetItem ListBox, SelectedGadgetItem(ListBox), "Selected"
End Select
Forever

Notice how when we click on an item in the listbox, the item changes to the text Selected as per our instruction in the ModifyGadgetItem function above. The SelectedGadgetItem function is once again used to retrieve the index of the item which was clicked on by the user.

Unfortunately the ModifyGadgetItem function does not allow us to just modify the parameter that we want. To modify the icon for example, we have to resort to 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

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

Repeat
WaitEvent()
Select EventID()
Case EVENT_WINDOWCLOSE
End
Case EVENT_GADGETACTION
     Local i:Int=SelectedGadgetItem(listbox)
     Local text:String=GadgetItemText(ListBox,i)
     Local flag:Int=GadgetItemFlags(ListBox,i)
     Local icon:Int=GadgetItemIcon(ListBox,i)
     icon=icon+1
     If icon>11 icon=0
     ModifyGadgetItem ListBox, i, text, flag, icon
End Select
Forever

We can see in the picture below that selecting the item changes the icon attached to the item.

Let us try to understand our program a bit better:-

Case EVENT_GADGETACTION
     Local i:Int=SelectedGadgetItem(listbox)
     Local text:String=GadgetItemText(ListBox,i)
     Local flag:Int=GadgetItemFlags(ListBox,i)
     Local icon:Int=GadgetItemIcon(ListBox,i)

We are now using an iconstrip to attach icons to our list elements (see the loadiconstrip statement above, wwe have already covered iconstrips in an earlier tutorial). You can now see 3 new functions, GadgetItemText, GadgetItemFlags and GadgetItemIcon, all of which allows us to retrieve the current value of our GadgetItem list at the particular index.

     icon=icon+1
     If icon>11 icon=0
     ModifyGadgetItem ListBox, i, text, flag, icon
End Select

We then increase the icon# by one so that the next icon in our iconstrip will be used by the list element. We also need to check that we have not gone beyond the last icon in our iconstrip. If we do, we reset the icon# back to zero.

Notice that in our ModifyGadgetItem line, we place back the original text and flag which we had retrieved earlier and only changed the icon variable

ModifyGadgetItem ListBox, i, text, flag, icon

There is also a GadgetItemExtra function but that is too advanced for this tutorial so we will not cover that here.

The last function we want to cover here is the InsertGadgetItem function which as you can surmise from its name allows us to insert an item at a particular location in 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
Case EVENT_GADGETACTION
Local i:Int=SelectedGadgetItem(listbox)
InsertGadgetItem ListBox, i, "Inserted Item"
End Select
Forever

Clicking on an item in a list will cause an insertion to happen at that point as can be seen below:-

Summary

So that ends our three tutorial long treatise on Listboxes and the functions required to manipulate them.
In this tutorial we looked at

ModifyGadgetItem and InsertGadgetItem, two functions which allow us to modify an existing item in a list and insert an item to a selected location in a list respectively.
We also saw 3 functions, GadgetItemText, GadgetItemFlags and GadgetItemIcon, all of which allows us to retrieve the current value of our GadgetItem list at the particular index.

Back to Tutorial Index.