When you statically link to the VCF, you won't automatically pick up the resource images and default ICO for the windows. You can fix by adding the ApplicationKit.res file, which does get built for you, to your link step. In VC6, go to the Link tab of your project's settings, and add the ApplicationKit.res like so:
$(VCF_ROOT)/lib/ApplicationKit.res
This will fix it so you get access to resources for the ApplicationKit.
Monday, November 10, 2008
Thursday, May 1, 2008
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:
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*.
Now we've defined our callback. Let's add it to the application for later retrieval:
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.
has an option delegates section, defined like so:
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:
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:
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:
Add our callback:
And then wire it up in the VFF:
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
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
Monday, April 14, 2008
Models, Views, and Items - a Saga for the Ages
In the recent past we had a tight coupling between a Model and an Item. The idea
was that an Item represented an individual "thing", or element of data, in the model. The implementation of the model worked out how to store the item (i.e. as
a std::vector<item*> for example). This meant that the model had to store a collection of Items, regardless of what theses items stood for, and the design of the Item meant that it stored all sorts of UI information that meant nothing to the model, such as the item's state, color, font, etc. So what happened is that the Item class ended up storing all sorts of data, some of which was relevant to the item's UI and some relevant to the model. This made it more difficult than necessary to make general purpose models.
So, I'm proposing breaking the direct connection of having a model store Items. Instead the model *only* stores data, which is really as it should be. The collection of Items, if appropriate, is maintained instead by the View/Control. Thus the Item becomes a "bridge" between the Model and the control, and is used by the control/view to help "compartmentalize" the drawing process and allow for things like custom item rendering. You could even think of the Item as a sort of "mini" View.
The model will allow for data access by using the VariantData class. Obviously we could use templates for this, but that has it's own issues. I think, in this case, it's easier to understand and to deal with using VariantData classes. Remembering that the public interface, common to a specific type of model (for example, a list model) would use VariantData types for it's methods, but the actual storage could be accomplished however you want. The default storage implementation might be, for a list model, an array of VariantData, but a custom design could certainly use something else, so long as methods are implemented correctly.
The Model class has a generic method for getting
and setting data that allows you to get or set an element of data using a VariantData class to hold the data, and also to specify an optional "key" using a VariantData class to hold the key information. So, if you had a model that represented an array of doubles, then the "key" might be an integer that indicated the index to use to set or get an element from the array, while the result of the "get" or the data for the "set", a double value, would be stored in the VariantData instance. All of this would be done using the generic get and set methods of the Model class. Of course you could provide your own more specific set of methods on your concrete model class. For example, the ListModel provides a set of methods for getting and setting values in a collection of data. It also implements the generic Model get/set methods - you can use either one, it's up to you.
So, to reiterate: a Model stores data, an Item stores visual information and serves as a bridge between the control and model. An Item does NOT store data relevant to the model. An Item may have methods that allow you to retrieve data from the model, but they are simply convience methods, you achieve the same thing by calling the appropriate methods on the specific model class.
Lets look at some changes to the base classes for MVC in the framework, specifically the Model and Item classes, and then move on to looking at some specific model types.
The Model class doesn't change a great deal. It still has a collection of Views, and it still has delegates that fire events. It does have several new methods for generically getting or setting data on the model.
The exact implementation is up to the designer of the specific model class. The default
implementations do nothing or return VariantData objects that are set to NULL (the
VariantData's isNull() method will return true).
The Item class has a pointer to the model it's associated with. It has a pointer to the Control it's associated with. It stores data related to it's visual display, specifically, it holds a pointer to a font, display state mask that can hold various values, an image index, a void pointer for some application specific value, if need be, and a boolean value indicating whether or not it's selected. It has a virtual method that is used to indicate whether or not the item can paint itself, and also a virtual method for the actual paint() method.
The Item class is a base class, and there are specific sub classes of it for use by the various controls. For example, there's a ListItem for use in list like controls, a TreeItem for tree or hierarchical controls, a TableCellItem, and so forth.
An Item's lifetime is managed by the control it's associated with. An Item may or may not be created at the moment you make a change to the model. For example, if you have a header control, then for each element you add to the model, a new Item is created. This is OK, as headers rarely have a high number of elements to them (think of a control with more than 100 hundred header items - not very likely). However other controls, like a Tree Control, only create teh items when you need them. This saves enormously on memory since if you have a TreeModel with 1 million elements in it then creating 1 million corresponding TreeItem's doesn't make a whole lot of sense, especially since none of them will be needed right away. Moral of the story: don't cache Item's directly - store the key or index you used to retrieve them instead.
Some changes to specific models are a cleaned up interface, for example the ListModel now looks like this:
The functions that you have to implement are for read only support are:
These are fairly self explanatory.
The functions that modify the model, specifically:
are a little more involved. They are not virtual. Instead they call virtual methods that by default are no ops, and are intended to do the actual work of modifying the underlying collection or data store (whatever that might be). If these methods return a true value, then the non virtual modifier method do the work of ensuring that events are fired on the model's correct delegate(s). This makes is simpler on the implementer, and they don't have to worry about writing a lot of boiler plate code.
The virtual methods for modifying the model are:
When you call ListModel::insert(), it calls doInsert() to perform the actual data insertion on the collection, and then fires the appropriate events. Likewise, set() calls doSet(), and so forth.
The ListModel has support for adding/removing/getting sub items, and these methods work in a similar fashion as the previous functions. One note: sub items are zero indexed, so if you have a list model with an element at index 0, and it has 2 sub items, then the sub item indices would be 0 and 1, and you could access them by calling ListModel::getSubItem(0,0) and ListModel::getSubItem(0,1).
The list control's have been modified (or are in the process of being modified) to use a common ListControl base class. This provides a common set of functionality for dealing with a list of items and displaying them to the user. Controls that derive from this are the ListViewControl, ListBoxControl, and DropDownControl. The ListControl handles events from the ListModel and deals with creating or removing ListItems accordingly. The class looks something like this (only listing methods dealing with Items):
Note that these methods are simply meant as shortcuts to using the list model methods for adding/removing elements. Under the hood the list model ends up getting called. With these methods you're limited to the kind of data that you can store since the caption is simply passed to the list model as a string. If the caption is the string "Hello" and your list model is implemented to expect numbers then the data that gets entered into it will be incorrect.
You can add, insert, or remove items, as well as get or set a specific item. Adding/removing items is fairly straight forward. You add an item by specifying a caption and optional image index, and you're returned a ListItem instance.
You can test for the presence of a ListItem by calling itemExists(), which will return true if there is an ListItem at the specified index.
You can change an existing ListItem to something completely different (for example, perhaps you have a custom ListItem that you want to use instead of the default) by calling the setItem, passing in an index and a valid instance. The old ListItem will be deleted and the new one put in it's place. If the new item doesn't have a component owner, then the list control will take over and you don't have to worry about the ownership (and cleanup) of the item.
These changes have been made to other model classes as well, including the TreeModel, the TableModel, the TextModel, and so on. Changes to the various controls to facilitate this have also been made, and the TreeControl and ListViewControl's underlying peer implementation has also changed quite a bit, making them alot more robust.
was that an Item represented an individual "thing", or element of data, in the model. The implementation of the model worked out how to store the item (i.e. as
a std::vector<item*> for example). This meant that the model had to store a collection of Items, regardless of what theses items stood for, and the design of the Item meant that it stored all sorts of UI information that meant nothing to the model, such as the item's state, color, font, etc. So what happened is that the Item class ended up storing all sorts of data, some of which was relevant to the item's UI and some relevant to the model. This made it more difficult than necessary to make general purpose models.
So, I'm proposing breaking the direct connection of having a model store Items. Instead the model *only* stores data, which is really as it should be. The collection of Items, if appropriate, is maintained instead by the View/Control. Thus the Item becomes a "bridge" between the Model and the control, and is used by the control/view to help "compartmentalize" the drawing process and allow for things like custom item rendering. You could even think of the Item as a sort of "mini" View.
The model will allow for data access by using the VariantData class. Obviously we could use templates for this, but that has it's own issues. I think, in this case, it's easier to understand and to deal with using VariantData classes. Remembering that the public interface, common to a specific type of model (for example, a list model) would use VariantData types for it's methods, but the actual storage could be accomplished however you want. The default storage implementation might be, for a list model, an array of VariantData, but a custom design could certainly use something else, so long as methods are implemented correctly.
The Model class has a generic method for getting
and setting data that allows you to get or set an element of data using a VariantData class to hold the data, and also to specify an optional "key" using a VariantData class to hold the key information. So, if you had a model that represented an array of doubles, then the "key" might be an integer that indicated the index to use to set or get an element from the array, while the result of the "get" or the data for the "set", a double value, would be stored in the VariantData instance. All of this would be done using the generic get and set methods of the Model class. Of course you could provide your own more specific set of methods on your concrete model class. For example, the ListModel provides a set of methods for getting and setting values in a collection of data. It also implements the generic Model get/set methods - you can use either one, it's up to you.
So, to reiterate: a Model stores data, an Item stores visual information and serves as a bridge between the control and model. An Item does NOT store data relevant to the model. An Item may have methods that allow you to retrieve data from the model, but they are simply convience methods, you achieve the same thing by calling the appropriate methods on the specific model class.
Lets look at some changes to the base classes for MVC in the framework, specifically the Model and Item classes, and then move on to looking at some specific model types.
The Model class doesn't change a great deal. It still has a collection of Views, and it still has delegates that fire events. It does have several new methods for generically getting or setting data on the model.
class Model {
public:
virtual VariantData getValue( const VariantData& key=VariantData::null() );
virtual VariantData getValueAsString( const VariantData& key=VariantData::null() );
virtual void setValue( const VariantData& value, const VariantData& key=VariantData::null() );
virtual void setValueAsString( const String& value, const VariantData& key=VariantData::null() )
}
The exact implementation is up to the designer of the specific model class. The default
implementations do nothing or return VariantData objects that are set to NULL (the
VariantData's isNull() method will return true).
The Item class has a pointer to the model it's associated with. It has a pointer to the Control it's associated with. It stores data related to it's visual display, specifically, it holds a pointer to a font, display state mask that can hold various values, an image index, a void pointer for some application specific value, if need be, and a boolean value indicating whether or not it's selected. It has a virtual method that is used to indicate whether or not the item can paint itself, and also a virtual method for the actual paint() method.
The Item class is a base class, and there are specific sub classes of it for use by the various controls. For example, there's a ListItem for use in list like controls, a TreeItem for tree or hierarchical controls, a TableCellItem, and so forth.
An Item's lifetime is managed by the control it's associated with. An Item may or may not be created at the moment you make a change to the model. For example, if you have a header control, then for each element you add to the model, a new Item is created. This is OK, as headers rarely have a high number of elements to them (think of a control with more than 100 hundred header items - not very likely). However other controls, like a Tree Control, only create teh items when you need them. This saves enormously on memory since if you have a TreeModel with 1 million elements in it then creating 1 million corresponding TreeItem's doesn't make a whole lot of sense, especially since none of them will be needed right away. Moral of the story: don't cache Item's directly - store the key or index you used to retrieve them instead.
Some changes to specific models are a cleaned up interface, for example the ListModel now looks like this:
class ListModel : public Model {
void insert( const uint32 & index, const VariantData& item );
void add( const VariantData& item );
void remove( const uint32& index );
void set( const uint32& index, const VariantData& item );
virtual void setAsString( const uint32& index, const String& item );
virtual VariantData get( const uint32& index );
virtual String getAsString( const uint32& index );
virtual uint32 getIndexOf( const VariantData& item );
virtual bool getItems( std::vector& items );
virtual Enumerator* getItems();
virtual bool getRange( const uint32& start, const uint32& end, std::vector& items );
virtual uint32 getCount();
}
The functions that you have to implement are for read only support are:
virtual VariantData get( const uint32& index );
virtual uint32 getIndexOf( const VariantData& item );
virtual bool getItems( std::vector& items );
virtual Enumerator* getItems();
virtual bool getRange( const uint32& start, const uint32& end, std::vector& items );
virtual uint32 getCount();
These are fairly self explanatory.
The functions that modify the model, specifically:
void insert( const uint32 & index, const VariantData& item );
void add( const VariantData& item );
void remove( const uint32& index );
void set( const uint32& index, const VariantData& item );
are a little more involved. They are not virtual. Instead they call virtual methods that by default are no ops, and are intended to do the actual work of modifying the underlying collection or data store (whatever that might be). If these methods return a true value, then the non virtual modifier method do the work of ensuring that events are fired on the model's correct delegate(s). This makes is simpler on the implementer, and they don't have to worry about writing a lot of boiler plate code.
The virtual methods for modifying the model are:
virtual bool doInsert( const uint32 & index, const VariantData& item );
virtual bool doRemove( const uint32& index );
virtual bool doSet( const uint32& index, const VariantData& item );
When you call ListModel::insert(), it calls doInsert() to perform the actual data insertion on the collection, and then fires the appropriate events. Likewise, set() calls doSet(), and so forth.
The ListModel has support for adding/removing/getting sub items, and these methods work in a similar fashion as the previous functions. One note: sub items are zero indexed, so if you have a list model with an element at index 0, and it has 2 sub items, then the sub item indices would be 0 and 1, and you could access them by calling ListModel::getSubItem(0,0) and ListModel::getSubItem(0,1).
The list control's have been modified (or are in the process of being modified) to use a common ListControl base class. This provides a common set of functionality for dealing with a list of items and displaying them to the user. Controls that derive from this are the ListViewControl, ListBoxControl, and DropDownControl. The ListControl handles events from the ListModel and deals with creating or removing ListItems accordingly. The class looks something like this (only listing methods dealing with Items):
class ListControl {
ListModel* getListModel();
void setListModel(ListModel * model);
ListItem* addItem( const String& caption, const uint32 imageIndex=0 );
ListItem* insertItem( const uint32& index, const String& caption, const uint32 imageIndex=0 );
bool itemExists( const uint32& index );
ListItem* getItem( const uint32& index );
void setItem( const uint32& index, ListItem* item );
void selectItem( const uint32& index );
Enumerator* getSelectedItems();
uint32 getFocusedItem();
uint32 getSelectedItem();
uint32 hitTest( const Point& point );
};
Note that these methods are simply meant as shortcuts to using the list model methods for adding/removing elements. Under the hood the list model ends up getting called. With these methods you're limited to the kind of data that you can store since the caption is simply passed to the list model as a string. If the caption is the string "Hello" and your list model is implemented to expect numbers then the data that gets entered into it will be incorrect.
You can add, insert, or remove items, as well as get or set a specific item. Adding/removing items is fairly straight forward. You add an item by specifying a caption and optional image index, and you're returned a ListItem instance.
You can test for the presence of a ListItem by calling itemExists(), which will return true if there is an ListItem at the specified index.
You can change an existing ListItem to something completely different (for example, perhaps you have a custom ListItem that you want to use instead of the default) by calling the setItem, passing in an index and a valid instance. The old ListItem will be deleted and the new one put in it's place. If the new item doesn't have a component owner, then the list control will take over and you don't have to worry about the ownership (and cleanup) of the item.
These changes have been made to other model classes as well, including the TreeModel, the TableModel, the TextModel, and so on. Changes to the various controls to facilitate this have also been made, and the TreeControl and ListViewControl's underlying peer implementation has also changed quite a bit, making them alot more robust.
Subscribe to:
Posts (Atom)
