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