About Gui's

Learn all about how user interfaces in SwinGame work, and how you can create your own. 

Level

Beginner

Details

Creating a GUI

The SwinGame User Interface functionality makes it easy for you to create a custom user interface that will fit well with your game's theme. The user interfaces in SwinGame are designed using Panels. You can create Panels that contain Regions for buttons, lists, check boxes, and radio buttons. An example is shown in the following image. ui composition.png

Designing a Panel

Before you start designing your own Panels, you will need to understand a little about how SwinGame creates and manages the user interface. SwinGame uses an image composition model based on combining together three images: a background image, a active image, and a inactive image. When the Panel is drawn SwinGame first draws the background image. It then looks at each of your controls, and if they are active it draws just the area of the active image that relates to that control. Similarly if the control is inactive is draws the control from the inactive bitmap. The following image shows an example of this. Panels are composed from a background, active, and inactive image

The best way to design your own Panel is to start by drawing all of the controls in their default state onto a background image. Once you are happy with the basic layout you can draw a second image with all of the controls in an active state. In this image you can add shadows, highlight buttons, draw selected radio buttons and check boxes. If you are going to disable controls on the form you then need to draw a third image with all of the controls in an inactive state.

The great thing about composing the user interface from custom images is that you have complete control over how the controls appear. You could use bullet holes for radio buttons in a shooter game, paint brushes for check boxes in a drawing program, or just use a sketch of the form for a rough and ready look. Use your imagination!You draw the panel and its controls, so you can make them anything you want!

Panels

A panel is part of your interface, an interface can be made up of multiple panels. The benefit of using multiple panels is that you can hide panels in certain situations, you can also allow panels to be draggable which means you can drag each individual part of your interface around.

Interfaces can be updated and drawn to the screen, this is done in SwinGame using UpdateInterface, and DrawInterface.

UpdateInterface

This procedure checks to see if any of the fields in your user interface have been clicked in which case the field active version of that field will be displayed on screen. It also checks to see if any panels are being dragged, and if they are it updates the panels position.

This procedure should be called every game loop during the update phase to ensure the interface acts smoothly.


DrawInterface

This procedure draws all visible panels to screen including their regions in the correct position. Like UpdateInterface it should be called every game loop during the draw phase to ensure the interface looks smooth.  


Creating Panels

When you create your own custom user interface you must create three different versions of the same image:

  • One where all fields are inactive, or unclickable
  • One where all fields are clicked, or active
  • One where all fields are unclicked, or inactive
Once the images are drawn you can write the panel resource file. This file describes the panel area as well as the regions within a panel. The following is an example of a panel declaration in a panel resource file.

  
    // The initial x position of the panel 
    x: 10 
    // The initial y position of the panel 
    y: 10 
    // Width of the panel 
    w: 100 
    // Height of the panel 
    h: 100 
    // The active bitmap 
    a: myActiveBitmap.jpg 
    // The inactive bitmap 
    i: myInactiveBitmap.jpg 
    // The background 
    b: mybackgroundBitmap.jpg 
    // Is draggable 
    d: true 
    // is vector 
    v: false 



This goes at the top of your panel resource file, following this is the region declaration where all the region data is placed.

Regions

A panel contains regions, regions are used by SwinGame to define where the elements are. Regions are created within panels, and so their position is set from the panels position. Each region kind can have different fields, the region kinds are listed below:

The required format is 'r: x, y, w, h, kind', depending on the kind of region other fields may be required.


Region kinds:

  • Label
  • TextBox
  • CheckBox
  • RadioGroup
  • Button
  • List

Label

To declare a label the following line must be used. The font field refers to the name of the font in SwinGame, the font must be loaded before the panel is loaded. Alignment has three possible values: l, c, r. The text field is the text value of the field, this is the text that is printed in the font and alignment specified.

  
    // r: x, y, width, height, kind, identifier, font, alignment, text 
    r: 0, 5, 200, 25, Label, myLabel, arial, c, my text here 
 


TextBox

Textboxes are where the user can type in keyboard input that can be read by SwinGame and used in your program. The maximum characters field refers to the maximum characters the user can type into the region. The text is the initial text in the text box, this text can be used as a prompt for the user. The current text in the text box can be obtained using TextBoxText, which returns the current string in the text box.

 

  
    // r: x, y, width, height, kind, identifier, font, maximum characters, alignment, text 
    r: 20, 10, 200, 50, TextBox, myTextBox, arial, 1024, l, This is where text goes 



CheckBox

Check boxes can be used where a user needs to select a category from any number of categories. The state of a check box can be obtained using CheckboxState which returns whether the check box is checked or not.

  
    // r: x, y, width, height, kind, identifier, checked 
    r: 5, 5, 50, 50, CheckBox, myCheckBox, false 



RadioGroup

To declare a radio group use the following code in the region section of your interface file. A radio group is a set of radio buttons, only one of which can be selected at a time. RadioGroups with different identifiers are recognised as different radio groups by SwinGame. Thereforce for each group identifier one radio button may be pressed.

  
    // r: x, y, width, height, kind, identifier, groupID 
    r: 5, 5, 50, 50, RadioGroup, myButton1, group1 
    r: 60, 5, 50, 50, RadioGroup, myButton2, group1 


List


To declare drop down list region you use the following code. Drop down lists are populated in your code using ListAddItem. The active item refers to the default selected item, this is useful if a user has to select an item from the list. If active item is -1 then there is no active item. Scroll size refers to the width or height depending on whether the scroll kind is horizontal or vertical. The scroll bar can be either horizontal (h) or vertical (v) and can have a scroll bar image.

  
    // r: x, y, width, height, kind, identifier, kind, columns, rows, active item, font, alignment, scroll size, scroll kind, scroll bitmap 
    r: 50, 50, 200, 150, List, myList, 1, 4, -1, courier, l, 12, v, scrollbutton.png