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

For the om_set message, the rkmmodelclass dispatcher steps through the
attribute/value pairs passed to it in the OM_SET message looking for the
local attributes (see om_new for the om_set message structure).  the
rkmmod_limit attribute is easy to process.  just find it and record the
value in the local rkmmoddata.vallimit field.

Because the function of the rkmmodelclass's om_set and om_update methods
are almost identical, the rkmmodelclass dispatcher handles them as the
same case.  The only difference is that, because the OM_UPDATE message
comes from another Boopsi object, the OM_UPDATE method can report on
transitory state changes of an attribute.  For example, when the user
slides a Boopsi prop gadget, that prop gadget sends out an interim
OM_UPDATE message for every interim value of pga_top.  when the user lets
go of the prop gadget, the gadget sends out a final OM_UPDATE message.
The OM_UPDATE message is almost identical to the OM_SET message:

    #define OPUF_INTERIM    (1<<0)

    /* the OM_NOTIFY method uses the same structure */

    struct opUpdate {
        ULONG             MethodID;
        struct TagItem    *opu_AttrList;
        struct GadgetInfo *opu_GInfo;
        ULONG             opu_Flags;      /* The extra field */
    };

A dispatcher can tell the difference between an interim and final
om_update message because the om_update message has an extra field on it
for flags.  If the low order bit (the OPUF_INTERIM bit) is set, this is an
interim OM_UPDATE message.  The interim flag is useful to a class that
wants to ignore any transitory messages, processing only final attribute
values.  Because rkmmodelclass wants to process all changes to its
attributes, it processes all OM_UPDATE messages.

The rkmmod_currval attribute is a little more complicated to process. the
dispatcher has to make sure the new current value is within the limits set
by rkmmod_limit, then record that new value in the local
rkmmoddata.currval field.  because other objects need to hear about
changes to RKMMOD_CurrVal,  the dispatcher has to send a notification
request.  It does this by sending itself an om_notify message.  the
OM_NOTIFY message tells an object to notify its targets (its ica_target
and the objects in its broadcast list) about an attribute change.  The
OM_NOTIFY method does this by sending om_update messages to all of an
object's targets.

The rkmmodelclass dispatcher does not handle the om_notify message itself.
It inherits this method from modelclass, so the rkmmodelclass dispatcher
passes OM_NOTIFY messages on to its superclass. To notify its targets, the
rkmmodelclass dispatcher has to construct an OM_NOTIFY message.  The
OM_NOTIFY method uses the same message structure as om_update.  using the
stack-based version of dosupermethoda(), dosupermethod(), the dispatcher
can build an OM_NOTIFY message on the stack:

     . . .

    struct TagItem tt[2];
    struct opUpdate *msg;
     . . .

    tt[0].ti_Tag  = RKMMOD_CurrVal;  /* make a tag list.  */
    tt[0].ti_Data = mmd->currval;
    tt[1].ti_Tag  = TAG_END;

    DoSuperMethod(cl, o, OM_NOTIFY, tt, msg->opu__GInfo,
                  ((msg->MethodID == OM_UPDATE) ? (msg->opu_Flags) : 0L));
     . . .

Because the om_notify needs a tag list of attributes about which to issue
updates, the dispatcher builds a tag list containing just the
rkmmod_currval tag and its new value.  the dispatcher doesn't use the tag
list passed to it in the om_update/om_notify message because that list can
contain many other attributes besides RKMMOD_CurrVal.

The msg variable in the dosupermethod() call above is the om_set or
om_update message that was passed to the dispatcher.  the dispatcher uses
that structure to find a pointer to the gadgetinfo structure that the
om_notify message requires.  the gadgetinfo structure comes from intuition
and contains information that Boopsi gadgets need to render themselves.
For the moment, don't worry about what the GadgetInfo structure actually
does, just pass it on.  The targets of an rkmmodel will probably need it.

Notice that the dispatcher has to test to see if the message is an om_set
or om_update so it can account for the opu_flags field at the end of the
OM_UPDATE message.

Processing the rkmmod_up and rkmmod_down attributes is similar to the
rkmmod_currval attribute.  when the dispatcher sees one of these, it has
to increment or decrement the local rkmmoddata.currval, making sure
RKMModData.currval is within limits.  The dispatcher then sends an
om_notify message to the superclass about the change to rkmmoddata.currval.

The return value from the dispatcher's om_set method depends on the what
effect the attribute change has to the visual state of the objects in the
rkmmodel's broadcast list.  If an attribute change will not affect the
visual state of the rkmmodel's objects, the OM_SET method returns zero.
If the attribute change could trigger a change to the rkmmodel's objects,
it returns something besides zero. For example, the rkmmodelclass om_set
method returns 1L if an rkmmodel's rkmmod_currval, rkmmod_up, or
rkmmod_down attribute is changed.

At some point the rkmmodelclass dispatcher has to allow its superclasses
to process these attributes it inherits.  Normally a dispatcher lets the
superclass process its attributes before attempting to process any local
attributes.  The rkmmodelclass dispatcher does this by passing on the
om_set or om_update message using dosupermethoda() (inheritance at work!).
As an alternative, the dispatcher can use the amiga.lib function
setsuperattrs().  see the amiga.lib autodocs for more details on this
function.