List VCD Properties

This chapter shows you how to retrieve all properties of a video capture device using the new VCD property interface.

All properties that are retrieved from the video capture device are displayed in a TreeView. The TreeView was chosen, because it perfectly matches the organization of the properties, since they establish a tree structure. The root of the tree is the VCDPropertyItems collection. The collection contains all VCDPropertyItems that are provided by the current video capture device. Every VCDPropertyItem has one or more VCDPropertyElements, which have one or more VCDPropertyInterfaces that are used to access the property.

The source code for this sample program is contained in the samples\VB6\List VCD Properties sample source directory.

Setting up the Project

Create a new project and add IC Imaging Control to the form. Before you run the program, select the video device, input and video format as shown in the First Steps in Visual Basic 6 chapter. Alternatively, run the program without selecting a device. In this case, the program shows the device selection dialog provided by IC Imaging Control. If you close this dialog without making a selection, the program displays an error message and terminate.

This sample uses the module VCDPropertyID.bas and some user controls. They can be found in the directory samples\VB6\common. Before you can use them, you have to add them to the project. To add the module, select Project from the menu and then choose Add Module. In the dialog click on the Existing tab and browse to the samples\VB6\common folder. Select VCDPropertyID.bas and click Open. To include the user controls, select Project from the menu and choose Add User Control. Click on the Existing tab and browse to the samples\VB6\common folder. Select AbsValSlider.ctl and click the Open button. The other user controls, namely PushButton.ctl, RangeSlider.ctl, StringCombo.ctl and Switch.ctl are included the same way. Now you are ready to use the user controls.

Add 2 buttons to the form, name them btnSelectDevice and btnShowPage and label them Select Device and Show Property Page. They will be used to show the device settings and property page dialog provided by IC Imaging Control. Now add one instance of every user control to the form. Give them the same name as the control itself, e.g. name the AbsValSlider AbsValSlider. Each of the user controls represents a special type of interface derived from VCDPropertyInterface.

Now add an image list and a tree view to the form. The image list will contain the graphical elements that are used to visualize the tree. Therefore, it is very important to add the image list before the tree view, because otherwise it is not possible to bind the image list to the tree view. Name the image list TreeImageList and the tree view Tree. Using the right mouse button, click on the image list and select Properties from the context menu. Under the General tab choose the 16x16 format and make sure that UseMaskColor is checked. Now switch to the Color tab and set both, the Back- and the MaskColor to white. Finally switch to the "Images" tab and add the following images in the given order: slider.bmp, switch.bmp, button.bmp, combo.bmp, value.bmp, auto.bmp and item.bmp. All these bitmap files can be found in the directory of this sample. Now, the image list can be added to the tree view. To do so, right click button, on the tree view. Select Properties from the context menu and select the General tab in the properties dialog. Change the Style to 5 - tvwTreelinesPictureText and set ImageList to TreeImageList. This will bind the image list to the tree view.

Adding Functionality

Add the Click events for the Select Device and Show Property Page buttons and insert the following code:

Now add a Form_Load event and insert the code below:

As you can see in the code above, the btnSelectDevice_Click and the Form_Load event both call the procedures ListAllPropertyItems and QueryVCDProperties. QueryVCDProperties fills the tree view with the properties of the current video capture device. Additionally, ListAllPropertyItems prints the tree structure of those properties to the debug output window. The debug output shows you the pure organization of the VCDProperties without taking care of other aspects like controls. Let's have a look at the code for the procedure ListAllPropertyItems:

The three nested For Each loops in the code above reflects the tree structure of the VCDProperties. The first loop covers all available VCDPropertyItems and prints their names to the debug output. For each item, the second loop prints out all available VCDPropertyElements. The third loop prints out all types of interfaces that the element provides. Please note that the interfaces are sorted according to their extend of detail. The most detailed one is the "AbsoluteValue" interface, followed by the "MapStrings" interface. "Switch" and "Button" are detailed interfaces providing simple functionality: toggle On/Off, trigger. The "Range" interface is the most generic one, but does not provide a meaning for the values that represents. For example the "Brightness" range may be from 0 to 255. There is no way to tell, whether 0 or 255 is the maximum brightness value.

Now let's have a look at the QueryVCDProperties procedure. This procedure fills the tree view with appropriate values. The code for this procedure looks as follows:

The procedure above clears the tree view and creates a new root node. The root node is labeled VCDPropertyItems. Then the procedure QueryVCDPropertyItems inserts all available property items. This procedure looks as follows:

QueryVCDPropertyItems iterates through all available property items. For every item, it creates a new node. All of these nodes are direct children of the root node. The name of the VCDPropertyItem (e.g. "Brightness", "Gain" or "Exposure") is assigned to the Text property of the node. An empty string is assigned to the key property of the node. Then, QueryVCDPropertyElements is called for the new node. QueryVCDPropertyElements looks as follows:

QueryVCDPropertyElements iterates through all available elements. For every element, it creates a new node. All of these nodes are children of the node which represents the VCDPropertyItem to which these VCDPropertyElements belong. The Select block determines the appropriate graphical tree element for the node and sets its base name, depending on the type of the element. The name of the VCDPropertyElement (e.g. "Value", "Auto" or "Enable") is added to the base name and then assigned to the Text property of the node. An empty string is assigned to the key property of the node. Then, QueryVCDPropertyInterface is called for the new node. QueryVCDPropertyInterface looks as follows:

QueryVCDPropertyInterface iterates through all available interfaces of an element. For every interface, it creates a new node. All of these nodes are children of the node which represents the VCDPropertyElement to which these VCDPropertyInterface belong. The Select block determines the appropriate graphical tree element for the node and sets its name, depending on the type of the interface. The name is then assigned to the Text property of the node. The interface path that consists of an itemID, an elementID and an interfaceID is assigned to the key property of the node. The interface node makes up a leaf of the tree.

Accessing and Manipulating a VCDProperty

Now that the tree is built, we want to access the properties. To do this, add a NodeClick event for the tree view and insert the following code:

Now it becomes clear, why the keys of the interface nodes store the interface path. If you click an interface node, the appropriate control should appear on the form, so that you can manipulate the setting of the property. To get the correct interface, the method FindInterface is used. FindInterface needs the interface path (or GUID) as a parameter. The key of an interface node represents this interface path (or GUID). The Select block maps the appropriate user control to the desired interface and calls the respective "Show%%" procedure. These procedures set the Visible property of the user control to True, so that it can be used to manipulate the setting of the specified property. The ShowAbsoluteValueControl procedure for example is implemented as follows:

The appropriate procedures for the other user controls are implemented in the same way.

<< Programmer's Guide