home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / GetSelect.3 < prev    next >
Encoding:
Text File  |  1993-04-01  |  3.7 KB  |  94 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/GetSelect.3,v 1.6 93/04/01 09:41:39 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_GetSelection tkc
  25. .BS
  26. .SH NAME
  27. Tk_GetSelection \- retrieve the contents of the selection
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tk.h>\fR
  31. .sp
  32. int
  33. \fBTk_GetSelection\fR(\fIinterp, tkwin, target, proc, clientData\fR)
  34. .SH ARGUMENTS
  35. .AS Tk_GetSelProc clientData
  36. .AP Tcl_Interp *interp in
  37. Interpreter to use for reporting errors.
  38. .AP Tk_Window tkwin in
  39. Window on whose behalf to retrieve the selection (determines
  40. display from which to retrieve).
  41. .AP Atom target in
  42. Form in which to retrieve selection.
  43. .AP Tk_GetSelProc *proc in
  44. Procedure to invoke to process pieces of the selection as they
  45. are retrieved.
  46. .AP ClientData clientData in
  47. Arbitrary one-word value to pass to \fIproc\fR.
  48. .BE
  49.  
  50. .SH DESCRIPTION
  51. .PP
  52. \fBTk_GetSelection\fR retrieves the selection in the format
  53. specified by \fItarget\fR.  The selection may actually be
  54. retrieved in several pieces;  as each piece is retrieved,
  55. \fIproc\fR is called to process the piece.  \fIProc\fR should
  56. have arguments and result that match the type \fBTk_GetSelProc\fR:
  57. .nf
  58. .RS
  59. typedef int Tk_GetSelProc(
  60. .RS
  61. ClientData \fIclientData\fR,
  62. Tcl_Interp *\fIinterp\fR,
  63. char *\fIportion\fR);
  64. .RE
  65. .RE
  66. .fi
  67. The \fIclientData\fP and \fIinterp\fR parameters to \fIproc\fR 
  68. will be copies of the corresponding arguments to
  69. \fBTk_GetSelection\fR.  \fIPortion\fR will be a pointer to
  70. a string containing part or all of the selection.  For large
  71. selections, \fIproc\fR will be called several times with sucessive
  72. portions of the selection.  The X Inter-Client Communication
  73. Conventions Manual allows the selection to be returned in formats
  74. other than strings, e.g. as an array of atoms or integers.  If
  75. this happens, Tk converts the selection back into a string
  76. before calling \fIproc\fR.  If the selection is returned as an
  77. array of atoms, Tk converts it to a string containing the atom names
  78. separated by white space.  For any other format besides string,
  79. Tk converts the selection to a string containing hexadecimal
  80. values separated by white space.
  81. .PP
  82. \fBTk_GetSelection\fR returns to its caller when the selection has
  83. been completely retrieved and processed by \fIproc\fR, or when a
  84. fatal error has occurred (e.g. the selection owner didn't respond
  85. promptly).  \fBTk_GetSelection\fR normally returns TCL_OK;  if
  86. an error occurs, it returns TCL_ERROR and leaves an error message
  87. in \fIinterp->result\fR.  \fIProc\fR should also return either
  88. TCL_OK or TCL_ERROR. If \fIproc\fR encounters an error in dealing with the
  89. selection, it should leave an error message in \fIinterp->result\fR
  90. and return TCL_ERROR;  this will abort the selection retrieval.
  91.  
  92. .SH KEYWORDS
  93. format, get, selection retrieval
  94.