home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / RestrictEv.3 < prev    next >
Encoding:
Text File  |  1993-04-01  |  3.6 KB  |  91 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/RestrictEv.3,v 1.6 93/04/01 09:41:55 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_RestrictEvents tkc
  25. .BS
  26. .SH NAME
  27. Tk_RestrictEvents \- filter and selectively delay X events
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tk.h>\fR
  31. .sp
  32. Tk_RestrictProc *
  33. \fBTk_RestrictEvents\fR(\fIproc, arg, prevArgPtr\fR)
  34. .SH ARGUMENTS
  35. .AS Tk_RestrictProc **prevArgPtr
  36. .AP Tk_RestrictProc *proc in
  37. Predicate procedure to call to filter incoming X events.
  38. NULL means do not restrict events at all.
  39. .AP char *arg in
  40. Arbitrary argument to pass to \fIproc\fR.
  41. .AP char **prevArgPtr in/out
  42. Pointer to place to save argument to previous restrict procedure.
  43. .BE
  44.  
  45. .SH DESCRIPTION
  46. .PP
  47. This procedure is useful in certain situations where applications
  48. are only prepared to receive certain X events.  After
  49. \fBTk_RestrictEvents\fR is called, \fBTk_DoOneEvent\fR (and
  50. hence \fBTk_MainLoop\fR) will filter X input events through
  51. \fIproc\fR.  \fIProc\fR indicates whether a
  52. given event is to be processed immediately or deferred until some
  53. later time (e.g. when the event restriction is lifted).  \fIProc\fR
  54. is a standard X predicate procedure, of the sort passed to
  55. \fBXCheckIfEvent\fR.  It must have arguments and result that match
  56. the type \fBTk_RestrictProc\fR:
  57. .nf
  58. .RS
  59. typedef Bool Tk_RestrictProc(
  60. .RS
  61. Display *\fIdisplay\fR,
  62. XEvent *\fIeventPtr\fR,
  63. char *\fIarg\fR);
  64. .RE
  65. .RE
  66. .fi
  67. The \fIdisplay\fR argument to \fIproc\fR is the display from which
  68. \fIeventPtr\fR was received, and \fIeventPtr\fR points to an event
  69. under consideration.  The \fIarg\fR argument is a copy of the \fIarg\fR
  70. passed to \fBTk_RestrictEvents\fR;  it may be used to provide
  71. \fIproc\fR with information it needs to filter events.  \fIProc\fR
  72. must return \fBTrue\fR or \fBFalse\fR.  \fBTrue\fR means the event
  73. should be processed immediately and \fBFalse\fR means the event
  74. should not be processed now, but should be saved for some later
  75. time.
  76. .PP
  77. \fBTk_RestrictEvents\fR uses its return value and \fIprevArgPtr\fR
  78. to return information about the current event restriction procedure
  79. (a NULL return value means there are currently no restrictions).
  80. These values may be used to restore the previous restriction state
  81. when there is no longer any need for the current restriction.
  82. .PP
  83. There are very few places where \fBTk_RestrictEvents\fR is needed.
  84. Please use it only where it is absolutely necessary.
  85. If only a local restriction is needed, it can probably
  86. be achieved more cleanly by changing event-to-Tcl bindings or by
  87. calling \fBTk_DeleteEventHandler\fR.
  88.  
  89. .SH KEYWORDS
  90. delay, event, filter, restriction
  91.