.if n .pH ref.object @(#)object	40.1

.ig
imagen 8/31/89
docformat -c -s4 -dqm4 -p1 object
..
.SO mstr.hdr
.ds Lb Shapes
.BK "Shapes Reference Manual"
.\" turn off automatic hyphenation -- JHevelin (08-09-89)
.am RT
.nh
..
.nh
.\" BEGIN SHAPES------------------------------------------------
.if !"\*(Lb"Paint" \{\
.br
.CH "Object Operators" "10"
.H 1 "Object Operators" 
.H 2 "Introduction"
.P
Shapes is object-oriented:\ \&
it functions as a set of \f2operators\fP that
send messages to the Shapes \f2objects\fP.
The data area of a Shapes object is not directly accessible;
individual attributes are inquired via ``Get'' operations.
The internal format and implementation of Shapes
objects is not public and may vary widely across devices.
.P
All object operators are implemented by C macros,
and some operations are done completely with macros.
For example, most Get operators reference the
structure field representing the attribute being gotten.
.P
The majority of operations on Shapes objects
result in subroutine calls that are dispatched
through a table of pointers to functions that
implement the operation.
Each object has a pointer to the function table
defining its implementation.
Different objects of the same class may reference
different function tables,
allowing objects to have device-dependent behavior.
For example, a screen raster associated with a
monochrome display would have a different
dispatch table from one associated with a color display.
.H 2 "Allocating Objects"
.P
Shapes provides a mechanism for creating, destroying,
and extending memory-based data objects.
This \f2object manager\fP is the basis on which
all Shapes objects are built.
The object manager hides the details of memory
management from the caller so that different
schemes may be supported.
The current memory management scheme is based on
reference counting and uses the ``palloc'' allocator.
Shapes can also be configured to use the standard
UNIX malloc routines.
.H 2 "Creating and Destroying Objects"
.P
When an object is created,
an \f2object ID\fP is returned.
This descriptor
is represented by type OBJID.
The actual C type associated with
OBJID is implementation-dependent.
All implementations guarantee that NULL is not a
valid object ID,
but rather indicates an object cannot be created.
.P
The size of an object is determined when it is
create and cannot be changed;
it may, however, be replaced by an object of a
different size.
This distinction is important when you consider
subsequent references to an object.
If an object is re-sized,
it will not have the same object ID;
the re-sizing process will produce a different handle.
Shapes objects that grow dynamically, such as paths,
are implemented via two objects:\ \&
a fixed size header object which references a
variable size data object.
.P
The object manager maintains a reference count
for each object.
When an object ID is stored in another object,
the reference count is incremented.
When an entry that contains an object ID is
assigned a new value,
the reference count is decremented.
If it goes to zero,
the memory associated with the old value is freed.
.P
For an example, examine the following:
.SS
	ras = Create_Raster(RAS_TYPE_SCREEN);
				/* ras ref count = 2 */
	ctx = Create_Context(CTX_GENERIC, ras);
				/* ref count = 3 */
				/* ctx->CTX_RASTER points */
				/*to same object as ras  */
	Destroy_Raster(ras);			
				/* ref count = 2 */
		.
		.
		.
	Display_Context(ctx);
				/* ctx->CTX_RASTER is still valid */
	Destroy_Context(ctx);	
				/* Now the raster can be destroyed */
				/* as ref count < 2 means destroy */
.ft1
.SE
In the above example,
the object pointed to originally by \f2ras\fP is
needed after the Destroy_Raster() command because
the context, ctx->CTX_RASTER,
still refers to it specifically.
In this instance,
the Destroy_Raster command only decrements the
raster object reference count.
.P
Although it is easy to circumvent this macro and
have your code work initially by just setting the
objptr to point to the object,
the long range effect is the unpredictable
disappearance or lingering of memory.
Don't neglect to use the Assign_Obj macro where appropriate.
.IX "object operators"
.H 4 "NAME"
.P
Assign_Obj \- Assigns an object to a pointer.
.IX "Assign_Obj"
.tm .CE U 3 "Assign_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Assign_Obj\f2(objptr, obj)\f1
.br
OBJID *objptr;
.br
OBJID obj;
.H 4 "DESCRIPTION"
.P
Assigns an object to a pointer.
The old object referred to by the object pointer
is removed (dereferenced) by a Destroy_Obj call
and the new object is referenced by a Use_Obj call.
.AB C
This macro has side effects.
It expands both arguments more than once.
.AC
\f2objptr\f1
The pointer to an object ID (the object handle).
\f2obj\f1
The object ID of the object to be assigned.
.H 4 "RETURNED VALUE"
.P
OBJID *
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
Create_Obj \- Creates and initializes an object
of the given class.
.IX "Create_Obj"
.tm .CE U 3 "Create_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Create_Obj\f2(class, type)\f1
.br
CLASS class;
.br
OBJ_type type;
.H 4 "DESCRIPTION"
.P
Creates an object of the designated type within
the specified class.
The object has an initial reference count of 1.
.P
\f2class\f1
Specifies the class to which the new object belongs.
.P
\f2type\f1
Specifies the type of device the new object will be used on.
.H 4 "RETURNED VALUE"
.P
OBJECT
.H 4 "SEE ALSO"
.P
Call_Class
.H 4 "NAME"
.P
Destroy_Obj \- Destroys the reference to an object.
.IX "Destroy_Obj"
.tm .CE U 3 "Destroy_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Destroy_Obj\f2(obj)\f1
.br
OBJID obj;
.H 4 "DESCRIPTION"
.P
Decrements the reference count and frees the
object and its resources if all references are gone.
If other objects refer to the specified object,
the resources are not freed until the references
are removed.
Destroy_Obj only works on objects that are
reference counted:
.br
CMAP
.br
CONTEXT
.br
RASTER
.br
PATH
.br
PATTERN
.br
TRANSFORM
.P
Destroy_Obj does not work for GLYPH, POINT, COLOR, or PATH_READER.
.P
This operator calls the destroy function in the
object's function table to free the objects resources.
The destroy function is always the first function
in the dispatch table.
The operator ID for destroy is the same for all
objects:
.DS
     xxx_OP_Destroy==0
.DE
\f2obj\f1
Specifies the ID of the object.
.H 4 "RETURNED VALUE"
.P
[None]
.H 4 "SEE ALSO"
.P
Create_xxx
.br
Use_Obj
.br
Assign_Obj
.H 4 "NAME"
.P
Extend_Obj \- Extend an existing object.
.IX "Extend_Obj"
.tm .CE U 3 "Extend_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Extend_Obj\f2(obj, n)\f1
.br
OBJID obj
.br
unsigned int n;
.H 4 "DESCRIPTION"
.P
Extends the size of an existing object, making it larger.
The object may need to be copied to a different memory
area to be extended.
The excess entries are
.UI "not"
zeroed.
.P
If an object's flag is marked OBJ_NOSHRINK,
Extend_Obj will return without enlarging the object.
.P
\f2obj\f1
Specifies the object ID of object to be extended.
.P
\f2n\f1
Specifies the number of bytes to extend the object.
This is in addition to the amount of storage already being used.
.H 4 "RETURNED VALUE"
.P
OBJID, NULL is returned if an error occurs.
.H 4 "SEE ALSO"
.P
Size_Obj
.br
Create_Obj
.H 4 "NAME"
.P
Get_Obj \- Returns the setting for the specified attribute.
.IX "Get_Obj"
.tm .CE U 3 "Get_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Get_Obj\f2(obj, attr)\f1
.br
OBJID obj;
.br
OBJECT_attr attr;
.H 4 "DESCRIPTION"
.P
Returns the setting for the specified attribute.
.P
\f2obj\f1
Specifies the ID of the object for which the
attribute setting is to be returned.
.P
\f2attr\f1
Specifies the attribute for which the setting is to be returned.
.H 4 "RETURNED VALUE"
.P
Attribute setting
.H 4 "SEE ALSO"
.P
Set_Obj
.br
Get_Class
.H 4 "NAME"
.P
GetOper_Obj \- Returns a pointer to the function
that currently implements the operator for the
specified object.
.IX "GetOper_Obj"
.tm .CE U 3 "GetOper_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3GetOper_Obj\f2(obj, opID)\f1
.br
OBJID obj;
.br
int opID;
.H 4 "DESCRIPTION"
.P
Returns a pointer to the function that currently
implements the operator for the specified object.
It is the same table as the CLASS_FUNC for the object's
class.
The pointer to the dispatch table is stored in
the object operations.
The setting OBJ_CLASS, OBJ_CLASS_TYPE,
or OBJ_CLASS_ID may change this pointer.
.P
\f2obj\f1
Specifies the object for which the pointer is to be returned.
.P
\f2opID\f1
Specifies the ID of the operator for which the
function returns a pointer.
.H 4 "RETURNED VALUE"
.P
CLASS_OPER
.H 4 "SEE ALSO"
.P
Get_Obj
.br
Get_Class
.br
OBJ_CLASS
.br
OBJ_CLASS_ID
.br
OBJ_CLASS_TYPE
.br
CLASS_FUNC
.br
Call_Obj
.br
Call_Class
.H 4 "NAME"
.P
Init_Obj \- Initializes the specified object.
.IX "Init_Obj"
.tm .CE U 3 "Init_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Init_Obj\f2(obj)\f1
.br
OBJID obj;
.H 4 "DESCRIPTION"
.P
Initializes the specified object by calling its
class initialization function.
This operator calls the object initialization
function in the object dispatch table.
This is always the second entry in the table.
The operator ID for initialization is always the
same:
.DS
     xxx_OP_Init==1
.DE
\f2obj\f1
Specifies the object for which the class is initialized.
.H 4 "RETURNED VALUE"
.P
OBJID
.H 4 "SEE ALSO"
.P
Create_Class
.br
Create_Obj
.H 4 "NAME"
.P
New_Obj \- Creates an object belonging to a
specified class.
.IX "New_Obj"
.tm .CE U 3 "New_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3New_Obj\f2(classid, size)\f1
.br
CLASS_ID classid;
.br
int size;
.H 4 "DESCRIPTION"
.P
Creates an object belonging to a specified class.
The class type of the new object will be SCR_DEV_GENERIC.
The new object is
.UI "not"
initialized,
and its contents are random.
Use Init-Obj to initialize it.
It has no references,
but it has a valid operator dispatch table.
.P
\f2class\f1
Specifies the class to which the new object is to belong.
.P
\f2size\f1
Specifies the size of the new object.
If the specified size is 0,
the class default size is used.
The default size is the maximum of \f2size\fP.
.H 4 "RETURNED VALUE"
.P
OBJID
.P
NULL is returned if the object cannot be created.
.H 4 "SEE ALSO"
.P
Destroy_Obj
.br
Init_Obj
.br
Create_Obj
.br
Temp_Obj
.br
Create_Class
.br
Class_Size
.H 4 "NAME"
.P
Size_Obj \- Sets the size of an existing object.
.IX "Size_Obj"
.tm .CE U 3 "Size_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Size_Obj\f2(obj, n)\f1
OBJID obj
unsigned int n;
.H 4 "DESCRIPTION"
.P
Sets the size of an existing object.
This can make the object larger or smaller
depending on its current size.
.P
If an object is being made larger,
it may need to be copied to a different memory
area to be extended.
The excess entries are
\f2not\f1
zeroed.
If an object is being made smaller,
the excess entries are given back to the dynamic
memory allocator.
.P
If an object's flag is marked OBJ_NOSHRINK,
Size_Obj will return without resizing the object.
.P
\f2obj\f1
Specifies the object ID of object to be sized.
.P
\f2n\f1
Specifies the new size of the object.
.H 4 "RETURNED VALUE"
.P
OBJID, null is returned if an error occurs.
.H 4 "SEE ALSO"
.P
Create_Obj
.br
Extend_Obj
.H 4 "NAME"
.P
Temp_Obj \- Creates an object with no references.
.IX "Temp_Cmap"
.tm .CE U 3 "Temp_Cmap" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Temp_Obj\f2(class, type)\f1
.br
CLASS class;
.br
Obj_type type;
.H 4 "DESCRIPTION"
.P
Temp_Obj differs only in one respect from Create_Obj:\ \&
the initial reference count is set to zero.
.P
\f2class\f1
Specifies the class to which the new object belongs.
.P
\f2type\f1
Specifies the type of device the new object will
be used on.
.H 4 "RETURNED VALUE"
.P
OBJECT
.H 4 "SEE ALSO"
.H 4 "NAME"
.P
Use_Obj \- References the specified object.
.IX "Use_Obj"
.tm .CE U 3 "Use_Obj" \n(PN
.H 4 "SYNOPSIS"
.P
\f3Use_Obj\f2(obj)\f1
.br
OBJID obj;
.H 4 "DESCRIPTION"
.P
References the specified object.
.H 4 "RETURNED VALUE"
.P
OBJID
.H 4 "SEE ALSO"
.H 2 "Object Attributes"
.H 4 "NAME"
.P
OBJ_BASE
.IX "OBJ_BASE"
.tm .CE U 3 "OBJ_BASE" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the lowest level of the superclass.
.H 4 "RETURNED VALUE"
.P
CLASSID
.H 4 "SEE ALSO"
.P
Create_Class
.H 4 "NAME"
.P
OBJ_CLASS
.IX "OBJ_CLASS"
.tm .CE U 3 "OBJ_CLASS" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the class of the object.
.H 4 "RETURNED VALUE"
.P
CLASS
.H 4 "SEE ALSO"
.P
OBJ_CLASS_ID
.br
OBJ_CLASS_TYPE
.br
Create_Class
.H 4 "NAME"
.P
OBJ_CLASS_ID
.IX "OBJ_CLASS_ID"
.tm .CE U 3 "OBJ_CLASS_ID" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the class ID of the object.
.H 4 "RETURNED VALUE"
.P
CLASS_ID
.H 4 "SEE ALSO"
.P
OBJ_CLASS
.br
OBJ_CLASS_TYPE
.br
Create_Class
.H 4 "NAME"
.P
OBJ_CLASS_TYPE
.IX "OBJ_CLASS_TYPE"
.tm .CE U 3 "OBJ_CLASS_TYPE" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the class type of the object.
.H 4 "RETURNED VALUE"
.P
CLASS_TYPE
.H 4 "SEE ALSO"
.P
OBJ_CLASS
.br
OBJ_CLASS_ID
.br
Create_Class
.br
NewType_Class
.br
Call_Obj
.H 4 "NAME"
.P
OBJ_FLAGS
.IX "OBJ_FLAGS"
.tm .CE U 3 "OBJ_FLAGS" \n(PN
.H 4 "DESCRIPTION"
.P
Specifies the flags set for the object.
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
Size_Obj
.br
Destroy_Obj
.br
OBJ_NOSHRINK
.br
OBJ_NOKILL
.H 4 "NAME"
.P
OBJ_OPERS
.IX "OBJ_OPERS"
.tm .CE U 3 "OBJ_OPERS" \n(PN
.H 4 "DESCRIPTION"
.P
Points to the dispatch vector.
.H 4 "RETURNED VALUE"
.P
CLASS_OPER *
.H 4 "SEE ALSO"
.P
Get_Oper
.br
CLASS_FUNC
.H 4 "NAME"
.P
OBJ_SIZE
.IX "OBJ_SIZE"
.tm .CE U 3 "OBJ_SIZE" \n(PN
.H 4 "DESCRIPTION"
.P
The size of the object in bytes.
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.P
CLASS_SIZE
.br
New_Obj
.H 4 "NAME"
.P
OBJ_USE
.IX "OBJ_USE"
.tm .CE U 3 "OBJ_USE" \n(PN
.H 4 "DESCRIPTION"
.P
Use-count of object:
.P
1 = object defined
.P
2 = object defined and referenced once
.P
The object is destroyed when the use count falls below 2.
.H 4 "RETURNED VALUE"
.P
Integer
.H 4 "SEE ALSO"
.br \}
.\"  ENDIF SHAPES------------------------------------------------
