This tutorial should give you a basic idea how to use the CorEngine GUI system.

Step 1: Getting the tutorial resources

[tutorial6_resources.zip] contains the images and the font which we will be using in this tutorial.

Step 2: Extracting the tutorials resources

The tutorial resource package contains a folder called resources. Copy and paste that folder to the folder where you have your CorEngine Developmet Kit.

Step 3: Setting up init.lua

For this tutorials base init.lua, we will use just a simple script that creates a gui and run the engine. We don't need a level in this tutorial, so we don't load a one.

  gui1 = Create.Gui()
  Engine.SetGui( gui1 )

  while ( Engine.Run() == true ) do
  end

We create a regular GUI with Create.Gui() and set it as the current GUI with Engine.SetGui(). Always remember to set the gui which you create if you want to use it.

Step 4: Adding a picture

First, we will create just a picture that does nothing. Lets use the CorEngine logo for that!

  gui1 = Create.Gui()
  Engine.SetGui( gui1 )

  -- Create the CorEngine logo
  picture1 = Create.Picture( gui1, "Logo", 0, 0, "resources/powered.png" )

  Picture.SetScale( picture1, 0.2, 0.2 )

  size = Gui.GetObjectSize( picture1 )
  Gui.SetObjectPosition( picture1, 
    Context.GetWindowWidth() - size.x - 2, Context.GetWindowHeight() - size.y - 2 )

  while ( Engine.Run() == true ) do
  end

If you are wondering about the line -- Create the CorEngine logo, it is just a comment line for documentation purposes. It doesn't get executed.

First we load a texture for the picture with Create.TextureFromFile. Most GUI elements use textures, so you'll be using this function quite often. Next we create the picture and set its texture. Then we set the picures position with Gui.SetObjectPosition to the upper right corner of the sceen. The Set/GetGuiObject* functions can be called for any GUI object (label/picture/button/textfield/etc...).

You might wonder what are we doing with the Gui.GetObjectSize(pic).x part. We are getting the GUI object size, which is a vector of two elements, x (width) and y (height). Then we get the .x element straight away. Another way would be to store the size to some variable, like this: size = Gui.GetObjectSize(pic) and then access the width with size.x, like this: Gui.SetObjectPosition(pic, Context.GetWindowWidth()-size.x, 0), but since we aren't going to use the size anywhere else, we just accessed it straight away.

Oh, and just to be sure, the Gui.SetObjectPosition takes the gui object as the first argument, the x position as the second, and the y position as the last. The x and y position are counted from the upper left corner of the gui element.

The last thing we do, is adding the picture to the gui with Gui.AddObject. NOTE: REMEMBER TO ADD THE OBJECT TO A GUI. Otherwise it won't display.

If everything went well, you should be seeing the CorEngine logo. If not, check your code and the console/ConEngine.log for errors.

Step 5: Adding a label

Now we will add a label that displays the FPS to the GUI.

  gui1 = Create.Gui()
  Engine.SetGui( gui1 )

  -- Create the CorEngine logo
  picture1 = Create.Picture( gui1, "Logo", 0, 0, "resources/powered.png" )

  Picture.SetScale( picture1, 0.2, 0.2 )

  size = Gui.GetObjectSize( picture1 )
  Gui.SetObjectPosition( picture1, 
    Context.GetWindowWidth() - size.x - 2, Context.GetWindowHeight() - size.y - 2 )

  -- Add a label
  font1 = Create.FontFromFile( "resources/freesans.ttf", 12 )

  label1 = Create.Label( gui1, "FPSLabel", 10, 10, "FPS: 0" )
  Label.SetFont( label1, font1 )

  while ( Engine.Run() == true ) do
    Label.SetText( label1, "FPS: " .. Engine.GetFps() )
  end

First we load the font we are going to use for the label. Only True Type font's are supported at the moment. The first parameter Create.FontFromFile is the file path to the font, and the second is the preferred size of the font.

Next we create our label, set the font, set the text and set its position. Then we add the label to the gui. The last thing we do, is updating the text of the label on each frame in the while loop.

Step 6: Some more GUI elements

Now that you have the basic hang of GUI elements, I'll show you some snippets of code for setting up more GUI elements. The codes are not full init.lua scripts, but just small parts of the code which you can add/remove/write yourself.

First some buttons.

  -- Add exit button
  exbtexoff  = Create.TextureFromFile( "ExitOff",  "resources/dsbexitoff.png"  )
  exbtexover = Create.TextureFromFile( "ExitOver", "resources/dsbexitover.png" )
  exbtexon   = Create.TextureFromFile( "ExitOn",   "resources/dsbexiton.png"   )

  exb = Create.Button( gui1, "ExitButton", 10, 30, 0, 0, "Exit" )

  Button.SetOffTexture ( exb, exbtexoff  )
  Button.SetOverTexture( exb, exbtexover )
  Button.SetOnTexture  ( exb, exbtexon   )

  exscr = Create.Script( "ExitScript" )
  Script.SetText( exscr, "Engine.Quit()" )
  Gui.SetObjectScript( exb, exscr )

Buttons have three textures. One for when the mouse is off the button, one for when the mouse is on the button and one for when the mouse is clicking or on the button. We load all of them, create the button, set the textures and set the position of the texture.

Now we would like the button to do something, so we create a script for it. Then we set the script text to "Engine.Quit()", the quit function in the API. You could also load and external script with Create.ScriptFromFile if you wanted. We attach the script to the button and add the button to the GUI.

Next we move to check boxes

  -- Create a check box
  cbtexoff = Create.TextureFromFile( "CheckOff", "resources/dscboff.png" )
  cbtexon  = Create.TextureFromFile( "CheckOn",  "resources/dscbon.png"  )

  cb = Create.CheckBox( gui1, "MyCheckBox", 52, 30, false )

  CheckBox.SetOffTexture( cb, cbtexoff )
  CheckBox.SetOnTexture ( cb, cbtexon  )

The check box only has on and off textures. We load the textures, create the check box, set the textures, set the position and add the check box to the GUI.

Lastly we study some text fields.

  -- Add text field
  font1   = Create.FontFromFile( "resources/freesans.ttf", 12 )
  txbxtex = Create.TextureFromFile( "TextFieldTex", "resources/dstxbx.png" )

  txf = Create.TextField( gui1, "MyTextField", 82, 30, 100, "Some text..." )

  TextField.SetFont   ( txf, font1   )
  TextField.SetTexture( txf, txbxtex )
  TextField.SetOffset ( txf, 4, 1    )

First we load the font and the background texture for the text field. Then we create the text field, set its font, set its texture and text.

Next we set the text field offset. Whats that? The text field offset is the offset the text in the text field will be displayed against the text field background. Most likely, the text won't be aligned in the center of the background by default, so with the TextField.SetOffset function, you can adjust the offset yourself.

Lastly we set the position of the text field and add it to our GUI.

Step 7: GUI element scripts and events

When we created the button in an earlier step, you might have noticed that we set a script for it. You can assign a script for any GUI element, and the script will be called if the gui element invokes GUI events. In the buttons case, the script gets called each time the button is clicked. But this is not the case with some other GUI elements.

Text fields invoke the script each time they are activated, a character is inputted to them, and when they are deactivated. How to find out which event is going on? The current event of a gui object can be accessed with Gui.GetObjectEvent. For example, if a text field was clicked, and it became active, you would check for it with
if ( Gui.GetObjectEvent(me) == GAIN_FOCUS ) then ... end
in the text fields script.

Here is a list of event types for different GUI element:

Buttons - CLICKED
Text Fields - GAIN_FOCUS, LOSE_FOCUS, CHAR_INPUT
Sliders - VALUE_CHANGED
Text Lists - SELECTION_CHANGED
Check boxes - STATE_CHANGED

Thats it! I hope you enjoyed the tutorial, and if you have any comments about it, please post to the forums.