home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 0 / 0998 / CreateComm.3 < prev    next >
Encoding:
Text File  |  1990-12-28  |  4.6 KB  |  117 lines
  1. '\" Copyright 1989 Regents of the University of California
  2. '\" Permission to use, copy, modify, and distribute this
  3. '\" documentation for any purpose and without fee is hereby
  4. '\" granted, provided that this notice appears in all copies.
  5. '\" The University of California makes no representations about
  6. '\" the suitability of this material for any purpose.  It is
  7. '\" provided "as is" without express or implied warranty.
  8. '\" 
  9. '\" $Header: /sprite/src/lib/tcl/RCS/Tcl_CreateCommand.man,v 1.2 89/03/24 14:15:58 ouster Exp $ SPRITE (Berkeley)
  10. '\" 
  11. .so \*(]ltmac.sprite
  12. .HS Tcl_CreateCommand tcl
  13. .BS
  14. .SH NAME
  15. Tcl_CreateCommand \- define an application-specific command binding
  16. .SH SYNOPSIS
  17. .nf
  18. \fB#include <tcl.h>\fR
  19. .sp
  20. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  21. .SH ARGUMENTS
  22. .AS ClientData (*deleteProc)()
  23. .AP Tcl_Interp *interp in
  24. Interpreter in which to create new command.
  25. .AP char *cmdName in
  26. Name of new command.  Tcl_CreateCommand makes a copy of this value
  27. for its own use.
  28. .AP int (*proc)() in
  29. Implementation of new command:  \fIproc\fR will be called whenever
  30. \fIcmdName\fR is invoked as a command.
  31. .AP ClientData clientData in
  32. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  33. .AP void (*deleteProc)() in
  34. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  35. allows for command-specific cleanup.  If NULL, then no procedure is
  36. called before the command is deleted.
  37. .BE
  38.  
  39. .SH DESCRIPTION
  40. .PP
  41. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  42. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  43. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  44. will call \fIproc\fR
  45. to process the command.  If there is already a command \fIcmdName\fR
  46. associated with the interpreter, it is deleted.  \fIProc\fP should
  47. have the following structure:
  48. .nf
  49. .RS
  50. int
  51. proc(\fIclientData, interp, argc, argv\fP)
  52. .RS
  53. ClientData \fIclientData\fP;
  54. Tcl_Interp *\fIinterp\fP;
  55. int \fIargc\fP;
  56. char *\fIargv[]\fP;
  57. .RE
  58. {
  59. }
  60. .RE
  61. .fi
  62. The \fIclientData\fP and \fIinterp\fR parameters are
  63. copies of the \fIclientData\fP and \fIinterp\fR arguments given
  64. to \fBTcl_CreateCommand\fR.
  65. Typically, \fIclientData\fR points to an application-specific
  66. data structure that describes what to do when the command procedure
  67. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  68. the command, \fIargc\fR giving the number of arguments (including
  69. the command name) and \fIargv\fR giving the values of the arguments
  70. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  71. the first \fIargc\fR values point to the argument strings, and the
  72. last value is NULL.
  73. .PP
  74. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  75. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  76. for details on what these codes mean.  Most normal commands will only
  77. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  78. \fIinterp->result\fR to point to a string value;
  79. in the case of a \fBTCL_OK\fR return code this gives the result
  80. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  81. The \fBTcl_Return\fR procedure provides an easy interface for setting the return
  82. value;  for complete details on how the \fIinterp->result\fR field is managed,
  83. see the \fBTcl_Interp\fR man page.  Before invoking a command procedure,
  84. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  85. commands can return an empty result by doing nothing at all.
  86. .PP
  87. The contents of the \fIargv\fR array are copies made by the Tcl interpreter
  88. for the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
  89. in \fIargv\fR.  However, the \fIargv\fR array
  90. is recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
  91. \fIinterp->result\fR to point anywhere within the \fIargv\fR values (call Tcl_Return
  92. with status \fBTCL_VOLATILE\fR if you want to return something from the
  93. \fIargv\fR array).
  94. .PP
  95. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  96. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  97. or by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
  98. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  99. application an opportunity to release any structures associated
  100. with the command.  \fIDeleteProc\fR should have the following form:
  101. .nf
  102. .RS
  103. void
  104. deleteProc(\fIclientData\fP)
  105. .RS
  106. ClientData \fIclientData\fP;
  107. .RE
  108. {
  109. }
  110. .RE
  111. .fi
  112. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  113. argument passed to \fBTcl_CreateCommand\fR.
  114.  
  115. .SH KEYWORDS
  116. bind, command, create, interpreter
  117.