Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Itcl_RegisterC(3)	 [incr Tcl] Library Procedures	     Itcl_RegisterC(3)

       Itcl_RegisterC,	Itcl_RegisterObjC,  Itcl_FindC	- Associate a symbolic
       name with a C procedure.

       #include	<itcl.h>

       Itcl_RegisterC(interp, cmdName, argProc,	clientData, deleteProc)

       Itcl_RegisterObjC(interp, cmdName, objProc, clientData, deleteProc)

       Itcl_FindC(interp, cmdName, argProcPtr, objProcPtr, cDataPtr)

       Interpreter in which to create new command.  Name of  command.	Imple-
       mentation of new	command:  argProc will be called whenever The Tcl_Cmd-
       Proc * to receive the pointer.	Implementation	of  the	 new  command:
       objProc	will  be  called  whenever The Tcl_ObjCmdProc *	to receive the
       pointer.	 Arbitrary one-word value to pass to proc and deleteProc.  The
       ClientData to receive the pointer.  Procedure to	call before cmdName is
       deleted from the	interpreter; allows for	command-specific cleanup.   If
       NULL, then no procedure is called before	the command is deleted.

       Used  to	associate a symbolic name with an (argc,argv) C	procedure that
       handles a Tcl command.  Procedures that are registered in  this	manner
       can  be	referenced  in	the  body of an	[incr Tcl] class definition to
       specify C procedures to acting as methods/procs.	 Usually invoked in an
       initialization routine for an extension,	called out in Tcl_AppInit() at
       the start of an application.

       Each symbolic procedure can have	an arbitrary client data value associ-
       ated  with  it.	This value is passed into the command handler whenever
       it is invoked.

       A symbolic procedure name can be	used  only  once  for  a  given	 style
       (arg/obj)  handler.   If	the name is defined with an arg-style handler,
       it can be redefined with	an  obj-style  handler;	 or  if	 the  name  is
       defined	with  an  obj-style  handler, it can be	redefined with an arg-
       style handler.  In either case, any previous client data	 is  discarded
       and the new client data is remembered.  However,	if a name is redefined
       to a different handler of the same style,  this	procedure  returns  an

       Returns TCL_OK on success, or TCL_ERROR (along with an error message in
       interp->result) if anything goes	wrong.

       C procedures can	be integrated into an [incr Tcl] class	definition  to
       implement  methods,  procs, and the "config" code for public variables.
       Any body	that starts with "@" is	treated	as the symbolic	name for  a  C

       Symbolic	 names are established by registering procedures via Itcl_Reg-
       isterC().  This is usually done in the Tcl_AppInit()  procedure,	 which
       is automatically	called when the	interpreter starts up.	In the follow-
       ing example, the	procedure My_FooCmd() is registered with the  symbolic
       name  "foo".   This  procedure can be referenced	in the body command as
       "@foo".	int Tcl_AppInit(interp)
	   Tcl_Interp *interp;	   /* Interpreter for application. */ {
	   if (Itcl_Init(interp) == TCL_ERROR) {
	       return TCL_ERROR;

	   if (Itcl_RegisterC(interp, "foo", My_FooCmd)	!= TCL_OK) {
	       return TCL_ERROR;
	   } } C procedures are	implemented just like ordinary	Tcl  commands.
       See  the	 CrtCommand man	page for details.  Within the procedure, class
       data members can	be accessed like  ordinary  variables  using  Tcl_Set-
       Var(),  Tcl_GetVar(), Tcl_TraceVar(), etc.  Class methods and procs can
       be executed like	ordinary commands using	Tcl_Eval().  [incr Tcl]	 makes
       this  possible by automatically setting up the context before executing
       the C procedure.

       This scheme provides a natural migration	 path  for  code  development.
       Classes	can  be	developed quickly using	Tcl code to implement the bod-
       ies.  An	entire application can be built	and tested.   When  necessary,
       individual  bodies  can	be  implemented	with C code to improve perfor-

       See the Archetype class in [incr	Tk] for	an example of how this C link-
       ing method is used.

       Tcl_CreateCommand, Tcl_CreateObjCommand

       class, object

itcl				      3.0		     Itcl_RegisterC(3)


Want to link to this manual page? Use this URL:

home | help