CELLLINUX64/util/CELLLINUX64/man/man3/GetImage.3

   1 '\"
   2 '\" Copyright (c) 1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id: GetImage.3,v 1.5 2002/08/05 04:30:38 dgp Exp $
   9 '\"
  10 '\" The definitions below are for supplemental macros used in Tcl/Tk
  11 '\" manual entries.
  12 '\"
  13 '\" .AP type name in/out ?indent?
  14 '\"     Start paragraph describing an argument to a library procedure.
  15 '\"     type is type of argument (int, etc.), in/out is either "in", "out",
  16 '\"     or "in/out" to describe whether procedure reads or modifies arg,
  17 '\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  18 '\"     needed;  use .AS below instead)
  19 '\"
  20 '\" .AS ?type? ?name?
  21 '\"     Give maximum sizes of arguments for setting tab stops.  Type and
  22 '\"     name are examples of largest possible arguments that will be passed
  23 '\"     to .AP later.  If args are omitted, default tab stops are used.
  24 '\"
  25 '\" .BS
  26 '\"     Start box enclosure.  From here until next .BE, everything will be
  27 '\"     enclosed in one large box.
  28 '\"
  29 '\" .BE
  30 '\"     End of box enclosure.
  31 '\"
  32 '\" .CS
  33 '\"     Begin code excerpt.
  34 '\"
  35 '\" .CE
  36 '\"     End code excerpt.
  37 '\"
  38 '\" .VS ?version? ?br?
  39 '\"     Begin vertical sidebar, for use in marking newly-changed parts
  40 '\"     of man pages.  The first argument is ignored and used for recording
  41 '\"     the version when the .VS was added, so that the sidebars can be
  42 '\"     found and removed when they reach a certain age.  If another argument
  43 '\"     is present, then a line break is forced before starting the sidebar.
  44 '\"
  45 '\" .VE
  46 '\"     End of vertical sidebar.
  47 '\"
  48 '\" .DS
  49 '\"     Begin an indented unfilled display.
  50 '\"
  51 '\" .DE
  52 '\"     End of indented unfilled display.
  53 '\"
  54 '\" .SO
  55 '\"     Start of list of standard options for a Tk widget.  The
  56 '\"     options follow on successive lines, in four columns separated
  57 '\"     by tabs.
  58 '\"
  59 '\" .SE
  60 '\"     End of list of standard options for a Tk widget.
  61 '\"
  62 '\" .OP cmdName dbName dbClass
  63 '\"     Start of description of a specific option.  cmdName gives the
  64 '\"     option's name as specified in the class command, dbName gives
  65 '\"     the option's name in the option database, and dbClass gives
  66 '\"     the option's class in the option database.
  67 '\"
  68 '\" .UL arg1 arg2
  69 '\"     Print arg1 underlined, then print arg2 normally.
  70 '\"
  71 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
  72 '\"
  73 '\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  74 .if t .wh -1.3i ^B
  75 .nr ^l \n(.l
  76 .ad b
  77 '\"     # Start an argument description
  78 .de AP
  79 .ie !"\\$4"" .TP \\$4
  80 .el \{\
  81 .   ie !"\\$2"" .TP \\n()Cu
  82 .   el          .TP 15
  83 .\}
  84 .ta \\n()Au \\n()Bu
  85 .ie !"\\$3"" \{\
  86 \&\\$1  \\fI\\$2\\fP    (\\$3)
  87 .\".b
  88 .\}
  89 .el \{\
  90 .br
  91 .ie !"\\$2"" \{\
  92 \&\\$1  \\fI\\$2\\fP
  93 .\}
  94 .el \{\
  95 \&\\fI\\$1\\fP
  96 .\}
  97 .\}
  98 ..
  99 '\"     # define tabbing values for .AP
 100 .de AS
 101 .nr )A 10n
 102 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 103 .nr )B \\n()Au+15n
 104 .\"
 105 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 106 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 107 ..
 108 .AS Tcl_Interp Tcl_CreateInterp in/out
 109 '\"     # BS - start boxed text
 110 '\"     # ^y = starting y location
 111 '\"     # ^b = 1
 112 .de BS
 113 .br
 114 .mk ^y
 115 .nr ^b 1u
 116 .if n .nf
 117 .if n .ti 0
 118 .if n \l'\\n(.lu\(ul'
 119 .if n .fi
 120 ..
 121 '\"     # BE - end boxed text (draw box now)
 122 .de BE
 123 .nf
 124 .ti 0
 125 .mk ^t
 126 .ie n \l'\\n(^lu\(ul'
 127 .el \{\
 128 .\"     Draw four-sided box normally, but don't draw top of
 129 .\"     box if the box started on an earlier page.
 130 .ie !\\n(^b-1 \{\
 131 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 132 .\}
 133 .el \}\
 134 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 135 .\}
 136 .\}
 137 .fi
 138 .br
 139 .nr ^b 0
 140 ..
 141 '\"     # VS - start vertical sidebar
 142 '\"     # ^Y = starting y location
 143 '\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 144 .de VS
 145 .if !"\\$2"" .br
 146 .mk ^Y
 147 .ie n 'mc \s12\(br\s0
 148 .el .nr ^v 1u
 149 ..
 150 '\"     # VE - end of vertical sidebar
 151 .de VE
 152 .ie n 'mc
 153 .el \{\
 154 .ev 2
 155 .nf
 156 .ti 0
 157 .mk ^t
 158 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 159 .sp -1
 160 .fi
 161 .ev
 162 .\}
 163 .nr ^v 0
 164 ..
 165 '\"     # Special macro to handle page bottom:  finish off current
 166 '\"     # box/sidebar if in box/sidebar mode, then invoked standard
 167 '\"     # page bottom macro.
 168 .de ^B
 169 .ev 2
 170 'ti 0
 171 'nf
 172 .mk ^t
 173 .if \\n(^b \{\
 174 .\"     Draw three-sided box if this is the box's first page,
 175 .\"     draw two sides but no top otherwise.
 176 .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
 177 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 178 .\}
 179 .if \\n(^v \{\
 180 .nr ^x \\n(^tu+1v-\\n(^Yu
 181 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 182 .\}
 183 .bp
 184 'fi
 185 .ev
 186 .if \\n(^b \{\
 187 .mk ^y
 188 .nr ^b 2
 189 .\}
 190 .if \\n(^v \{\
 191 .mk ^Y
 192 .\}
 193 ..
 194 '\"     # DS - begin display
 195 .de DS
 196 .RS
 197 .nf
 198 .sp
 199 ..
 200 '\"     # DE - end display
 201 .de DE
 202 .fi
 203 .RE
 204 .sp
 205 ..
 206 '\"     # SO - start of list of standard options
 207 .de SO
 208 .SH "STANDARD OPTIONS"
 209 .LP
 210 .nf
 211 .ta 5.5c 11c
 212 .ft B
 213 ..
 214 '\"     # SE - end of list of standard options
 215 .de SE
 216 .fi
 217 .ft R
 218 .LP
 219 See the \\fBoptions\\fR manual entry for details on the standard options.
 220 ..
 221 '\"     # OP - start of full description for a single option
 222 .de OP
 223 .LP
 224 .nf
 225 .ta 4c
 226 Command-Line Name:      \\fB\\$1\\fR
 227 Database Name:  \\fB\\$2\\fR
 228 Database Class: \\fB\\$3\\fR
 229 .fi
 230 .IP
 231 ..
 232 '\"     # CS - begin code excerpt
 233 .de CS
 234 .RS
 235 .nf
 236 .ta .25i .5i .75i 1i
 237 ..
 238 '\"     # CE - end code excerpt
 239 .de CE
 240 .fi
 241 .RE
 242 ..
 243 .de UL
 244 \\$1\l'|0\(ul'\\$2
 245 ..
 246 .TH Tk_GetImage 3 4.0 Tk "Tk Library Procedures"
 247 .BS
 248 .SH NAME
 249 Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage \- use an image in a widget
 250 .SH SYNOPSIS
 251 .nf
 252 \fB#include <tk.h>\fR
 253 .sp
 254 Tk_Image
 255 \fBTk_GetImage\fR(\fIinterp, tkwin, name, changeProc, clientData\fR)
 256 .sp
 257 \fBTk_RedrawImage\fR(\fIimage, imageX, imageY, width, height, drawable, drawableX, drawableY\fR)
 258 .sp
 259 \fBTk_SizeOfImage\fR(\fIimage, widthPtr, heightPtr\fR)
 260 .sp
 261 \fBTk_FreeImage\fR(\fIimage\fR)
 262 .SH ARGUMENTS
 263 .AS Tk_ImageChangedProc *changeProc
 264 .AP Tcl_Interp *interp in
 265 Place to leave error message.
 266 .AP Tk_Window tkwin in
 267 Window in which image will be used.
 268 .AP "CONST char" *name in
 269 Name of image.
 270 .AP Tk_ImageChangedProc *changeProc in
 271 Procedure for Tk to invoke whenever image content or size changes.
 272 .AP ClientData clientData in
 273 One-word value for Tk to pass to \fIchangeProc\fR.
 274 .AP Tk_Image image in
 275 Token for image instance;  must have been returned by a previous
 276 call to \fBTk_GetImage\fR.
 277 .AP int imageX in
 278 X-coordinate of upper-left corner of region of image to redisplay
 279 (measured in pixels from the image's upper-left corner).
 280 .AP int imageY in
 281 Y-coordinate of upper-left corner of region of image to redisplay
 282 (measured in pixels from the image's upper-left corner).
 283 .AP "int" width (in)
 284 Width of region of image to redisplay.
 285 .AP "int" height (in)
 286 Height of region of image to redisplay.
 287 .AP Drawable drawable in
 288 Where to display image.  Must either be window specified to
 289 \fBTk_GetImage\fR or a pixmap compatible with that window.
 290 .AP int drawableX in
 291 Where to display image in \fIdrawable\fR: this is the x-coordinate
 292 in \fIdrawable\fR where x-coordinate \fIimageX\fR of the image
 293 should be displayed.
 294 .AP int drawableY in
 295 Where to display image in \fIdrawable\fR: this is the y-coordinate
 296 in \fIdrawable\fR where y-coordinate \fIimageY\fR of the image
 297 should be displayed.
 298 .AP "int" widthPtr out
 299 Store width of \fIimage\fR (in pixels) here.
 300 .AP "int" heightPtr out
 301 Store height of \fIimage\fR (in pixels) here.
 302 .BE
 303
 304 .SH DESCRIPTION
 305 .PP
 306 These procedures are invoked by widgets that wish to display images.
 307 \fBTk_GetImage\fR is invoked by a widget when it first decides to
 308 display an image.
 309 \fIname\fR gives the name of the desired image and \fItkwin\fR
 310 identifies the window where the image will be displayed.
 311 \fBTk_GetImage\fR looks up the image in the table of existing
 312 images and returns a token for a new instance of the image.
 313 If the image doesn't exist then \fBTk_GetImage\fR returns NULL
 314 and leaves an error message in \fIinterp->result\fR.
 315 .PP
 316 When a widget wishes to actually display an image it must
 317 call \fBTk_RedrawImage\fR, identifying the image (\fIimage\fR),
 318 a region within the image to redisplay (\fIimageX\fR, \fIimageY\fR,
 319 \fIwidth\fR, and \fIheight\fR), and a place to display the
 320 image (\fIdrawable\fR, \fIdrawableX\fR, and \fIdrawableY\fR).
 321 Tk will then invoke the appropriate image manager, which will
 322 display the requested portion of the image before returning.
 323 .PP
 324 A widget can find out the dimensions of an image by calling
 325 \fBTk_SizeOfImage\fR:  the width and height will be stored
 326 in the locations given by \fIwidthPtr\fR and \fIheightPtr\fR,
 327 respectively.
 328 .PP
 329 When a widget is finished with an image (e.g., the widget is
 330 being deleted or it is going to use a different image instead
 331 of the current one), it must call \fBTk_FreeImage\fR to
 332 release the image instance.
 333 The widget should never again use the image token after passing
 334 it to \fBTk_FreeImage\fR.
 335 There must be exactly one call to \fBTk_FreeImage\fR for each
 336 call to \fBTk_GetImage\fR.
 337 .PP
 338 If the contents or size of an image changes, then any widgets
 339 using the image will need to find out about the changes so that
 340 they can redisplay themselves.
 341 The \fIchangeProc\fR and \fIclientData\fR arguments to
 342 \fBTk_GetImage\fR are used for this purpose.
 343 \fIchangeProc\fR will be called by Tk whenever a change occurs
 344 in the image;  it must match the following prototype:
 345 .CS
 346 typedef void Tk_ImageChangedProc(
 347         ClientData \fIclientData\fR,
 348         int \fIx\fR,
 349         int \fIy\fR,
 350         int \fIwidth\fR,
 351         int \fIheight\fR,
 352         int \fIimageWidth\fR,
 353         int \fIimageHeight\fR);
 354 .CE
 355 The \fIclientData\fR argument to \fIchangeProc\fR is the same as the
 356 \fIclientData\fR argument to \fBTk_GetImage\fR.
 357 It is usually a pointer to the widget record for the widget or
 358 some other data structure managed by the widget.
 359 The arguments \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
 360 identify a region within the image that must be redisplayed;
 361 they are specified in pixels measured from the upper-left
 362 corner of the image.
 363 The arguments \fIimageWidth\fR and \fIimageHeight\fR give
 364 the image's (new) size.
 365
 366 .SH "SEE ALSO"
 367 Tk_CreateImageType
 368
 369 .SH KEYWORDS
 370 images, redisplay