manpagez: man pages & more
man Tcl_ClassSetConstructor(3)
Home | html | info | man
Method(3)               TclOO Library Functions              Method(3)




NAME

       Tcl_ClassSetConstructor,    Tcl_ClassSetDestructor,   Tcl_MethodDeclar-
       erClass,  Tcl_MethodDeclarerObject,  Tcl_MethodIsPublic,  Tcl_MethodIs-
       Type, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_Object-
       ContextInvokeNext,     Tcl_ObjectContextIsFiltering,     Tcl_ObjectCon-
       textMethod,   Tcl_ObjectContextObject,  Tcl_ObjectContextSkippedArgs  -
       manipulate methods and method-call contexts


SYNOPSIS

       #include <tclOO.h>

       Tcl_Method
       Tcl_NewMethod(interp, class, nameObj, isPublic,
                     methodTypePtr, clientData)

       Tcl_Method
       Tcl_NewInstanceMethod(interp, object, nameObj, isPublic,
                             methodTypePtr, clientData)

       Tcl_ClassSetConstructor(interp, class, method)

       Tcl_ClassSetDestructor(interp, class, method)

       Tcl_Class
       Tcl_MethodDeclarerClass(method)

       Tcl_Object
       Tcl_MethodDeclarerObject(method)

       Tcl_Obj *
       Tcl_MethodName(method)

       int
       Tcl_MethodIsPublic(method)

       int
       Tcl_MethodIsType(method, methodTypePtr, clientDataPtr)

       int
       Tcl_ObjectContextInvokeNext(interp, context, objc, objv, skip)

       int
       Tcl_ObjectContextIsFiltering(context)

       Tcl_Method
       Tcl_ObjectContextMethod(context)

       Tcl_Object
       Tcl_ObjectContextObject(context)

       int
       Tcl_ObjectContextSkippedArgs(context)


ARGUMENTS

       The interpreter holding the object or  class  to  create  or  update  a
       method  in.   The  object to create the method in.  The class to create
       the method in.  The name of the method to create. Should  not  be  NULL
       unless  creating  constructors  or  destructors.  A boolean flag saying
       whether the method is to be exported.  A description of the type of the
       method to create, or the type of method to compare against.  A piece of
       data that is passed to the implementation of the method without  inter-
       pretation.   A  pointer  to a variable in which to write the clientData
       value supplied when the method was created.  If  NULL,  the  clientData
       value will not be retrieved.  A reference to a method to query.  A ref-
       erence to a method-call context. Note that client code must not  retain
       a  reference  to  a  context.   The  number of arguments to pass to the
       method implementation.  An array of arguments to  pass  to  the  method
       implementation.  The number of arguments passed to the method implemen-
       tation that do not represent "real" arguments.


DESCRIPTION

       A method is an operation carried out on an object  that  is  associated
       with the object. Every method must be attached to either an object or a
       class; methods attached to a class are associated  with  all  instances
       (direct and indirect) of that class.

       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 func-
       tion 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.

   METHOD CREATION
       Methods  are  created by Tcl_NewMethod and Tcl_NewInstanceMethod, which
       create a method attached to a class or an object respectively. In  both
       cases, the nameObj argument gives the name of the method to create, the
       isPublic argument states whether the method  should  be  exported  ini-
       tially,  the methodTypePtr argument describes the implementation of the
       method (see the METHOD TYPES section below) and the clientData argument
       gives some implementation-specific data that is passed on to the imple-
       mentation of the method when it is called.

       When the nameObj argument to Tcl_NewMethod is NULL, an  unnamed  method
       is  created, which is used for constructors and destructors.  Construc-
       tors should be installed into their class  using  the  Tcl_ClassSetCon-
       structor  function,  and  destructors (which must not require any argu-
       ments) should be installed into their class using  the  Tcl_ClassSetDe-
       structor  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.

   METHOD CALL CONTEXTS
       When a method is called, a method-call context reference is  passed  in
       as  one  of  the arguments to the implementation function. This context
       can be inspected to provide information about the  caller,  but  should
       not be retained beyond the moment when the method call terminates.

       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  cur-
       rent 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 func-
       tion  is  executing.  Note  also  that the method-call context is never
       deleted during the execution of this function.


METHOD TYPES

       The types of methods are described by a  pointer  to  a  Tcl_MethodType
       structure, which is defined as:

       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 particu-
       lar  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.

   TCL_METHODCALLPROC FUNCTION SIGNATURE
       Functions  matching  this  signature  are  called  when  the  method is
       invoked.

       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 discov-
       ered  through  the  objectContext argument, and the return value from a
       Tcl_MethodCallProc is any Tcl return code (e.g. TCL_OK, TCL_ERROR).

   TCL_METHODDELETEPROC FUNCTION SIGNATURE
       Functions matching this signature are used when a  method  is  deleted,
       whether  through  a  new  method being created or because the object or
       class is deleted.

       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.

   TCL_CLONEPROC FUNCTION SIGNATURE
       Functions matching this signature are used to copy a  method  when  the
       object or class is copied using Tcl_CopyObjectInstance (or oo::copy).

       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  proce-
       dure  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.


SEE ALSO

       Class(3), oo::class(n), oo::define(n), oo::object(n)


KEYWORDS

       constructor, method, object




TclOO                                 0.1                        Method(3)

tcl 8.6.1 - Generated Mon Sep 30 07:34:27 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.