MetaClass: 2.5 Utility Messages: Event Messages

| Up: GEOS SDK TechDocs | Up | Prev: 2.4 User Interface Utility Meta Messages | Next: 2.6 Variable Data Messages

These messages are used to send classed events to other objects. A classed event is typically an event stored earlier with the Goc keyword @record .

MSG_META_DISPATCH_EVENT

Boolean	MSG_META_DISPATCH_EVENT(
        AsmPassReturn 	*retVals,
        EventHandle 	eventHandle,
        MessageFlags msgFlags););

This message causes an object to @send or @call a message of another object. This is useful for getting one object run by a different thread to call yet another object or to send a reply to the first object. This message can cause complex synchronization problems if not used with extreme care.

Source: Unrestricted.

Destination: Any object.

Interception: Unnecessary, as MetaClass does the right thing.

Parameters: retValue structure to hold return values.

eventHandle
Event which will be sent.
msgFlags
flags which will determine how message is sent.

Return: If MF_CALL specified, then carry flag return value will be returned.

Structures: 

 typedef struct {
	word 	ax;
	word 	cx;
	word 	dx;
	word 	bp;
} AsmPassReturn;

MSG_META_SEND_CLASSED_EVENT

void	MSG_META_SEND_CLASSED_EVENT(
        EventHandle	 	event,
        TravelOption 		whereTo);

This message sends a previously recorded classed event to a certain type of destination defined in the TravelOption argument whereTo .

This message's interesting behavior is actually added by the User Interface, which defines GenTravelOption types. The default behavior provided here in MetaClass is to destroy the event if TO_NULL is passed, else to deliver the event to itself if it is capable of handling it (the object is a member of the class stored with the event). The event is always freed, whether or not it is deliverable.

MetaClass recognizes the following TravelOption values:

TO_NULL
TO_SELF
TO_OBJ_BLOCK_OUTPUT
TO_PROCESS
TO_OBJ_BLOCK_OUTPUT sends the event to the object block's output set in its block header.

Source: Unrestricted.

Destination: Any object.

Interception: By default, MetaClass handlers deal with just the most primitive of the TravelOption values. Object classes can add new TravelOption types, but must then intercept this message to implement them (calling the superclass if it doesn't recognize the TravelOption passed).

Parameters: event Classed event, probably created using @record .

whereTo
TravelOption describing target of message.

Return: Nothing.

MSG_META_GET_OBJ_BLOCK_OUTPUT

optr	MSG_META_GET_OBJ_BLOCK_OUTPUT();

This message returns the output optr of an object block that contains the object sent the message.

Source: Unrestricted.

Destination: Any object (except a process object).

Return: Optr of the block's output field.

Interception: Generally not intercepted.

MSG_META_SET_OBJ_BLOCK_OUTPUT

void	MSG_META_SET_OBJ_BLOCK_OUTPUT(
        optr		output);

This message sets the object block output--the block containing the object sent the message-- to the passed optr.

Source: Unrestricted.

Destination: Any object (except a process object).

Parameters: output Optr of the object to act as the block's output.

Interception: Generally not intercepted.

MSG_META_GET_OPTR

optr	MSG_META_GET_OPTR();

This message returns the object's optr. This is useful when combined with MSG_GEN_GUP_CALL_OBJECT_OF_CLASS to get the optr of an object of a given class somewhere up in a Generic Tree.

Note: MSG_GEN_GUP_CALL_OBJECT_OF_CLASS dies if an object of the class doesn't exist. Use MSG_GEN_GUP_TEST_FOR_OBJECT_OF_CLASS before using MSG_GEN_GUP_CALL_OBJECT_OF_CLASS if there is some question as to whether an object of a given class exists.

Source: Unrestricted.

Destination: Any object.

Interception: Unlikely.

Parameters: None.

Return: The object's optr.

MSG_META_GET_TARGET_AT_TARGET_LEVEL

void	MSG_META_GET_TARGET_AT_TARGET_LEVEL(
        GetTargetParams *retValue,
        TargetLevel level);

This message returns the GetTargetParams structure containing, among other things, the current target object at a given target level. The MetaClass handler simply returns information about the current object since it is assumed to be the current target. GenClass and VisClass handlers will handle this message and pass it down the travel hierarchy. If you intercept this message, you should correctly pass this message down as well, either explicitly or by calling the superclass. See the Input chapter, for information on target.

Source: Unrestricted.

Destination: Any object.

Interception: Must be handled by target nodes to correctly pass the request on down to the next target below current node in hierarchy.

Parameters: level Zero for leaf, otherwise TargetLevel , as defined by UI.

retValue
Structure to hold return value.

Return: Nothing returned explicitly.

retValue
Filled with return values.

Structures: 

  typedef struct {
	ClassStruct 				*GTP_class;
	optr 				GTP_target;
} GetTargetParams;
| Up: GEOS SDK TechDocs | Up | Prev: 2.4 User Interface Utility Meta Messages | Next: 2.6 Variable Data Messages