When you generate the C++ source code for your project, a C++ class is created for each SHELL object in the project. The C++ class name is formed by adding a leading 'C' character to the SHELL's name. Of course naming a SHELL object is mandatory.
The C++ class includes by default an attribute for each named GUI object falling in the SHELL hierarchy and methods for all callbacks set to objects in the same hierarchy.
The 'Owner class' OptionEdit allows you to select another SHELL class as the owner of the class being edited. This causes the generated class constructor to include a pointer to the 'Owner class' in the argument list. Such pointer is automatically stored in an attribute named 'owner', allowing you to refer to the owner C++ object within the code of any callback in the class.
Owned classes are usually associated to Modal windows that need to make some actions on objects residing in another window (the owner). Typically this consists of calling a public method provided by the owner class.
Although the Class Options dialog is only available for SHELL objects
in the Designer project, you may decide to bind the C++ class
to a C++ class having a RowForm as the main object instead of a SHELL.
This is useful if you're interested in creating a C++ class with no
top level window associated. In this case the C++ constructor includes a
'CmContainer *' parent GUI object and you are able to use this class
as a new complex GUI object at run time.
Or you can add new methods to the C++ class bound to the SHELL or
FORM using options in tab Methods.
For example, you can add alternative contructors.
You can also disable the definition of the Standard Constructor provided
by the Designer and/or enable the Default destructor
Two additional utility methods: preGUIcreation() and
postGUIcreation() can be activated in the class definition.
The standard constructor provided by the Designer takes care of the definition
of both methods and calls them when appropriate.
More precisely, it calls preGUIcreation() before actually creating
the GUI layout (which is done via the private method GUIcreate()).
The postGUIcreation() method is called instead after the GUI layout
has been created and so all GUI objects are available, though not yet visible.
The postGUIcreation() is often used to set values or change properties
to objects in the layout which can only be determined at run time.
Here's an example of how to use the Owner class option and the
user defined methods.
Let's suppose we have to deal with a text editor. The main
window of this program includes the menu bar and the MultiLine EditWindow
object.
We name the SHELL of such window main_window, so the corresponding
c++ class is named Cmain_window. Let's add two public methods to
this class (using the 'Class Options' dialog):
int findForward(const char *text);
int findBackward(const char *text);
Now let's consider a modal dialog window that allows the user to search
text in the edit window. The SHELL of this window, named search_window,
contains an EditField object, named text_to_search, and two push
buttons saying 'Search Backward' and 'Search Forward'.
Let's assign the first button a callback named searchBackwardCB
and the second one a callback named searchForwardCB.
Provided that we make class Csearch_window owned by Cmain_window,
we can suppose the following code to be suitable for the searchForwardCB
callback:
Csearch_window::searchForwardCB(void)
{
char text[128];
text_to_search->getText(text);
owner->findForward(text);
}