intro_oocbs (ul_oocbs)


	intro_oocbs

	Object Oriented Colliding Beams Software (OOCBS) is a class library for
	console applications.

	It builds on UL_OBJECTS, a class library for any application.
	
	An object is a data structure that contains both data and pointers
	to methods for manipulating that data (look at any _H topic).  It
	belongs to a Class.  For example, you may want a Matrix called
	new_matrix that belongs to the class Complex_Matrix, with methods for
	inverting it, taking its determinant, etc.

	In effect, an object is a data structure, methods are functions that
	take the data structure as an argument and a class is the data type
	of the data structure.

	Objects are intended to be "black boxes".  All you need is a pointer
	to the object, a statement creating it, and you can call its methods.

   1. Using Classes and Objects

	You use UL_OOCBS by including a
		
		#include "UL_OOCBS:my_favourite_class.h"

	statement in your header file (preferred) or program file for each
	class you wish to use.

	You must create an object before you use it:

		My_Favourite_Class *new_object;	(* note pointer declaration*)
		new_object = create_My_Favourite_Class(... initial data ...);

	You may then use any method you wish with the following syntax:

		(*new_object->desired_method)(new_object, ... other args ...);

	The object is always the first (and often only) argument.  The reason
	for the function pointer construction is to allow several objects to
	use the same name for there methods. 

	You may read or set private data (discouraged) by the syntax:

		new_object->private_datum = my_preferred_value; or
		what_id_like_to_know = new_object->private_datum;

	For certain common methods shared by several classes (e.g. DESTROY)
	there are macro shortcuts.  These are located in UL_OBJECTS:hello.h.
	To use the shortcut just say

		DESTROY(my_defunct_object); (* note capital letters *)
	
	Some objects may define special macro shortcuts in their include 
	files.  See the _Class help file for syntax details.

	All objects have three integers associated with them: an error code,
	a system error code, and a type.

		stat = CHECK(my_object); (* returns error code *)
		stat = CBS_CHECK(my_object); (* returns system code *)

	You may set error codes via:

		stat = ERROR(my_object,code);
		stat = CBS_ERROR(my_object,cbs_error);


   2. Available help:

	For a general description of the class <Class_Name> and syntax for 
		its methods  see <Class_Name>_Class.
	For class definitions see the <Class_Name>_H help topic.
	For help creating the object, see create_<Class_Name>.
	
   3. Creating Your Own Classes:

	Copy ooshell.hsav and ooshell.csav from usr$diska:[jgoodwin.oocbs] 
	to your working area and modify.  It is recommended that 
	you look at a class definition first.
	
	To submit: $MECCA UL_OOCBS, then $MECCA/GEN UL_OOCBS.

   4. Coding Standards:

	a.  variables begin with small letters
	b.  classes (typedefs) have the form My_New_Class (mixed caps and 
		underscore).
	c.  macros that are shared by all objects (defined by 
		UL_OBJECTS:hello.h) are all caps: DESTROY, UPDATE.
	d.  macros that are special to a Class are in form goGetDataForMe(),
		TVErasePlease(), or setColor().
	e.  all classes have a header file that points to 
	f.  header files follow ooshell.h rigidly.
	g.  every class My_Stuff has the following help topics:  
		My_Stuff_h (copies header), create_My_Stuff, and My_Stuff_Class.
	h.  every object has the data included via REGISTERED_OBJECT macro.
		to enable error handling and type codes.
	i.  classes which create storage via malloc are responsible for 
		freeing it.

   LAST MODIFIED:  	15 OCT 1992
   SOURCE:		intro_oocbs.h