Using SftBox/OCX with Delphi 2005 And Newer
|
|
|
|
|
|
Using SftBox/OCX with Delphi 2005 And Newer |
This section describes how SftBox/OCX is typically used with Delphi 2005 and more recent Delphi versions. For information on how to use this product with older Delphi versions, such as Delphi 7, please see "Using SftBox/OCX with Delphi 7 and Newer".
Adding SftBox/OCX To Delphi
Adding SftBox/OCX To A Project
Special Considerations
- Picture Properties
- Font Properties
- Color Properties
- Object vs. Interface
The SftBox/OCX control must be added to the Tool Palette before it can be used in a project.
In order to add the control to the Tool Palette, a package has to be created containing the control.
First, using the File, Package - Delphi for Win32 menu command, create a new package using a suitable name, saving it in a permanent location.
Once the package has been created, the control can be imported into the package using the menu command Component, Import Component....
Make sure to select Import ActiveX Control from the following dialog, the click Next>>.
On the Import Component dialog, select the control "SftBox/OCX 4.5 Combo Box Control Version 4.5 by highlighting it and click Next>>. Make sure to select "SftBox/OCX 4.5 Combo Box Control Version 4.5" and not the control named "SftBox/OCX 4.5 Combo Box Control IE" as that control is specific to Internet Explorer and HTML pages. Click Next>>.
In the resulting dialog you are prompted for a Palette Page and additional information. Make sure to specify a permanent location for Unit Dir Name, so generated files are later accessible by applications. Then click Next>>.
On the following dialog, select Add unit to <yourpackagename> project, then click Finish.
Now the package is prepared and contains the required definitions for SftBox/OCX 4.5.
Finally, the package can be installed by right-clicking on the package name in the Project Manager window. Select Install from the popup menu presented. This will add the control to your Tool Palette.
Now the control can be added to a form by clicking on the SftBox/OCX button of the Tool Palette (ActiveX tab).
All required steps have now been completed to use SftBox/OCX.
Add the following sample code:
procedure TForm1.FormCreate(Sender: TObject);
var
index : Integer;
begin
SftBox1.Items.TreeLineStyle := treeLineStyleSftBoxDotted0;
SftBox1.ButtonStyle := buttonsSftBoxAll;
index := SftBox1.Items.Add('Item 1');
index := SftBox1.Items.Add('Item 2');
SftBox1.Item[index].Level := 1;
SftBox1.Cell[index,0].Image.Appearance := sftImageCheckboxYes;
index := SftBox1.Items.Add('Item 3');
SftBox1.Items.Selection := 0;
end;
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.
When adding SftBox/OCX to a project, Delphi generates a class wrapper to fully support an ActiveX control such as SftBox/OCX. After the control has been added to the Delphi Component Palette, the Imports directory in the Delphi product location contains the file SftBoxLib45_TLB.pas. This file has been generated by Delphi and contains all property and method definitions. The generated file should be used as a reference. Please note that the Pascal definitions are generated by Delphi and are not part of SftBox/OCX.
While some graphics properties are generated to use a TPicture type, many properties and methods do not. These use the OLE picture type IPictureDisp instead, which cannot directly be used with a TPicture type. The Syntax portion of each method, property and event shows the full syntax and required picture type (TPicture or IPictureDisp).
The TPicture type can easily be converted into an IPictureDisp type using Delphi's GetOlePicture function.
The Cell.Image property (for example) can now be used as follows:
uses ActiveX
. . .
var
pOLEPic : IPictureDisp;
. . .
GetOlePicture(Image1.Picture, pOLEPic);
SftBox1.Cell[0,0].Image.Picture := pOLEPic;
In this example, Image1 is an image control, part of the form, containing an image.
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.
While some font properties are generated to use a TFont type, many properties and methods do not. These use the OLE font type IFontDisp instead, which cannot directly be used with a TFont type. The Syntax portion of each method, property and event shows the full syntax and required font type (TFont or IFontDisp).
The TFont type can easily be converted into a IFontDisp type using Delphi's GetOleFont function.
The Cell.Font property (for example) can now be used as follows:
uses ActiveX
. . .
var
f : TFont;
pFont : IFontDisp;
. . .
f := TFont.Create();
f.Name := 'Times New Roman';
f.Size := 16;
GetOleFont(f, pFont);
SftBox1.Cell[0,0].Font := pFont;
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 of the SftBox object use the Delphi TColor type, but all other properties and objects (such as SftBoxCell, etc.) use the Cardinal type (an OLE color value). Converting a Delphi TColor type to a Cardinal is easily accomplished using the ColorToRGB conversion.
The valid range for a color value is 0 to 16,777,215 ($00ffffff). 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 ($FF). 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 TColor type or an OLE color of type Cardinal is used.
TColor Type
var c : TColor;
SftBox1.ToolTipBackColor := clHighlight; SftBox1.ToolTipBackColor := clRed; SftBox1.ToolTipBackColor := $000000FF; // red
c := SftBox1.ToolTipBackColor;
OLE Color Value
var c : TColor;
SftBox1.Cell[0,0].BackColor := ColorToRGB(clHighlight); SftBox1.Cell[0,0].BackColor := ColorToRGB(clRed); SftBox1.Cell[0,0].BackColor := $000000FF; // red
c := SftBox1.Cell[0,0].BackColor;
The main control is represented by an object of the TSftBox 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 TSftBox class is mostly equivalent to the ISftBox interface exposed by the control, Delphi can introduce minor differences. Such differences are shown in the Syntax section of the affected methods and properties. All other objects 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.
Some properties (particularly font and picture properties) may require different types. For example, the Font property accepts a TFont object when accessed through a TSftBox class object, but uses a IFontDisp interface pointer when accessed directly though the ISftBox interface pointer. IFontDisp can be provided using the GetOLEFont function.