Understanding the basic structure of an application

Your application's class can have several methods that will be called at different points during the execution of the program. The following table lists these methods:

Method	Usage
prepareSettings	This method is called once at the very beginning of the application, before creating the renderer. Here, we may define several parameters of the application before the application gets initialized, such as the frame rate or the size of the window. If none are specified, the application will initialize with default values.
setup	This method is called once at the beginning of the application lifecycle. Here, you initialize all members and prepare the application for running.
update	This method is called in a loop during the application's runtime before the draw method. It is used to animate and update the states of the application's components. Even though you may update them during the draw method, it is recommended you keep the update and drawing routines separate as a matter of organization.
draw	This method is called in a loop during the application's runtime after the update. All drawing code should be placed here.
shutdown	This method is called just before the application exits. Use it to do any necessary cleanup such as freeing memory and allocated resources or shutting down hardware devices.

To execute our code, we must overwrite these methods with our own code.

Getting ready

It is not mandatory to override all of the preceding methods; you can use the ones that your application requires specifically. For example, if you do not want to do any drawing, you may omit the draw method.

In this recipe and for the sake of learning, we will implement all of them.

Declare the following methods in your class declaration:

Void prepareSettings( Settings *settings );
Void setup();
Void update();
Void draw();
Void shutdown();

How to do it…

We will implement several methods that make up the basic structure of an application. Perform the following steps to do so:

1. Implement the prepareSettings method. Here we can define, for example, the size of the window, its title, and the frame rate:

   void MyApp::prepareSettings( Settings *settings ){
     settings->setSize( 1024, 768 );
     settings->setTitle( "My Application Window" );
     settings->setFrameRate( 60 );
   }

2. Implement the setup method. Here we should initialize all members of the application's class. For example, to initialize capturing from a webcam we would declare the following members:

   int mCamWidth;
   int mCamHeight;
   Capture mCapture;
   And initialize them in the setup
   void Myapp::setup(){
     mCamWidth = 640;
     mCamHeight = 480;
     mCapture = Capture( mCamWidth, mCamHeight );
   }

3. Implement the update method. As an example, we will print the current frame count to the console:

   void MyApp::update(){
     console() < < geElapsedFrames() < < std::endl;
   }

4. Implement the draw method with all the drawing commands. Here we clear the background with black and draw a red circle:

   void MyApp::draw(){
     gl::clear( Color::black() );
     gl::color( Color( 1.0f, 0.0f, 0.0f ) );
     gl::drawSolidCircle( Vec2f( 300.0f, 300.0f ), 100.0f  );
   }

5. Implement the shutdown method. This method should take code for doing cleanup, for example, to shut down threads or save the state of your application.

6. Here's a sample code for saving some parameters in an XML format:

   void MyApp::shutdown(){
     XmlTree doc = XmlTree::createDoc();
     XmlTree settings = xmlTree( "Settings", "" );
     //add some attributes to the settings node
     doc.push_back( settings );
     doc.write( writeFile( "Settings.xml" ) );
   }

How it works...

Our application's superclass implements the preceding methods as virtual empty methods.

When the application runs, these methods are called, calling our own code we implemented or the parent class' empty method if we didn't.

In step 1 we defined several application parameters in the prepareSettings method. It is not recommended to use the setup method to initialize these parameters, as it means that the renderer has to be initialized with the default values and then readjusted during the setup. The result is extra initialization time.

There's more...

There are other callbacks that respond to user input such as mouse and keyboard events, resizing of the window, and dragging files onto the application window. These are described in more detail in the Responding to mouse input, Responding to key input, Responding to touch input, Accessing files dragged on the application window, and Adjusting a scene after resizing the window recipes.

See also

To learn how to create a basic app with TinderBox, read the Creating a project for a basic application recipe.