Hide

SftOptions 1.0 - ActiveX Options Control

Using SftOptions with .NET

Adding SftOptions to Visual Studio .NET
Adding The SftOptions Control To A Project
Adding The SftOptsIO Control To A Project
Special Considerations
- Indexed Properties
- Picture and Font Properties
- Bitmap Transparency
Object vs. Interface

Adding SftOptions to Visual Studio .NET

The SftOptions control must be added to the Toolbox before it can be used in a project. The Toolbox normally displays the standard Visual Studio .NET controls and any other controls that have been added previously.

Using the Tools, Customize Toolbox... menu command, the Customize Toolbox dialog is displayed.

Once this dialog is displayed, click on the COM Components tab:

Select the controls "SftOptions 1.0 I/O Control" and "SftOptions 1.0 Options Control" by placing a check mark next to them and click OK.

This adds two controls to the Toolbox, the SftOptions user interface control and the SftOptsIO options I/O control.

SftOptions user interface control
SftOptsIO options I/O control

If you don't see the controls in the list or once you click OK an error message is displayed, the product SftOptions is not correctly installed or the control may have been unregistered accidentally. Quit Visual Studio .NET and use the entry Register Design Time Control in the SftOptions 1.0 program group to register the control. Restart Visual Studio .NET and try to add the control to the Toolbox again.

Adding The SftOptions Control To A Project

Once the control has been added to the Toolbox, it can be added to a form by clicking on the SftOptions button of the Toolbox.

In order to be able to use font and picture properties, a small helper class must be added to each project that uses SftOptions. This helper class OLECvt is used to convert OLE types to .NET types.

Use the Project, Add Existing Item... menu command and add the file OLEConvert.vb (VB) or OLEConvert.cs (C#) to your project. This file is located in the product directory \Program Files\Softelvdm\SftOptions 1.0\dotNET.

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 AxSftOptionsLib10
Imports SftOptionsLib10
Imports yourprojectname.OLEConvert ' substitute actual project name

using SftOptionsLib10;
using AxSftOptionsLib10;
using OLEConvert;

All required steps have now been completed to use SftOptions.

For a complete example, also add two button controls to the form, a Close button (named closeButton) and an Apply button (named applyButton).

Then, add the following sample code to initialize the control:

Private Sub AxSftOptions1_ApplyStatusChange(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles AxSftOptions1.ApplyStatusChange
	ApplyButton.Enabled = AxSftOptions1.ApplyStatus
End Sub

Private Sub ApplyButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles ApplyButton.Click
	AxSftOptions1.Save()
End Sub

Private Sub CloseButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles CloseButton.Click
	 AxSftOptions1.Save()
	 Application.Exit()
End Sub

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
	ApplyButton.Enabled = False
	AxSftOptions1.Add("", "Main", "Your first sample", SftOptionsEntryConstants.entrySftOptionsTopic, "", "", Nothing, "", "", "", "")
	AxSftOptions1.Add("Main", "Rb1", "Radio Button 1", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", Nothing, "", "", "", "")
	AxSftOptions1.Add("Main", "Rb2", "Radio Button 2", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", Nothing, "", "", "", "")
	AxSftOptions1.Add("Main", "Rb3", "Radio Button 3", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", Nothing, "", "", "", "")
	AxSftOptions1.Add("", "Cb1", "Check Box Option", SftOptionsEntryConstants.entrySftOptionsCheckBox, "", "", Nothing, "", "", "", "")
	AxSftOptions1.IO.Registry = "USR:Software\Softelvdm\TestData\FirstSample"
	AxSftOptions1.Load()
	AxSftOptions1.InitializationComplete()
End Sub

private void Form1_Load(object sender, System.EventArgs e)
{
	 applyButton.Enabled = false;
	 axSftOptions1.Add("", "Main", "Your first sample", SftOptionsEntryConstants.entrySftOptionsTopic, "", "", null, "", "", "", "");
	 axSftOptions1.Add("Main", "Rb1", "Radio Button 1", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", null, "", "", "", "");
	 axSftOptions1.Add("Main", "Rb2", "Radio Button 2", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", null, "", "", "", "");
	 axSftOptions1.Add("Main", "Rb3", "Radio Button 3", SftOptionsEntryConstants.entrySftOptionsRadioButton, "", "", null, "", "", "", "");
	 axSftOptions1.Add("", "Cb1", "Check Box Option", SftOptionsEntryConstants.entrySftOptionsCheckBox, "", "", null, "", "", "", "");
	 axSftOptions1.IO.Registry = "USR:Software\\Softelvdm\\TestData\\FirstSample";
	 axSftOptions1.Load();
	 axSftOptions1.InitializationComplete();
}

private void axSftOptions1_ApplyStatusChange(object sender, System.EventArgs e)
{
	applyButton.Enabled = axSftOptions1.ApplyStatus;
}

private void applyButton_Click(object sender, System.EventArgs e)
{
	axSftOptions1.Save();
}

private void closeButton_Click(object sender, System.EventArgs e)
{
	axSftOptions1.Save();
	Application.Exit();
}

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 option entries 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.

You can run the sample application and it displays a simple Options dialog with a few entries. After modifying some of the entries, click the Apply Button. Using Regedit you can review the registry settings at HKEY_CURRENT_USER\Software\Softelvdm\TestData\FirstSample. For example, if you select the check box in this example, the registry key "Cb1" is set to the value "1".

Adding The SftOptsIO Control To A Project

The SftOptsIO control offers simplified Registry and INI file I/O to retrieve or set option values without a user interface.

The SftOptsIO control is added to the Toolbar in the same manner as the SftOptions control (see Adding The SftOptions Control To A Project).

The SftOptsIO control can be added to a form by clicking on the SftOptsIO button of the Toolbox. This control is only visible at design-time. At run-time it is not visible to the end-user. It can only be used by the application.

The SftOptsIO control must be initialized by setting its Registry property (this could of course also be done using the property pages):

AxSftOptsIO1.Registry = "USR:Software\Softelvdm\TestData\FirstSample"

axSftOptsIO1.Registry = "USR:Software\\Softelvdm\\TestData\\FirstSample";

Retrieving an option value using the same name as used by the SftOptions control is very easy:

Dim CheckBoxValue As String
CheckBoxValue = AxSftOptsIO1.get_OptionValue("Cb1")

string CheckBoxValue;
CheckBoxValue = axSftOptsIO1.get_OptionValue("Cb1");

In this example, the CheckBoxValue variable would contain "1" if the option is selected.

The SftOptions 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 SftOptions 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 SftOptions to a project, Visual Studio .NET generates a class wrapper to fully support an ActiveX control such as SftOptions. 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 OptionValue property, which requires a subscript (or index), is used as follows:

CheckBoxValue = axSftOptsIO1.get_OptionValue("Cb1");

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

The Syntax portion of each method, property and event shows the full syntax, including any prefix (such as get_ and set_, etc.).

Picture and Font Properties

While some graphics properties are generated to use an Image type, many properties do not (such as Entry.Picture, etc.). These use the OLE picture type stdole.IPictureDisp instead, which cannot directly be used with an Image type.

Some font properties use the OLE font type stdole.IFontDisp instead of the expected type System.Drawing.Font (e.g., Header.Font, etc.).

However, if these properties are used, the types can be easily converted using the provided class OLECvt. This class is added to each project using SftOptions (see Adding The SftOptions Control To A Project).

public static stdole.IFontDisp ToOLE_IFontDisp(Font f);

public static stdole.IPictureDisp ToOLE_IPictureDisp(Image i);

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

Public Shared Function ToOLE_IPictureDisp(ByVal i As Image) As stdole.IPictureDisp

ToOLE_IFontDisp returns an stdole.IFontDisp pointer given a Font object. ToOLE_IPictureDisp returns a stdole.IPictureDisp pointer given an Image object.

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

AxSftOptions1.get_Entry("EntryName").Picture = OLECvt.ToOLE_IPictureDisp(pictureBox1.Image)

Bitmap Transparency

Defining images at run-time using an Image control is not compatible with bitmap transparency. While an Image control can be used, even with GIF, JPEG, etc. which can define transparency, bitmap transparency is not available. If bitmaps must be used, an ImageList control with the correct TransparentColor setting has to be used instead.

However, any bitmap that is loaded at design-time using the SftOptions property pages is fully supported for bitmap transparency.

Object vs. Interface

The main control is represented by an object of the SftOptions class, but can also be represented by its ISftOptions interface. The ISftOptions 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 SftOptions class is mostly equivalent to the ISftOptions 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 Entry property, when accessed through a SftOptions class object, is retrieved using the get_Entry function call. When accessed directly though the ISftOptions interface pointer, it is instead retrieved as an actual property named Entry. The ISftOptions 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 SftOptions class object, but uses a stdole.IFontDisp interface pointer when accessed directly though the ISftOptions 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 SftOptions class object. When accessed directly though the ISftOptions interface pointer it is named Refresh.

Other classes, such as SftOptionsEntry and SftOptionsHeader, make no distinction between the class and interface. The classes SftOptionsEntry and SftOptionsHeader are equivalent to their respective interfaces ISftOptionsEntry and ISftOptionsHeader.

Documentation

DLL-Based Controls

ActiveX Controls

.NET Controls

Support