home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / ConfigWind.3 < prev    next >
Encoding:
Text File  |  1993-07-07  |  6.7 KB  |  173 lines
  1. '\"
  2. '\" Copyright (c) 1990-1993 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/ConfigWind.3,v 1.14 93/07/07 16:27:29 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_ConfigureWindow tkc 3.3
  25. .BS
  26. .SH NAME
  27. .na
  28. Tk_ConfigureWindow, Tk_MoveWindow, Tk_ResizeWindow, Tk_MoveResizeWindow, Tk_SetWindowBorderWidth Tk_ChangeWindowAttributes, Tk_SetWindowBackground, Tk_SetWindowBackgroundPixmap, Tk_SetWindowBorder, Tk_SetWindowBorderPixmap, Tk_SetWindowColormap, Tk_DefineCursor, Tk_UndefineCursor \- change window configuration or attributes
  29. .ad
  30. .SH SYNOPSIS
  31. .nf
  32. \fB#include <tk.h>\fR
  33. .sp
  34. \fBTk_ConfigureWindow\fR(\fItkwin, valueMask, valuePtr\fR)
  35. .sp
  36. \fBTk_MoveWindow\fR(\fItkwin, x, y\fR)
  37. .sp
  38. \fBTk_ResizeWindow\fR(\fItkwin, width, height\fR)
  39. .sp
  40. \fBTk_MoveResizeWindow\fR(\fItkwin, x,  y, width, height\fR)
  41. .sp
  42. \fBTk_SetWindowBorderWidth\fR(\fItkwin, borderWidth\fR)
  43. .sp
  44. \fBTk_ChangeWindowAttributes\fR(\fItkwin, valueMask, attsPtr\fR)
  45. .sp
  46. \fBTk_SetWindowBackground\fR(\fItkwin, pixel\fR)
  47. .sp
  48. \fBTk_SetWindowBackgroundPixmap\fR(\fItkwin, pixmap\fR)
  49. .sp
  50. \fBTk_SetWindowBorder\fR(\fItkwin, pixel\fR)
  51. .sp
  52. \fBTk_SetWindowBorderPixmap\fR(\fItkwin, pixmap\fR)
  53. .sp
  54. .VS
  55. \fBTk_SetWindowColormap\fR(\fItkwin, colormap\fR)
  56. .sp
  57. \fBTk_DefineCursor\fR(\fItkwin, cursor\fR)
  58. .sp
  59. \fBTk_UndefineCursor\fR(\fItkwin\fR)
  60. .VE
  61. .SH ARGUMENTS
  62. .AS XSetWindowAttributes borderWidth
  63. .AP Tk_Window tkwin in
  64. Token for window.
  65. .AP "unsigned int" valueMask in
  66. OR-ed mask of values like \fBCWX\fR or \fBCWBorderPixel\fR,
  67. indicating which fields of \fI*valuePtr\fR or \fI*attsPtr\fR to use.
  68. .AP XWindowChanges *valuePtr in
  69. Points to a structure containing new values for the configuration
  70. parameters selected by \fIvalueMask\fR.  Fields not selected
  71. by \fIvalueMask\fR are ignored.
  72. .AP int x in
  73. New x-coordinate for \fItkwin\fR's top left pixel (including
  74. border, if any) within tkwin's parent.
  75. .AP int y in
  76. New y-coordinate for \fItkwin\fR's top left pixel (including
  77. border, if any) within tkwin's parent.
  78. .AP "unsigned int" width in
  79. New width for \fItkwin\fR (interior, not including border).
  80. .AP "unsigned int" height in
  81. New height for \fItkwin\fR (interior, not including border).
  82. .AP "unsigned int" borderWidth in
  83. New width for \fItkwin\fR's border.
  84. .AP XSetWindowAttributes *attsPtr in
  85. Points to a structure containing new values for the attributes
  86. given by the \fIvalueMask\fR argument.  Attributes not selected
  87. by \fIvalueMask\fR are ignored.
  88. .AP "unsigned long" pixel in
  89. New background or border color for window.
  90. .AP Pixmap pixmap in
  91. New pixmap to use for background or border of \fItkwin\fR.  WARNING:
  92. cannot necessarily be deleted immediately, as for Xlib calls.  See
  93. note below.
  94. .AP Colormap colormap in
  95. .VS
  96. New colormap to use for \fItkwin\fR.
  97. .AP Cursor cursor in
  98. New cursor to use for \fItkwin\fR.  If \fBNone\fR is specified, then
  99. \fItkwin\fR will not have its own cursor;  it will use the cursor
  100. of its parent.
  101. .VE
  102. .BE
  103.  
  104. .SH DESCRIPTION
  105. .PP
  106. These procedures are analogous to the X library procedures
  107. with similar names, such as \fBXConfigureWindow\fR.  Each
  108. one of the above procedures calls the corresponding X procedure
  109. and also saves the configuration information in Tk's local
  110. structure for the window.  This allows the information to
  111. be retrieved quickly by the application (using macros such
  112. as \fBTk_X\fR and \fBTk_Height\fR) without having to contact
  113. the X server.  In addition, if no X window has actually been
  114. created for \fItkwin\fR yet, these procedures do not issue
  115. X operations or cause event handlers to be invoked;  they save
  116. the information in Tk's local
  117. structure for the window;  when the window is created later,
  118. the saved information will be used to configure the window.
  119. .PP
  120. See the X library documentation for details on what these
  121. procedures do and how they use their arguments.
  122. .PP
  123. In the procedures \fBTk_ConfigureWindow\fR, \fBTk_MoveWindow\fR,
  124. \fBTk_ResizeWindow\fR, \fBTk_MoveResizeWindow\fR, and
  125. \fBTk_SetWindowBorderWidth\fR,
  126. if \fItkwin\fR is an internal window then event handlers interested
  127. in configure events are invoked immediately, before the procedure
  128. returns.  If \fItkwin\fR isn't a top-level window
  129. then the event handlers will be invoked later, after X has seen
  130. the request and returned an event for it.
  131. .PP
  132. Applications using Tk should never call procedures like
  133. \fBXConfigureWindow\fR directly;  they should always use the
  134. corresponding Tk procedures.
  135. .PP
  136. .VS
  137. The size and location of a window should only be modified by the
  138. appropriate geometry manager for that window and never by a window
  139. itself (but see \fBTk_MoveToplevelWindow\fR for moving a top-level
  140. window).
  141. .VE
  142. .PP
  143. .VS
  144. It is not allowable to use \fBTk_ConfigureWindow\fR to change the
  145. stacking order of a window (\fIvalueMask\fR may not contain the
  146. \fBCWSibling\fR or \fBCWStackMode\fR bits).
  147. To change the stacking order, use the procedure \fBTk_RestackWindow\fR.
  148. .VE
  149.  
  150. .SH BUGS
  151. .PP
  152. \fBTk_SetWindowBackgroundPixmap\fR and \fBTk_SetWindowBorderPixmap\fR
  153. differ slightly from their Xlib counterparts in that the \fIpixmap\fR
  154. argument may not necessarily be deleted immediately after calling
  155. one of these procedures.  This is because \fItkwin\fR's window
  156. may not exist yet at the time of the call, in which case \fIpixmap\fR
  157. is merely saved and used later when \fItkwin\fR's window is actually
  158. created.  If you wish to delete \fIpixmap\fR, then call
  159. \fBTk_MakeWindowExist\fR first to be sure that \fItkwin\fR's window exists
  160. and \fIpixmap\fR has been passed to the X server.
  161. .PP
  162. .VS
  163. A similar problem occurs for the \fIcursor\fR argument passed to
  164. \fBTk_DefineCursor\fR.  The solution is the same as for pixmaps above:
  165. call \fBTk_MakeWindowExist\fR before freeing the cursor.
  166. .VE
  167.  
  168. .SH "SEE ALSO"
  169. Tk_MoveToplevelWindow, Tk_RestackWindow
  170.  
  171. .SH KEYWORDS
  172. attributes, border, color, configure, height, pixel, pixmap, width, window, x, y
  173.