Sourceforge.net - The VCF's Project Host
   The VCF Website Home   |   Online Discussion Forums   |   Sourceforge.net Project Page   

Visual Component Framework Documentation

devmain-0.9.8

What follows is documentation for the main VCF source documentaion page.This document is meant, first of all, as a general introduction to the VCF. It intends to orient you to the basic concepts of how the VCF is designed and how to begin using the features. Here’s what it won’t do: It won’t teach you how to program; nor will it show you details about features of the framework (see the Reference Manual for this information); nor will it present you with step-by-step information about how to build a program. No, this document will paint a “big picture” of what’s going on in the VCF. Enough rambling… now onto the details.

Understanding the kits of the VCF
The VCF is organized into a series of kits. Each one is built into a separate library. Here are the main ones:
The VCF also has additional secondary kits that perform specific functions. At the moment, we have three: Since components’ interactions with the operating system vary from system to system, each kit contains implementations of the generalized components. Classes prefaced with Win32 pertain to 32-bit Windows environments; those prefaced with Linux, to Linux; with OSX, to Mac OS X. Generally, you need not access the specific implementation; you can keep to the generalized classes. (In other words, use class VCF::Thread, not class VCF::Win32Thread.). These classes also represent the concrete implementations of the various peer interfaces that are used to describe the various OS services. Peer classes are used by the internals of the framework.

Using examples to start your application
A standard download of the VCF will contain an examples directory, replete with basic demonstrations of features of the VCF. If you are completely unaware of how to use a feature, it is best first to consult one of these examples.
For example, if you want to use a slider control (like one Windows uses to control the volume), use VisualStudio to open up the project in examples/Sliders. If you build this project, it will appear in the examples/Sliders/vcXX/Debug directory. Here, you will see horizontal and vertical sliders, sliders with different begin and end values, sliders which send update events upon moving, etc. You can read the code and use these ideas to begin your application.

If you aren’t sure which example contains a certain item, perform a recursive search through the examples directory with your item’s name. Then open up one of the projects that contains the item.

Fine-tuning your application via the source manual
Of course, examples can’t exhaustively demonstrate all of the features of an application. Thus the API is available to facilitate your creative use of the features. To view this, see the Source Manual. The Class List will show a list of the classes.
When you click on a class, you will see its inheritance diagram. If you wish to view the class’s inherited members, click the “List of all members” link.

Sifting through the functions
The purpose of each function is designed to be easily understandable and not cryptic. If the class is a control, a paint method will paint the control; you should not call this method as it is called automatically.
Sometimes methods have models which represent a collection of multiple items. For example, a ListBoxControl (a vertical list of items) uses a ListModel (available via the getListModel command) to manage a group of ListItems. To build a list, create a DefaultListItem (an implementation of ListItem), add it to the ListModel via addItem, and it will be added to the ListBoxControl.

Other methods use events. There may be various event-handler methods present in a class. Again, you will usually not access these directly.

A control can be positioned and sized via the setBounds method, or via setLeft, setRight, setTop, setBottom, setWidth, and setHeight methods. These are universally inherited from the base Control class.

Some items use enumerations to specify particular functionalities. You can click on the class name to view a full description of the enumeration. An example from the directory should help you flesh this out.

Understanding accessories
If you wish to add event handlers to a control, various delegates are accessible in a class. The delegate names should adequately describe their functionality as distinguished from each other. An EventHandler can be added to each delegate to handle an event occurring at a certain point in the code. There are several types of EventHandlers; you can use the GenericEventHandler or fetch the specific type of EventHandler for your specific need.
In the following example, an EventHandler is added to a ListBoxControl, calling the function onChange every time the selection is changed in the ListBox.

VCF::ListBoxControl *lbc = new VCF::ListBoxControl();
lbc->SelectionChanged += new
   ListModelEventHandler<ThisClassName>(this,
   &ThisClassName::onChange,
   “ThisClassName::onChange”);

Sometimes, a method is available to add events, in lieu of a Delegate.

Going back to the original source
If you need to know the exact details of how a function acts, you may access the original source code. Sometimes, you may need to access the specific implementation for your operating system. It will be available in the src/vcf/[KitName]/ directory. Be sure to read the class – header and cxx file – thoroughly so that you understand everything that is going on.
Suggesting new functionality
Suppose you wish to change how a function operates, or that you wish to add new functionality to a class. You can change the source code directly to make this happen. You may want to suggest the change in the forums or talk over the change to ensure that you don’t unnecessarily break something.
Or suppose that you wish to create your own custom classes. You can inherit from a base class much as the already existing classes do. For example, you can inherit from class VCF::CustomControl to make your own control. You may need to write the paint method, much as the other controls do, to be sure that it is painted correctly.

If you run into trouble, be sure to pose a question in the forums. Chances are that someone will be able to relate to your concern.

   Comments or Suggestions?    License Information