The MaxGUI Beginner Tutorial Series

BlitzMax Forums/BlitzMax Tutorials/The MaxGUI Beginner Tutorial Series

assari(Posted 2005) [#1]
[Updated Feb 21 2006] 1 new tutorial added (see list below)

I am writing a series of tutorials (which I am hoping) will be an extensive series of beginner level tutorials for MaxGUI.

These tutorials are pitched at beginners although I do expect some familiarity with using Blitzmax, the Editor MaxIDE, cutting&pasting code into the IDE , compiling and running BlitzMax programs. I'm also assuming some basic programming knowledge such as variables, loops and conditionals.

The tutorials can be found at

[updated Feb 21 2006]
The Tutorials:
Tutorial 1:Using CreateWindow
Tutorial 2:Buttons and Events
Tutorial 3:More Buttons and Events
Tutorial 4:Panels
Tutorial 5:Panels and Mouse Event
Tutorial 6:Labels and TextFields
Tutorial 7:Listboxes, GadgetItems and Iconstrips
Tutorial 8:More Listboxes and GadgetItems
Tutorial 9: Listboxes, Modify and Insert GadgetItems
Tutorial 10: ComboBoxes
Tutorial 11: Tabbers
Tutorial 12: Canvas, Events and 2D Graphics
Tutorial 13: Sliders and Scrollbars
Tutorial 14: Menus and Popup Menus
Tutorial 15: EventHooks
Tutorial 16: The TextArea Gadget
Tutorial 17: Toolbars and Progress Bars
Tutorial 18: The Treeview Gadget - Part 1

Eric(Posted 2005) [#2]
I just went through all three of them... Very informative. Thanks for taking the time to do something like that. Keep'em coming.


assari(Posted 2005) [#3]
Thank you for your encouragement. More coming soon.

Who was John Galt?(Posted 2005) [#4]
A nice clear intro. Good work!

assari(Posted 2005) [#5]
2 More tutorials added.
Tutorial 4:Panels
Tutorial 5:Panels and Mouse Event

sigi(Posted 2005) [#6]
Cool, Thank You :)

assari(Posted 2005) [#7]
3 More tutorials added.
Labels and TextFields
Listboxes, GadgetItems and Iconstrips
More Listboxes and GadgetItems

frolicy(Posted 2005) [#8]

assari, thank you very much from an eternal newbie, lol, who appreciates any tutorials in any subject!

Booticus(Posted 2005) [#9]
Awesome stuff. Thanks!

semar(Posted 2005) [#10]
Really useful, thank you !


Tibit(Posted 2005) [#11]

I like that you explain every step, and with screenshots. And you mange to keep the examples small and focused on the current subject. The tutorials are very well done. I strongly recommend this to anyone new to MaxGUI.

I would like a tutorial on how to manage larger MaxGUI applications. Seems to me most MaxGUI programs gets quite "messy" pretty quick when you start to add a lot of things, if you get my point :)

Thanks, it helped me to finally get a grip of MaxGUI.

assari(Posted 2005) [#12]
Thanks wave and everyone for the kind words. More complicated stuff could appear later. I still have a few more beginner topics to get done and the vacation days are coming to an end:(

Two more tutorials
Tutorial 9: Listboxes, Modify and Insert GadgetItems
Tutorial 10: ComboBoxes

assari(Posted 2005) [#13]
Two more tutorials added

Tutorial 11: Tabbers
Tutorial 12: Canvas, Events and 2D Graphics

Happy New Year to everyone

Eric(Posted 2006) [#14]
This is great, Thanks for all of your help!!


frolicy(Posted 2006) [#15]
thank you - assari - thank you very much!!!!

just in case - if you feel like more, lol - then do not stop yourself - please continue ;-))

Bremer(Posted 2006) [#16]
Great work, and highly appreciated. Keep it up.

assari(Posted 2006) [#17]
OK, one more tutorial added. There are a few more topics to cover but updates are going to be slower from now on :(

Anyhow, enjoy this one

Tutorial 13: Sliders and Scrollbars

assari(Posted 2006) [#18]
One more tutorial added:-
Tutorial 14: Menus and Popup Menus

see complete set at

degac(Posted 2006) [#19]
I've a problem with your last tutorial relative to the MODIFIER_COMMAND: ALT+F4 close immediately the program WITHOUT displaying the notify messagge, CTRL+F4 is indeed ok.

assari(Posted 2006) [#20]
see help file for more

In my example the Menu Command will capture only CTRL+F4.
ALT+F4 happens to be the hotkey that windows uses to exit a window.
If you change the example to use MODIFIER_OPTION instead, it will work as you'd expect


degac(Posted 2006) [#21]
doh! silly me...I didn't notice that the combination ALT+F4 is the normal way I close the applications! Sorry!

kiami(Posted 2006) [#22]
I just played, modified and studies your canvas codes, and looked at all other examples. Now, MaxGUI is really alive. Thanks for your effort.

Eric(Posted 2006) [#23]

How about one on EventHooks. :)

assari(Posted 2006) [#24]
EventHooks are not exactly beginner stuff. I'm afraid I cannot commit at the moment, a few more topics that I would like to cover in this beginner series.

snation(Posted 2006) [#25]
Hi assari,

Really appreciate this series!
However, I agree with Eric, I'd REALLY like to understand eventhooks... you do such a great job.

Again, thanks for your efforts.

GameScrubs(Posted 2006) [#26]

assari(Posted 2006) [#27]
Suggest you re-post this question in the beginner forum. I would like to keep this thread focused on this tutorial series.

Thank you for your cooperation.

Eric(Posted 2006) [#28]
In anycase, Assari, I love your series and use it for reference alot.

degac(Posted 2006) [#29]
Assari, good work!
Big houses are made on solid fundaments, and your tutorial is very well explained.
And I join the snation's request on eventhook, something it's clear, something's not...

Grisu(Posted 2006) [#30]
Great job.

Could you add a tutorial that explains how to read out the mousebuttons, mousewheel, mousemovement and keypress events?

You have left these out and the bmx help as well.

How does one check KEY_ESCAPE e.g.

assari(Posted 2006) [#31]
OK, by popular demand, an eventhook tutorial :)
Tutorial 15: EventHooks

assari(Posted 2006) [#32]
I have not made any specific tutorial on how to catch mouse and key events but they are mentioned when relevant (scattered across the tutorials). What specifically are you after?

Grisu(Posted 2006) [#33]
Simple stuff:

How to check
1. the mousebuttons clicks (1-5)
2. check the mousewheel up/down
3. check if a key has been pressed = keyhit (ESC, Cursor Keys)

Maybe I have to relook all tutorials to find the answer...

kiami(Posted 2006) [#34]
Yes, like Grisu, I am looking to know how to do those things. Also, does KeyHit(KEY_X), becomes irrelevent when Canvas is used?
Why buttons doesn't show up when Canvas is used? For example, I like canvas to be in the left side of the window and buttons on right side, or on a panel, on the right side. How can we deal with those situations?

degac(Posted 2006) [#35]
Thank you very much Assary! Very useful.
Just some little info & question: I had a look to the source of AddHook and I saw little interesting things:
- the maximum number of AddHook is 255;
- AddHook is not properly a 'list' but an if you want to change the 'order of execution' you need to set up a prioriry value or mess in other ways;

The question is: can we 'suspend' a user-hook function? I'm lost in the event system at the moment, but I miss any function to 'hold' an event-emission...

Keep on going ahead with this tutorials...

snation(Posted 2006) [#36]
Haven't even read the tutorial yet on eventhooks, just wanted to say thanks in advance - I know it'll be helpful.
Thank You!

Amon(Posted 2006) [#37]
Top Tutorials. Is there a possibility of having these converted to chm or to have them all in one downloadable zip?

Thanks :)

assari(Posted 2006) [#38]
It's on the Roadmap. I want to complete the series first

Bremer(Posted 2006) [#39]
These tutorials are really great, thanks for your contribution to the community, its highly appreciated.

Wellmt(Posted 2006) [#40]
These are great tutorials, I can actually make sense of MaxGUI now!

I don't suppose there is any chance of you a tutorial for doing a file open dialog?

Also please regarding the request above, please not just a .chm file, we're not all Windows users!


assari(Posted 2006) [#41]
Now that I have completed my other tutorial; Making a MaxGUI Application: StripAnimMakerLite, here is another tutorial in this beginner series Tutorial 16: The TextArea Gadget

Haramanai(Posted 2006) [#42]
Top rated tutorials. Thanks.
The images from Tutorial 13: Sliders and Scrollbars are not displaying.

assari(Posted 2006) [#43]
Thanks Haramanai for pointing out re the missing images. All fixed now.

tonyg(Posted 2006) [#44]
Hi Assari,
Excellent series of tutorials.
I had trouble with this code in Tutorial 9...

unless I changed it to...

In the first example, after adding an icon flag, I got a default icon (rather than no icon if the path was wrong) unless I changed the code around.

assari(Posted 2006) [#45]
I think it make sense to first set the iconstrip to the listbox before assigning an icon number to the gadgetitem.

I got the same error as you described as well if I assign the icons flag before setting the iconstrip to the listbox.

assari(Posted 2006) [#46]
Another one completed: Tutorial 18: The Treeview Gadget - Part 1

Have a read and see what you think.

allos(Posted 2006) [#47]
assari, I think you are doing a truly great work, and very useful to me.
I have a couple of (maybe naive) questions about treeviews.
One is: how can I return the string of a terminal leaf of the treeview by clicking on it?
For instance, I need in my program a big tree and user is allowed to expand nodes until he reaches the desired item (which I call a "terminal leaf"), in a cascading route: how can I return the string associated with it to fill, eg, a database field?
Another problem id double clicking on an item; this makes the program crash with an error message (in debug mode).
I hope you find the time to answer my questions.
Thank you again.


assari(Posted 2006) [#48]
I would prefer that you ask these questions in the beginner's forum. More people will help you there.
One is: how can I return the string of a terminal leaf of the treeview by clicking on it?
From my example tutorial
        Local Node:TGadget = SelectedTreeViewNode(MyTreeView)
        Local s:String=String(Node.Context)
add the print line and you will see the text from the tree displayed.

The double clicking bug has been reported. It may have been fixed w 1.18. I have not tried it yet

allos(Posted 2006) [#49]
thank you assari, I will try again


3Ddoofus(Posted 2006) [#50]
This is a superb resource ASSARI.
Just what I've been looking for.
Thanks for all your efforts.

Grisu(Posted 2006) [#51]
I have got some questions about listboxes:

1) How do I change their background color?
2) Can I set the listbox, so it does not create a horizontal slider bar?

tonyg(Posted 2006) [#52]
1) Think it can't be done and is a bug.
Button colours
The problem in the first link still seems to occur so not sure about Skid's comment about it being fixed in the next update.

P.S. For 2) your guess is as good as mine. There's a 'style' parm but not documentation on what to set it to.

P.S. It might be better to ask these in the normal forum.
It fills this tutorial thread and, also, it could be missed.

SB(Posted 2006) [#53]
in your tutorials you don't mask your iconstrips ... looks not that nice. i recently figured out how to mask them. perhaps this is useful for your tuts.

IncBin "icons.bmp"
Local IconStrip:TIconStrip= LoadIconStrip (MaskPixmap(LoadPixmap("incbin::icons.bmp"),255,0,255))
SetGadgetIconStrip(tree, IconStrip)

assari(Posted 2006) [#54]
thanks S.B. thats a nice tip.

Kuron(Posted 2006) [#55]
Any chance you would consider making the MAXGUI tutorials into a PDF so that they could easily be read on non-net connected PCs and easily printed out?

Grisu(Posted 2006) [#56]
Thanks Assari!

Please add the:
TEXTAREA_READONLY your textarea tutorial!

SillyPutty(Posted 2006) [#57]
excellant stuff, I really enjoyed going through your tuts

I second making a pdf so that we could download it :)

Good job !

Robert Cummings(Posted 2006) [#58]
Wow - great tutorials! I just bought maxgui and this is a boon. Thank you.

Grisu(Posted 2006) [#59]
I'm currently writing an maxgui app and have the problem that the listboxes I use start flickering a lot when I change the selected icon or start resizing the app window itself. As you have far more knowledge of bmx, could you test my app if you have some time?

I really want this app to be perfect when released and I don't know if this is a bmx bug or can be corrected via event hooks. I dislike giving away the app on the forums, as I still have to discuss some legal issues regarding the cover art and data presented inside. Thus it would be nice if you could check it privately.

P.S.: Your e-mail box at hotmail is full!

assari(Posted 2006) [#60]
Check your email.

Grisu(Posted 2006) [#61]
I did, now check yours.. :)


P.S. Running the app maxed maybe best to see the effect more often.

Russell(Posted 2006) [#62]
Good job, Assari! Any possibility of continuing with the more advanced topics, such as pointers, interfacing with external libraries and such?


p.s. I also second the idea of creating either a pdf or an encapsulated html structure (so everyone with a browser could see it offline).

ImaginaryHuman(Posted 2006) [#63]
This is a great collection of tutorials! Thanks especially for helping me to understand how the whole hooks and events stuff works.

AdrianT(Posted 2006) [#64]
Wow Asarri, this is great stuff, almost want to but the gui lib just to go through the tuts :). Probably will do soon, as I think I'll have a need for maxgui soon :)

bradford6(Posted 2006) [#65]
Excellent Work. Very well done!

Miss Blitz(Posted 2006) [#66]
Assari, bless you for writing these tutorials! I was *this* close to giving up hope for this IDE I was working on....

ashmantle(Posted 2006) [#67]
Good tutorials, thank you for taking the time!

Chroma(Posted 2006) [#68]
These tutorials are a life-saver! Thanks assari.

TwoCorin517(Posted 2008) [#69]
I didn't see a rule about resurrecting. But I have a question. You talked about Tabbers in Tutorial 11. What does the
Select EventData()
do? I tried it in my program but it didn't seem to work well, I replaced it with an
	Select SelectedGadgetItem(WindowTabber); Case 0;
and that worked much better.

tonyg(Posted 2008) [#70]
Generally resurrecting is frowned upon but this is a sticky so it doesn't really matter.
From the tutorial :
When a user click one of the tabs, a EVENT_GADGETACTION event will be triggered by MaxGUI. We then need to check the event's eventdata by using the EventData() function. When the user clicks the first tab, EvenData() returns zero and when the user clicks the 2nd tab, EventData() returns 1.

It's going to be difficult to explain eventdata clearer than that.
Without seeing what you have done in your program it's difficult to say what is different or why it is not working.
How about adding a post to the MaxGUI forum with some sample code and asking why eventdata isn't returning what you think it should?

TwoCorin517(Posted 2008) [#71]
Ah, I see, its only returning the needed information when I select the tab, so when I use a gadget, and go back to the same tab, it won't display it until I select the tab.

Rivera(Posted 2008) [#72]
Hello, New to the board. I was trying to follow your tuts but I got stuck on the first one! I copied and pasted the code from tut 1 and went to compile and run. It fails with message "Identifier 'TGadget' not found". Do you know how I could fix this?

tonyg(Posted 2008) [#73]
You have to have MaxGUI.

Rivera(Posted 2008) [#74]
Ahhh, thank you. I bought the module and it works now. Thank you.

tonyg(Posted 2008) [#75]
@Assari, if you are still around.
The latest version of MaxGUI (1.16) needs a 'ViewRoot' specifically created :

<edit> and, of course, import maxgui.drivers for each if the SVN version of MAXGui is used.

iprice(Posted 2008) [#76]
An excellent series of tutorials. Thankyou.

ker2x(Posted 2010) [#77]
Thank you for the tutorials, very helpfull :)

Captain Wicker (crazy hillbilly)(Posted 2012) [#78]
Great Turorials!

Raz(Posted 2012) [#79]
Just to repeat what others have said but, these really are great tutorials. Great pacing, detail and opportunities for you to try things yourself.

Galdy(Posted 2013) [#80]
Can't access at the moment.

GaryV(Posted 2013) [#81]
Perhaps a moderator/admin can unsticky this thread?

Captain Wicker (crazy hillbilly)(Posted 2013) [#82]

Hardcoal(Posted 2013) [#83]
Great tutorials mate

Hotshot2005(Posted 2015) [#84]
The Links is dead!

Cocopino(Posted 2015) [#85]
The webarchive link 3 posts up is still working, also, this is pretty informative:

and of course the examples from the
[blitzmax path]/mod/maxgui.mod/doc/

nuno(Posted 2015) [#86]
Hey guys!
I accessed and re-printed all the pages of the tutorial from 'assari' in .pdf format.
I uploaded it to my animation/VFX company website, but I can't let it be there forever...

So, if someone could re-upload to some other host, cloud, I think it would be nice for all of us!

Here's the link:

nuno(Posted 2015) [#87]
Also, I packed the .zip with a snapshot of this post, for future references... who knows...

Xerra(Posted 2015) [#88]
I've uploaded the archive to our Dexterity Design website hosting as well via my blog, as that's not likely to be going anywhere soon so an alternative download site is:

nuno(Posted 2015) [#89]
Cool! Thank you, Xerra!

Juiceter(Posted 2015) [#90]
Very nice help Xerra. Much appreciated! I'm just converting from blitz 2d to blitz max now that it is free. I was one of the guys who bought blitz 2d just as blitz max was coming out!

Just a quick question though - do you think it is possible to scroll graphical icons as gadgets? i.e. scroll down a graphical icon list using the GUI gadgets bmax gives you?