Using SftDirectory with Delphi 7 and Newer
|
|
|
|
|
|
Using SftDirectory with Delphi 7 and Newer |
This section describes how SftDirectory is typically used with Delphi 7 and other, older versions of Delphi. For information on how to use this product with more recent Delphi versions, such as Delphi 2007, please see "Using SftDirectory with Delphi 2005 And Newer".
Adding SftDirectory To Delphi
Adding SftDirectory To A Project
Special Considerations
- Picture and Font Properties
- Color Properties
- Object vs. Interface
The SftDirectory control must be added to the Component Palette before it can be used in a project.
The control is added to the Component Palette using the Component, Import ActiveX Control... menu command, which displays the following dialog:
Select the control "SftDirectory 2.5 Directory Control" by highlighting it and click Install.
In the resulting dialog you are prompted to save the definition into a new or existing package. Enter a suitable new package name or select an existing package name (such as "Borland User Components") and click OK.
Click Yes once you are prompted to build and install the new package.
Now the control has been added to the Component Palette under the ActiveX tab. If an error message is displayed instead, the product SftDirectory is not correctly installed or the control may have been unregistered accidentally. Quit Delphi and use the entry Maintenance, Register SftDirectory in Windows Registry in the SftDirectory 2.5 program group to register the control. Restart Delphi and try to add the control to the Component Palette again.
After the control has been added to the Delphi Component Palette, the Imports directory in the Delphi product location contains the file SftDirectoryLib25_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 SftDirectory.
This adds two SftDirectory controls to the Component Palette, one for most development tools and one for Internet Explorer. You could use either with Delphi. It is recommended to use the regular control.
for
use with Delphi (and other
development tools)
for
use with Internet Explorer, VBScript only
Now the control can be added to a form by clicking on the SftDirectory button of the Component Palette (ActiveX tab).
All required steps have now been completed to use SftDirectory.
For a complete example, add the following sample code to initialize the control:
procedure TForm1.FormCreate(Sender: TObject);
begin
SftDirectory1.TopMostFolder := 'C:\';
SftDirectory1.Headers.Style := headersSftDirectoryButton;
SftDirectory1.ColumnEntry[0].HeaderText := 'Folders';
end;
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.
You can run the sample application and it displays a list of folders located on your C: drive.
After adding the control to the form, right click on the control and select the Properties... entry of the popup menu. This displays the Property Dialog for the control.
Please note that you can right-click on a property or double-click on the description of a property to access its complete help information.
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 SftDirectory 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 SftDirectory to a project, Delphi generates a class wrapper to fully support an ActiveX control such as SftDirectory. After the control has been added to the Delphi Component Palette, the Imports directory in the Delphi product location contains the file SftDirectoryLib25_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 SftDirectory.
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 an TPicture type.
Some font properties use the OLE font type IFontDisp instead of the expected type TFont (e.g., Folder.Font, etc.).
However, if these properties are used, the types can easily be converted using Delphi's GetOlePicture and SetOleFont functions. The functions are shown in the "Examples (Delphi)" section of the font and picture properties.
Color properties of the SftDirectory object use the Delphi TColor type, but all other properties and objects (such as SftDirectoryFolder, 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;
SftDirectory1.BackColor := clHighlight; SftDirectory1.BackColor := clRed; SftDirectory1.BackColor := $000000FF; // red
c := SftDirectory1.BackColor;
OLE Color Value
var c : TColor;
SftDirectory1.CurrentFolder.BackColor := ColorToRGB(clHighlight); SftDirectory1.CurrentFolder.BackColor := ColorToRGB(clRed); SftDirectory1.CurrentFolder.BackColor := $000000FF; // red
c := SftDirectory1.CurrentFolder.BackColor;
The main control is represented by an object of the TSftDirectory class, but can also be represented by its ISftDirectory interface. The ISftDirectory 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 TSftDirectory class is mostly equivalent to the ISftDirectory 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 TSftDirectory class object, but uses a IFontDisp interface pointer when accessed directly though the ISftDirectory interface pointer. IFontDisp can be provided using the GetOLEFont function.