Word Clock – Part 3

The main.lua File

The main.lua file is the starting point of every Corona SDK app. It must be found in the main root of the project folder, otherwise the project will not compile.

If you create a new project with the Corona Simulator like we did in part 1, all mandatory files are created for you.

Let’s take a look at the main.lua file.

Open main.lua

Open up Sublime and the Word Clock project we have set up in part 1 of this course. Use Sublime’s open project command at Project>Open Project ... or look if it is listed under Project>Recent Projects.

Now you should see the project folder structure in the left side bar.

Click the main.lua file to open it in the editor. Have a look at the lower right corner of the editor and check if Corona SDK Lua is set as current syntax. If not you should set it to.

Our current main.lua file

Our current main.lua file

Now you should have a similar screen like in the Screenshot. The main.lua file contains our Hello World code from part 1.

Now the main.lua file could be used to write down the whole application code here, but this would lead to a very big complex code which is hard to maintain.

Instead we should always try to break the whole app into smaller pieces.

This is why, when developing a Corona SDK app, we almost always use the main.lua file to create some initializing procedures for the app only. For example displaying a loading screen, make some general settings or loading some configuration data.

And in the end of the main.lua we goto the first scene.

But before diving deeper into scenes let’s have a look at our final main.lua code .

— hide the status bar
display.setStatusBar( display.HiddenStatusBar )
local composer = require( "composer" )

— load the clock screen
composer.gotoScene( "clock", { effect = "fade" } )

This is all we need for the main.lua file. Let’s go through each line of code.

Lua Comments

The first line is a comment. Comments in Lua do begin with two hyphens.

If you want to create a multiline block comment you can also use two hyphens followed by two open square brackets, like in the following code example:

--[[
This is a bigger comment over
several lines 
]]

Furthermore you have to close a block comment with two closing square brackets like in the code above.

Hiding the Device’s Status Bar

The second line in the main.lua file hides the status bar at the top of the display. The status bar of the smartphone/tablet device shows some infos about the quality of the mobile network, the time, the battery status etc.

Since we are showing a clock app that shows the time I decided to hide the status bar.

The function display.setStatusBar( mode ) supports four different modes. You can use the following values for the mode parameter:

  • display.HiddenStatusBar – hides the status bar like in the code above
  • display.DefaultStatusBar – sets the status bar to its default appearance
  • display.TranslucentStatusBar – makes a see-through status bar
  • display.DarkStatusBar – changes the status bar to a dark version which might better fit to the look of your app

And here the link to the online documentation for further informations.

Composer and Scenes

The so called Composer library is a very important part of the Corona SDK. It manages different scenes and it offers commands to change scenes with optional transition effects.

This app does only have one scene (the word clock scene), so the Composer and Scene concept is not that important here. But if you create some more complex apps you will use it for sure.

So what is a Scene?

Technically a Scene is one Lua file that describes a certain screen. Imagine a game that starts with a main menu that contains buttons to start the game and to display the highscore screen.

This main menu could be one Scene we call mainmenu.lua

If you press the play button you would load a different scene, for example level1.lua which shows the first level of the game.

As mentioned above we do have a screen for the high scores. This could be a further Scene called highscore.lua.

See the following screenshot to get the idea of different Scenes.

Scribble of Example Scenes

Scribble of Example Scenes

Now let’s say we want to go to the level1 Scene after the player pressed the play button. We do this with a call to the composer library like this:

composer.gotoScene("level1")

As you can see, when calling a composer.gotoScene we omit the .lua suffix.

I really recommend reading the official docs about Corona’s Composer & Scenes concept

 

Loading the Composer Library

 

Back to our main.lua file: our next line of code loads the Composer library, because you have to load it first before you can use it:

local composer = require( "composer" )

Loading a library or a module does always use the require command: it requires an external file. In this case the composer library file.

The require returns the instance of the Composer library, so we need to store it in a variable. Therefore we create the local variable composer

Scopes – Local vs. Global

Local variables are only available in the scope where they have been created – in this case the scope is the whole main.lua file. This means the variable is not available in other Lua files.

If we omit the word local the variable is automatically created in the global scope. This means the variable would be accessible in all Lua files in the whole project.

Again: this is something we really want to avoid. Because we never know if we overwrite another global variable that has the same name by accident.

More on scopes in the progress of this course.

Goto to the Next Scene

So the line of code above loads the Composer library and stores it into the local variable called composer.

Now we can use the functions of the Composer library. One function is called gotoScene(). We use this function in the last line of our main.lua file:

composer.gotoScene( "clock", { effect = "fade" } )

Here we use the composer.gotoScene() function to load the scene called clock. Furthermore we use a fade transition effect to let the word clock slowly fade in.

In a later part I will explain the curly brackets here.

Also I recommend to open the online docs. Bring the cursor on the composer.gotoScene word and press F1 to open the online docs for this command.

Compile the project now. Use Cmd+F10 or Corona Editor>Run Project.

RUNTIME ERROR

BAM! Compiler Error!

BAM! Compiler Error!

BAM! You should get an error now.

But don’t be afraid: when developing apps you will get them regularly. This I why I want you to examine the infos of the error message to get rid of the buggy code.

I marked some important infos in the screenshot. You can see that a module could not be loaded because the file is missing: “no file”.

And at the bottom part, it also says the exact line where the error occurs. In this case it says: the error occurred when calling a gotoScene function in the file main.lua at line 14.

The problem is, we have not created a clock.lua file yet. This is why the compiler throws that error. And this is why we need to go to the next part of this course – it is time to create the clock.lua file.

Conclusion

In this part we learned what the main.lua file is used for and how we can change settings regarding the device’s status bar.

Furthermore I introduced the concept of Composer & Scenes and how to load another scene with a fade transition.

We also learned some basic concepts of variable scopes and we examined a Runtime Error Message to find the position of an error in the code.