Hi Helen,

wouldn't this be another TI or an article worth, because I'm sure
that IBO newbiews won't find *this* posting when getting started
with IBObjects ;-).

Cheers,
Thomas
PS: *Very* neat interview at InterBase-World ;-)

> -----Original Message-----
> From: Helen Borrie [mailto:helebor@...]
> Sent: Tuesday, March 04, 2003 4:29 PM
> To: ibobjects@yahoogroups.com
> Subject: [IBO] About IBO helpfiles, source files, etc. (LONG)
>
>
> Hello all,
> If you are interested to know a few of the less obvious features of the IBO
> help and how it's related to the organisation of the sources, read on. It
> might get quite long...
>
> The Source Files
>
> Source files for some components are found in files which have been split
> up in various ways, using a consistent naming standard to indicate which
> section of a hypothetical larger unit they belong to. As well as .pas
> files, we have also .INT files, containing the declarations for the
> INTerface section, usually for one base component and one or more
> implemented descendant class. So, for example, IB_Bars.INT contains all of
> the declarations for the various "bar" controls.
>
> Wherever you see an INT file, there will be a corresponding IMP
> file. There, you find the IMPlementation code for each of the methods
> declared in the INT file.
>
> The INT file contains also - as comments - all of the text which appears in
> the IBO Help file. You will notice various tags in some blocks of this
> text, some of which you may recognise as HTML and Javadoc tags. I will
> explain later how this text gets into the help file.
>
> If you simply open an INT or IMP file in the Delphi or Kylix editor, it
> appears as plain text - not very useful if you are trying to browse the
> file as code. You can very simply display INT and IMP files with correct
> syntax highlighting by adding these suffixes to the semi-colon-separated
> list in the IDE, Tools > Editor >General tab, in the field labelled 'Syntax
> Extensions'.
>
> To "track" contiguously through the source code for a family of components,
> you can simply start by opening the INT file. By moving the cursor to any
> other unit name and pressing Ctrl-Enter, you can open that file (or move to
> it, if it is already open). You can start in any file, however, and move
> in either direction through the code files.
>
> Each of the IBO code files uses a convention of placing, in curly braces,
> the name of the preceding file at the top of the file, and the name of the
> next file at the bottom. The Ctrl-Enter technique works equally well on
> these tags. You will generally find links to .pas files as // comments,
> listed in the body of the INT file, beneath the uses clause.
>
> An extra level of naming convention applies to several component
> groupings. INT and IMP files that contain the native data access classes
> begin with "IBA_". Those for the native IBO data access controls begin
> with "IBC_". The base classes for the forms that are used in the property
> editors and in some of the demo apps are in complete .pas units beginning
> with "IBF".
>
> Why are the units broken up in this way?
>
> The main reasons for breaking up the units are the hugeness of the IBO code
> base and the depth of many of the main class hierarchies. It makes the
> maintenance of the code simpler and - once you understand how it all hangs
> together - it makes it easier for you to find the blocks of code you are
> looking for, without having to wade through the enormous "hypothetical"
> unit. There are other reasons, related to the inheritance tree,
> version-conditional code and code re-use, that make the splitting of the
> files useful.
>
> Each of the huge "hypothetical" units has a stub .pas file which has
> tag-links to all of the INT, IMP and other .pas files that belong to
> it. You can identify which stub .pas file you are looking for, by
> inspecting the main page of the help file for the class you are interested
> in, high up on the page under the heading "Unit".
>
> For example, the help file names IB_Components[.pas] as the unit where
> TIB_Dataset is defined. Open IB_Components.pas, and you will be able to
> link to the INT and/or IMP files for TIB_Dataset {IBA_Dataset.INT} and
> {IBA_Dataset.IMP} (or one of many other components, of course).
>
> The IBO Help file
>
> The comment blocks in the INT files follow some special tagging and format
> conventions because these comments are picked up in the generation of the
> IBO Help files and transformed into help text. We use an extremely smart
> help generator by a Norwegian company name Digital Logikk. The developers
> - Jarle Stabell and Svein Glenndal - have been working together on this
> Delphi tool for almost as long as Delphi has existed. The tool is called
> Time2Help. I have been privileged to be involved in beta-testing T2H since
> 1998.
>
> It is a highly object-oriented tool which uses the syntax of the Delphi
> code itself to generate the entire skeleton help file. It automatically
> places the tagged comment blocks into the help file it generates. It can
> also incorporate extra, external files hyperlinked and compiled as popups.
>
> The most recent versions of T2H use XML to construct the elements from the
> source code. Custom XML templates can be made, using a text editor, to
> include just about any kind of extra documentation: images, code samples,
> how-tos...
>
> The structure of a T2H helpfile is more object-oriented than the
> conventional help files that you generally find in Delphi and in other
> component suites. It happens to suit IBO very well, because IBO's
> structure is very strict about adhering to OO rules. That means that a
> newbie may need to practise a little to begin with, to work out where
> apparently "missing" help items are.
>
> The T2H hyperlinking is very faithful to the hierarchy of the component
> classes. Jason's INT comments follow the hierarchy closely. As a general
> rule, if you don't find what you are looking for at the item you are
> interested in, you will find hyperlinks on the page to take you there. If
> you don't see them in the main text, you will find them by clicking on the
> Hierarchy button in the toolbar.
>
> One of the files generated by Time2Help is a visual representation of the
> entire hierarchy, which you can use as an optional interface to the WinHelp
> file. It has the same name as the .hlp file, with the extension
> .T2H. Digital Logikk provides a freely distributable runtime library for
> use with the .T2H file. If there is interest in having these two files
> available for download, I will add them to the Downloads page.
>
> TIB_* Native Data-aware Controls
>
> In most cases, the native data aware controls descend from custom VCL
> control classes. Properties and methods that appear undocumented in the
> IBO Help will usually be found in the custom VCL ancestor control class.
>
> You may notice some properties with names similar to protected ancestor
> properties. If they are similar, but not exactly the same, you are looking
> at a new property that is similar, but with extra capability not able to be
> implemented from the original property. For example, TIB_Grid implements a
> set property named DrawCellTextOptions, which offers a set of default
> attributes for grid cells that combines some useful features that you might
> otherwise code individually in the OnDrawText Event and the Options
> property of the TCustomGrid ancestor.
>
> If you are using the native IBO components and TIB_Grid, be prepared for
> some surprises. In IBO, the datasets drive the controls, not the reverse
> as is true of the Delphi VCL and well-known TDataset-compatible third-party
> grids. There is no Columns[] property where you set the individual grid
> column attributes: these are all set on the data columns, in the dataset
> property editor.
>
>
> The TDataset-compatible components
>
> Because these components are TDataset descendants, much of their help text
> can be found in the ancestor classes, located in the Delphi
> helpfile. However, many of the TDataset-compatible classes carry
> properties inherited from the native IBO classes which are embedded in
> them. Because these members (properties and methods) are implemented as
> wrappers, T2H does not pick them up when it builds its class
> hierarchies. You need to go to the wrapper classes themselves to find the
> documentation for these members:
>
> Data access classes all descend from TIBODataset, which is wrapped by
> TIB_BDataset.
> TIBODatabase is a descendant of TIB_Database, which wraps a
> TIB_Connection and a TIB_Transaction.
> TIBOTransaction is a descendant of TIB_Transaction.
>
> What can you do if you can't the find the help you need?
>
> TechInfo sheets (TI Sheets)
> The IBO helpfile is so large, that we have needed to economise on its size
> over time. Many of the How-To documents that used to be in the help file
> are now downloadable as TechInfo sheets from the TechInfo page of the website.
>
> Online FAQ
> Here we have about 1000 short articles in a searchable database, running
> under an IBO web application. Most of these articles started life as
> threads in this list.
>
> Getting Started Guide - "GSG"
>
> Covers the "big hump" of getting acquainted with the very different ways
> that IBO implements client/server connectivity. It is not a substitute for
> the help file and it doesn't cover everything you will ever need to know to
> make the most of IBO. It will help you to understand IBO's connectivity
> model, the concepts of using data-driven visual controls and working in a
> transaction-aware client/server environment. It is not free.
>
> The GSG is currently close to a new revision. However, don't let that stop
> you from subscribing to it now. A one-off subscription to the GSG entitles
> you to download all revisions at no extra cost.
>
> I hope this helps to clear up a few difficulties some of our newer uses are
> having.
>
> regards,
> Helen
>
>
>
>
>
> ___________________________________________________________________________
> IB Objects - direct, complete, custom connectivity to Firebird or InterBase
> without the need for BDE, ODBC or any other layer.
> ___________________________________________________________________________
> http://www.ibobjects.com - your IBO community resource for Tech Info papers,
> keyword-searchable FAQ, community code contributions and more !
>
> Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
>
>
>