CDE/cde/programs/dtappbuilder/src

%W% %G%

$XConsortium: README.src /main/3 1995/11/06 17:09:47 rswiston $

CDE1.0 Application Builder Source Code Documentation
-----------------------------------------------------------------------
-----------------------------------------------------------------------


This document describes the structure & style guidelines for the source
code of the CDE1.0 Application Builder reference implementation. This
document covers:

I. Source Architecture (libraries & dependencies)
II. Source Directory Structure
III. Style Guidelines
A. Files (.h & .c)
i. naming
ii. structure
B. Functions
i. naming
ii. return values
C. Data
i. naming



I. Source Architecture
----------------------

The Application Builder consists of 2 independent (but tightly
integrated) executables:
. The AB Front-end (ab): the GUI which is used to 'build'
the GUI & application-framework definitions for a CDE
application and write them out into BIL (Builder Interchage
Language) files.

. The AB Code-generator (abmf): the engine which interprets
the BIL files and generates the appropriate Motif/CDE
C code/resource files/etc.

Both of these executables are based on a common internal mechanism
which is implemented in a set of separate libraries. Each library
is composed of one or more logical modules.


libAButil
|
----------------------------------
| | | |
| | libABobj |
| | | |
| | ------------------ |
| | | | | |
| libABobjXm | libABil
| | | |
| | | |
-----------------------------------
| |
Front-end Code-generator
ab . . . . . . . . . abmf


1. libAButil - Provides general purpose utility mechanisms used
throughout the source code, including definitions of
common types and an efficient string-handling
mechanism. This library is window-system/toolkit
independent.

2. libABobj - Provides core mechinism for storing the representation
for an application (and the objects it contains) in
memory. This library is window-system/toolkit
independent ("mechanism", NOT "policy").

3. libABobjXm- Provides engine which manipulates the libABobj data
structures in a way appropriate for, and dependent on,
the Motif toolkit. This library is heavily dependent
on the X11 window-system & the Motif toolkit
(implements the "policy" for libABobj).

4. libABil - Provides the mechanism for translating the libABobj
data structures in memory to disk (reads/writes
BIL, UIL files).




II. Source Directory Structure
-------------------------------

The source code for the CDE Application Builder is organized
in a "flattened" structure corresponding to the architecture
described above. The directory structure looks like the following:

/src
|
-------------------------------------------------------------
| | | | | | | |
/ab /abmf /doc /include /libABil /libABobj /libABobjXm /libAButil
|
------------
| |
ab/ ab_private/


Each directory contains a Makefile, and all header & .c source
files for its modules. The "ab" & "ab_private" include directories
contain symbolic links to the shared header files in each directory
(make include-paths simpler!).

Below is a desription of each directory & the modules it includes:

ab:
pal- implements the mainwindow palette of objects
ab - manipulates the UI objects created by the user
(create, resize, copy, etc)
brws - implements the AB Browser mechanism
conn - implements the AB Connections manager
proj - implements the AB Project mechanism
prop - implements the AB Property Dialogs
help - implements the AB Help Editor
ttalk- implements the AB ToolTalk Editor
abui - implements UI utility routines used by all ab modules
abx - implements X utility routines used by all ab modules

abmf:
abmf - implements the code generator

libABil:
abil - implements generic interchange-language functions
bil - implements reading/writing BIL files
uil - implements reading/writing UIL files

libABobj:
obj - implements the AB object data structures
trav - implements the traversal mechanisms for the 'obj'
data structures

libABobjXm:
objxm - implements Motif-izing 'obj' data structures

libAButil:
abio - implements AB input/output routines
util - implements general-purpose AB utilities
istr - implements the AB string library




III. Style Guidelines
---------------------

Since the Application Builder is a large & complex application
being developed by multiple engineers, a set of coding style
conventions have been adopted in order to make the source more easily
readable.

0. The general C programming style follows the Guidelines
outlined in the "The C++ Programming Style Guide Quick Reference"
(by HP & SunSoft) (except that indent is 4 spaces, not 8).

A. Files
Each module consists of a single public header file, and one or
more private header & source files, as required.

If the module contains a GUI (built with AB), then the module may
also include BIL & AB-generated-source files.

i. naming
a) All files for a module are prefixed by their module-name.
b) The public header file matches identically the module-name.
c) Any private header files are appended with a "P".

e.g. brws module -->>

public header: brws.h
private headers: brws_mthdsP.h
source files: brws.c, brws_mthds.c, ...

bil files: brws.bil
AB-generated: brws_ui.c, brws_stubs.c

ii. structure
All header & source files generally follow the format contained
in the "template.h" & "template.c" files present in each
directory (see those files for details).


B. Functions

Functions are categorized into 3 basic categories:
. public : other modules/libraries may call them
. module-private : only files within the module may call them
. private : static within a file

i. naming
a) All public functions are prefixed with the module name*
b) All module-private functions are prefixed with the module
name + "P"
c) All private functions do NOT have the module prefix,
but have a unique and relatively meaningful name

e.g.
public: objxm_instantiate_obj()
module-private: objxmP_merge_args()
private: destroy_widget_tree()

ii. return values
a) If a function does not return any specific data and is
relatively guaranteed to complete successfully, it is
defined as type "void".
b) Otherwise, it returns an "int" indicating the degree of
success in completing its task, with values >=0 defining
success (the return codes defined in libAButil/[ABerror.h]
are used for consistency).


C. Data

Data is categorized into 3 classes:
. global : other modules within the library/directory can
access them (AVOIDED WHENEVER POSSIBLE!)
. module-global : different files within a module may access
. private : statically defined in a file

i. naming
a) All global data is prefixed with the module name, first
letter capitalized
b) All module-global data is prefixed with the module name
+ "P"
c) All private data is NOT prefixed, but should have a
unique and relatively meaningful name

e.g.
global: Ab_project
module-global: abP_grid_size
private: gbox_gc