Hide

SftBox/OCX 5.0 - Combo Box Control

Using SftBox/OCX with .NET

Adding SftBox/OCX To The Toolbox
Adding SftBox/OCX To A Project
Adding The SftHelperComponent To A Project
Preparing a Project
Special Considerations
- Indexed Properties
- Picture Properties
- Font Properties
- Color Properties
- Object vs. Interface

Adding SftBox/OCX To The Toolbox

The controls are automatically added to the Visual Studio Toolbox in the toolbox group "Softel vdm, Inc.", except for Visual Studio .NET 2002 and some Visual Studio Express Editions. For these, the controls have to be added "manually" using the simple procedure outlined in "Adding Controls To The Visual Studio Toolbox".

If you are using Visual Studio .NET 2002 or some of the Visual Studio Express Editions, please take a moment to add the controls using the simple procedure outlined in "Adding Controls To The Visual Studio Toolbox" before continuing.

Adding SftBox/OCX To A Project

The SftBox/OCX control can be added to a form, by locating the control in the toolbox group "Softel vdm, Inc.". It can be added to a form by clicking on the SftBox/OCX button of the toolbox, then clicking on the form or by dragging the SftBox/OCX button of the toolbox to the form.

Adding The SftHelperComponent To A Project

In order to be able to use .NET images, color and font properties, a small helper component must be added to each project that uses SftBox/OCX. This helper component assists in to converting OLE types to .NET types.

The SftHelperComponent control can be added to a form, by locating the control in the toolbox group "Softel vdm, Inc.". It can be added to a form by clicking on the SftHelperComponent button of the toolbox, then clicking on the form or by dragging the SftHelperComponent button of the toolbox to the form.

The component will not appear on the form, but will instead be shown as a component used by the form.

Preparing a Project

Add the following Imports and using statements to your project source file(s). This simplifies name resolution, makes most enumerated constants available and provides access to the OLECvt class.

Imports AxSftBoxLib50
Imports SftBoxLib50
Imports Softelvdm.OLEConvert

using SftBoxLib50;
using AxSftBoxLib50;
using Softelvdm.OLEConvert;

All required steps have now been completed to use SftBox/OCX.

Add the following sample code to initialize the control:

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    Dim ItemIndex As Long
    AxSftBox1.Items.TreeLineStyle = SftBoxTreeLineStyleConstants.treeLineStyleSftBoxDotted0
    AxSftBox1.ButtonStyle = SftBoxButtonStyleConstants.buttonsSftBoxAll
    ItemIndex = AxSftBox1.Items.Add("Item 1")
    ItemIndex = AxSftBox1.Items.Add("Item 2")
    AxSftBox1.get_Item(ItemIndex).Level = 1
    AxSftBox1.get_Cell(ItemIndex, 0).Image.Appearance = SftPictureImageConstants.sftImageCheckboxYes
    ItemIndex = AxSftBox1.Items.Add("Item 3")
    AxSftBox1.Items.Selection = 0
End Sub

private void Form1_Load(object sender, System.EventArgs e)
{
    int index;
    axSftBox1.Items.TreeLineStyle = SftBoxTreeLineStyleConstants.treeLineStyleSftBoxDotted0;
    axSftBox1.ButtonStyle = SftBoxButtonStyleConstants.buttonsSftBoxAll;
    index = axSftBox1.Items.Add("Item 1");
    index = axSftBox1.Items.Add("Item 2");
    axSftBox1.get_Item(index).Level = 1;
    axSftBox1.get_Cell(index,0).Image.Appearance = SftPictureImageConstants.sftImageCheckboxYes;
    index = axSftBox1.Items.Add("Item 3");
    axSftBox1.Items.Selection = 0;
}

You can run the sample application and it displays a simple combo box with three items. The second item has a check box displayed as cell graphic. By implementing the ItemClick event, the check box can be toggled. This is demonstrated in the Pictures sample.

In this example, the control is initialized at run-time using code. Of course it is also possible (and much easier) to set up all properties using the property pages. You can access the property pages by right-clicking on the control and select the Properties... entry of the popup menu.

Please note that you can right-click on a property in a Property Dialog or double-click on the description of a property to access its complete help information.

You may want to change the Style property to choose a suitable basic combo box style. Additional columns can be defined using the Columns.Count property (by displaying the Property Dialog, click on the Columns tab). Also change the Scrollbars property (Attributes tab) to "3 - Both" to display horizontal and vertical scroll bars.

This control has many properties and methods which you can use. This is a very simple example and doesn't even begin to exploit the capabilities of this control. Please take a moment to familiarize yourself with the objects offered by the SftBox/OCX control. Each object represents a specific area of the control and can be fully customized. Also make sure to run the demo which is included with this product and take a look at the included samples.

Special Considerations

When adding SftBox/OCX to a project, Visual Studio .NET generates a class wrapper to fully support an ActiveX control such as SftBox/OCX. Unfortunately, this class wrapper is slightly incomplete and generates initially unexpected function names for certain properties. However, these issues are easily resolved.

Indexed Properties

Indexed properties (i.e., properties which require additional parameters, such as an index) are converted into method calls with a get_ and set_ prefix.

For example, the Item property, which requires a subscript (or index), is used as follows:

AxSftBox1.get_Item(ItemIndex).Level = 1

All other properties with additional parameters use a get_ and set_ prefix.

The C#.NET and VB.NET syntax description of properties and methods shows the complete syntax (including get_, set_ prefix).

Picture Properties

While some graphics properties are generated to use an Image type, many properties and methods do not. These use the OLE picture type stdole.IPictureDisp instead, which cannot directly be used with an Image type. The Syntax portion of each method, property and event shows the full syntax and required picture type (Image or stdole.IPictureDisp).

The Image type can easily be converted into a stdole.IPictureDisp type using the provided class OLECvt. This class is added to each project using SftBox/OCX (see Adding SftBox/OCX To A Project above).

Public Shared Function ToIPictureDisp(ByVal i As Image) As stdole.IPictureDisp
Public Shared Function ToImage(ByVal pic As stdole.IPictureDisp) As Image

public static stdole.IPictureDisp ToIPictureDisp(Image i);
public static Image ToImage(stdole.IPictureDisp pic);

ToIPictureDisp returns a stdole.IPictureDisp pointer given an Image object.

With this helper class in place, the Cell.Image property (for example) can now be used as follows:

AxSftBox1.get_Cell(0, 0).Image.Picture = OLECvt.ToIPictureDisp(PictureBox1.Image)

axSftBox1.get_Cell(0,0).Image.Picture = OLECvt.ToIPictureDisp(pictureBox1.Image);

In this example, PictureBox1 is a PictureBox control, part of the form, containing an image.

If you are using the same image many times, make sure to convert it once only and use the saved stdole.IPictureDisp. Converting the same image many times will create multiple OLE Picture objects, which can deplete virtual storage and available systems resources.

The Syntax section of picture properties typically shows Get, Put and PutRef forms. If both Put and PutRef are available, PutRef is the preferred form as it conserves resources and assigns a picture object reference to the control. Put causes the control to completely copy the picture object.

Font Properties

While some font properties are generated to use a Font type, many properties and methods do not. These use the OLE font type stdole.IFontDisp instead, which cannot directly be used with a Font type. The Syntax portion of each method, property and event shows the full syntax and required font type (Font or stdole.IFontDisp).

The Font type can easily be converted into a stdole.IFontDisp type using the provided class OLECvt. This class is added to each project using SftBox/OCX (see Adding SftBox/OCX To A Project above).

Public Shared Function ToIFontDisp(ByVal f As Font) As stdole.IFontDisp

public static stdole.IFontDisp ToIFontDisp(Font f);

ToIFontDisp returns an stdole.IFontDisp pointer given a Font object.

With this helper class in place, the Cell.Font property (for example) can now be used as follows:

Dim NewFont As New Font("Times New Roman", 16, FontStyle.Regular)
AxSftBox1.get_Cell(ItemIndex, 0).Font = OLECvt.ToIFontDisp(NewFont)

Font NewFont = new Font("Times New Roman", 16, FontStyle.Regular);
axSftBox1.get_Cell(0, 0).Font = OLECvt.ToIFontDisp(NewFont);

If you are using the same font many times, make sure to convert it once only and use the saved stdole.IFontDisp. Converting the same font many times will create multiple OLE Font objects, which can deplete virtual storage and available systems resources.

The Syntax section of font properties typically shows Get, Put and PutRef forms. If both Put and PutRef are available, PutRef is the preferred form as it conserves resources and assigns a font object reference to the control. Any change to the font object is reflected in the control also. Put on the other hand causes the control to completely copy the font object.

Color Properties

Color properties of the SftBox object use the .NET Color structure, but all other properties and objects (such as SftBoxCell, etc.) use the native type UInt32 (uint). Converting a .NET Color structure color to a UInt32 (OLE color value) and vice versa is easily accomplished using the provided class OLECvt. This class is added to each project using Softelvdm.OLEConvert (see Preparing a Project above).

Public Shared Function ToOleColor(ByVal clr As System.Drawing.Color) As UInt32
Public Shared Function ToColor(ByVal clr As UInt32) As System.Drawing.Color

public static uint ToOleColor(System.Drawing.Color clr);
public static System.Drawing.Color ToColor(uint clr);

The valid range for a color value is 0 to 16,777,215 (&HFFFFFF). The high order byte of a number in this range equals 0; the lower 3 bytes, from least to most significant byte, determine the amount of red, green, and blue, respectively. The red, green, and blue components are each represented by a number between 0 and 255 (&HFF). If the high byte is not 0, the system colors as defined in Control Panel's settings are used. The Windows API GetSysColor defines all valid constants. Please see your development environment's documentation for applicable color constants.

The Syntax portion of each method and property shows whether a Color structure or an OLE color value is used.

Color Structure - VB

AxSftBox1.ToolTipBackColor = SystemColors.Highlight
AxSftBox1.ToolTipBackColor = Color.Red
AxSftBox1.ToolTipBackColor = OLECvt.ToColor(&HFF) ' red

Dim c As Color
c = AxSftBox1.ToolTipBackColor

Color Structure - C#

axSftBox1.ToolTipBackColor = SystemColors.Highlight;
axSftBox1.ToolTipBackColor = Color.Red;
axSftBox1.ToolTipBackColor = OLECvt.ToColor(0x00000ff); // red

Color c = axSftBox1.ToolTipBackColor;

OLE Color Value - VB

AxSftBox1.get_Cell(0, 0).BackColor = OLECvt.ToOleColor(SystemColors.Highlight)
AxSftBox1.get_Cell(0, 0).BackColor = OLECvt.ToOleColor(Color.Red)
AxSftBox1.get_Cell(0, 0).BackColor = &HFF ' red

Dim c As Color
c = OLECvt.ToColor(AxSftBox1.get_Cell(0, 0).BackColor)

OLE Color Value - C#

axSftBox1.get_Cell(0,0).BackColor = OLECvt.ToOleColor(SystemColors.Highlight);
axSftBox1.get_Cell(0,0).BackColor = OLECvt.ToOleColor(Color.Red);
axSftBox1.get_Cell(0,0).BackColor = 0x00000ff; // red

Color c = OLECvt.ToColor(axSftBox1.get_Cell(0,0).BackColor);

Object vs. Interface

The main control is represented by an object of the SftBox class, but can also be represented by its ISftBox interface. The ISftBox interface can be retrieved using the Direct property.

Certain methods and properties have different names and return types, based on how they are accessed. While (for example) an object based on the SftBox class is mostly equivalent to the ISftBox interface exposed by the control, .NET can introduce minor differences. Such differences are shown in the Syntax section of the affected methods and properties. All other classes are identical to their interfaces and no distinction is made.

The Syntax portion shows both forms, the class member and the interface method (the interface method is always marked with a Note indicator). If both forms are identical, only one entry is shown.

For example, the Cell property, when accessed through a SftBox class object, is retrieved using the get_Cell function call. When accessed directly though the ISftBox interface pointer, it is instead retrieved as an actual property named Cell. The ISftBox interface can be retrieved using the Direct property.

VB, C#

Some properties (particularly font and picture properties) may require different types. For example, the Font property accepts a System.Drawing.Font when accessed through a SftBox class object, but uses a stdole.IFontDisp interface pointer when accessed directly though the ISftBox interface pointer. stdole.IFontDisp can be provided using the OLECvt class.

Some properties or methods use different names, depending on how they are accessed. For example, the Refresh method is named CtlRefresh when accessed through a SftBox class object. When accessed directly though the ISftBox interface pointer it is named Refresh.

Other classes, such as SftBoxCell and SftBoxHeader, etc., are equivalent to their respective interfaces ISftBoxCell and ISftBoxHeader.

Documentation

DLL-Based Controls

ActiveX Controls

.NET Controls

Support