util/X86LINUX64/man/man3/Tk_CanvasSetStippleOrigin.3

   1 '\"
   2 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tk.h>\fR
 281 .sp
 282 Tk_Window
 283 \fBTk_CanvasTkwin\fR(\fIcanvas\fR)
 284 .sp
 285 int
 286 \fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR)
 287 .sp
 288 \fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR)
 289 .sp
 290 \fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR)
 291 .sp
 292 \fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
 293 .sp
 294 \fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
 295 .sp
 296 Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
 297 .sp
 298 Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;
 299 .SH ARGUMENTS
 300 .AS Tk_ItemType *drawableXPtr
 301 .AP Tk_Canvas canvas in
 302 A token that identifies a canvas widget.
 303 .AP Tcl_Interp *interp in/out
 304 Interpreter to use for error reporting.
 305 .AP "const char" *string in
 306 Textual description of a canvas coordinate.
 307 .AP double *doublePtr out
 308 Points to place to store a converted coordinate.
 309 .AP double x in
 310 An x coordinate in the space of the canvas.
 311 .AP double y in
 312 A y coordinate in the space of the canvas.
 313 .AP short *drawableXPtr out
 314 Pointer to a location in which to store an x coordinate in the space
 315 of the drawable currently being used to redisplay the canvas.
 316 .AP short *drawableYPtr out
 317 Pointer to a location in which to store a y coordinate in the space
 318 of the drawable currently being used to redisplay the canvas.
 319 .AP GC gc out
 320 Graphics context to modify.
 321 .AP short *screenXPtr out
 322 Points to a location in which to store the screen coordinate in the
 323 canvas window that corresponds to \fIx\fR.
 324 .AP short *screenYPtr out
 325 Points to a location in which to store the screen coordinate in the
 326 canvas window that corresponds to \fIy\fR.
 327 .AP int x1 in
 328 Left edge of the region that needs redisplay.  Only pixels at or to
 329 the right of this coordinate need to be redisplayed.
 330 .AP int y1 in
 331 Top edge of the region that needs redisplay.  Only pixels at or below
 332 this coordinate need to be redisplayed.
 333 .AP int x2 in
 334 Right edge of the region that needs redisplay.  Only pixels to
 335 the left of this coordinate need to be redisplayed.
 336 .AP int y2 in
 337 Bottom edge of the region that needs redisplay.  Only pixels above
 338 this coordinate need to be redisplayed.
 339 .BE
 340 .SH DESCRIPTION
 341 .PP
 342 These procedures are called by canvas type managers to perform various
 343 utility functions.
 344 .PP
 345 \fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular
 346 canvas.
 347 .PP
 348 \fBTk_CanvasGetCoord\fR translates a string specification of a
 349 coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision
 350 canvas coordinate.
 351 If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR
 352 stores the corresponding canvas coordinate at *\fIdoublePtr\fR
 353 and returns \fBTCL_OK\fR.
 354 Otherwise it stores an error message in the interpreter result and
 355 returns \fBTCL_ERROR\fR.
 356 .PP
 357 \fBTk_CanvasDrawableCoords\fR is called by type managers during
 358 redisplay to compute where to draw things.
 359 Given \fIx\fR and \fIy\fR coordinates in the space of the
 360 canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding
 361 pixel in the drawable that is currently being used for redisplay;
 362 it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR.
 363 This procedure should not be invoked except during redisplay.
 364 .PP
 365 \fBTk_CanvasSetStippleOrigin\fR is also used during redisplay.
 366 It sets the stipple origin in \fIgc\fR so that stipples drawn
 367 with \fIgc\fR in the current offscreen pixmap will line up
 368 with stipples drawn with origin (0,0) in the canvas's actual
 369 window.
 370 \fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee
 371 that stipple patterns line up properly when the canvas is
 372 redisplayed in small pieces.
 373 Redisplays are carried out in double-buffered fashion where a
 374 piece of the canvas is redrawn in an offscreen pixmap and then
 375 copied back onto the screen.
 376 In this approach the stipple origins in graphics contexts need to
 377 be adjusted during each redisplay to compensate for the position
 378 of the off-screen pixmap relative to the window.
 379 If an item is being drawn with stipples, its type manager typically
 380 calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR
 381 to draw something;  after it is finished drawing, the type manager
 382 calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0)
 383 (the restore is needed because graphics contexts are shared, so
 384 they cannot be modified permanently).
 385 .PP
 386 \fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR
 387 except that it returns coordinates in the canvas's window on the
 388 screen, instead of coordinates in an off-screen pixmap.
 389 .PP
 390 \fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager
 391 to inform Tk that a portion of a canvas needs to be redrawn.
 392 The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments
 393 specify the region that needs to be redrawn, in canvas coordinates.
 394 Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR,
 395 since Tk can normally figure out when an item has changed and make
 396 the redisplay request on its behalf (this happens, for example
 397 whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR).
 398 The only time that a type manager needs to call
 399 \fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own
 400 without being invoked through one of the procedures in its Tk_ItemType;
 401 this could happen, for example, in an image item if the image is
 402 modified using image commands.
 403 .PP
 404 \fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are
 405 procedures that handle the \fB\-tags\fR option for canvas items.
 406 The code of a canvas type manager will not call these procedures
 407 directly, but will use their addresses to create a \fBTk_CustomOption\fR
 408 structure for the \fB\-tags\fR option.   The code typically looks
 409 like this:
 410 .PP
 411 .CS
 412 static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
 413     Tk_CanvasTagsPrintProc, (ClientData) NULL
 414 };
 415
 416 static const Tk_ConfigSpec configSpecs[] = {
 417     ...
 418     {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
 419         NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
 420     ...
 421 };
 422 .CE
 423 .SH KEYWORDS
 424 canvas, focus, item type, redisplay, selection, type manager