HowTo: Start a Real-time Application

Provides a high level look at creating a Real-time Application using TurtleBrains.

Creating an application with TurtleBrains is as easy as counting to three.

1. Derive a custom class from ApplicationHandlerInterface and create an instance.
2. Create an instance of the RealtimeApplication and get the window Open and running.
3. Customize the application by adding a window menu, context menu, status bar, and, if desired, dialog prompts.

Create your application handler.

The most important part of creating an application is handling events, either from the operating system or from user interactions with your application. The ApplicationHandlerInterface provides a way for you to handle any of these events and actions. The following code demonstrates creating a custom subclass of ApplicationHandlerInterface for your applications.

my_application_handler.h

#include "turtle_brains/tb_application_kit.h"

class MyApplicationHandler : public tbApplication::ApplicationHandlerInterface
{
public:
    MyApplicationHandler(void);
    virtual ~MyApplicationHandler(void);
    
    virtual void OnWindowOpen(void);
    virtual void OnRealtimeUpdate(void);
    virtual void OnMenuAction(const MenuIdentifier& menu, const MenuItemIdentifier& menuItem);
    virtual void OnDialogAction(const DialogIdentifier& dialog, const DialogControlIdentifier& dialogControl);  
};

my_application_handler.cpp

#include "my_application_handler.h"

MyApplicationHandler::MyApplicationHandler(void)
{
}

MyApplicationHandler::~MyApplicationHandler(void)
{
}

void MyApplicationHandler::OnWindowOpen(void)
{
    //Perform initialization and handle the window open event.
}

void MyApplicationHandler::OnRealtimeUpdate(void)
{
    //Perform the update of a single frame in the Realtime Application, render a frame using OpenGL.
    glClearColor(0.0f, 0.0f, 0.0f, 1.0f);
    glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
}

void MyApplicationHandler::OnMenuAction(const MenuIdentifier& menu, const MenuItemIdentifier& menuItem)
{
    //Perform any actions when the user interacts with a particular menu / menuItem.
}

void MyApplicationHandler::OnDialogAction(const DialogIdentifier& dialog, const DialogControlIdentifier& dialogControl)
{
    //Perform any actions when the user interacts with a particular dialog / dialogControl.
}

That is all it takes to handle different events for the application. Of course this is only an example handler and there are many other events and actions that can be handled. To see a full list of the possibilities look at the TurtleBrains::Application::ApplicationHandlerInterface documentation.

Create and open the application.

With the application handler created and ready for use, it is time to create the application and get it running. The application takes a handler as a parameter, and expects the handler to remain in scope at least as long as the application itself.

main.cpp

#include "my_application_handler.h"

void main(int argumentCount, char* argumentValues[])
{
    MyApplicationHandler myHandler;
    tbApplication::RealtimeApplication theApplication(myHandler);
    theApplication.Open();
    //The code path will remain busy until the application is closed.
    return 0;
}

That was short and simple, and should result in a real-time window with a blank, black screen.

Customize your application.

Since it is likely your application will need more than a blank, black screen here are links to guides on adding a status bar, menus and dialog prompts. /// The following steps are the same basic steps taken to add a Status Bar, Menu, or Dialog Prompt to your application.

1. Create the necessary identifiers. (ex. MenuIdentifier / MenuItemIdentifier)
2. Create and customized the object as desired, setting up everything as needed. (ex. ApplicationMenu / AddMenuItem)
3. Handle events in the ApplicationHandler when the user interacts with the object. (ex. OnMenuAction).

For more information about adding these customizations to your application see the following:

• Adding Menus
• Adding Dialogs
• Adding a Status Bar