November 1997

Building components, part 3

In the September 1997 issue of C++Builder Developer's Journal, part 1 of this series looked at the basic elements of component building in C++ Builder. In part 2, we built a small example component. This month, we'll demonstrate how to add some polish to your component--finishing touches like writing a help file to document the component, creating custom property and component editors to make it easier to use, and adding an icon to set the component apart from others. This article is, in essence, three articles in one; so feel free to jump to the section(s) of interest to you.

Let's start with the most important task to perform once the component is working: writing a help file.

A custom help file

Basically, you'll use your favorite word processor to prepare the text of your help file. But instead of chapters containing pages, you structure your help file as books containing topics. At the very least, your help file must contain a general overview and a topic for each new property and event your component publishes. Each topic can be as long or as short as you like--there are no physical page constraints. You can easily embed text, images, and simple tables. Don't expect to be able to do too much fancy formatting--the help compiler will choke on some of the more sophisticated features of the major word processors. Stick to simple tables, avoid all but the standard fonts, and try to use 16- or 256-color Windows bitmap (BMP) files. Another trap to avoid is the "keep (paragraph) with next" feature that's used for most headings in a normal document. HCW uses it to mark non-scrolling regions that are allowed only once at the top of a topic--so, don't use your favorite style sheet for your help file topics! Mark the end of each topic using a hard page break ([Ctrl][Enter] in Microsoft Word). HCW requires specific information about each topic in order to produce the final help file. You must title the main topics, provide key words and phrases for the index, and assign Topic IDs to allow for hypertext jumps. If you want the reader to be able to browse through your topics, you must also assign a browse sequence to tell HCW the order of the topics. You pass all this information to HCW by embedding it in footnotes. When you find a footnote marker in a book--like this*--you know that at the bottom of the page will appear a note with an asterisk in front of it. HCW reads your topics in much the same way. If it finds a footnote that uses a dollar sign--like this$--it takes the corresponding footnote text to be the title of the current topic. Let's look at the other footnotes you'll need for each topic, along with the characters that identify them.

K--keyword

K TDBShortList; ComboBox; Short List

+ 001

#--topic IDs

# 1001

..the ListDefaults1001 property..

..the ListDefaults property..

For a component, the A-footnote must be formatted as the name of the component followed by _Object, a semicolon, and the name of the component again, as follows:

A TDBShortList_Object;TDBShortList

TDBShortList:

A TDBShortList_ListDefaults; ListDefaults_Property;
 ListDefaults

A TDBShortList_OnAddNew; OnAddNew_Event; OnAddNew

After compiling your project, you'll have a working TDBShortList.HLP file. Integrating it with the C++Builder IDE is easy. The documented procedure is to use the OpenHelp tool, but that didn't work on my system--my OpenHelp.INI file was corrupt. An alternate technique that's guaranteed to work is to copy your help and contents files (TDBShortList.HLP/CNT) to the CBuilder\Help directory; then, add the following two lines to your BcbHelp.CFG file (in the same directory):

:INDEX TDBShortList=TDBShortList.hlp
:LINK TDBShortList.hlp

void *p = __typeinfo(AnsiString);

TPropertyAttributes __fastcallGetAttributes(void);
AnsiString __fastcall GetValue(void);
void __fastcall SetValue(AnsiString v);
void __fastcall Edit(void);

// VCL wrapper class for an AnsiString
class TText : public TPersistent 
{ public:
  __fastcall TText() : TPersistent() {};
  __fastcall ~TText() {};
  PROP_PUBLISHED(AnsiString,Text,nodefault);
}
.
.
// from class TDBShortList, change ListName to:
PROP_PUBLISHED(TText*,ListName,nodefault);
.
.
class TTextProperty : public TPropertyEditor 
{ public:
  virtual AnsiString __fastcall
    GetValue(void) { return 
    ((TText*)GetOrdValue())-&gtText; };
  virtual void __fastcall
    SetValue(AnsiString v) {
    ((TText*)GetOrdValue())-&gtText = v; };
  virtual TPropertyAttributes __fastcall
    GetAttributes(void) 
    { return (TPropertyAttributes() <<
      paDialog << paRevertable); };
  TTextProperty() : TPersistent() {};     
};
.
.
class TFileNameProperty : public TTextProperty 
{ public:
  virtual void __fastcall Edit(void);
  TFileNameProperty() : TTextProperty() {};     
};
.
.
// in the register() function:
RegisterPropertyEditor(
  __typeinfo(TText),
  __classid(TDBShortList),"ListName",
  __classid(TFileNamesProperty) );
.
.
// in the constructor for TDBShortList:
  ListName = new TText;
//in the destructor for TDBShortList: delete ListName;
.
.
#include "dir.h"
void __fastcall TFileNameProperty::Edit(void)
{
  TOpenDialog *o=new TOpenDialog(Application);

  o-&gtFileName = GetValue();
  o-&gtDefaultExt = "*.lst";
  o-&gtFilter = "List Files (*.lst)|*.lst"
            "|All Files (*.*)|*.*";
  o-&gtFilterIndex = 1;
  o-&gtTitle = "List File Name";

  char buf[MAXPATH+1];
  o-&gtInitialDir = getcwd( buf, sizeof(buf) );

  if ( o-&gtExecute() == true )
  {  SetValue( o-&gtFileName );
    Designer-&gtModified();
  };
  delete o;
}

// max chars in ListDefaults string
#define MAXLISTDEFAULTSTEXT 4096
.
.
class TCommaTextProperty : public TTextProperty
{
  public:
    virtual int __fastcall GetEditLimit(void)
    { return MAXLISTDEFAULTSTEXT; };

    virtual void __fastcall Edit(void);
    TCommaTextProperty() : TTextProperty() {};
};


class TCommaTextForm : public TForm
{
__published:   // IDE-managed Components
  TListBox *ListBox;
  TBitBtn *BClose;
  TBitBtn *BAdd;
  TBitBtn *BDelete;
  TEdit *Item;
  void __fastcall BAddClick(TObject *Sender);
  void __fastcall BDeleteClick(TObject *Sender);
private:// User declarations
  AnsiString Get(void) 
    { return ListBox-&gtItems-&gtCommaText; };
  void Set(AnsiString v) 
    { ListBox-&gtItems-&gtCommaText = v; };
public:// User declarations
  __fastcall TCommaTextForm(TComponent* Owner) :
                            TForm(Owner) { };
  __property AnsiString CommaText = { 
                          read=Get, write=Set };
};
.
.
// in the register() function:
RegisterPropertyEditor( __typeinfo(TText),
                        __classid(TDBShortList),
                        "ListDefaults",
                        __classid(TCommaTextProperty)
                      );
.
.
// in the constructor for TDBShortList:
  ListDefaults = new TText;
// in the detructor for TDBShortList: delete ListDefaults;
.
.
void __fastcall TCommaTextProperty::Edit(void)
{
  TCommaTextForm *f= new TCommaTextForm(Application);

  f-&gtCommaText = GetValue();
  f-&gtShowModal();

  if ( GetValue() != f-&gtCommaText )
  { if (f-&gtCommaText.Length() > MAXLISTDEFAULTSTEXT)
    {  MessageBox( 0, ("The limit is " +
       AnsiString(MAXLISTDEFAULTSTEXT) +
       " characters. The text will be truncated.")
       .c_str(), "Sorry - too much text",
       MB_ICONEXCLAMATION );

       f-&gtCommaText.SetLength(MAXLISTDEFAULTSTEXT);
  };
    SetValue( f-&gtCommaText );
    Designer-&gtModified();
  };

   delete f;
}

class TDBShorListEditor : public TDefaultEditor
{
  private:
    TDBShortList *Component;
    TFormDesigner *Designer;
    int index;

  public:
    virtual void __fastcall EditProperty(
            TPropertyEditor *pe,
            bool &con, bool &fre );

    void Reset(void); // demos use of comp ptr

    virtual int __fastcall GetVerbCount(void)
    { return 3; };

    virtual AnsiString __fastcall GetVerb(int i)
    { const char *verb[] = { "ListDefaults",
                     "ListName", "Reset Example" };
      return verb[i]; };

    virtual void __fastcall ExecuteVerb(int i)
    { if ( i < 2 ) { index = i; Edit(); } 
         else Reset(); };

    void Modified(void) 
    { if ( Designer ) Designer-&gtModified(); };

    __fastcall virtual ~TDBShorListEditor(void) {};
    __fastcall virtual DBShorListEditor(
                 TComponent* c, TFormDesigner* d) :
                 TDefaultEditor(c, d)
    {Component= (TDBShortList *)c; Designer = d;};
};
.
.
RegisterComponentEditor(__classid(TDBShortList),
                        __classid(TDBShorListEditor));
.
.
void TDBShorListEditor::Reset( void )
{
  if ( !Component || !Designer ) // be careful
    return;

  if ( MessageBox( 0, 
    "Reset the component to the example defaults?",
    "Are You Sure?", MB_YESNO ) != IDYES )
  return; // customer said no... so quit

  Component-&gtListDefaults-&gtText = "Red, Yellow, Blue";
  Component-&gtListName-&gtText = "color.txt";
  Modified();
}

void __fastcall TDBShorListEditor::EditProperty(
     TPropertyEditor *pe, bool &con, bool &fre )
{
  if ( !strcmpi( pe-&gtGetName().c_str(), 
       !index ? "ListDefaults" : "ListName" ) )
  {  pe-&gtEdit();
    con = false;
  };
}