2 '\" Copyright (c) 1990-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tk_Alloc3DBorderFromObj 3 8.1 Tk "Tk Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
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.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .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
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tk_Alloc3DBorderFromObj, Tk_Get3DBorder, Tk_Get3DBorderFromObj, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_3DBorderColor, Tk_3DBorderGC, Tk_Free3DBorderFromObj, Tk_Free3DBorder \- draw borders with three-dimensional appearance
281 \fB#include <tk.h>\fR
284 \fBTk_Alloc3DBorderFromObj(\fIinterp, tkwin, objPtr\fB)\fR
287 \fBTk_Get3DBorder(\fIinterp, tkwin, colorName\fB)\fR
290 \fBTk_Get3DBorderFromObj(\fItkwin, objPtr\fB)\fR
293 \fBTk_Draw3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
296 \fBTk_Fill3DRectangle(\fItkwin, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
299 \fBTk_Draw3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
302 \fBTk_Fill3DPolygon(\fItkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
305 \fBTk_3DVerticalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftBevel, relief\fB)\fR
308 \fBTk_3DHorizontalBevel\fR(\fItkwin, drawable, border, x, y, width, height, leftIn, rightIn, topBevel, relief\fB)\fR
311 \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
314 \fBTk_NameOf3DBorder(\fIborder\fB)\fR
317 \fBTk_3DBorderColor(\fIborder\fB)\fR
320 \fBTk_3DBorderGC(\fItkwin, border, which\fB)\fR
322 \fBTk_Free3DBorderFromObj(\fItkwin, objPtr\fB)\fR
324 \fBTk_Free3DBorder(\fIborder\fB)\fR
326 .AS "Tk_3DBorder" borderWidth
327 .AP Tcl_Interp *interp in
328 Interpreter to use for error reporting.
329 .AP Tk_Window tkwin in
330 Token for window (for all procedures except \fBTk_Get3DBorder\fR,
331 must be the window for which the border was allocated).
332 .AP Tcl_Obj *objPtr in
333 Pointer to value whose value describes color corresponding to
334 background (flat areas). Illuminated edges will be brighter than
335 this and shadowed edges will be darker than this.
336 .AP char *colorName in
337 Same as \fIobjPtr\fR except value is supplied as a string rather
339 .AP Drawable drawable in
340 X token for window or pixmap; indicates where graphics are to be drawn.
341 Must either be the X window for \fItkwin\fR or a pixmap with the
342 same screen and depth as \fItkwin\fR.
343 .AP Tk_3DBorder border in
344 Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
346 X-coordinate of upper-left corner of rectangle describing border
349 Y-coordinate of upper-left corner of rectangle describing border or
352 Width of rectangle describing border or bevel, in pixels.
354 Height of rectangle describing border or bevel, in pixels.
355 .AP int borderWidth in
356 Width of border in pixels. Positive means border is inside rectangle
357 given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
358 border is outside rectangle.
360 Indicates 3-D position of interior of value relative to exterior;
361 should be \fBTK_RELIEF_RAISED\fR, \fBTK_RELIEF_SUNKEN\fR, \fBTK_RELIEF_GROOVE\fR,
362 \fBTK_RELIEF_SOLID\fR, or \fBTK_RELIEF_RIDGE\fR (may also be \fBTK_RELIEF_FLAT\fR
363 for \fBTk_Fill3DRectangle\fR).
364 .AP XPoint *pointPtr in
365 Pointer to array of points describing the set of vertices in a polygon.
366 The polygon need not be closed (it will be closed automatically if it
369 Number of points at \fI*pointPtr\fR.
370 .AP int polyBorderWidth in
371 Width of border in pixels. If positive, border is drawn to left of
372 trajectory given by \fIpointPtr\fR; if negative, border is drawn to
373 right of trajectory. If \fIleftRelief\fR is \fBTK_RELIEF_GROOVE\fR or
374 \fBTK_RELIEF_RIDGE\fR then the border is centered on the trajectory.
375 .AP int leftRelief in
376 Height of left side of polygon's path relative to right. \fBTK_RELIEF_RAISED\fR
377 means left side should appear higher and \fBTK_RELIEF_SUNKEN\fR means right side
378 should appear higher;
379 \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean the obvious things.
380 For \fBTk_Fill3DPolygon\fR, \fBTK_RELIEF_FLAT\fR may also be specified to
381 indicate no difference in height.
383 Non-zero means this bevel forms the left side of the value; zero means
384 it forms the right side.
386 Non-zero means that the left edge of the horizontal bevel angles in,
387 so that the bottom of the edge is farther to the right than
389 Zero means the edge angles out, so that the bottom is farther to the
392 Non-zero means that the right edge of the horizontal bevel angles in,
393 so that the bottom of the edge is farther to the left than the top.
394 Zero means the edge angles out, so that the bottom is farther to the
397 Non-zero means this bevel forms the top side of the value; zero means
398 it forms the bottom side.
400 Specifies which of the border's graphics contexts is desired.
401 Must be \fBTK_3D_FLAT_GC\fR, \fBTK_3D_LIGHT_GC\fR, or \fBTK_3D_DARK_GC\fR.
405 These procedures provide facilities for drawing window borders in a
406 way that produces a three-dimensional appearance.
407 \fBTk_Alloc3DBorderFromObj\fR
408 allocates colors and Pixmaps needed to draw a border in the window
409 given by the \fItkwin\fR argument. The value of \fIobjPtr\fR
410 is a standard Tk color name that determines the border colors.
411 The color indicated by \fIobjPtr\fR will not actually be used in
412 the border; it indicates the background color for the window
413 (i.e. a color for flat surfaces).
414 The illuminated portions of the border will appear brighter than indicated
415 by \fIobjPtr\fR, and the shadowed portions of the border will appear
416 darker than \fIobjPtr\fR.
418 \fBTk_Alloc3DBorderFromObj\fR returns a token that may be used in later calls
419 to \fBTk_Draw3DRectangle\fR. If an error occurs in allocating information
420 for the border (e.g. a bogus color name was given)
421 then NULL is returned and an error message is left as the result of
422 interpreter \fIinterp\fR.
423 If it returns successfully, \fBTk_Alloc3DBorderFromObj\fR caches
424 information about the return value in \fIobjPtr\fR, which speeds up
425 future calls to \fBTk_Alloc3DBorderFromObj\fR with the same \fIobjPtr\fR
428 \fBTk_Get3DBorder\fR is identical to \fBTk_Alloc3DBorderFromObj\fR except
429 that the color is specified with a string instead of a value. This
430 prevents \fBTk_Get3DBorder\fR from caching the return value, so
431 \fBTk_Get3DBorder\fR is less efficient than \fBTk_Alloc3DBorderFromObj\fR.
433 \fBTk_Get3DBorderFromObj\fR returns the token for an existing border, given
434 the window and color name used to create the border.
435 \fBTk_Get3DBorderFromObj\fR does not actually create the border; it must
436 already have been created with a previous call to
437 \fBTk_Alloc3DBorderFromObj\fR or \fBTk_Get3DBorder\fR. The return
438 value is cached in \fIobjPtr\fR, which speeds up
439 future calls to \fBTk_Get3DBorderFromObj\fR with the same \fIobjPtr\fR
442 Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
443 invoked to draw the border.
444 The \fItkwin\fR argument specifies the
445 window for which the border was allocated, and \fIdrawable\fR
446 specifies a window or pixmap in which the border is to be drawn.
447 \fIDrawable\fR need not refer to the same window as \fItkwin\fR, but it
448 must refer to a compatible
449 pixmap or window: one associated with the same screen and with the
450 same depth as \fItkwin\fR.
451 The \fIx\fR, \fIy\fR, \fIwidth\fR, and
452 \fIheight\fR arguments define the bounding box of the border region
453 within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
454 \fIwidth\fR and \fIheight\fR are the dimensions of the window), and
455 \fIborderWidth\fR specifies the number of pixels actually
456 occupied by the border. The \fIrelief\fR argument indicates
457 which of several three-dimensional effects is desired:
458 \fBTK_RELIEF_RAISED\fR means that the interior of the rectangle should
459 appear raised relative to the exterior of the rectangle, and
460 \fBTK_RELIEF_SUNKEN\fR means that the interior should appear depressed.
461 \fBTK_RELIEF_GROOVE\fR and \fBTK_RELIEF_RIDGE\fR mean that there should appear to be
462 a groove or ridge around the exterior of the rectangle.
464 \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
465 that it first fills the rectangular area with the background color
467 to the color used to create \fIborder\fR). Then it calls
468 \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
469 the rectangular area. The argument \fIrelief\fR indicates the desired
470 effect (\fBTK_RELIEF_FLAT\fR means no border should be drawn; all that
471 happens is to fill the rectangle with the background color).
473 The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
474 shapes with a three-dimensional appearance. The \fIpointPtr\fR and
475 \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
476 indicates how wide the border should be (and on which side of the
477 trajectory to draw it), and \fIleftRelief\fR indicates which side
478 of the trajectory should appear raised. \fBTk_Draw3DPolygon\fR
479 draws a border around the given trajectory using the colors from
480 \fIborder\fR to produce a three-dimensional appearance. If the trajectory is
481 non-self-intersecting, the appearance will be a raised or sunken
482 polygon shape. The trajectory may be self-intersecting, although
483 it's not clear how useful this is.
485 \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
486 \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR: it fills
487 the polygonal area with the background color from \fIborder\fR,
488 then calls \fBTk_Draw3DPolygon\fR to draw a border around the
489 area (unless \fIleftRelief\fR is \fBTK_RELIEF_FLAT\fR; in this case no
492 The procedures \fBTk_3DVerticalBevel\fR and \fBTk_3DHorizontalBevel\fR
493 provide lower-level drawing primitives that are used by
494 procedures such as \fBTk_Draw3DRectangle\fR.
495 These procedures are also useful in their own right for drawing
496 rectilinear border shapes.
497 \fBTk_3DVerticalBevel\fR draws a vertical beveled edge, such as the
498 left or right side of a rectangle, and \fBTk_3DHorizontalBevel\fR
499 draws a horizontal beveled edge, such as the top or bottom of a
501 Each procedure takes \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR
502 arguments that describe the rectangular area of the beveled edge
503 (e.g., \fIwidth\fR is the border width for \fBTk_3DVerticalBevel\fR).
504 The \fIleftBorder\fR and \fItopBorder\fR arguments indicate the
505 position of the border relative to the
508 \fIrelief\fR indicates the relief of the inside of the value relative
510 \fBTk_3DVerticalBevel\fR just draws a rectangular region.
511 \fBTk_3DHorizontalBevel\fR draws a trapezoidal region to generate
512 mitered corners; it should be called after \fBTk_3DVerticalBevel\fR
513 (otherwise \fBTk_3DVerticalBevel\fR will overwrite the mitering in
515 The \fIleftIn\fR and \fIrightIn\fR arguments to \fBTk_3DHorizontalBevel\fR
516 describe the mitering at the corners; a value of 1 means that the bottom
517 edge of the trapezoid will be shorter than the top, 0 means it will
519 For example, to draw a rectangular border the top bevel should be
520 drawn with 1 for both \fIleftIn\fR and \fIrightIn\fR, and the
521 bottom bevel should be drawn with 0 for both arguments.
523 The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
524 pixel and/or pixmap of \fItkwin\fR to produce a result compatible
525 with \fIborder\fR. For color displays, the resulting background will
526 just be the color specified when \fIborder\fR was created; for monochrome
527 displays, the resulting background
528 will be a light stipple pattern, in order to distinguish the background from
529 the illuminated portion of the border.
531 Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
532 will return the color name that was used to create the border.
534 The procedure \fBTk_3DBorderColor\fR returns the XColor structure
535 that will be used for flat surfaces drawn for its \fIborder\fR
536 argument by procedures like \fBTk_Fill3DRectangle\fR.
537 The return value corresponds to the color name that was used to
539 The XColor, and its associated pixel value, will remain allocated
540 as long as \fIborder\fR exists.
542 The procedure \fBTk_3DBorderGC\fR returns one of the X graphics contexts
543 that are used to draw the border.
544 The argument \fIwhich\fR selects which one of the three possible GC's:
545 \fBTK_3D_FLAT_GC\fR returns the context used for flat surfaces,
546 \fBTK_3D_LIGHT_GC\fR returns the context for light shadows,
547 and \fBTK_3D_DARK_GC\fR returns the context for dark shadows.
549 When a border is no longer needed, \fBTk_Free3DBorderFromObj\fR
550 or \fBTk_Free3DBorder\fR should
551 be called to release the resources associated with it.
552 For \fBTk_Free3DBorderFromObj\fR the border to release is specified
553 with the window and color name used to create the
554 border; for \fBTk_Free3DBorder\fR the border to release is specified
555 with the Tk_3DBorder token for the border.
556 There should be exactly one call to \fBTk_Free3DBorderFromObj\fR or
557 \fBTk_Free3DBorder\fR for each call to \fBTk_Alloc3DBorderFromObj\fR
558 or \fBTk_Get3DBorder\fR.
560 3D, background, border, color, depressed, illumination, value, polygon, raised, shadow, three-dimensional effect
OSDN Git Service
