Working with Delegates in Visual Form Files

So you've got your interface put together via your Visual Form File resource. Now you want to hook up some event handlers or callbacks in your application code to the UI. No problem!

The first thing you need to to is write the code. Let's start off by using our application class as a place to put the callbacks. Later on we'll investigate using the main window class as well, but for now, lets look at our app class:

class LOLCatsApp : public Application {
public:

};

OK let's put in some code to handle a button click. The command button class has a delegate that takes a function with one parameter, a ButtonEvent* and returns nothing (void). Since ButtonEvent derives from Event, and in this case we really don't care much about the event per se, we can "cheat" a bit and simply write a function that takes a generic Event*.

class LOLCatsApp : public Application {
public:
 void myCallBack( Event* ) {
   Dialog::showMessage( "Hello there!" );
 }
};

Now we've defined our callback. Let's add it to the application for later retrieval:

class LOLCatsApp : public Application {
public:
 LOLCatsApp( int argc, char** argv ) :
   Application(argc, argv) {
   addCallback( new ClassProcedure1<Event*,LOLCatsApp>(this, &LOLCatsApp::myCallBack), "LOLCatsApp::myCallBack" );
 }

 void myCallBack( Event* ) {
   Dialog::showMessage( "Hello there!" );
 }
};

An application is component, and therefore can have 0 or more callbacks. So we call the app's addCallback() method and create a link to our callback function making sure to give a correct name.

At this point, we've defined/implemented a callback function, and added it to the list of callbacks the application maintains and that can be retreived by others via a call to the app's getCallback() function. All we have left is to hook the application's callback to the component in our VFF definition.

Like properties, a component can expose the delegates it has via the VCF's RTTI macros. This allows you to access them in the vff definition. The rule for this is that each object block, i.e.

object MyObj : MyClass

end

has an option delegates section, defined like so:

object MyObj : MyClass
 delegates
 end
end

Within this block, you can reference the delegates of the component and then assign an array of callbacks to the delegate. Each callback in the array will be added to the delegate. In other words:

object MyObj : MyClass
 delegates
   MyDelegate = [SomeComponentName@SomeComponentClass::SomeCallBackFunction]
 end
end

Each item in the array of callbacks has the following format: the name of a valid component instance, the "@" character, and the name of the callback. Technically the name of the callback can be anything you want, however the convention is to use fully qualified C++ names, so that's usually the name of the component instance's class, the "::" qualifier, and the name of the method.

The component referenced can be any component in the VFF definition, or it can be the name of the app class. By default, the name of the app is it's class name *unless* you explicitly change it before you load up your form(s).

Armed with this information, lets add our callback to a button:

object myBtn : VCF::CommandButton  
 caption = 'Click Me'
 delegates
   ButtonClicked = [LOLCatsApp@LOLCatsApp::myCallBack]
 end
end

When the form is loaded the framework will look at the myBtn instance, get access to it's ButtonClicked delegate and the callback named "LOLCatsApp::myCallBack" in the LOLCatsApp instance, and then add the callback to the delegate. At that point everything is "wired" together - when you click the button, the LOLCatsApp::myCallBack code will be invoked!

One question might be how to know what delegates are available. You can always browse the code, but that may nor may not immediately tell you that the delegate is exposed via the RTTI macros. Another way is use the new ClassRegistry Browser ( ClassRegistryBrowser.zip ). This is a graphical program that shows all the registered classes in the VCF's ClassRegistry. A class must be registered in the ClassRegistry for it to available for reference in a VFF definition. When you select a class, the program then iterates through all of the properties and delegates of the class. Something a bit like this:



Using this tool you can definitively determine what delegates are available and can be safely referenced in your VFF definition.

Now, let's make a change and instead of using our app class, lets use our window class to hold our callback. Let's add the code to our class first:

class LOLCatsWindow : public Window {
public:
 LOLCatsWindow();

 virtual ~LOLCatsWindow(){};

 void myCallBack( Event* ) {
   Dialog::showMessage( "Hello there!" );
 }

};

Add our callback:

class LOLCatsWindow : public Window {
public:
 LOLCatsWindow() {
   addCallback( new ClassProcedure1<Event*,LOLCatsWindow>(this, &LOLCatsWindow::myCallBack), "LOLCatsWindow::myCallBack" );
  
 }

 virtual ~LOLCatsWindow(){};

 void myCallBack( Event* ) {
   Dialog::showMessage( "Hello there!" );
 }

};

And then wire it up in the VFF:

object LOLCats  : VCF::Window
 object myBtn : VCF::CommandButton  
   caption = 'Click Me'
   delegates
     ButtonClicked = [LOLCats@LOLCatsWindow::myCallBack]
   end
 end
end

That's it! You've now got your window class handling a button click.

This same technique can be applied to any component that exposes delegates through the VCF's RTTI. For more examples you might want to look at the following:
vcf/examples/LOLCats
vcf/examples/ClassRegistryBrowser
vcf/examples/ListViews