The MaxGUI Beginner Tutorial Series - Tutorial 4: Panels
(c) Assari Dec 20 2005

In the previous tutorial we covered buttons. In this tutorial we are going to look at a more complicated MaxGUI gadget called Panels

To create panels, we use the CreatePanel function with the following syntax:-

Function CreatePanel:TGadget(x,y,w,h,group:TGadget,style=0,title$="")

Let us see how the simplest panel would look like

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Example", 200,200,320,240)
Local MyPanel:TGadget=CreatePanel(5,5,200,200, MyWindow)

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


Nothing very exciting as can be seen below. In fact it look exactly like our first CreateWindow tutorial.

   

A panel can actually have 3 styles:-

Constant Meaning
PANEL_BORDER Panel is drawn with a border
PANEL_ACTIVE Panel generates mouse move events
PANEL_GROUP Panel is drawn with a titled etched border

So lets put a border around our panel by using the PANEL_BORDER style

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Example w Border", 200,200,320,240)
Local MyPanel:TGadget=CreatePanel(60,5,180,155, MyWindow, PANEL_BORDER)

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


Now there is a sunken border on our panel

   

The next style, PANEL_GROUP, allows us the display a name on our panel

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Example w Border", 200,200,320,240)
Local MyPanel:TGadget=CreatePanel(60,5,180,155, MyWindow, PANEL_GROUP, "My Group")

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


The panel now has a nice border and a name to go with it.

   

Apart from making nicer windows, panels actually have some use. Grouping of radio gadgets is one of them.
Lets revisit our radio button example from the previous tutorial, now with a different survey

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Tutorial", 200,200,320,240)

Local Label0:TGadget=CreateLabel("Prefered Language for 2d and 3D?",80,10,300,20, MyWindow)
Local Radio1:TGadget=CreateButton("Blitz2D",120,40,100,20, MyWindow,BUTTON_RADIO)
Local Radio2:TGadget=CreateButton("BlitzMax",120,60,100,20, MyWindow,BUTTON_RADIO)
Local Radio3:TGadget=CreateButton("Blitz 3D",120,80,100,20, MyWindow,BUTTON_RADIO)
Local Radio4:TGadget=CreateButton("BlitzMax with irrlicht",120,100,120,20, MyWindow,BUTTON_RADIO)

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


The problem with our set of radio buttons is that we can only select one out of the four. Whereas we would like the survey to allow the users to select their favourite 2D and 3D languages

   

This is where our panel grouping capability comes in handy. So our program can be re-coded as follows:-

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Select your prefered Language", 200,200,320,240)

Local Panel2D:TGadget=CreatePanel(70,10,200,70, MyWindow, PANEL_GROUP, "2D")
Local Radio1:TGadget=CreateButton("Blitz2D",1,1,100,20, Panel2D,BUTTON_RADIO)
Local Radio2:TGadget=CreateButton("BlitzMax",1,22,100,20, Panel2D,BUTTON_RADIO)

Local Panel3D:TGadget=CreatePanel(70,82,200,70, MyWindow, PANEL_GROUP, "3D")
Local Radio3:TGadget=CreateButton("Blitz 3D",1,1,100,20, Panel3D,BUTTON_RADIO)
Local Radio4:TGadget=CreateButton("BlitzMax with irrlicht",1,22,120,20, Panel3D,BUTTON_RADIO)

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


Now we can see that the panel grouping allows us to select an answer for each 2D and 3D group.

   

Before we move on the the last panel style PANEL_ACTIVE, let us explore another interesting property of panels, namely the ability to change background color and have an image background.

Lets start with changing its background color.

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Background Color", 200,200,320,240)
Local Panel2D:TGadget=CreatePanel(70,40,200,70, MyWindow)
SetPanelColor Panel2D, 1,81,107

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


If you were to execute the above program, you should get the following:-

   

As you can see we now has a colored panel, courtesy of the SetPanelColor function. The parameters for SetColorPanel are
The formal syntax is:-
Function SetPanelColor( panel:TGadget,r,g,b )

A more interesting feature is the SetPanelPixmap function. Instead of a background color you can specify a background image. The formal syntax looks like this:-

Function SetPanelPixmap( panel:TGadget,pixmap:TPixmap,flags=PANELPIXMAP_TILE)

Let's us see how a simple example would look like:-

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Background Image", 200,200,320,240)
Local Panel2D:TGadget=CreatePanel(70,40,200,70, MyWindow)

Local image:TPixmap=LoadPixmap("D:\My Documents on E\_Tutorials\B-max.png")
SetPanelPixmap Panel2D, image


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


Our panel now has a tiled image of the Blitzmax logo. 

   

    Local image:TPixmap=LoadPixmap("D:\My Documents on E\_Tutorials\B-max.png")

Note that the above line loads a image from a file. You will need to specify your own directory for this example to work. Otherwise you will just get a blank panel with no image on it.

The SetPanelPixmap function has several flags (similar to style that we have seen before) as follows:-

Constant Meaning
PANELPIXMAP_TILE The panel is filled with repeating tiles (default)
PANELPIXMAP_CENTER The pixmap is positioned at the center of the Panel.
PANELPIXMAP_FIT The pixmap is scaled to best fit the Panel size.
PANELPIXMAP_STRETCH The pixmap is stretched to fit the entire Panel.

The TILE style is the default style, similar to tiling of images on webpages. Let us see how a STRETCH style would look like:-

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Panel Background Image", 200,200,320,240)
Local Panel2D:TGadget=CreatePanel(70,40,200,70, MyWindow)

Local image:TPixmap=LoadPixmap("D:\My Documents on E\_Tutorials\B-max.png")
SetPanelPixmap Panel2D, image, PANELPIXMAP_STRETCH


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


Our Blitzmax logo is now stretched to fill up the size of the panel.

   

I will leave it as an exercise for you to see how the other style works.

Summary

That ends the tutorial for now. In the next installment, we will learn about mouse events, the last style of CreatePanel; PANEL_ACTIVE

So before we end this tutorial let us recap what we have learnt.
The real power of panels is from their ability to track mouse events, which we shall cover next.

Return to Tutorial Index