Toolbox objects

The tbx library provides a light wrapper around the Toolbox objects, gadgets and menu items.

The classes to manipulate the toolbox objects can be treated as references to the underlying toolbox object.

Copying the C++ classes does not make a copy of the object, rather it copies the reference so both classes refer to the same object.

Example 4.2. Multiple C++ instances refer to one Toolbox object

tbx::Window w1("Window"); // Creates a C++ class instance and the underlying toolbox object
tbx::Window w2 = w1;      // Creates a new C++ class instance, but refers to the same toolbox object

w1.title("New Title");        // Changes "Window" toolbox items title to "New Title"
w2.title("Even newer title"); // "Window" toolbox item title has been changed again

Any toolbox object can be represented by the Object class. To manipulate it using the properties and methods for that specific class you need to first copy it into a class derived from it. At the point of the copy the toolbox object class type is checked to ensure the C++ class it is copied to is correct and an exception is thrown if it is not.

In some cases you will be returned a C++ class instance that is not currently assosiated with a toolbox object. To determine if a C++ class instance does not reference a toolbox object call the null() method on the object class.

To associate a toolbox class with a C++ class you can either create the toolbox class from the C++ class by using the constructor that takes a template name, use the set_autocreate_listener on the Application class which will be triggered when an object is auto-created by the toolbox, or get it from a property or method of another toolbox object that returns an object.

Example 4.3. Creating a toolbox object in code

// Create the toolbox object named "Window" defined in the "Res" file.
tbx::Window main_window("Window");

Example 4.4. Getting a reference to a toolbox object when it is autocreated

// Class to get reference to toolbox object
class GetMainWindow : tbx::AutoCreateListener
{
public:
  // Subroutine called when object is auto created
  virtual void auto_created( std::string template_name,  tbx::Object object)
  {
     tbx::Window main_window(object); // main_window now refers to the object created
     // Do stuff with main_window
     ...
  }        
};

// Code fragment from main setting up the listener for toolbox object "Window"
GetMainWindow get_main_window;
test_app.set_autocreate_listener("Window", &get_main_window);

Example 4.5. Getting a reference toolbox object from another toolbox object

// main_window is a tbx::Window instance
tbx::Menu main_menu = main_window.menu();

To detect when a toolbox object is deleted automatically you can add a listener for the has been deleted event. If the toolbox does not delete the object automatically you can delete the toolbox object from the C++ class instance by calling the delete_object method.

A MatchLifetime templated class provides a convenient way to match the life time of a C++ class instance with a toolbox object. If its constructor is provided with a template name it will automatically add the above listeners for you.