8. Udělání komponenty dostupné při návrhu

Registrovanou komponentu instalujeme na Paletu komponent a potom ji můžeme vybírat, umisťovat ji na formulář a manipulovat s ní při návrhu. Udělání naší komponenty dostupné během návrhu vyžaduje několik kroků:

• Komponentu registrujeme
• Přidáme bitovou mapu zobrazenou na paletě
• Poskytneme pro naši komponentu nápovědu
• Přidáme editory vlastností
• Přidáme editor komponenty
• Přeložíme komponentu do balíčku

Registrace komponenty

• Deklarování funkce Register
• Zápis funkce Register

Deklarování funkce Register

Zápis funkce Register

Přidání bitové mapy zobrazené na paletě

Poskytnutí nápovědy pro naši komponentu

1. Každá komponenta musí mít prvek nápovědy. Prvek nápovědy komponenty obsahuje stručný popis komponenty. Prvek nápovědy komponenty musí obsahovat vazby na sekundární okna, které popisují pozici komponenty v objektové hierarchii a které obsahují seznamy všech vlastností, událostí a metod dostupných pro uživatele komponenty. Vývojář aplikace zpřístupňuje tento prvek nápovědy výběrem komponenty na formuláři a stiskem klávesy F1. Prvek nápovědy musí mít poznámku pod čarou # s unikátní hodnotou pro prvek. Poznámka pod čarou # jednoznačně identifikuje každý prvek v nápovědném systému.

Prvek nápovědy komponenty musí mít poznámku pod čarou "K" pro vyhledávání klíčových slov, která obsahuje jméno třídy komponenty. Např. poznámka pod čarou klíčového slova pro komponentu TMemo je "TMemo". Prvek nápovědy komponenty musí mít také poznámku pod čarou "$", která poskytuje titulek prvku. Titulek se zobrazuje v dialogovém okně Topics Found, dialogovém okně Bookmark a okně History.
2. Každá komponenta musí mít sekundární navigační prvky nápovědy. Jedná se o:
• Prvek hierarchie s vazbami na každého předka komponenty v hierarchii komponent.
• Seznam všech vlastností dostupných v komponentě, s vazbami na prvky popisující tyto vlastnosti.
• Seznam všech událostí dostupných v komponentě, s vazbami na prvky popisující tyto události.
• Seznam metod dostupných v komponentě, s vazbami na prvky popisující tyto metody.
Vazby na objekty tříd, vlastností, metod nebo událostí v nápovědném systému C++ Builderu mohou být provedeny pomocí Alink. Když se odkazujeme na objekt třídy, pak Alink používá jméno objektu třídy, následované podtržením a řetězcem "object". Např. k vazbě na objekt TCustomPanel použijeme:
!AL(TCustomPanel_object,1)
U vazeb na vlastnost, metodu nebo událost, předchází jméno vlastnosti, metody nebo události jméno třídy, která ji implementuje a podtržení. Např. k vazbě na vlastnost Text, která je implementovaná TControl použijeme:
!AL(TControl_Text,1)
Abychom viděli příklad sekundárních navigačních prvků, zobrazíme prvek nápovědy nějaké komponenty a klikneme na vazbu popsanou ?hierarchy?, ?properties?, ?methods? nebo ?events?.
3. Každá vlastnost, událost a metoda, která je deklarována v komponentě musí mít nápovědný prvek. Prvek nápovědy vlastnosti, události nebo metody zobrazuje deklaraci prvku a popisuje jeho používání. Vývojář aplikace vidí tyto prvky po jejich výběru v Inspektoru objektů a stisku F1 nebo umístěním textového kurzoru v Editoru kódu na jméno prvku a stiskem F1.

Prvek nápovědy pro vlastnost, událost nebo metodu musí obsahovat poznámku pod čarou "K" se jménem vlastnosti, metody nebo události a toto jméno v kombinaci se jménem komponenty. Tedy vlastnost TextTControl má následující "K" poznámku pod čarou:
Text,TControl;TControl,Text;Text,
Prvek nápovědy vlastnosti, metody a události musí mít také poznámku pod čarou "$", která určuje titulek prvku, např. ?TControl::Text?.
Všechny tyto prvky nápovědy musí mít unikátní ID prvku, zadané jako poznámka pod čarou #.

Přidání editorů vlastností

1. Odvození třídy editoru vlastnosti
2. Editace vlastnosti jako text
3. Editace vlastnosti jako celek
4. Specifikaci atributů editoru
5. Registrace editoru vlastnosti.

Odvození třídy editoru vlastnosti

Následuje deklarace třídy jednoduchého editoru vlastnosti nazvaného TMujEditorVlastnosti:
class PACKAGE TMujEditorVlastnosti : public TPropertyEditor
{
   typedef TPropertyEditor inherited;
public:
   virtual bool __fastcall AllEqual(void);
   virtual System::AnsiString __fastcall GetValue(void);
   virtual void __fastcall SetValue(const System::AnsiString Value);
   __fastcall virtual ~TMujEditorVlastnosti(void) { }
   __fastcall TMujEditorVlastnosti(void) : Dsgnintf::TPropertyEditor() { }
};

Editování vlastnosti jako text

Když předefinujeme metodu GetValue, můžeme stále volat jednu z metod "Get" a když předefinujeme metodu SetValue, můžeme stále volat jednu z metod "Set".
Metoda GetValue editoru vlastnosti vrací řetězec, který reprezentuje současnou hodnotu vlastnosti. Inspektor objektů používá tento řetězec ve sloupci hodnot pro vlastnost. Implicitně GetValue vrací "unknown".
K poskytnutí řetězcové reprezentace pro naši vlastnost, předefinujeme metodu GetValue editoru vlastnosti. Jestliže vlastnost nemá řetězcovou hodnotu, naše GetValue musí převést hodnotu na její řetězcovou reprezentaci.
Metoda SetValue editoru vlastnosti přebírá řetězec zapsaný uživatelem v Inspektoru objektů, převádí jej na příslušný typ a nastavuje hodnotu vlastnosti. Jestliže řetězec nemá reprezentaci příslušné hodnoty pro vlastnost, SetValue generuje výjimku a nevhodnou hodnotu nepoužije. Pro přečtení řetězcové hodnoty z vlastnosti, předefinujeme metodu SetValue editoru vlastnosti. SetValue musí převádět řetězec a ověřovat hodnotu před voláním jedné z metod "Set".

Editování vlastnosti jako celek

Specifikování atributů editoru

Vlastnost Color má několik možností, jak ji uživatel zadá v Inspektoru objektů: zápisem, výběrem ze seznamu a editorem. Metoda GetAttributes TColorProperty, tedy obsahuje několik atributů ve své návratové hodnotě:
virtual __fastcall TPropertyAttributes TColorProperty::GetAttributes()
{
  return TPropertyAttributes()<<paMultiSelect<<paDialog<<paValueList;
}

Registrace editoru vlastnosti

Přidávání editoru komponenty

• Přidání prvku k místní nabídce
• Změna chování dvojitého kliknutí
• Přidání formátu schránky
• Registrace editoru komponenty.

Přidávání prvku k místní nabídce

Změna chování dvojitého kliknutí

Přídávání formátu schránky

Registrace editoru komponenty

Překlad komponent do balíčků

• Chybějící modifikátor PACKAGE u funkce Register.
• Chybějící modifikátor PACKAGE u třídy.
• Chybějící #pragma package(smart_init) ve zdrojovém kódu C++.
• Funkce Register není nalezena ve jmenném prostoru se stejným jménem jako je jméno modulu zdrojového kódu.
• Register není úspěšně exportován. Použijte tdump na soubor BPL k prohlédnutí exportovaných funkcí:

tdump -ebpl mypack.bpl mypack.dmp
V sekci exports vidíme zda funkce Register (ve jmenném prostoru) byla exportována

1. Když pracujeme s připojenou databází, je často užitečné mít ovladač spojen s nějakou položkou databáze. Aplikace tedy může založit propojení mezi ovladačem a nějakou částí databáze. C++ Builder obsahuje datové ovladače typů editačních oken, seznamů, kombinovaných oken a mřížek. Můžeme také vytvořit svůj vlastní datový ovladač. Je několik stupňů závislosti dat datových ovladačů. Nejjednodušší je datová závislost pouze pro čtení, nebo prohlížení dat, a umožnění reakce na aktuální stav databáze. Složitější je editovatelná datová závislost, kde uživatel může editovat hodnoty v databázi manipulací s ovladačem.

Nyní se pokusíme vytvořit ovladač určený pouze pro čtení, který je spojen s jednou položkou v databázi. Ovladač bude používat kalendář vytvořený v předchozí kapitole.
Vytvoření datového ovladače kalendáře provedeme v následujících krocích: vytvoříme a registrujeme komponentu, uděláme ovladač určeny pouze pro čtení, přidáme datové propojení a reakce na změny dat.
Použijeme obecný postup s těmito specifikami: jednotku komponenty nazveme DBCal, odvodíme nový typ komponenty nazvaný TDBCalendar od TSampleCalendar a registrujeme TDBCalendar na stránce Samples Palety komponent.
Výsledek naší práce je (nejprve je uveden výpis hlavičkového souboru jednotky):
#ifndef DBCalH
#define DBCalH
#include <vcl\sysutils.hpp>
#include <vcl\controls.hpp>
#include <vcl\classes.hpp>
#include <vcl\forms.hpp>
#include <vcl\grids.hpp>
#include "CALSAMP.h"
class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
protected:
public:
__published:
};
#endif
CPP soubor vypadá takto:
#pragma link "Calsamp"  // vazba na TSampleCalendar
#include <vcl\vcl.h>
#pragma hdrstop
#include "DBCal.h"
#pragma package(smart_init);
static inline TDBCalendar *ValidCtrCheck()
{
 return new TDBCalendar(NULL);
}
namespace Dbcal
{
  void __fastcall PACKAGE Register()
  {
    TComponentClass classes[1] = {__classid(TDBCalendar)};
    RegisterComponents("Samples", classes, 0);
  }
}
2. Jelikož tento kalendář bude určen pouze pro čtení, je vhodné znemožnit uživateli provádění změn v ovladači. Provedeme to ve dvou krocích: přidáme vlastnost ReadOnly a dovolíme potřebné aktualizace. Když tato vlastnost je nastavena na true, jsou všechny buňky v ovladači nevybíratelné. Přidáme deklaraci vlastnosti a soukromou položku k uložení hodnoty:

class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
  bool FReadOnly;
protected:
public:
  __fastcall TDBCalendar(TComponent* Owner);
__published:
  __property bool ReadOnly={read=FReadOnly,write=FReadOnly,default=true};
};
Zapíšeme definici konstruktoru:
__fastcall TDBCalendar::TDBCalendar(TComponent* Owner)
 : TSampleCalendar(Owner)
{
  FReadOnly = true;
}
a předefinujeme metodu SelectCell k zákazu výběru, jestliže ovladač je pouze pro čtení.
bool __fastcall TDBCalendar::SelectCell(long ACol, long ARow)
{
  if (FReadOnly) return false;
  return TSampleCalendar::SelectCell(ACol, ARow);
}
Nesmíme zapomenout přidat deklaraci SelectCell k deklaraci třídy TDBCalendar. Jestliže nyní přidáme kalendář na formulář, zjistíme, že komponenta ignoruje kliknutí a stisky kurzorových kláves.
Kalendář pouze pro čtení používá metodu SelectCell pro všechny typy změn, včetně nastavování vlastností Row a Col. Metoda UdpateCalendar nastavuje Row a Col pokaždé, když se změní datum, ale jelikož SelectCell nepovolí změny, výběr se nemění, i když se změní datum. K omezení tohoto absolutního zákazu změn, můžeme přidat interní logickou položku ke kalendáři a povolit změny, když je tato položka nastavena na true:
class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
bool FUpdating;
public:
  virtual void __fastcall UpdateCalendar();
};

bool __fastcall TDBCalendar::SelectCell(long ACol, long ARow)
{
  if (!FUpdating && FReadOnly) return false;
  return TSampleCalendar::SelectCell(ACol, ARow);
}
void __fastcall TDBCalendar::UpdateCalendar()
{
  FUpdating = true;
  try
  {
    TSampleCalendar::UpdateCalendar();
  }
  catch(...)
  {
    FUpdating = false;
    throw;
  }
  FUpdating = false;
}
Kalendář stále neumožňuje uživateli provádět změny datumu, ale již správně reaguje na změny datumu provedené změnou vlastností datumu. Dále potřebujeme ke kalendáři přidat schopnost prohlížet datumy.

3. Propojení mezi ovladačem a databází je obsluhováno objektem nazvaným datový spoj. C++ Builder poskytuje několik typů datových spojů. Objekt datového spoje, který propojuje ovladač s jednou položkou v databázi je TFieldDataLink. Jsou také datové spoje pro celé tabulky. Objekt datového ovladače vlastní svůj objekt datového spoje. Tj. ovladač má odpovědnost za vytvoření i uvolnění datového spoje. K vytvoření datového spoje jako vlastněného objektu provedeme tři kroky: deklarujeme objektovou položku, deklarujeme přístupové vlastnosti a inicializujeme datový spoj.

Komponenta vyžaduje položku pro každý svůj vlastněný objekt. V našem případě kalendář potřebuje položku typu TFieldDataLink pro svůj datový spoj:
class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
  TFieldDataLink *FDataLink;
};
Dříve než můžeme přeložit aplikaci, musíme vložit hlavičkové soubory DB.HPP a DBTables.HPP do hlavičkového souboru naší jednotky.
Každý datový ovladač má vlastnost DataSource, která specifikuje který objekt datového zdroje v aplikaci poskytuje data ovladači. Dále ovladač, který přistupuje k samostatné položce vyžaduje vlastnost DataField ke specifikaci položky datového zdroje. Tyto přístupové vlastnosti neposkytují přístup k vlastněnému objektu sami, ale odpovídajícími vlastnostmi ve vlastněném objektu. Deklarujeme vlastnosti DataSource a DataField a jejich implementační metody a zapíšeme metody jako ?předávající? metody k odpovídajícím vlastnostem objektu datového spoje.
class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
  AnsiString __fastcall GetDataField();
  TDataSource *__fastcall GetDataSource();
  void __fastcall SetDataField(const AnsiString Value);
  void __fastcall SetDataSource(TDataSource *Value);
__published:
  __property AnsiString DataField = {read=GetDataField,
                                     write=SetDataField, nodefault};
  __property TDataSource *DataSource = {read=GetDataSource,
                                        write=SetDataSource, nodefault};
};

AnsiString __fastcall TDBCalendar::GetDataField()
{
  return FDataLink->FieldName;
}
TDataSource *__fastcall TDBCalendar::GetDataSource()
{
  return FDataLink->DataSource;
}
void __fastcall TDBCalendar::SetDataField(const AnsiString Value)
{
  FDataLink->FieldName = Value;
}
void __fastcall TDBCalendar::SetDataSource(TDataSource *Value)
{
  if(Value != NULL)
    Value->FreeNotification(this);
  FDataLink->DataSource = Value;
}
Nyní, když máme vytvořeno spojení mezi kalendářem a jeho datovým spojem, je jeden velmi důležitý krok. Musíme při vytváření ovladače kalendáře vytvořit objekt datového spoje a datový spoj zrušit před zrušením kalendáře.
Datový ovladač vyžaduje přístup k svému datovému spoji prostřednictvím své existence, a musíme tedy vytvořit objekt datového spoje v jeho vlastním konstruktoru a zrušit objekt datového spoje před svým samotným zrušením. Přepíšeme tedy konstruktor a destruktor kalendáře k vytváření a rušení objektu datového spoje.
class PACKAGE TDBCalendar : public TSampleCalendar
{
public:
  __fastcall TDBCalendar(TComponent* Owner);
  __fastcall ~TDBCalendar();
};

__fastcall TDBCalendar::TDBCalendar(TComponent* Owner)
 : TSampleCalendar(Owner)
{
  FReadOnly = true;
  FDataLink = new TFieldDataLink();
  FDataLink->Control = this;
}
__fastcall TDBCalendar::~TDBCalendar()
{
  FDataLink->Control = NULL;
  FDataLink-OnUpdateData = NULL;
  delete FDataLink;
}
Nyní máme kompletní datový spoj, ale nemáme možnost řídit, která data budou čtena z připojené položky.

4. Náš ovladač má datový spoj a vlastnosti specifikující datový zdroj a datovou položku a musíme ještě vytvořit reakce na změny v datech této datové položky, neboť se můžeme přesunout na jiný záznam. Všechny objekty datových spojů mají události nazvané OnDataChange. Když datový zdroj indikuje změnu ve svých datech, objekt datového spoje volá obsluhu událostí připojenou k této události. K aktualizaci ovladače v reakci na datové změny, připojíme obsluhu k události OnDataChange datového spoje.

V našem případě, přidáme metodu DataChange ke kalendáři a určíme ji jako obsluhu pro OnDataChange datového spoje v konstruktoru. V destruktoru musíme obsluhu odpojit a to před zrušením objektu.
class PACKAGE TDBCalendar : public TSampleCalendar
{
private:
  void __fastcall DataChange(TObject *Sender);
};

__fastcall TDBCalendar::TDBCalendar(TComponent* Owner)
 : TSampleCalendar(Owner)
{
  FReadOnly = true;
  FDataLink = new TFieldDataLink();
  FDataLink->Control = this;
  FDataLink->OnDataChange = DataChange;
}
__fastcall TDBCalendar::~TDBCalendar()
{
  FDataLink->Control = NULL;
  FDataLink-OnUpdateData = NULL;
  FDataLink->OnDataChange = NULL;
  delete FDataLink;
}
void __fastcall TDBCalendar::DataChange(TObject *Sender)
{
  if (FDataLink->Field == NULL) CalendarDate = 0;
  else CalendarDate = FDataLink->Field->AsDateTime;
}
Tím je zobrazovací databázový ovladač kalendáře hotov.

5. Pokuste se u právě vytvořené komponenty zadat bitovou mapu zobrazenou na paletě a vytvořit nápovědu, kterou zapojíte do nápovědného systému C++ Builderu.

8. Udělání komponenty dostupné při návrhu