Overview

This chapter and the next two cover building components. Component development is one of the most important technologies in contemporary programming, and no C++

environment on the market makes them easier to use or to create than BCB.

You build three types of components in this chapter:

• Descendants that change default settings in existing components.

  　

• Descendants that add features to existing components.

  　

• Tools built on top of abstract component base classes such as TWinControl, TCustomControl, TComponent, and TGraphicControl. You make descendants from these classes if you want to build your own components from the bottom up.

This chapter presents material on building visual components, Chapter 23 focuses on building unique components that are polymorphic, and Chapter 24 explores building nonvisual components. Nonvisual components descend directly from TComponent and appear on the form only at design time.

More specifically, the components built in this chapter fall into two categories:

• The first group is a set of TEdit, TLabel, and TPanel descendants that show how to change default colors, captions, and fonts. This section of the chapter also covers building components that consist of several different child components; that is, this section shows how to group components together to form new components. The specific example included with this book shows a panel that comes with two radio buttons.

  　

• The second tool is a clock component that can be dropped on a form, and stopped and started at will.

In Chapter 24, you will see a nonvisual control that knows how to iterate through subdirectories. You can use it to build programs that search for files, delete all files with a certain extension, and so on.

Besides components, this chapter also briefly covers two related topics: Property editors are used to edit the properties of components. The classic examples are the common dialogs that pop up when you edit the Color or Font properties that belong to most visible components. The drop-down lists and string-editing capabilities found in the Object Inspector are also property editors.

Component editors are associated not with a single property, but with an entire component. An example is the Fields Editor used with the TTable and TQuery components.

The property editors and component editors are related to a broader topic called the Tools API. The Tools API consists of a series of interfaces to the BCB IDE that allows you to build experts, interfaces to version control systems, and similar utilities. The API for property editors and component editors and the Tools API are defined in files with names that end in INTF, which stands for "Interface." For example, the TPropertyEditor class is found in DSGNINTF.HPP.

Components, properties, and events, along with their associated component editors and property editors are perhaps the most important topics in BCB programming. In many ways, this chapter and the next two are the keystones around which this entire book has been designed.

The source for all the components created in this chapter is found in the Chap22

and Utils directories on the CD that accompanies this book. The source on the CD compiles correctly, and all of these components work as described in this chapter. Because of the default behavior of the C++ linker, you might have to run a program called BuildObjs before installing some of these components. This program is in the Utils directory. A description of this program is in the readme file on the CD. If you have any trouble with the code in this chapter, turn to the

readme!

Component Theory

BCB components have three outstanding strengths:

• They are native components, built in BCB's language, without recourse to a complicated API such as OLE. You therefore can write, debug, and test your components using the same rules you use in standard BCB programs. You don't need to learn a whole new programming model, as you do when you write ActiveX controls. In short, writing a BCB component is about 10 times easier than writing an OCX or VBX component.

  　

• They are fully object-oriented, which means you can easily change or enhance existing components by creating descendant objects.

  　

• They are small, fast, and light, and can be linked directly into your executables. Native BCB components are orders of magnitude smaller than most ActiveX controls, and they link directly into your programs. In particular, a native BCB component is just a particular kind of object, so it links into your programs naturally, just as any other object would, without any handwaving.

Few people would claim that VBXs aren't groundbreaking, that ActiveX controls aren't going to be very important, or that OLE2 is not an enormously promising architecture. However, BCB components are relatively easy to create and come in a light, easy-to-use package. You can create BCB components that do nearly anything, from serial communications to database links to multimedia. These capabilities give BCB a big advantage over other tools that force you to use large, complex, and unwieldy component models.

---

NOTE: Most publicly available components cost in the range of $50 to $150. Many of these tools encapsulate functionality that might cost tens of thousands of dollars to produce in-house. For example, a good communication library might take a year to build. However, if a company can sell the library in volume, it can afford to charge $100 or $200 for the same product. That's a real bargain. And most of these tools are easy to use. Building components is a great way for relatively small third-party companies to make money, and buying components is a great way to save time on big projects. These ground-breaking tools are changing everything about the way programs are constructed.

---

　

BCB components are flexible tools easily built by anyone who knows OOP and the BCB language. In this package, you have explanations detailing all the prerequisite knowledge that component builders need, from a description of BCB itself, through a description of its language, and on to an overview of its implementation of OOP. From this foundation, you can easily begin building your own components.

Creating Descendants of an Existing Component

In this section, you will see how to create a series of custom TEdit, TPanel, and TLabel controls. The changes made to the standard TEdit and TLabel components involve tweaking their colors, as well as their fonts' colors, names, sizes, and styles. The goal is to show how to create a suite of custom controls that you can place on the Component Palette and use for special effects, or to define the look and feel of a certain set of applications belonging to a particular department or company.

With projects like this, starting with one simple example is best, and then you can move on to more complex components. Listings 22.1 through 22.3 contain a sample component and a program that allows you to test the new component before you place it on the Component Palette. The component is stored in a module called Unleash1. The Unleash1 source code is the first version of a unit that will be expanded later in the chapter. Scan through it and check out its basic structure. Once it is clear to you how to create and test the component, I will briefly discuss how to place it on the Component Palette.

Listing 22.1. The header file for a simple component descending from TEdit.

#endif

Listing 22.2. The code for a simple component descending from TEdit.

//----------------------------------

Listing 22.3. The main form for the TestUnleash1 program serves as a test bed for the Unleash1 unit.

}

This program is designed to test the TSmallEdit control before you add it to the Component Palette. The test program has a single button that responds to clicks. If you click the program's button, the new component appears at the top left of the form, as shown in Figure 22.1. Once again, the goal of the program is to make sure the new edit control is meeting your expectations before trying to compile it as a component.

Figure 22.1.At runtime, the TestUnleash1 main form features a TButton and a custom Edit control called TSmallEdit.

You can easily create this unit, test it, and compile it as a component that's merged in with the rest of the tools on the Component Palette. To start creating the component, choose File | New and select Component from the first page of the Object Repository. The dialog shown in Figure 22.2 then appears.

Figure 22.2.The Component Wizard dialog.

The Component Wizard is a simple code generator, of the type that any reader of this book who has made it this far should be able to write in an hour or two. It simply asks you for the name of the component you want to create and to then select its parent from a drop-down list. After you define the type of tool you want to create, you can select the page in the Component Palette where you want it to reside. You should fill in the blanks with the following information:

Class Name: TSmallEdit

For your efforts, the Component Expert churns out the code in Listings 22.4 and 22.5, in which everything is boilerplate except for the first line of the class declaration, the constructor, and the parameters passed to the RegisterComponents method.

Listing 22.4. The header produced by the standard boilerplate output of the Component Expert.

#endif

Listing 22.5. The implementation of TSmallEdit as produced by the standard boilerplate output of the Component Expert.

//----------------------------------

The Component Expert starts by giving you #include directives designed to cover most of the bases you are likely to touch in a standard component:

The next step is to give you a basic class declaration, in which the name and parent are filled in with the choices you specified in the Component Expert dialog. All this business about the scoping directives is just for your convenience, and you can delete any portion of it that you don't think you'll need.

class TSmallEdit : public TEdit

Before you can place a component on the Component Palette, you first must register it with the system:

void __fastcall Register()

Registering a class makes it known to the BCB Component Palette when the unit is compiled into the BCB component library. The Register procedure has no impact on programs compiled with this unit. Unless your program calls the Register procedure (which it should never do), the code for the Register procedure will never execute.

This method first creates an array consisting of the types of components you want to register. Recall that __classid is one of the new pieces of syntax added to the language. It is dis- cussed in Chapter 2, "Basic Facts About C++Builder." After creating the array, you call RegisterComponents, which takes the name of the page you want to use in the Component Palette in the first parameter, the array of metaclasses in the second parameter, and the size of the array in the third parameter. If the page does not exist, it will be created automatically. Here is the declaration for RegisterComponents:

extern void __fastcall RegisterComponents(const System::AnsiString Page,

Recall that TMetaClass is declared in SysDefs.h and that it represents a subset of TObject. You can get the metaclass of a VCL object by calling the object's ClassType method.

If you look back at the source for the whole project, you will see that the Register method is placed in its own namespace. This happens because multiple declarations for methods with that name will occur throughout your projects and, indeed, inside BCB itself. As a result, the compiler's need for order must be satiated with a few discreetly placed namespaces. This whole subject will come up again in just a moment, when I talk about recompiling CmpLib32.ccl.

After using the Component Expert, you should save the project. Proceed as you normally would by creating a directory for the project and saving Main.pas and TestUnleash1.cpp inside it. You should not save the new unit that you created into the same directory, however, but you should place it in the Utils directory where you store files such as CodeBox. This code is now going to come into play as part of your system, and as such you want a single path that leads to all related files of this type. If you have all your components in different subdirectories, you will end up with a source path that is long and unwieldy.

---

NOTE: ValidCtrCheck() verifies that creating an instance of the object at compile time is possible. If you forget to override a pure virtual function, the compilation of the component will fail because the statement "new foo(0)" is now invalid. You can test this by creating a component derived from TCustomGrid (an abstract class) and installing it without doing any work to change the object.

Because ValidCtrCheck is inline and never called, no code will be generated--so there is no runtime cost.

---

　

The goal of this project is to give a component of type TEdit a new set of default behaviors so that it starts out with certain colors and certain fonts. To do so, you need to override the Create method and change the fonts inside it. The method declaration itself appears automatically:

class TSmallEdit : public TEdit

Notice that in the preceding declaration I have removed the private,

__published, and protected directives created by the Component Expert. Making this change is neither here nor there; I do it just to keep the amount of code you need to look at as small as possible.

The Create method for TSmallEdit is declared as public. If you think about the process of creating a component dynamically, you will see that the Create method has to be public. This is one method that must be exposed. Like all VCL constructors, TSmallEdit is declared virtual and __fastcall.

Create is passed a single parameter of type TComponent, which is a base class that encapsulates the minimum functionality needed to be an owner of another component and to place a component on the Component Palette. In particular, whatever form you place a component on usually will be the owner of that component.

The implementation of the Create method is simple:

__fastcall TSmallEdit::TSmallEdit(TComponent* Owner)

The code first calls Create, passing in the variable AOwner. As I stated previously, the owner of a component will often, though not always, be the form on which the component is to be displayed. In other words, the user will drop the component onto a form, and that form will become the owner of the component. In such a case, AOwner is a variable that points to the form. The VCL uses it to initialize the Owner property, which is one of the fields of all components.

The next step is to define the color and font that you want to use, with Font->Style defined as follows:

enum TFontStyle { fsBold, fsItalic, fsUnderline, fsStrikeOut };

---

NOTE: Don't let all this gobbledygook confuse you! All that occurs in this declaration is that a simple enum type is declared, and then you see a Set declaration for the type that ranges from a low value of fsBold to a high value of fsStrikeOut. Piece of cake!

---

　

If you want to add the underline and bold style to the text in the edit control, write the following:

Font->Style = TFontStyles << fsBold << fsUnderline;

If you then want to add the italic style at runtime, write this:

Font->Style = Font->Style << fsItalic;

To remove the style, write this line:

Font->Style = Font->Style >> fsItalic;

At this stage, the code is ready to go on the Component Palette. However, most of the time when you write components, you should test them first to see whether they work.

Even on a fast machine, the process of recompiling CmpLib32.ccl and adding your component to the Component Palette takes between 10 seconds and 2 minutes. Perhaps I'm a bit impatient, but that's a little too long a wait for me if all I need to tweak is a few aspects of my code. As a result, I test things first in a small program and then add the component to the IDE.

To test the new class, drop a button on the program's main form, and create an OnClick handler:

void __fastcall TForm1::Button1Click(TObject *Sender)

Don't forget to use View | Project Manager and add the unit to the project. This ensures that the USEUNIT macro is placed in your project source.

This code creates the component and shows it on the main form. this, of course, is the way that TForm1 refers to itself from inside one of its own methods. The owner of the new component is Form1, which will be responsible for disposing of the component when finished with it. This process happens automatically. You never need to worry about disposing of a visible component shown on a form.

The parent of the component is also Form1. The Parent variable is used by Windows when it is trying to decide how to display the form on the screen. If you place a panel on a form and drop a button on the panel, the owner of that

button is the form, but the parent is the panel. Ownership determines when and how the component is deallocated, and parental relationships determine where and how the component is displayed. Ownership is fundamentally a BCB issue, whereas parental

relationships are primarily concerns of Windows.

---

NOTE: The next paragraph in this section explains how to recompile CmpLib32.ccl. Remember that you should always keep a backup copy of CmpLib32.ccl on your hard drive. CmpLib32.ccl is stored in the ..\CBUILDER\BIN directory. Beneath this directory, I have created another directory called BACK where I keep a backup copy of CmpLib32.ccl. If worse comes to worst, you can always copy the version of CmpLib32.ccl on your installation CD back into the BIN subdirectory.

My personal experience is that everyone, sooner or later, makes a tasty Mulligan's Stew out of a copy of CmpLib32.ccl. The worst-case scenario is that you're on the road when this mess happens, and that you don't have access to your installation disk. Don't let this situation happen to you. Keep a backup copy of CmpLib32.ccl on your hard drive at all times!
?FIGURE 17.16. Creating SQL selection criteria in ReportSmith. CCL stands for C++Builder Component Library.

---

　

After you run the program and test the component, the next step is to put it up on the Component Palette. To do so, choose Components | Install and then click the Add button. Browse through the directories until you find Unleash1.Cpp, select OK, and then close the Install Components dialog by clicking OK. At this point, a project called CmpLib32.cpp is compiled. This project creates a huge DLL called CmpLib32.ccl, which contains all the components in the Component Palette, all the component and property editors associated with those components, the form designer part of the IDE, the experts, and other support modules.

After CmpLib32.ccl finishes recompiling, you can start a new project, turn to the newly created Unleash page, and drop your new component onto a form. It will have a blue background, default to Times New Roman, and have its font style set to bold and its font color to yellow. Notice that all the properties of TEdit have been inherited by TSmallEdit. That's OOP in action. You can see an example of the form that uses this control in Figure 22.3.

Figure 22.3.Using the TSmallEdit control on a standard VCL form.

Understanding the Project Source for CmpLib32

You can save the CmpLib32.cpp file used during compilation of CmpLib32.ccl to disk if you choose Options | Environment | Library | Save Library Source Code. After choosing this option and recompiling CmpLib32.ccl, you can go to the \CBUILDER\BIN directory and view your copy of CmpLib32.cpp.

Here is an example of the source code produced by the IDE for use when compiling CmpLib32.ccl:

To understand the unit, start at the bottom, with the DllEntryPoint function. This routine is called when Windows first loads the DLL into memory and each time it is accessed by a BCB thread. ProcessAttachTLS and related routines are all part of the internal system code. This code is none of our business, so we can safely "pay no attention to the man behind the curtain."

InitCmpLib calls the Register method for each of the modules used in the project. If you look at the bottom of the list, you will see where the

Register method for Unleash1 is listed. You might think that we don't have enough calls in this section to create the over 100 components found on the Component Palette. The issue here is that some of the Register methods

register 20 or 30 different components at one shot. Here, for example, is the Register method from StdReg.pas:

procedure Register;

Sorry about bringing Object Pascal code into the book again, but I think it helps to see what is happening behind the scenes in cases like this one. I will talk about RegisterPropertyEditor later in this chapter. Notice that the VCL calls

RegisterComponents just as you do. When you recompile Cmplib, you are rebuilding part of BCB itself and simultaneously redefining the way the VCL works.

The DCR files listed in CmpLib32.cpp are a series of standard Windows resources that contain bitmaps that are placed in the Component Palette. The bitmaps representing each component come from here. In the case of TSmallEdit, it descends from TEdit, and so it inherits TEdit's bitmap, unless I create a DCR file for the component. I will create and discuss DCR files later in this chapter and in the next chapter.

The key point to grasp about DCR files is that they are standard Windows resources containing a bitmap. You can build them with the Image Editor that ships with BCB.

Extending the Unleash Unit

In the second version of the Unleash unit, a new edit control is added, along with two labels and two panels. The additional edits and labels show how quickly you can build on an idea or object when you understand where you're headed. One of the panels shows how you can get rid of the annoying label that always shows up in the middle of a panel, and the other shows a preliminary take on how you can create a single component that contains other components. Specifically, it shows how to create a panel that comes already equipped with two radio buttons.

The code for the new version of the Unleash2.cpp unit is shown in Listings 22.6 and 22.7, and its test bed appears in Listing 22.8. Run TestBed first, and make sure the new components are working correctly. If all is well, then add the new components to the Component Palette.

If you have two units on your system, both of which contain instances of TSmallEdit, uninstalling the first instance before trying to install the new instance is probably best. For instance, you may have two files on your system, one called Unleash1.cpp and the second called Unleash2.cpp. Both might contain an instance of TSmallEdit. Under such circumstances, it's best to use Component | Install | Remove to remove the first version of TSmallEdit before replacing it with a second version. A second alternative is just to rename the second version of the component to TSmallEditTwo, which is what I do with the source found on the CD that accompanies this book. If you have only one version of TSmallEdit, and you just want to update it, you don't need to remove the first instance before installing the updated instance.

Listing 22.6. The header for the second version of the

Unleash2.cpp unit contains a class that comes equipped with two radio buttons.

#endif

Listing 22.7. The second version of the Unleash unit, called Unleash2, contains a class that comes equipped with two radio buttons.

//----------------------------------

Listing 22.8. The test bed for the Unleash2 unit.

}

You can find this program in the directory called TestUnleash2 on the CD that accompanies this book. Figure 22.4 shows the program in action.

Figure 22.4.The TestUnleash2 program demonstrates how to test a series of components before placing them on the Component Palette.

After you've created a component that does something you like, you can easily create children of it. Class TBigEdit descends from TSmallEditTwo:

class TBigEdit : public TSmallEditTwo

It inherits its font nearly unchanged from TSmallEditTwo, except that it sets Font->Size to 24, a hefty figure that helps the control live up to its name. This elegant syntax is a good example of how OOP can save you time and trouble while still allowing you to write clear code.

The label controls shown in this code work in exactly the same way the edit controls do, except that they descend from TLabel rather than from TEdit.

The TEmptyPanel component rectifies one of the petty issues that sometimes annoys me: Every time you put down a panel, it gets a caption. Most of the time, the first thing you do is delete the caption so that you can place other controls on it without creating a mess!

At first, it would appear that you can change the caption of TPanel by overriding its constructor. All you would need to do is set the Caption property to an empty string:

class TEmptyPanel : public TPanel

This code should work correctly, but in the first version of C++Builder the caption does not get changed. There are two interesting workarounds for this problem that illustrate interesting facts about the VCL. The first workaround is to override the Loaded method:

void __fastcall TEmptyPanel::Loaded(void)

The code shown in this overridden Loaded method will change the caption of the component at runtime, but not at design time. The Loaded method is called after a component has been loaded from a stream but before it is shown to the user. The method exists so that you can set the value of properties that rely on the value of other properties.

A second technique involves overriding the SetParent method:

void __fastcall TEmptyPanel::SetParent(TWinControl *AParent)

This will fix the problem at both design time and at runtime.

In this example, I am not using SetParent for its intended purpose. To understand the method's real purpose, you need to remember that a component is always shown on the surface of its parent. The primary purpose of the SetParent method is to give you a chance to change the parent of a component just as it is being made visible to the user. This allows you to store a component in a DFM file with one parent, and to change that parent at runtime. It's unlikely you will ever need to change the parent of a component, but there are occasions when it is useful, and so the VCL gives you that ability.

It is obviously useful to know that you can override the SetParent and

Loaded methods in order to change properties at two different stages in the process of allocating memory for a component. You should note, however, that in this case it is a bit strange that you have to do so, because merely overriding the constructor should have turned the trick.

The last new component in Unleash2.cpp enables you to drop down a panel that comes equipped with two radio buttons. This way, you can make a single control out of a set of components that are often combined.

You could create other controls that contain three, four, or more radio buttons. Or you could even create a panel that would populate itself with a specific number of radio buttons.

The declaration for this new radio button is fairly simple:

class TRadio2Panel : public TEmptyPanel

The actual radio buttons themselves are declared as private data, and access to them is given by the Radio1 and Radio2 properties.

Write access to the radio button properties is not needed because you can modify without it. The following statement performs one read of RP->Radio1 and one write to the Caption property of that radio button:

P->Radio1->Caption = "Control one";

You don't want write access to the properties either because that would allow the user to assign them garbage (or NULL).

The constructor for the Radio2Panel begins by setting the width and height of the panel:

__fastcall TRadio2Panel::TRadio2Panel(TComponent *Owner)

The next step is to create the first radio button. Notice that the code passes

this as the owner and sets the parent to the panel itself. The rest of the code in the Create method is too trivial to merit comment.

Under some circumstances, you may need to register TRadioButton:

TComponentClass classes[1]={__classid(TRadioButton)};

This event would normally occur when you drop a component on a form. However, in this case a TRadioButton is not necessarily ever dropped explicitly on a form. As a result, the safe thing to do is register the component, possibly in the constructor for the class.

When you're ready to test the TRadio2Panel object, you can write the following code in the test-bed program to take it through its paces:

TRadio2Panel *P = new TRadio2Panel(this);

Note that each radio button that belongs to the panel acts exactly as you would expect a normal radio button to act, except you have to qualify it differently before you access it. I use the TextWidth property of Canvas to discover the width needed for the string, and then add 20 to take into account the button itself.

---

NOTE: If you want, you can surface Radio1 and Radio2 in the Object Inspecter as published properties of TRadio2Panel. However, when you first do so, they will have no property editors available because BCB has no built-in property editors for TRadioButtons. To build your own, you can refer to the DsgnIntf.pas unit that ships with BCB, as well as the upcoming discussion of the Clock component and the Tools API.

---

　

The following code is used to register the objects in the Unleash2 unit so they can be placed on the Component Palette:

namespace Unleash2

Notice how I register multiple components in this example at once by creating an array of type TComponentClass. After registering the objects, you can place them on the Component Palette and use them in a program, as shown in Figures 22.5 and 22.6.

Figure 22.5.The main form of a VCL application that uses some of the components from the Unleash2 unit.

Figure 22.6.The new components on the Component Palette, along with some other controls created in later chapters.

---

NOTE: To create custom bitmaps for components shown on the Component Palette, you need to create a standard resource with the extension .dcr. The Image Editor component that ships with BCB is designed to handle this chore.

I ship a few DCR files in the Utils directory on the CD that accompanies this book. You can study them to see how to proceed, or you can find the DCR files for other components that ship with BCB. To look at a DCR file, open it with the Image Editor.

The DCR file should have the name of the unit that contains the controls, and each small 24x24 bitmap that you create in the file should be named after the component to which it belongs. For example, the DCR file for this unit would be called Unleash2.dcr, and the bitmaps inside it would have names like TBIGEDIT and TEMPTYPANEL.
I will discuss this subject in more depth later in this chapter.

---

　

Before closing this section, I'd like to add some notes about how BCB handles streaming chores. The good news is that most of the time you don't have to concern yourself with streaming at all. BCB handles most streaming chores automatically. In particular, it will automatically stream published properties that are simple types. Only under limited circumstances must you explicitly stream the fields of your object.

If a property type is a TComponent or descendant, the streaming system assumes it must create an instance of that type when reading it in. If a property type is TPersistent but not TComponent, the streaming system assumes it is supposed to use the existing instance available through the property and read values into that instance's properties.

The Object Inspector knows to expand the properties of TPersistent but not TComponent descendants. This expansion is not done for TComponent descendants because they are likely to have a lot more properties, which would make navigating the Object Inspector difficult.

Building Components from Scratch

In the previous examples, you created descendants of existing components. Now you're ready to see how to create entirely new components. The main idea to grasp here is that you can make a new component descend from three abstract objects. The term "abstract" can have a specific technical meaning, but here I'm using it to refer to any object that exists only so that you can create descendants of it. In short, the following three objects have built-in functionality that all components need to access, but you would never want to instantiate an instance of any of them:

• TWinControl and TCustomControl are base classes that can be used to produce a Windows control that can receive input focus and that has a standard Windows handle that can be passed to API calls. TWinControl descendants exist inside their own window. TEdit, TListBox, TTabbedNotebook, TNotebook, and TPanel are all examples of this type of control. Most components of this type actually descend from TCustomControl, which is in turn a descendant of TWinControl. The distinction between the two classes is that TCustomControl has a Paint method, and TWinControl does not. If you want to draw the display of your new component, you should make it inherit from TCustomControl. If the object already knows how to draw itself, inherit from TWinControl.

  　

• TGraphicControl is for components that don't need to receive input focus, don't need to contain other components, and don't need a handle. These controls draw themselves directly on their parent's surface, thereby saving Windows resources. Not having a window handle eliminates a lot of Windows management overhead, and that translates into faster display updates. In short, TGraphicControls exist inside their parent's window. They use their parent's handle and their parent's device context. They still have Handle and Canvas fields that you can access, but they actually belong to their parent. TLabel and TShape objects are examples of this type of component. The drawback with this system is that the component can never get the focus!

  　

• TComponent enables you to create nonvisual components. If you want to make a tool such as the TTable, TQuery, TOpenDialog, or TTimer devices, this is the place to start. You can place these components on the Component Palette, but they perform some internal function that you access through code instead of appearing to the user at runtime. A tool such as TOpenDialog can pop up a dialog, but the component itself remains invisible.

Create a TWinControl or TCustomControl descendant whenever the user needs to interact directly with a visible control. If the user doesn't need to interact with a visible component, create a TGraphicControl descendant.

To get a handle on the issues involved here, you should place a TShape or TLabel control on a form and run the program. Clicking or attempting to type on these controls produces no noticeable result. These components don't ever receive the focus. Now place a TEdit control on the form. It responds to mouse clicks, gets the focus, and you can type in it. TEdit controls are descendants of TWinControl, and TShape is a descendant of TGraphicControl.

---

NOTE: I should add one caveat to the rules about TGraphicControl explained previously. In one limited sense, the user can interact with a TGraphicControl. For example, these controls do receive mouse messages, and you can set the mouse cursor when the mouse flies over them. They just can't receive keyboard input focus. If an object can't receive focus, it usually seems inert to the user.

---

　

If you're having trouble deciding whether you want to make descendants from TWinControl or TCustomControl, you should always go with TCustomControl. It has a real Paint method and some other functionality that is useful when creating a component of your own. If you want to wrap an existing Windows control inside a VCL object, you should start with TWinControl. Most BCB components that follow this path begin by creating intermediate custom objects, so the hierarchy of TEdit looks like this:

TWinControl

The hierarchy of TListBox looks like this:

TWinControl

Of course, BCB wraps all the major Windows controls for you, so you won't need to perform this operation unless you're working with a specialized third-party control of some sort.

Following are the declarations for TGraphicControl and TCustomControl, as they appear in Controls.hpp:

class __declspec(delphiclass) TGraphicControl;

You can see that these objects are fairly simple. If you go back one step further in the hierarchy to TControl or TWinControl, you see huge objects.

For example, the declaration for class TWinControl is nearly 200 lines long (not the implementation, mind you, just the type declaration).

I'm showing you this source code because component builders should work directly with the source rather than use the online help or the docs. For simple jobs, you can easily create your own components without the source. However, if you have a big project, you have to get the source code if it did not ship with your product. The INT files that ship with all versions of BCB are very helpful, but you'll find no replacement for the actual source. The source is available with the client/server version of BCB and also as an up-sell from Borland.

The Clock Component

You now know enough to build a component from the ground up. The CLOCK unit, as shown in Figure 22.7, is a simple clock that you can pop onto a form, and activate and deactivate at will. In particular, you can start the clock running and then tell it to stop by changing the value of a Boolean property called Running.

Figure 22.7.The CLOCK unit as it appears on its own test bed, before being placed on the Component Palette.

When you're constructing class TClock, the first thing you need to decide is whether the clock is going to descend from TWinControl or TGraphicControl. If you've built a clock in Windows before, you know that one of the best ways to drive it is with a Windows timer. Timers require the presence of a handle so that they can be stopped and started; furthermore, they send their WM_TIMER messages to the window that owns them. Because a TGraphicControl descendant isn't a real window, it will not automatically get the messages. As a result, TGraphicControl is not an ideal choice for this type of object.

Of course, the objections to using TGraphicControl raised in the preceding paragraph aren't insurmountable. If you really want to, you can still make your clock work this way. However, there's no point in expending effort that isn't strictly necessary, so I have opted for the simplest design possible and have made the class a descendant of TCustomControl. I chose TCustomControl rather than TWinControl because I needed a Paint method in which I could draw the clock. (See Figure 22.8.)

Figure 22.8.The TClock and TColorClock controls shown on a form.

The code, shown in Listings 22.9 through 22.11, also contains a special property editor, as well as a simple component editor. As you will see, neither of these tools is inherently difficult to build.

---

NOTE: Before installing the clock components, you might need to run the BuildObjs program found in the Utils directory. See the readme file on the CD that accompanies this chapter for additional information.

---

　

Listing 22.9. The header for the Clock component contains declarations for the clock and its property and component editors.

#endif

Listing 22.10. The code for the Clock component should be kept in the Utils subdirectory where you store CodeBox and other utility units.

}

Listing 22.11. The test bed for the clock component is stored in the TestClock subdirectory.

}

To run this program, you should first select the menu item that creates the clock and makes it visible on the form. The next logical step is to start the clock running; then, if you'd like, you can also change its color. You get an Access Violation if you click the latter two buttons before selecting the first. The problem is that calling a method or property of the TClock object before the object itself has been created is an error. To prevent this error from happening, you could enable and disable the second two buttons.

The code for the clock components uses inheritance, virtual methods, and properties. TClock has two pieces of private data:

int FTimer;

One is an identifier for the timer, and the other is a Boolean value that specifies whether the clock is running.

Windows timers are managed by two Windows API calls. When you want to start a timer, use SetTimer; when you want to stop a timer, use KillTimer. SetTimer takes four parameters:

• Handle is the HWND of your current window.

  　

• IDEvent is an integer identifier that uniquely identifies the timer inside the window that created it. You can make up this value off the top of your head, although I generally set the IDTimer for the first timer in a window to 1, the second timer to 2, and so on. Because you're going to have only one timer in each instance of a TClock window, you can set its IDEvent to 1.

  　

• Elapse is the length of time between calls to the timer, measured in milliseconds.

  　

• TimerFunc is a callback function that is not used in this program. One of the developers' big goals was to create a Windows product that didn't need to use callbacks, and I see no reason to open that can of worms now if I can avoid it. (If you want to create a callback in BCB, you will be able to do so, but it's usually not necessary.)

A typical call to SetTimer looks like this:

SetTimer(Handle, FTimer, 50, NULL);

50 specifies that the timer is called once every 50 milliseconds. SetTimer returns zero if the call fails. This is a real possibility, so programs that include error checking should inspect this value and put up a MessageBox if the call fails.

KillTimer takes two parameters, the first being the handle of your window and the second being the unique identifier associated with that timer:

KillTimer(Handle, FTimer);

When you're not using the callback function, timer events are sent to your window by way of messages:

void __fastcall WMTimer(TMessage &Message);

This classic dynamic method is of the kind covered in Chapter 4, "Events." The response to this event is a simple procedure that calls TextOut and gets the time from the VCL:

void __fastcall TMyClock::WMTimer(TMessage &Message)

The calls to SetTimer and KillTimer are managed primarily through a property called Running:

__property Boolean Running={read=FRunning, write=SetRunning};

The write mechanism, a procedure called SetRunning, is a fairly straightforward tool:

void __fastcall TMyClock::SetRunning(Boolean Run)

If the user sets the Running property to True, this procedure is executed and a call is made to the SetTimer function. If the user sets Running to False, KillTimer is called and the clock immediately stops functioning.

The final issue involving the timer concerns the case in which the user closes a form while the clock is still running. In such a case, you must be sure to call KillTimer before the application exits. If you don't make the call, the timer keeps running even after the application closes. Having the timer running wastes system resources and also uses up one of the dozen or so timers that are available to the system at any one time.

The logical place to call KillTimer is the Destroy method for the TClock object. Unfortunately, the window associated with the clock has already been destroyed by the time this call is made, so no valid handle is available for use when you call KillTimer. As a result, you need to respond to WM_DESTROY messages to be sure the timer is killed before the TClock window is closed:

void __fastcall TMyClock::WMDestroy(TMessage &Message)

Before leaving this description of the TClock object, I should briefly mention the Paint method. Here is the simplest possible version of the paint procedure for the program:

void __fastcall TMyClock::Paint(void)

This procedure is called whenever the circle defining the circumference of the clock needs to be repainted. You never have to check for this circumstance, and you never have to call Paint directly. Windows keeps an eye on the TClock window, and if the window needs to be painted, Windows sends you a WM_PAINT message. Logic buried deep in the VCL converts the WM_PAINT message into a call to Paint, the same way TClock translates WM_TIMER messages into calls to TCanvas->TextOut.

The actual paint procedure used in the program looks like this:

///////////////////////////////////////

This version of the Paint procedure takes into account the ClockAttributes property of TMyClock. TClockAttributes looks like this:

class TClockAttributes: public TPersistent

As you can see, it provides a shape and a background color for the clock. The most important aspect of the TClockAttributes type is the property editors I create for it. These editors let you access both properties of this class through a series of special techniques, described later in this chapter. For now, you might want to merely click the ClockAttributes property, open up its two fields,

and see how it works.

The TColorClock component, which is a descendant of TClock, adds color to the face of the control. I made TColorClock a separate object, instead of just adding a face color to TClock, for two different reasons (both of which are related to design):

• You might want to create a descendant of TClock that doesn't have color or one that implements color differently than TColorClock does. By creating two objects, one called TClock and the other called TColorClock, I enable programmers to have the greatest amount of freedom when creating descendants. This principle has only minimal weight in a simple object such as TClock, but it can become extremely important when you're developing large and complex hierarchies. In short, be careful of building too much functionality into one object!

  　

• TClock and TColorClock also provide another example of inheritance and vividly demonstrate how this technology can be utilized to your advantage.

TColorClock declares a private data store called FColor that is of type TColor. Users can set the FColor variable by manipulating the Color property:

__property TColor Color={read=FColor, write=SetColor};

SetColor is a simple procedure that sets the value of FColor and calls the Windows API call InvalidateRect:

void SetColor(TColor Color)

Just to be sure this information makes sense to you, taking a paragraph or two

to provide a refresher course on InvalidateRect is worthwhile. Here's the declaration for the routine:

BOOL InvalidateRect(

InvalidateRect forces the window specified in the first parameter to redraw itself completely if the third parameter is set to True. If the third parameter is set to False, only the portions of the window that you specifically repaint are changed. The middle parameter is a pointer to the RECT structure that can be used to define the area that you want to redraw. Compare this function with the native BCB function called Invalidate.

Calls to InvalidateRect naturally force calls to the TColorClick->Paint method:

void __fastcall TColorClock::Paint()

Paint sets the brush associated with the window's device context to the color specified by the user; then it calls the Paint method defined in TClock.

To add this object to the Component Palette, you must first register it:

void __fastcall Register()

Here, I specify that the TClock and TColorClock objects should be placed in a group called Unleash.

A number of properties implemented by TCustomControl and its ancestors do not surface automatically. To access these properties from the Component Palette, all you have to do is list them in the __published section of your class declaration:

__property Align;

These simple declarations give your component the ability to align itself with the surface on which it resides or set its color and font. The color, in this case, is the color of the background of the form, not of the face of the form. In the actual finished version of the control, I ended up replacing the Color property with the TClockAttributes property. Once again, the primary reason for adding the TClockAttributes property was to show you how to work with property editors.

There is, of course, a place where the Align, Color, and Font properties are declared replete with read and write parts. However, after you have declared the property, you can publish it simply by using the two-word declarations shown here.

On the CD that accompanies this book, you will find a program called GoldClock that uses the TClock component to create a small application displaying the time. You can customize the fonts and colors in this program, and the settings you make will be written to the Registry so that they can be preserved for the next run of the program. The main form of the GoldClock application is shown in Figure 22.9.

Figure 22.9.The main form of the GoldClock application.

That's all I'm going to say about TClock and TColorClock. Overall, these components are fairly simple; they're interesting primarily because they show you how to go about constructing your own controls from scratch. This kind of exercise lies very much at the heart of BCB's architecture, and I expect many readers will be spending most of their time engaged almost exclusively in the business of building components.

Tips on Creating Properties

A standard technique used in component development features base classes that do not publish any properties. Consumers of the component can then inherit the functionality of the class without having to stick with the original developer's choice of published

properties.

After a property has been published, there is no good way to "unpublish" it. The solution to this potential problem is to create base classes that do not publish any properties. The functionality is present, but it is not surfaced in a way that it can be viewed in the Object Inspector.

In many cases, the VCL creates classes that do nothing but publish the properties of their immediate ancestors. These classes sport no functions, no methods, nothing but a __published section full of declarations like the ones shown in the preceding section for the Align, Color, and Font properties. This architecture lets others inherit the capability of the class while still providing a choice regarding what will be published.

The naming convention used for classes of this type usually involves the word Custom: TCustomImageList, TCustomControl, TCustomMemoryStream,

TCustomGroupBox, TCustomLabel, TCustomEdit, TCustomMemo, TCustomCheckBox, and so on. Open StdCtrls.hpp to see more explicitly how this system works.

Making descendants from TEdit or TLabel as I do in this chapter is a perhaps a bit too simplistic. If you really want to create a custom version of the Edit control for your own purposes, you should probably make descendants from TCustomEdit. Once again, you would not miss any functionality by doing so because TEdit does nothing but surface the "hidden" properties of TCustomEdit. It has no methods or data of its own; everything is inherited from TCustomEdit. All it does is publish 20-odd properties.

You probably should not declare the read and write parts of a property in a published section because doing so forces consumers of the product to conform with your ideas for the component's interface. Instead, read and write declarations should go in the public section of a class that has Custom in the name. Then you should create a descendant of that class which actually publishes the property.

Creating Icons for Components

The icon associated with a component and placed in the Component Palette is defined in a file with a .DCR extension. If you do not provide this file, BCB uses the icon associated with the object's parent. If no icon is present anywhere in the component's ancestry, a default icon is used.

---

NOTE: A DCR file is a Windows resource file with the extension changed from .RES to .DCR. The resource file contains a bitmap resource with the same name as your component. For example, the bitmap resource in a DCR file for a TCOLOR component would have a resource ID of TColor. This resource should be a 56x28 pixel (or smaller) bitmap that can be edited in the Image Editor. All you need to do is place this DCR file in the same directory as your component, and the images defined therein will show up on the Component Palette. Use the Image Editor to explore the DCR files that ship with BCB. They are stored in the \CBUILDER\LIB directory. I also ship some DCR files with this book in the Utils subdirectory where CodeBox and other files are kept.

---

　

Follow these steps to associate your own bitmaps with a particular component.

1. Open the Image Editor from the Tools menu and choose New.

2. Chose File | New | Component Resource from the menu. A dialog called Untitled1.dcr appears.

3. Select Resource | New | Bitmap from the menu. A dialog called New Bitmap Attributes appears.

4. Set Colors to 16 colors, because this technology is available on nearly all Windows systems. Set Size in Pixels to 24x24.

5. Save the file as Clock1.dcr. Rename the bitmap you have created to Tmyclock.

If you don't like the Image Editor, you can create a 24x24 bitmap in Pbrush.exe or some other bitmap editor and then create an RC file that looks like this:

TMYCLOCK BITMAP clock.bmp

Save the file as Clock1.rc. Run the Borland Resource Compiler from the command line:

brcc32 -r clock.rc

The resulting file will be called Clock1.res. Rename that file Clock1.dcr.

Creating Help Files for Components

BCB enables you to define help files that can ship with your components. These help files can be merged into the help that ships with BCB, so users of your product will feel as though it is a native part of BCB.

The HLP file is a standard Windows help file that contains information about the properties, methods, and events implemented by your component. I strongly recommend that you obtain a third-party tool to aid in the construction of these help files. For example, you might buy a copy of FOREHELP from Borland, or you could turn to Blue Sky software, or some other third party that provides tools to help you create these files. As a last resort, you can use Word, WordPerfect, or even the TRichEdit component, to create RTF files, and then compile these RTF files into HLP files with the HCW.EXE help compiler that ships with BCB in the CBUILDER\HELP\Tools directory. You can also download this file from online sites such as the Microsoft Web site or CompuServe. (The copy of FOREHELP sold by Borland has not been upgraded for Windows 95, but it is still many times better than having no help tool at all. FOREHELP requires that you have a copy of HC.EXE or HCP.EXE on your system. These files ship with many compilers and are available royalty free on CompuServe and the Internet.)

All the tools mentioned here play a peripheral role in the creation of components. They don't require a knowledge of the fascinating syntax used in component creation, but they help to make your tools attractive and easy to use.

The Five Main Tools APIs

Each of the five main Tools APIs is accessible through a separate set of routines that ship with BCB. These APIs enable you to write code that can be linked directly into the BCB IDE. Specifically, you can link your tools into CmpLib32.ccl the same way you link in components. Here is a list of the Tools APIs and the native BCB source files that define them.

Experts: Enable you to write your own experts.

• ExptIntf.hpp

  　

• VirtIntf.hpp

  　

• ToolIntf.hpp: for enumerating the component pages and components installed, adding modules to the project, and so on

Version Control: Enables you to write your own Version Control system or to link in a third-party system.

• VcsIntf.pas: Include this file in your project to generate the HPP file. The Pascal source might not ship with all versions of BCB.

  　

• VirtIntf.hpp.

  　

• ToolIntf.hpp: for opening and closing files in the editor.

Component Editors: Create dialogs associated with a control at design time (for example, the DataSet Designer is a component editor).

• DsgnIntf.hpp

Property Editors: Create editors for use in the Object Inspector.

• DsgnIntf.hpp

Editor Interfaces: For use mostly by third-party editor vendors such as Premia, American Cybernetics, and so on.

• EditIntf.hpp

  　

• FileIntf.hpp

The letters INTF are an abbreviation for the word "Interface." This term was chosen because the Tools API is an interface between your own code and the BCB developers' code.

Needless to say, most people will never use the Tools API. However, it will be important to a small minority of developers, and its existence means that everyone will be able to buy or download tools that extend the functionality of the IDE.

Property Editors

The Tools API for creating property editors is perhaps the most commonly used interface into the heart of the IDE. When you first use BCB and start becoming familiar with the Object Inspector, you are bound to think that it is a static element that never changes. However, by now it should come as no surprise to learn that you can change the functionality of the Object Inspector by adding new property editors to it.

As I mentioned earlier, property editors control what takes place on the right side of the Properties page of the Object Inspector. In particular, when you click the Color property of TEdit, you can select a new color from a drop-down list, from a common dialog, or by typing in a new value. In all three cases, you're using a property editor.

If you want to create a new property editor, you should create a descendant of

TPropertyEditor, a class declared in DsgnIntf.hpp. TPropertyEditor has a number of children. Many of these are for handling simple types such as strings and integers. These editors are not very important to BCB programmers, because most simple types have no RTTI associated with them in C++.

Instead of working with simple types, BCB programmers work with properties that are class types. The classic example of a class type of Property is TFont. Note, for instance, that the Font property of a form can be expanded to show the several fields of the TFont object. You can also pop up a dialog to edit the TFont object. This is a complex property editor of the type that will be developed through the remainder of this chapter.

Here is the declaration for the property editor associated with the ClockAttributes property of the TMyClock component:

class TColorNameProperty: public TClassProperty

TColorNameProperty doesn't descend from TPropertyEditor directly. Instead, it descends from a child of TPropertyEditor called TClassEditor. TClassEditor is designed for programmers who want to create editors for complex properties that are also classes.

The TColorNameProperty editor doesn't pop up any dialogs, although it will in a version of this program shown at the end of this chapter. Instead of creating dialogs, it simply tells the Object Inspector that the ClockAttributes class can be edited as two properties. In particular, notice that the ClockAttributes class expands out to show a Color property and a Shape property. You need to click the plus sign in front of the ClockAttributes property before you can see these properties.

The GetAttributes method is a way of defining what types of property editors you want to have associated with TColorDialog:

TPropertyAttributes __fastcall TColorNameProperty::GetAttributes(void)

In this case I have set the paSubProperties flag, which tells the Object Inspector to place the plus sign before the property so it can be opened up to reveal sub properties.

A property editor that has the paMultiSelect flag remains active even if the user has selected more than one component of that type. For example, you can select 10 edit controls and change all their fonts in one step. BCB enables you to make this change because the TEdit control has the paMultiSelect flag set.

The paValueList flag dictates that the property editor drops down a list of values from an enumerated or set type when the user clicks the arrow button at the far right of the editor. This functionality is built into BCB, and you need only set the flag to have it be supported by your property editor.

Finally, paDialog states that the property editor pops up a dialog. Ultimately, the paDialog flag does little more than assure that the ellipsis button appears at the right of the property editor.

---

NOTE: When you choose both paDialog and paValuelist in a single component, the property editor button always winds up being a combo drop-down list button. In other words, the dialog button is obscured, even though the functionality is still present. See, for example, the Color property of a TForm or TEdit.

---

　

Streaming Properties of Type Class

The ClockAttributes property will not work properly unless it is streamed to disk. In particular, effective use of TClockAttributes depends on whether the two key properties in TClockAttributes get written to the DFM file where

the form is stored. To ensure that this happens, all you have to do is declare ClockAttributes as a published property, and then descend TClockAttributes from TPersistent, and make sure that the Shape and Color properties are published.

Here is the declaration for the TClockAttributes:

class TClockAttributes: public TPersistent

The key part of this declaration is where the Color and Shape properties are designated as published. This means that they will have RTTI associated with them, and that they will be streamed out to the DFM file automatically.

Here is a text version of the TMyClock component as it appears in a DFM file:

object MyClock2: TMyClock

Note that the two key properties of ClockAttributes have been included in the DFM file. I did not have to do anything special to make this happen. Instead, I just made sure that ClockAttributes itself was a published property, and that Color and Shape were published properties of TClockAttributes.

Once I was sure the properties were being streamed out, the only thing left to do was tell the Object Inspector to show both values of TClockAttributes. To do this, I simply created the simple, do-nothing TColorNameProperty class. As you saw, this class descends from TClassProperty, which is declared in Dsdintf.hpp.

Examining DsgnIntf.cpp

The DsgnIntf unit is unusual in that it is very carefully documented by the developer who created it. For example, here are excerpts from that unit describing the two methods I call in the descendant of TPropertyEditor:

Edit

These entries were written by the developers, and they extensively document this important interface to the core code inside the heart of the IDE.

Here are declarations for Edit and GetAttributes, as well as the other key functions in TPropertyEditor:

class __declspec(pascalimplementation) TPropertyEditor : public System::TObject

Once again, all these methods are carefully documented in DsgnIntf.hpp. You should study that file carefully in order to add to the knowledge about property and component editors outlined in the remainder of this chapter.

Registering the Property Editors

You must register property editors with the system before compiling them into CmpLib32.ccl. To register a property, call RegisterPropertyEditor in the Register method for your component:

RegisterPropertyEditor(__typeinfo(TClockAttributes),

The declaration for RegisterPropertyEditor looks like this:

extern void __fastcall RegisterPropertyEditor(

The various parameters are as follow:

• PropertyType. The first parameter passed to this function states the type of data handled by the editor. In this case, it is TClockAttributes. BCB uses this information as the first in a series of checklists that determine which properties should be associated with this editor. As noted above, this type cannot be a simple value such as an int or TColor. It must be a class type. If you want to work with simple types, you should either wrap them in a class or switch to Object Pascal.

  　

• ComponentClass. The second parameter further qualifies which components will use this editor. In this case, I have narrowed the range down to TMyClock and its descendants. If I had written TComponent instead of TMyClock, or if I had set this parameter to NULL, all properties of type TClockAttributes would start using that editor. You therefore can build a new editor for fonts or colors, install it on a customer's system, and it would work with all properties of that type. In other words, you don't have to create a component to be able to write an editor for it.

  　

• PropertyName. The third parameter limits the scope to properties with the name passed in this string. If the string is empty, the editor is used for all properties that get passed the first two parameters.

  　

• EditorClass. This parameter defines the class of editor associated with the properties defined in the first three parameters.

If you want to find out more about this function, refer to the comments in DsgnIntf.pas. These comments may not be copied into DsgnIntf.hpp, so check both places.

Working with Component Editors

After you have learned how to build property editors, understanding component editors is easy. These tools are descendants of TComponentEditor, just as property editors are descendants of TPropertyEditor:

class TClockEditor: public TComponentEditor

The TColorDialog has a simple editor that pops up a dialog requesting that the user choose a new color:

void __fastcall TClockEditor::Edit(void)

In this case, I'm popping up the standard TColorDialog that appears when you click the ellipsis icon in the Object Inspector for a property of type TColor. The difference, of course, is that this is a component editor, not a property editor. In the more complex component editor example shown later in this chapter, you pop open a form that allows the user to make several changes to the component.

It is easy to access the underlying component from inside a component editor. In particular, the component you are editing is available to you in a variable called

Component.

The Component variable referenced in this example is declared globally inside TComponentEditor objects. To access it, you merely have to typecast it as desired to get at the component you're currently editing. For example, in this example, I typecast Component as a TColorClock. I don't bother with a dynamic_cast in this example because the conversion has to work, by the very definition of the context of the call.

This component editor, of course, is the simplest possible, but it gets you started working with these useful tools. Figure 22.10 shows the component editor in action.

Figure 22.10.The first take on the component editor for the TClock component pops up a simple TColorDialog.

---

NOTE: Two additional component editors, each one more complex than the last, will be shown later in the chapter. In particular, you will see how to pop up a component editor that is built on top of a VCL form.

---

　

The Register method for TClockEditor looks like this:

The declaration for this procedure looks like this:

Clearly, the first parameter specifies the class with which the editor is associated, and the second parameter specifies the class of the editor.

In this section, I introduced you to property editors and component editors. These examples are important primarily because they help focus your attention on DsgnIntf.hpp, which is one of several files that ship with BCB that define the Tools API. If you want to extend the BCB IDE, you should get to know all the files that end in INTF.

Extending the Component and Property Editors

The original component and property editors for TMyClock and TColorClock components are very simple.

Of course, using such simple component and property editors is very limiting. You may use a normal VCL form as an editor. Examples of this type of form are shown in Figures 22.11 and 22.12.

Figure 22.11.The new property editor for ClockAttributes is a VCL form that gives the user considerable control over the appearance of the clock.

Figure 22.12.This component editor for TClock uses a standard VCL form and can be as complex as you want.

To create the form shown in Figure 22.12, I started a new project called TestClock2. I then copied the Clock1 files into a new set of files called Clock2 and changed all the names inside the files to reflect the change. For example, I renamed TMyClock to TMyClock2, TColorClock to TColorClock2, and so on.

I then created a new form called ClockEditor and added several buttons to it, a TColorDialog, and a TImage control. I arranged the controls as shown in Figure 22.12. I then made a few changes to the Edit method of TClockEditor2, and added a button to my main form so that I could test the editor. The source code for this new program is shown in Listings 22.12 through 22.15.

---

NOTE: Before installing the clock components, you might need to run the BuildObjs program found in the Utils directory. See the readme file on the CD that accompanies this chapter for additional information. In particular, BuildObjs makes sure that ClockAttributes.cpp and ClockEditor.cpp are both compiled into binary form as OBJ files.

　

---

　

Listing 22.12. The header file for the main unit of the TestClock2 program.

#endif

Listing 22.13. The main module for the TestClock2 program.

}

Listing 22.14. The header for the ColorEditor dialog.

extern TClockEditorDialog *ClockEditorDialog;

#endif

Listing 22.15. The main module for the ColorEditor dialog.

}

Listing 22.16. The header for the VCL form that serves a dialog for editing the ClockAttributes property.

#endif

Listing 22.17. The main source file for the VCL form that serves a dialog for editing the ClockAttributes property.

}

Listing 22.18. Here is the header for the new version of the clock components.

#endif

Listing 22.19. The main source file for the new version of the clock components.

}

When popping up a new form from inside a component editor, you have to create the actual instance of the form and assign it an owner. You need to do so because the form will not be auto-created in your program's project source file.

To handle the chore of creating the form, I created a special method inside the ClockEditor unit. The routine looks like this:

This routine takes an instance of the clock that needs to be edited as its sole parameter. It then creates an instance of the TClockEditorDialog and assigns the clock to an internal data store of the dialog. Finally, the code shows the dialog and cleans up the memory when the user is through making the edits.

To test this dialog, you can simply drop an instance of the clock onto the main form of the application and then call the dialog from a button click response method:

After you're sure that everything is working properly, you can change the TClockEditor2::Edit method so that it calls this dialog when the user double-clicks the component in design mode:

RunClockEditorDlg(((TColorClock2 *)(Component))); }

Once again, you can see that the code takes advantage of the Component object that is declared ahead of time by the VCL. All you need to do is typecast the object to the proper type and then pass it on to the ClockEditor object.

Inside the TClockEditorDialog itself, the act of changing the component is trivial:

void __fastcall TClockEditorDialog::SetFaceColorBtnClick(TObject *Sender)

This code simply pops up a color dialog and allows the user to choose a new face color. If the user makes a selection, the color is assigned to the relevant property of the TColorClock2 object.

I still need to address one subject in this project. The issue here is that the TClock2 project now consists of two different modules. The first module contains the TColorClock itself, and the second module contains the TClockEditorDialog.

When you add the Clock2.cpp module to the Component Palette, you also have to find a way to bring in ClockEditor.cpp; otherwise, the project will not compile. Unfortunately, you can't add ClockEditor directly to the CmpLib32 project because ClockEditor does not have a Register method. Without the Register method, the component library won't know what to do with the file.

The solution to this problem is provided by a pragma that can be added to Clock2.cpp to tell the compiler that it must include ClockEditor.obj in any projects that use this unit:

#pragma link "ClockEditor.obj"

After you add this line, CmpLib32 will know that it has to include ClockEditor.obj in the compilation. It will not, however, know to compile the unit from a CPP file into an OBJ file.

---

NOTE: In the first shipping version of BCB, a problem can occur if you try to recompile CmpLib32.ccl and do not provide a precompiled copy of ClockEditor.obj. In particular, the compiler does not treat ClockEditor as part of the project it is making, so it will not know to make ClockEditor.obj from ClockEditor.cpp.

One solution to this problem is to start a small project that will compile ClockEditor.cpp into ClockEditor.obj. For example, the simple TestClock2 program will create ClockEditor.obj each time it is compiled. The BuildObjs file included on the CD will do the same thing.

If you have created a copy of the OBJ file, and the compiler still complains, try touching the unit that uses ClockEditor. For example, make a small change to Clock2.cpp. Any change will do. You can just add a space to the unit and then remove it. The point is that you need to save the unit so that it has a new date and time. This time, when you recompile and link CmpLib32, it will find your new copy of ClockEditor.obj.

---

　

That's all I'm going to say about component editors. As you have seen, this subject

is not complicated, even when you create your own custom form for editing the object. Creating custom forms of this type can be very helpful for the user because it gives you a chance to step him or her through the process of initializing the object. You can even create a little expert that runs when the user double-clicks the component. The expert could take the user by the hand and ensure that he or she sets up your control properly.

The property editor for the ClockAttributes property is very similar to the component editor. The primary difference is in the way you access the underlying value that you want to edit:

void __fastcall TClockAttributeProperty::Edit()

Instead of having a ready-to-use variable called Component, you need to call the GetOrdValue method of TPropertyEditor. This function was originally intended to retrieve simply ordinal values. It can, however, do double-duty and retrieve pointer values. This is possible because a pointer and an integer both consist of 4 bytes.

In this case, I typecast the value returned from GetOrdValue as a variable of type TClockAttribute. I can then pass this value into my VCL form and edit it as I please. The principle here is exactly the same as in the Component editor, only this time I access the underlying property that I want to edit through GetOrdValue, rather than through a variable named Component.

Inside the ClockAttributes dialog you need to create a routine that will pop open the VCL form:

void RunClockAttributesDlg(TClockAttribute2 *AClockAttribute)

Most of this code is very routine and does nothing more than allocate memory for a form, show it modally, and then destroy it. Note the line that sets the value of the selected item in the form's combo box:

ClockAttributesDialog->ComboBox1->ItemIndex = (int)AClockAttribute->Shape;

This line accesses one of the fields of the TClockAttribute class. It then sets the ItemIndex of the combo box to the currently selected shape. Here are the values displayed in the combo box:

Rectangle

Square

RoundRect

RoundSquare

Ellipse

Circle

If the technique used here to select an item in the combo box does not make

sense to you, you might want to refer to similar code from the ShapeDem2 program in Chapter 2.

Summary

In this chapter, you have learned about building components. Specifically, you learned how to create components that do the following:

• Change an ancestor's default settings. For example, you created TEdit descendants with new default colors and fonts.

  　

• Add functionality not available in an ancestor object. For example, the TColorClock object does things that TClock does not.

  　

• Are built up from scratch so that they can add new functionality to the IDE. For example, the TClock component brings something entirely new to BCB programming that does not exist in any other component that ships with the product.

You also learned about tools and files associated with components, such as the DCR and KWF files. Finally, you learned about the Tools API and specifically about the art of making property editors and component editors.