TttViewlnputEvent msglnputEvent.
****************************************************************************/
'define (xl \
",tttViewDbgSet,OxlOOOOOO,x)
MsgHandlerWithTypes(TttViewlnputEvent, P_INPUT_EVENT, PP_TTT_VIEW_INST)
{
STATUS switch
s;
s ""
break;
default:
) {
s = ObjectCallAncestorCtx(ctX)i break;
return s;
/* TttViewlnputEvent */
Creating the Methods
This section describes how to write a method. While you read through this section, refer to the example code for Tic-Tac-Toe in \PENPOINT\SDK\
SAMPLE\TTT in the PenPoint Software Development Kit.
Declaring Entry Points for Methods
When the Class Manager sends a message to an instance, the Class Manager uses the method table to locate the entry point for the procedure that corresponds to the message. The procedure is called a method or message handler (the terms are synonyms). A single method can handle multiple messages; this allows one method to respond to all messages defined by a class and also avoids unnecessary replication of common code across the handling of several messages.
You must explicitly declare all methods. The Class Manager defines the symbol MSG_HANDLER to identify message handling procedures. MSG_HANDLER and all the macros described in this section are defined in CLSMGR.H. MSG_HANDLER expands to SfATUS CDECL. Using the symbol MSG_HANDLER makes your code much easier to read and search.
3.7
3.7.1
38 PEN POINT ARCHITECTURAL REFERENCE Part 1 I Class Manager
Message Parameters
When the Class Manager sends a message to your method, it always passes along the same five parameters:
msg the message.
self the UID of the object to which the message was sent.
pArgs the 32-bit value that indicates the client's arguments.
etx the context, required for calls by the method to ObjectWriteO and ObjeetCallAneestorO ..
pData a pointer to your object's instance data.
These parameters are described in the next five sections.
~ The msg Parameter
The msg parameter contains the value that identifies the message that you re-ceived. This is one of the three parameters specified by the client that sent the message to your object.
You use the msg parameter most frequently when you want to send the message to your ancestor from within your method.
You can also use this parameter to do specific processing for messages, especially if you have a wildcard method that needs to do special work for selected messages.
The self Parameter
The self parameter contains the UID of the object that was originally sent the message. This is the second of the three parameters specified by the client that sent the message to your object.
If an object needs to send a message to itself, the method uses self to identify the object executing the method. To forward the message to the object's ancestor class, use ObjeetCallAncestorO; using ObjeetCallO results in an infinite loop. Otherwise, use ObjeetCallO or ObjeetSendO to provide subclasses a chance to modify the mes-sage behavior or to simply notice that the mesmes-sage was sent.
~. The pArgs Parameter
The pArgs parameter contains the 32-bit argument value specified by the client.
This is the third of the three parameters specified by the client that sent the message to your object.
The pArgs parameter is typically a pointer to data, but in some cases is the argu-ment data (for example, when the only data required is a 32~bit value). When you design a method, you must decide what argument data it requires. You use the header file to document what data is required by each message.
~ The ctx Parameter
The etx parameter contains a CONTEXT structure that maintains information about where the current class is in relation to the class hierarchy. The ctx
3,,7~2
CHAPTER 3 I CREATING A NEW CLASS Creating the Methods
parameter is created and maintained by the Class Manager. ctx is used primarily by ObjectCallAncestorO, ObjectReadO and ObjectW riteO.
~ The pData Parameter
The pData parameter contains a pointer to the instance data for the object.
As described already in the section on instance data, the Class Manager maintains the instance data for each instance separately in write-protected memory.
If you will need to update your instance data, you must copy the instance data to your local memory, update the instance data, then write the instance data back with ObjectWriteO.
Method Declaration Macros
Many times when you define a method, you use the same declarations for all or most of the parameters. To free you from declaring all these parameters, and to make your code more readable, the Class Manager defines a number of macros that declare the procedure and its parameters.
Additionally, there are macros to manipulate the instance data pointer pData in your methods.
Table 3-1 lists the method macros.
Table 3~1
Method Declaration Macros
Purpose
Declares all parameters.
MsgHandlerO
MsgHandlerArgTypeO MsgHandlerWithTypesO
MsgHandler ParametersNo WarningO
Allows you to specify a different type for pArgs.
Allows you to specify different types for pArgs and pData.
Suppresses warning messages about unused parameters.
Using the MsgHandler() Macro
You use the MsgHandlerO macro when you do not need to explicitly define types for the pArgs or pData parameters when you use them. You might do this when your method simply issues a debug statement and returns (you might have specified objCallAncestorBefore or objCallAncestorAfter in your method table).
The syntax for the MsgHandlerO macro is:
MsgBandler(fn)
fn is the name of the message handler. For example:
MsgHandler(XferListMsgNewDefaults)
{
STATUS Si
((P_XFER_LIST_NEW)pArgs)-»object.cap 1= objCapCall;
return stsOK;
II Prevent compiler warnings for unused parameters MsgHandlerParametersNoWarning;
1* XferListMsgNewDefaults *1
II Abbrev. parameters
39
40 PENPOINT ARCHITECTURAL REFERENCE Part 1 I Class Manager
~ Using MsgHandlerArgType()
You use the MsgHandlerArgTypeO macro when you want to explicitly cast the type of the pArgs parameter in the method declaration.
The syntax for MsgHandlerArgType is:
MsgHandlerArgType (fn, pArgsType)
fn is the name of the message handler and pArgsType is the type to which to cast pArgs. pArgsType must be a pointer type. In the following code example, the type for pArgs is P _XFER_LIST _NEW:
MsgHandlerArgType(XferListMsgNewDefaults, P_XFER_LI ST_NEW)
{
STATUS s;
pArgs-»object.cap 1= objCapCall;
return stsOK;
II Prevent compiler warnings for unused parameters MsgHandlerParametersNoWarning;
1* XferListMsgNewDefaults *1
~ Using MsgHandlerWithTypes()
You use the MsgHandlerWithTypesO macro when you want to explicitly cast the types of both the pArgs and pData parameters in the method declaration. The syntax for MsgHandlerWith Types
0
is:MsgHandlerWithTypes(fn, pArgsType, pDataType)
fn is the name of the message handler, pArgsType is the type for pArgs, and pDataType is the type for pData. Both pArgsType and pDataType must be pointer types. In this example, the type of pArgs is P _OBJ_SAVE and the type of pData is PP _ TTT _APP _INST:
MsgHandlerWithTypes(TttAppSave, P_OBJ_SAVE, PP_TTT_APP_INST)
{
TTT_APP_FILED_O filed;
STATUS s;
DbgTttAppSave
«""»
~~ Using MsgHandlerParametersNoWarning()
Some C compilers generate warnings when you declare identifiers but don't use them in the function where they are declared. The method macros described in this section declare all five parameters passed by the Class Manager. If you do not reference one of these parameters, the compiler may generate a warning message.
3.7.3.2
3.7.3.3
3.7.3.4
To suppress these messages, indude the macro MsgHandlerParametersNoWarningO in your method. The macro simply adds references to all of a method's parameters that will satisfy the compiler without generating any unnecessary code.
msg, self, pArgs, ctx, pData;
By mentioning all the parameters, the macro effectively suppresses the warning messages.
CHAPTER 3 I CREATING A NEW CLASS Creating a Method Table