%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



		   







