Contents
---------------
1. [API Assistant]
2. [API Assistance]
3. [API Assistance On Dialog]
4. [Configure API Index File Dialog]
5. [API Assistant Database Utilities]

************************************************************************

[API Assistant]

CodeWright's API Assistant is an editing tool that helps complete and
insert functions and other common source code elements, with their
appropriate parameters, at the current document's cursor position.
Default API Assistant support is provided for Windows API, CodeWright
API, Microsoft Foundation Classes, standard C library functions, Java
functions, Sun Java functions, HTML tags, and Delphi functions.

To access the API Assistant, go to Help|API Assistance On

************************************************************************

[API Assistance]

You will find on the help menu the item 'API Assistance on...' This item
will provide you with help in completing a call to a subroutine or
function, if such help is available.  Currently, help is provided on the
Windows API, Standard C Library functions, Microsoft Foundation Classes,
HTML tags, Delphi, standard Java, Sun Java, and the CodeWright API. 

You can create your own customized API Assistant database files using
the API Assistant database utilities provided. 

Using the API Assistant 

To use the API Assistant, complete the following steps:
1.  Place the cursor at the end of the text for which help is being
sought.

2.  Select 'API Assistance On' from the Help menu. If there is a word
near the cursor when you do this, CodeWright will attempt to locate
assistance for that word.  If no word is nearby, you are prompted for a
subroutine or function name to look up.  

3.  If more than one occurrence of the word is found, select the
appropriate item in the list. 

4.  Fill out the form that displays.  There is an edit box, and a series
of either checkboxes or radio buttons, for each parameter used by the
subroutine or function.  Each edit box or set of buttons lists the
parameter type.  This makes it simple to ensure that all necessary
parameters are supplied, and are of the correct type.  If you need
additional information, press the Help button and you will see the
Windows API Help entry, or other helpfile entry, for that subroutine or
function.

5.  When the form is completed, press OK and the information you have
provided is assembled into a complete function call, including commas
and parentheses, and is inserted into the document.  

************************************************************************

[API Assistance On Dialog] 

The 'API Assistance On...' item on the Help menu lets you look up a
keyword or topic in one or more Assistance databases.  To set up an
Assistance list, use the 'Configure API Index File...' item on this 
menu.

This dialog is almost identical to the 'Search for Help On' dialog,
which is also on the Help menu.  While it uses similar technology, the
purpose of the two should not be confused.  The help index lets you view
information of almost any type in helpfiles.  The API Assistant actually
helps you complete function calls.

Assistance Keyword 
This is where you enter the keyword to look for, normally a function
name.  When you start typing, CodeWright automatically presents a list
of all Assistance Database files that contain the word you are typing.
The list appears in the listbox at the bottom of the dialog. 

Found in these Files - Select One: 
As you type into the Assistance Keyword field, keywords appear in this
listbox that match whatever is in that field at the moment.  The more
you type, the more exact the match.  The keyword appears on the left
column.  A brief description of the Assistance Database file in which it
was found appears on the right.

************************************************************************

[Configure API Index File Dialog]

CodeWright uses index (.TDX) files to match keywords (function names)
to Assistance Databases.  The 'Configure API Index File' item on the
Help menu allows you to customize the API Assistance index file.  The
index keeps track of which Assistance Database contains information  for
which functions. You cannot modify the databases from this  dialog, just
the index.

Assistance Database List 
The Assistance Database list shows all the assistance databases that
CodeWright knows about. 

Show Keywords 
If the Show Keywords checkbox is checked, then the list box will show
all the keywords defined in the selected assistance database.

Database Search Path 
This shows the path that CodeWright uses to find the database files.
When you invoke API Assistance, CodeWright looks in its TDX file for the
function name under the cursor.  The TDX file entry tells CodeWright
which assistance database lists that keyword. CodeWright then looks for
that database on the path specified in the Search Path display.
Semicolons separate the directories.

Edit  
This button brings up a dialog that allows you to modify the assistance
database name and its description.  The description appears in the API
Assistance On dialog when you invoke the API Assistant.  The file name
here is the name that CodeWright will use to find the database file.

Add 
Add an assistance database to the list.  This button presents a dialog
that lets you select a CodeWright Assistance Database to add to the
assistance database index.  These files have the extension .TDB. The add
operation will scan their contents and add them to the index for you.

You can download additional .TDB files, when available, or create them
yourself using the automation tools provided.  See the topic API
Assistant Database Utilities for details.

Remove 
Remove an assistance database from the list.  The selected database is
deleted from the list without further prompting.

Export 
Convert a function index to Help Information File (.HIF) format.
CodeWright uses Assistance Database Indexes (.TDX) to look up function
(keywords) in help files.  Each .TDX file can serve as a master index
for many assistance databases.  This operation extracts the keyword list
for the selected help file, and saves this list in HIF format.  It
brings up a dialog, which lets you specify a destination for the
converted file.  Since the HIF file is plain text, you can add entries
to it using any text editor.

Move Up 
This button moves the currently selected assistance database one place
closer to the top of the list.  Keywords are searched in the order that
their databases are listed, so its best to place most frequently used
files at the top, in case of duplicate keywords.

Move Down 
This button moves the currently selected assistance database one place
closer to the bottom of the list.  Databases not frequently used should
be placed at the bottom.

Load 
You can keep more than one TDX file on your system. Use the Load button
to get a dialog that will let you browse for a TDX file to load.

Save 
When you press the Save button, all the changes that you have made in
this dialog will be saved to the current TDX file.

Close 
The Close button will exit the dialog without prompting.  If you have
not saved your settings, they will be discarded.

************************************************************************

[API Assistant Database Utilities]

You can create your own customized API Assistant database files for use
with CodeWright. 

Database files are already provided for the Windows API,  C/C++ Library
functions, Microsoft Foundation Classes, HTML 3.0, Delphi, standard
Java, Sun Java, and the CodeWright API.  You can add function templates
to an existing database file using CWTEDIT.EXE, or you can create new
database files from scratch using the command line utilities provided.

The command line utilities for creating API Assistant Databases can be
found in the \ASSIST subdirectory under CodeWright's home directory.
Sample AWK scripts used to generate the various input template files
from the original header files are also located in the \ASSIST
subdirectory.

Assistant Database Utilities
Refer to the following available utilities:

MKTDB.EXE
    Generates a Database File (.TDB) from an Input Template File.

    MKTDB accepts an input template file (see description below) and 
    generates a CodeWright API Assistant database file (.TDB).
    Syntax:
        <cwdir>\ASSIST\mktdb.exe   <template-file> <template>.tdb

DUMPTDB.EXE
    Dumps a Database file (.TDB) into a Template File.
    
    DUMPTDB reads an existing database file (.TDB) and generates the 
    template file records it was created from. It is useful for making 
    global changes, additions, etc.
    Syntax:
        <cwdir>\ASSIST\dumptdb.exe <template>.tdb  <template-file>

AWK Scripts
    Create Input Template Files for use by MKTDB.EXE.
    
    Sample AWK scripts are provided in the ASSIST subdirectory.  
    Each AWK script processes a different style of header file, so be
    sure to read the comments in the file regarding the expected
    source format.
    Syntax (typical, using redirected I/O):
        awk -f <awk-script>  < <header-file> > <template-file>

CPP2DB.EXE
    Converts CPP header or source files to template files.
    
    CPP2DB reads an existing CPP header file and converts it to a 
    template  file. The template file can then be converted to an API
    Assistant database file (.TDB) file using MKTDB.EXE.
    Syntax:
        Cpp2db cpp2db.awk < <headerfile> > <templatefile>

API2DB.EXE
    Reads APIs from existing header or source files into template files.
    
    API2DB reads an existing header file and converts it to a template 
    file. The template file can then be converted to an API Assistant
    database file (.TDB) file using MKTDB.EXE.
    Syntax:
        API2db API2db.awk < <headerfile> > <templatefile>

CAPI2DB.EXE
    Reads APIs from existing header or source files into template files.
    
    CAPI2DB reads an existing header file and converts it to a template 
    file. The template file can then be converted to an API Assistant 
    database file (.TDB) file using MKTDB.EXE. 
    Syntax:
        CAPI2db CAPI2db.awk < <headerfile> > <templatefile>

Template Files
    Function Definition Records. 

    The input template files are usually generated by AWK scripts, 
    which convert header files into the required template record
    format.  Template files contain three 'records' of text for each
    function.  All three records comprise one function template
    definition:
        <function name>
        <length of the following template>
        <The actual template (it can span multiple lines)>
    The MKTDB program processes the template file one record at a time 
    and  adds the template definition to the API database file.

    Example:

    GetVersion
    100
    %DLG:%DEFR:DWORD   WINAPI$%DEFF:GetVersion$%DEFPL:($%DEFPS:,
    $ %DEF:\tvoid$ %DEFPR:)$%DEF1:\nvoid,eb$

    The format of the template record contains %DLG: and %DEF<x>: 
    macros, which are documented in cwstart\language.c.

    %DLG:       Defines a dialog.  Everything else in the template will
                appear in the dialog.
    %DEFF:<s>$  Defines a function with name <s>.
    %DEFC:<s>$  Defines a class name with name <s>
    %DEFT:<s>$  Defines a template which is executed when dialog is 
                complete.
    %DEFR:<s>$  Defines the return type, where <s> is the return string 
                displayed in the dialog.
    %DEF:<s>$   Defines a parameter with name <s>.
    %DEF<#>:<s>$    Defines a parameter, where <#> is the parameter 
                number and <s> is a string defining the type of
                parameter and its initial value(s).
    %DEFPO:<s>$ Defines the parameter binary OR operator which is used 
                when multiple radio button items are selected (usually
                '|' for 'C' type functions).
    %DEFPL:<s>$
    %DEFPS:<s>$
    %DEFPR:<s>$ Defines Left (usually '('), right (usually ')'), and 
                parameter separator (usually ',') for the function
                definition. 
            
The order of these macros is important and you should follow the
examples defined in the template files generated by the sample AWK
scripts or dumped by TDBDUMP. If you are having problems, try the
following steps:

1.  Use the CWTEDIT.EXE program to add one of your new functions to an 
    existing database.

2.  Run TDBDUMP against the modified database.

3.  Examine the resulting template definition records for your new 
    function(s) to see what it generates.

4.  Modify your template files (or the AWK script that creates them) to 
    produce the required record formats.


CodeWright  2001, Borland Corporation.  All Rights Reserved.
