D 2016-09-17T13:38:14.194 L Doc:\sTcl_Method N text/x-markdown P 434a3faf0a564ad9dc95a1be2a098b06b1250fff U dkf W 12527
Given a method, the entity that declared it can be found using Tcl\_MethodDeclarerClass which returns the class that the method is attached to (or NULL if the method is not attached to any class) and Tcl\_MethodDeclarerObject which returns the object that the method is attached to (or NULL if the method is not attached to an object). The name of the method can be retrieved with Tcl\_MethodName and whether the method is exported is retrieved with Tcl\_MethodIsPublic. The type of the method can also be introspected upon to a limited degree; the function Tcl\_MethodIsType returns whether a method is of a particular type, assigning the per-method clientData to the variable pointed to by clientDataPtr if (that is non-NULL) if the type is matched.
When the nameObj argument to Tcl\_NewMethod is NULL, an unnamed method is created, which is used for constructors and destructors. Constructors should be installed into their class using the Tcl\_ClassSetConstructor function, and destructors (which must not require any arguments) should be installed into their class using the Tcl\_ClassSetDestructor function. Unnamed methods should not be used for any other purpose, and named methods should not be used as either constructors or destructors. Also note that a NULL methodTypePtr is used to provide internal signaling, and should not be used in client code.
The method that is being called can be retrieved from the context by using Tcl\_ObjectContextMethod, and the object that caused the method to be invoked can be retrieved with Tcl\_ObjectContextObject. The number of arguments that are to be skipped (e.g. the object name and method name in a normal method call) is read with Tcl\_ObjectContextSkippedArgs, and the context can also report whether it is working as a filter for another method through Tcl\_ObjectContextIsFiltering.
During the execution of a method, the method implementation may choose to invoke the stages of the method call chain that come after the current method implementation. This (the core of the next command) is done using Tcl\_ObjectContextInvokeNext. Note that this function does not manipulate the call-frame stack, unlike the next command; if the method implementation has pushed one or more extra frames on the stack as part of its implementation, it is also responsible for temporarily popping those frames from the stack while the Tcl\_ObjectContextInvokeNext function is executing. Note also that the method-call context is never deleted during the execution of this function.
typedef struct { int version; const char \*name; Tcl\_MethodCallProc \*callProc; Tcl\_MethodDeleteProc \*deleteProc; Tcl\_CloneProc \*cloneProc; } Tcl\_MethodType;
The version field allows for future expansion of the structure, and should always be declared equal to TCL\_OO\_METHOD\_VERSION\_CURRENT. The name field provides a human-readable name for the type, and is the value that is exposed via the info class methodtype and info object methodtype Tcl commands.
The callProc field gives a function that is called when the method is invoked; it must never be NULL.
The deleteProc field gives a function that is used to delete a particular method, and is called when the method is replaced or removed; if the field is NULL, it is assumed that the method's clientData needs no special action to delete.
The cloneProc field is either a function that is used to copy a method's clientData (as part of Tcl\_CopyObjectInstance) or NULL to indicate that the clientData can just be copied directly.
typedef int Tcl\_MethodCallProc( ClientData clientData, Tcl\_Interp \*interp, Tcl\_ObjectContext objectContext, int objc, Tcl\_Obj \*const \*objv);
The clientData argument to a Tcl\_MethodCallProc is the value that was given when the method was created, the interp is a place in which to execute scripts and access variables as well as being where to put the result of the method, and the objc and objv fields give the parameter objects to the method. The calling context of the method can be discovered through the objectContext argument, and the return value from a Tcl\_MethodCallProc is any Tcl return code (e.g., TCL\_OK, TCL\_ERROR).
typedef void Tcl\_MethodDeleteProc( ClientData clientData);
The clientData argument to a Tcl\_MethodDeleteProc will be the same as the value passed to the clientData argument to Tcl\_NewMethod or Tcl\_NewInstanceMethod when the method was created.
typedef int Tcl\_CloneProc( Tcl\_Interp \*interp, ClientData oldClientData, ClientData \*newClientDataPtr);
The interp argument gives a place to write an error message when the attempt to clone the object is to fail, in which case the clone procedure must also return TCL\_ERROR; it should return TCL\_OK otherwise. The oldClientData field to a Tcl\_CloneProc gives the value from the method being copied from, and the newClientDataPtr field will point to a variable in which to write the value for the method being copied to.