2 '\" Copyright (c) 2004 Joe English
4 '\" RCS: @(#) $Id: ttk_Geometry.3,v 1.4 2007/12/13 15:23:44 dgp Exp $
6 .\" The -*- nroff -*- definitions below are for supplemental macros used
7 .\" in Tcl/Tk manual entries.
9 .\" .AP type name in/out ?indent?
10 .\" Start paragraph describing an argument to a library procedure.
11 .\" type is type of argument (int, etc.), in/out is either "in", "out",
12 .\" or "in/out" to describe whether procedure reads or modifies arg,
13 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
14 .\" needed; use .AS below instead)
17 .\" Give maximum sizes of arguments for setting tab stops. Type and
18 .\" name are examples of largest possible arguments that will be passed
19 .\" to .AP later. If args are omitted, default tab stops are used.
22 .\" Start box enclosure. From here until next .BE, everything will be
23 .\" enclosed in one large box.
26 .\" End of box enclosure.
29 .\" Begin code excerpt.
34 .\" .VS ?version? ?br?
35 .\" Begin vertical sidebar, for use in marking newly-changed parts
36 .\" of man pages. The first argument is ignored and used for recording
37 .\" the version when the .VS was added, so that the sidebars can be
38 .\" found and removed when they reach a certain age. If another argument
39 .\" is present, then a line break is forced before starting the sidebar.
42 .\" End of vertical sidebar.
45 .\" Begin an indented unfilled display.
48 .\" End of indented unfilled display.
51 .\" Start of list of standard options for a Tk widget. The manpage
52 .\" argument defines where to look up the standard options; if
53 .\" omitted, defaults to "options". The options follow on successive
54 .\" lines, in three columns separated by tabs.
57 .\" End of list of standard options for a Tk widget.
59 .\" .OP cmdName dbName dbClass
60 .\" Start of description of a specific option. cmdName gives the
61 .\" option's name as specified in the class command, dbName gives
62 .\" the option's name in the option database, and dbClass gives
63 .\" the option's class in the option database.
66 .\" Print arg1 underlined, then print arg2 normally.
69 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
72 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
73 .\" (for trailing punctuation) and then a closing parenthesis.
75 .\" RCS: @(#) $Id: man.macros,v 1.9 2008/01/29 15:32:33 dkf Exp $
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
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.
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
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
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
275 .TH Geometry 3 8.5 Tk "Tk Themed Widget"
278 Ttk_MakeBox, Ttk_PadBox, Ttk_ExpandBox, Ttk_PackBox, Ttk_StickBox, Ttk_PlaceBox, Ttk_BoxContains, Ttk_MakePadding, Ttk_UniformPadding, Ttk_AddPadding, Ttk_RelievePadding, Ttk_GetPaddingFromObj, Ttk_GetBorderFromObj, Ttk_GetStickyFromObj \- Tk themed geometry utilities
281 \fB#include <tkTheme.h>\fR
284 \fBTtk_MakeBox\fR(int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR);
287 \fBTtk_PadBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR);
290 \fBTtk_ExpandBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR);
293 \fBTtk_PackBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR);
296 \fBTtk_StickBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, unsigned \fIsticky\fR);
299 \fBTtk_PlaceBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR, unsigned \fIsticky\fR);
302 \fBTtk_AnchorBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, Tk_Anchor \fIanchor\fR);
305 \fBTtk_MakePadding\fR(short \fIleft\fR, short \fItop\fR, short \fIright\fR, short \fIbottom\fR);
308 \fBTtk_UniformPadding\fR(short \fIborder\fR);
311 \fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR;
314 \fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR);
317 \fBTtk_BoxContains\fR(Ttk_Box \fIbox\fR, int \fIx\fR, int \fIy\fR);
320 \fBTtk_GetPaddingFromObj\fR(Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR);
323 \fBTtk_GetBorderFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR);
326 \fBTtk_GetStickyFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, int *\fIsticky_rtn\fR);
330 .AP Tk_Anchor anchor in
331 One of the symbolic constants \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR,
332 etc. See \fITk_GetAnchorFromObj(3)\fR.
333 .AP "Ttk_Box *" cavity in/out
334 A rectangular region from which a parcel is allocated.
336 Extra padding (in pixels) to add uniformly to each side of a region.
338 Extra padding (in pixels) to add to the bottom of a region.
340 .AP "Ttk_Box *" box_rtn out
341 Specifies a rectangular region.
343 The height in pixels of a region.
344 .AP "Tcl_Interp *" interp in
345 Used to store error messages.
347 Extra padding (in pixels) to add to the left side of a region.
348 .AP "Tcl_Obj *" objPtr in
349 String value contains a symbolic name
350 to be converted to an enumerated value or bitmask.
351 Internal rep may be be modified to cache corresponding value.
352 .AP Ttk_Padding padding in
353 .AP "Ttk_Padding *" padding_rtn out
354 Extra padding to add on the inside of a region.
355 .AP Ttk_Box parcel in
356 A rectangular region, allocated from a cavity.
358 One of the standard Tk relief options
359 (TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.).
360 See \fBTk_GetReliefFromObj\fR.
362 Extra padding (in pixles) to add to the right side of a region.
364 One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR,
365 \fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR.
366 .AP unsigned sticky in
367 A bitmask containing one or more of the bits
368 \fBTTK_STICK_W\fR (west, or left),
369 \fBTTK_STICK_E\fR (east, or right,
370 \fBTTK_STICK_N\fR (north, or top), and
371 \fBTTK_STICK_S\fR (south, or bottom).
372 \fBTTK_FILL_X\fR is defined as a synonym for (TTK_STICK_W|TTK_STICK_E),
373 \fBTTK_FILL_Y\fR is a synonym for (TTK_STICK_N|TTK_STICK_S),
374 and \fBTTK_FILL_BOTH\fR and \fBTTK_STICK_ALL\fR
375 are synonyms for (TTK_FILL_X|TTK_FILL_Y).
376 See also: \fIgrid(n)\fR.
377 .AP Tk_Window tkwin in
378 Window whose screen geometry determines
379 the conversion between absolute units and pixels.
381 Extra padding at the top of a region.
383 The width in pixels of a region.
385 X coordinate of upper-left corner of region.
387 Y coordinate of upper-left corner of region.
391 The \fBTtk_Box\fR structure represents a rectangular region of a window:
400 All coordinates are relative to the window.
402 \fBTtk_MakeBox\fR is a convenience routine that contsructs
403 a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels
404 wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates.
406 \fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR,
407 shrunken according to the left, top, right, and bottom margins
408 specified by \fIpadding\fR.
410 \fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fR:
411 it returns a new box surrounding the specified \fIparcel\fR,
412 expanded according to the left, top, right, and bottom margins
413 specified by \fIpadding\fR.
415 \fBTtk_PackBox\fR allocates a parcel \fIwidth\fR by \fIheight\fR
416 pixels wide on the specified \fIside\fR of the \fIcavity\fR,
417 and shrinks the \fIcavity\fR accordingly.
419 \fBTtk_StickBox\fR places a box with the requested \fIwidth\fR
420 and \fIheight\fR inside the \fIparcel\fR according to the
423 \fBTtk_PlaceBox\fR combines \fBTtk_PackBox\fR and \fBTtk_StickBox\fR:
424 it allocates a parcel on the specified \fIside\fR of the \fIcavity\fR,
425 places a box of the requested size inside the parcel according to \fIsticky\fR,
426 and shrinks the \fIcavity\fR.
428 \fBTtk_AnchorBox\fR places a box with the requested \fIwidth\fR
429 and \fIheight\fR inside the \fIparcel\fR according to the
430 specified \fIanchor\fR option.
432 \fBTtk_BoxContains\fR tests if the specified \fIx, y\fR coordinate
433 lies within the rectangular region \fIbox\fR.
435 The \fBTtk_Padding\fR structure is used to represent
436 borders, internal padding, and external margins:
446 \fBTtk_MakePadding\fR is a convenience routine that contsructs
447 a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom
450 \fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure
451 with all components equal to the specified \fIborder\fR.
453 \fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together
454 and returns a combined padding containing the sum of the
455 individual padding components.
457 \fBTtk_RelievePadding\fR
458 adds an extra 2 pixels of padding to \fIpadding\fR
459 according to the specified \fIrelief\fR.
460 If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR,
461 adds two pixels at the top and left
462 so the inner region is shifted down and to the left.
463 If it is \fBTK_RELIEF_RAISED\fR, adds two pixels
464 at the bottom and right so
465 the inner region is shifted up and to the right.
466 Otherwise, adds 1 pixel on all sides.
467 This is typically used in element geometry procedures to simulate a
469 look for pushbuttons.
470 .SH "CONVERSION ROUTINES"
471 \fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR
472 to a \fBTtk_Padding\fR structure.
473 The string representation is a list of
474 up to four length specifications
475 .QW "\fIleft top right bottom\fR" .
476 If fewer than four elements are specified,
477 \fIbottom\fR defaults to \fItop\fR,
478 \fIright\fR defaults to \fIleft\fR, and
479 \fItop\fR defaults to \fIleft\fR.
480 See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications.
482 \fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fR
483 except that the lengths are specified as integers
484 (i.e., resolution-dependant values like \fI3m\fR are not allowed).
486 \fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR
487 to a \fIsticky\fR bitmask. The string contains zero or more
488 of the characters \fBn\fR, \fBs\fR, \fBe\fR, or \fBw\fR.
490 Tk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3)
492 geometry, padding, margins, box, region, sticky, relief