home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 March / Chip_1998-03_cd.bin / zkuste / delphi / qdb / QDBVCLD3.ZIP / qdbpanel.txt < prev    next >
Encoding:
Text File  |  1997-11-20  |  7.3 KB  |  226 lines
  1. QDBPanel v2.00 Beta Release 3
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. This is the third beta release of QDBPanel for QDB v2.00. QDB itself is 
  5. now ready for release but QDBPanel remains in beta for a while longer as
  6. certain design issues still need to be addressed.
  7.  
  8. There is no help file for this release -- this file will have to serve 
  9. for the moment.
  10.  
  11. Please be aware that you are quite likely to find bugs or other problems. 
  12. Please let me know about them at rrm@sprynet.com. Thanks for your help. 
  13. If you have any ideas for QDBPanel send them along too. A related 
  14. component, QDBGrid, is still in the alpha stage.
  15.  
  16. QDBPanel, which remains free, is Copyright (c) 1997 Robert R. Marsh, SJ & 
  17. the British Province of the Society of Jesus.
  18.  
  19.  
  20. Usage
  21. ~~~~~
  22. The QDBPanel simplifies the storage and retrieval of items via QDB. You 
  23. just drop a QDBPanel on a form and place on it whatever components you 
  24. wish to use. The panel knows how to save and load the controls' contents 
  25. in a QDB file. QDBPanel knows how to handle most common controls: those 
  26. which derive from TCustomEdit, TRichEdit, TCustomRadioGroup, 
  27. TCustomCheckBox, TCustomComboBox, TCustomListBox, & TImage. Other controls
  28. (like TLabel) are ignored. Controls contained by a TPageControl are also
  29. stored but not those handled by TTabNotebook.
  30.  
  31. If you want to store other data but don't want it to be visible at run-
  32. time you can drop an ordinary panel on the QDBPanel and set its Visible 
  33. property to false. Any controls dropped onto this "invisible" panel
  34. will be stored along with the visible ones.
  35.  
  36. On the other hand, if you want some controls on the QDBPanel to be 
  37. visible but not stored you can enclose them in an ordinary panel with its
  38. Tag property set to -999. The controls will still be visible and 
  39. available but they will not be included in the QDB. Individual controls 
  40. can be excluded in the same way by setting their Tag to -999.
  41.  
  42.  
  43. QDBPanel has the published properties:
  44.  
  45.   Enabled: boolean;
  46.     Enables/disables the panel and all the controls on it.
  47.  
  48.   ExcludeTag: longint;
  49.     The value of the tag used to signify a control should be 
  50.     excluded.
  51.  
  52.   FieldCount: integer;
  53.     The number of fields defined by the panel. (read-only)
  54.  
  55.   FieldNames[index: integer]: string;
  56.     The names of the fields (i.e., the control names). (read-only)
  57.  
  58.   QDB: TQDB;
  59.     The QDB file associated with the panel.
  60.  
  61. QDBPanel requires a handler for the OnKey event:
  62.  
  63.   OnKey: procedure (Sender: TObject; var key: TKey) of object;
  64.     which is called by the Fetch method (see below) to collect a key by 
  65.     which to store and retrieve an item.
  66.  
  67. QDBPanel has the following public methods:
  68.  
  69.   procedure Clear;
  70.     Clears all the controls placed on QDBPanel.
  71.  
  72.   procedure Store;
  73.     Stores the contents of the controls on the panel to the QDB file.
  74.  
  75.   procedure Fetch;
  76.     Loads the current item of the QDB file into the controls on the 
  77.     QDBPanel.
  78.  
  79.   procedure Post;
  80.     If Enabled saves the panel item to the QDB and makes Enabled false.
  81.  
  82.   procedure Edit;
  83.     Sets Enabled true to allow editing of the panel item.
  84.  
  85.   procedure Cancel;
  86.     Cancels editing and reloads the panel item.
  87.  
  88.   procedure Insert;
  89.     Clears the panel and allows editing.
  90.  
  91.   procedure Refresh;
  92.     Reloads the panel item.
  93.  
  94.   procedure Delete;
  95.     Deletes the current item, turns off editing and loads the new item 
  96.     onto the panel.
  97.  
  98.   procedure FirstItem;
  99.     Loads the first item of the QDB file onto the panel.
  100.  
  101.   procedure PrevItem;
  102.     Loads the previous item of the QDB file onto the panel.
  103.  
  104.   procedure NextItem;
  105.     Loads the next item of the QDB file onto the panel.
  106.  
  107.   procedure LastItem;
  108.     Loads the last item of the QDB file onto the panel.
  109.  
  110.   function FileIsValid: boolean;
  111.     (has been removed for the moment will probably return!)
  112.  
  113. Extending QDBPanel
  114. ~~~~~~~~~~~~~~~~~~
  115. If the controls you wish to use with QDBPanel descend from the default 
  116. controls listed above, there is nothing more you need to do. Just drop
  117. them on the panel and that's it. You can, however, override and extend 
  118. the default behaviors if necessary.
  119.  
  120.   procedure RegisterProcs(AClass: TControlClass; ClearProc, FetchProc, 
  121.                                  StoreProc: TClassProc);
  122.  
  123. If you wish to override the default storage behavior of already 
  124. registered controls or to provide instructions for handling other kinds of
  125. controls you use the RegisterProcs method to pass along three procedures 
  126. of type TClassProc:
  127.  
  128.   type TClassProc = procedure(AControl: TControl; Stream: TStream);
  129.  
  130. The ClearProc clears the control, FetchProc loads its contents from 
  131. Stream, and StoreProc saves to Stream. The most recently registered 
  132. procedures take precedence, permitting default behaviour to be overridden.
  133. For example, an edit box saves its contents as text but you may have a
  134. descendant of TCustomEdit, TIntegerBox that handles integers. By 
  135. registering new procedures for TIntegerBox it can be made to store its
  136. data in a new format while retaingin the default bahavior for all other
  137. edit boxes.
  138.  
  139. By default, Edit components store their text. The radio group and check 
  140. box store their state. Combo boxes store the chosen text while list boxes
  141. record which list items are selected. Images ...
  142.  
  143. The following examples illustrate how TCustomRadioGroup and TCustomEdit
  144. are handled.
  145.  
  146. RegisterProcs(TCustomEdit,ClearCustomEdit,FetchCustomEdit,StoreCustomEdit);
  147.  
  148. procedure ClearCustomEdit(AControl: TControl; Stream: TStream);
  149. begin
  150.   (AControl as TCustomEdit).Text := '';
  151. end;
  152.  
  153. procedure FetchCustomEdit(AControl: TControl; Stream: TStream);
  154. var
  155.   con: TCustomEdit;
  156.   p: pchar;
  157. begin
  158.   con := (AControl as TCustomEdit);
  159.   p := StrAlloc(Stream.Size);
  160.   try
  161.     Stream.ReadBuffer(p^, Stream.Size);
  162.     con.SetTextBuf(p);
  163.   finally
  164.     StrDispose(p);
  165.   end;
  166. end;
  167.  
  168. procedure StoreCustomEdit(AControl: TControl; Stream: TStream);
  169. var
  170.   con: TCustomEdit;
  171.   len: longint;
  172.   p: pchar;
  173. begin
  174.   con := (AControl as TCustomEdit);
  175.   len := con.GetTextLen + 1;
  176.   p := StrAlloc(len);
  177.   try
  178.     con.GetTextBuf(p, len);
  179.     Stream.Write(p^, len);
  180.   finally
  181.     StrDispose(p);
  182.   end;
  183. end;
  184.  
  185. RegisterProcs(TCustomRadioGroup,ClearCustomRadioGroup,FetchCustomRadioGroup,StoreCustomRadioGroup);
  186.  
  187. procedure ClearCustomRadioGroup(AControl: TControl; Stream: TStream);
  188. begin
  189.   TRadioGroup(AControl).ItemIndex := -1;
  190. end;
  191.  
  192. procedure FetchCustomRadioGroup(AControl: TControl; Stream: TStream);
  193. var
  194.   n: longint;
  195. begin
  196.   Stream.ReadBuffer(n, SizeOf(n));
  197.   TRadioGroup(AControl).ItemIndex := n;
  198. end;
  199.  
  200. procedure StoreCustomRadioGroup(AControl: TControl; Stream: TStream);
  201. var
  202.   n: longint;
  203. begin
  204.   n := TRadioGroup(AControl).ItemIndex;
  205.   Stream.WriteBuffer(n, SizeOf(n));
  206. end;
  207.  
  208. Finally a note about the default handling of TImage descendants. 
  209. QDBPanel knows how to load and save bitmaps, metafiles, and icons
  210. but you may, for example, have added support for jpeg files. You must 
  211. tell QDBPanel of added graphic formats using the RegisterGraphicFormat
  212. method:
  213.  
  214.   procedure RegisterGraphicFormat(AExtension: string; AGraphicClass: TGraphicClass);
  215.  
  216. For example, to register the new Delphi 3 jpg format you would write:
  217.  
  218.   RegisterGraphicFormat('jpg',TJPEGImage);
  219.  
  220.  
  221. TQDBPanel is still being developed. I hope it looks useful. The new demos
  222. (add_book.zip and animals.zip) show how easy it is to use,
  223.  
  224. Robert R. Marsh, SJ
  225. 17th November 1997
  226.