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

The following code, RKMModel.c,  makes up an initialization function and
the dispatcher function for a private class informally called
rkmmodelclass.

     rkmmodel.c 

Below is a diagram showing how an application could use an rkmmodelclass
object:

     figure 12-5: rkmmodelclass object diagram 

In this diagram, the application uses buttongclass boopsi gadgets to send
the rkmmodelclass the rkmmod_up and rkmmod_down attribute pulses.

The example takes advantage of an odd feature of buttongclass.  when the
user clicks on a buttongclass gadget, it sends an om_update to its
ica_target, even though no boopsi attribute of buttongclass has changed.
It does this because it's a convenient way to report button clicks.

Whenever a gadget sends a notification, the list of attribute/value pairs
in the om_notify message always contains the gadget's ga_id. this is an
easy way for the button to inform its target of its ID so the target knows
which gadget sent the om_update message.  when a buttongclass sends a
notification because of a button click, it only sends out an OM_UPDATE
about its GA_ID because none of its attributes changed.

When the user clicks one of the buttons in the rkmmodelclass diagram, the
button uses an ica_map to map its ga_id to one of the "dummy" pulse
attributes, rkmmod_up and rkmmod_down.  when the rkmmodel receives the
om_update message about rkmmod_up or rkmmod_down, it increments or
decrements its internal value.

There is one more important thing to note about rkmmodelclass. looking at
the rkmmodelclass Object diagram above, an rkmmodel's rkmmod_currval
changes because it received an om_update message from one of its gadgets.
RKMMOD_CurrVal can also change if the application explicitly set
RKMMOD_CurrVal using setattrs() or setgadgetattrs().

The primary difference between the om_set message that setattrs() sends
and the OM_SET message that setgadgetattrs() sends is that setattrs()
passes a NULL in opset.ops_ginfo instead of a gadgetinfo pointer.  this
doesn't present a problem for the rkmmodel object, because it doesn't use
the GadgetInfo structure.  The problem is that when the rkmmodel notifies
its targets, some of which are gadgets, they can't update their visual
state because they need a GadgetInfo to render themselves.  For this
reason, the rkmmodelclass dispatcher returns a positive non-zero value
when an attribute change occurs that could cause a change in the visual
state of any objects in its broadcast list.  An application that uses
rkmmodelclass must test the return value when calling SetAttrs() on an
rkmmodelclass object to tell if the attribute change requires a visual
refresh of the gadgets (see the Intuition Autodocs for refreshgadgets()).

    Boopsi Dispatchers Can Execute on Intuition's Context.
    ------------------------------------------------------
    Notice that the gadgets in the figure above send om_update messages
    to the rkmmodel when the user manipulates them.  Because Intuition
    handles the user input that triggers the OM_UPDATE messages,
    Intuition itself is sending the OM_UPDATE messages.  This means the
    rkmmodelclass dispatcher must be able to run on intuition's context,
    which puts some limitations on what the dispatcher is permitted to
    do: it can't use dos.library, it can't wait on application signals or
    message ports, and it can't call any Intuition functions which might
    wait on Intuition.

Although rkmmodelclass serves as an example of a class, it leaves a little
to be desired in a real-world implementation.  To create the
"prop-integer-up/down" super gadget from the diagram above, the
application has to create, initialize, and link nine Boopsi objects, which
is tedious, especially if the application needs several of these super
gadgets.  Ideally, all these functions would be rolled into some subclass
of gadgetclass.  if there were such a class, an application would only
have to create one instance of this subclass to get such a gadget.  When
the subclass received an om_new message, it would take care of creating,
initializing, and linking all of the Boopsi objects that make up the whole
super gadget.