249 lines
7.4 KiB
Plaintext
249 lines
7.4 KiB
Plaintext
%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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|