[Contents] [index] [Help] [Retrace] [browse <] [Browse >]

Boopsi gadgets and images were designed to be backwards compatible with
the old Intuition gadgets and images, so as part of their instance data,
both types of objects have the old Intuition structures built into them.
When newobject() creates a new gadget or image object, the pointer it
returns points to the object's embedded Gadget or Image corresponding
structure. Because Intuition can tell the difference between Boopsi images
and gadgets and the original images and gadgets, applications can use
Boopsi images and gadgets interchangeably with the older Intuition
entities.

Although normally considered a "programming sin", in some cases it is
legal for class dispatchers to directly manipulate some internal fields of
certain Boopsi objects.  For compatibility reasons, a Boopsi image or
gadget object contains an actual image or gadget structure.  these objects
are instances of the Transparent Base Classes, imageclass and gadgetclass.

To change an attribute of a Boopsi object, you normally invoke the set
method, om_set.  the intuition functions setattrs() and setgadgetattrs()
invoke this method.  A Boopsi class is informed of any attribute change at
that time, allowing it to react to this change.  The reaction can include
validating the changed attribute, changing other attributes to match, or
informing other objects of the change.  That is the inherent advantage of
using function calls to change attributes.

When using conventional images and gadgets, you generally modify the
structure's fields directly.  This operation is very fast.  For
conventional images and gadgets, there is no class that needs to know
about the changes, so there is no problem.  However, this is untrue of
Boopsi images and gadgets.  Although directly modifying the Boopsi
object's internal structure would provide a performance increase over
using the Boopsi om_set mechanism, altering a boopsi object's internal
structure directly will not give the class the opportunity to react to any
structure changes.  This violates the Boopsi concept, and therefore cannot
be done in general.

In order to provide a balance between the flexibility of function-access
and the performance of direct-access, the transparent base classes
imageclass and gadgetclass do not depend on being informed of changes to
certain fields in the internal image and gadget structures.  this means
that it is OK for the dispatchers of direct subclasses of imageclass and
gadgetclass to modify specific fields of Boopsi images or gadgets.
Applications and indirect subclass dispatchers of imageclass or
gadgetclass may not modify those fields, since their parent classes may
depend on hearing about changes to these fields, which the setattrs() call
(or a similar function) provides.

For dispatchers of direct subclasses of imageclass, the following are the
only fields of the image structure that are alterable:

    leftedge      width     imagedata
    topedge       height    planepick
    planeonoff

For dispatchers of direct subclasses of gadgetclass, the following are the
only fields of the gadget structure that are alterable:

    leftedge    flags           gadgettext
    topedge     gadgettype      specialinfo
    width       gadgetrender    activation
    height      selectrender

Under no circumstances may an application or an indirect subclass modify
one of these fields, even if the subclass knows the superclasses do not
depend on notification for this field.  This is the only way to preserve
the possibility for future enhancements to that superclass.  Note that
these fields are not alterable while the gadget or image object is in use
(for example, when it is attached to a window).