summaryrefslogtreecommitdiffstats
path: root/doc/ttk_Geometry.3
blob: 7617d6aaecccdbdcf51634f8139cc7cf91f8e51c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
'\"
'\" Copyright (c) 2004 Joe English
'\"
'\" RCS: @(#) $Id: ttk_Geometry.3,v 1.2 2006/11/15 13:29:17 dkf Exp $
'\" 
.so man.macros
.TH Geometry 3 8.5 Tk "Tk Themed Widget"
.BS
.SH NAME
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
.SH SYNOPSIS
.nf
\fB#include <tkTheme.h>\fR

Ttk_Box
\fBTtk_MakeBox\fR(int \fIx\fR, int \fIy\fR, int \fIwidth\fR, int \fIheight\fR);

Ttk_Box
\fBTtk_PadBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR);

Ttk_Box
\fBTtk_ExpandBox\fR(Ttk_Box \fIparcel\fR, Ttk_Padding \fIpadding\fR);

Ttk_Box
\fBTtk_PackBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR);

Ttk_Box
\fBTtk_StickBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, unsigned \fIsticky\fR);

Ttk_Box
\fBTtk_PlaceBox\fR(Ttk_Box *\fIcavity\fR, int \fIwidth\fR, int \fIheight\fR, Ttk_Side \fIside\fR, unsigned \fIsticky\fR);

Ttk_Box
\fBTtk_AnchorBox\fR(Ttk_Box \fIparcel\fR, int \fIwidth\fR, int \fIheight\fR, Tk_Anchor \fIanchor\fR);

Ttk_Padding
\fBTtk_MakePadding\fR(short \fIleft\fR, short \fItop\fR, short \fIright\fR, short \fIbottom\fR);

Ttk_Padding
\fBTtk_UniformPadding\fR(short \fIborder\fR);

Ttk_Padding
\fBTtk_AddPadding\fR(Ttk_Padding \fIpadding1\fR, Ttk_Padding \fIpadding2\fR;

Ttk_Padding 
\fBTtk_RelievePadding\fR(Ttk_Padding \fIpadding\fR, int \fIrelief\fR);

int
\fBTtk_BoxContains\fR(Ttk_Box \fIbox\fR, int \fIx\fR, int \fIy\fR);

int
\fBTtk_GetPaddingFromObj\fR(Tcl_Interp *\fIinterp\fR, Tk_Window \fItkwin\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR);

int
\fBTtk_GetBorderFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, Ttk_Padding *\fIpadding_rtn\fR);

int
\fBTtk_GetStickyFromObj\fR(Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR, int *\fIsticky_rtn\fR);
.fi

.SH ARGUMENTS
.AP Tk_Anchor anchor in
One of the symbolic constants \fBTK_ANCHOR_N\fR, \fBTK_ANCHOR_NE\fR,
etc.  See \fITk_GetAnchorFromObj(3)\fR.
.AP "Ttk_Box *" cavity in/out
A rectangular region from which a parcel is allocated.
.AP short border in
Extra padding (in pixels) to add uniformly to each side of a region.
.AP short bottom in
Extra padding (in pixels) to add to the bottom of a region.
.AP Ttk_Box box in
.AP "Ttk_Box *" box_rtn out
Specifies a rectangular region.
.AP int height in
The height in pixels of a region.
.AP "Tcl_Interp *" interp in
Used to store error messages.
.AP int left in
Extra padding (in pixels) to add to the left side of a region.
.AP "Tcl_Obj *" objPtr in
String value contains a symbolic name 
to be converted to an enumerated value or bitmask.
Internal rep may be be modified to cache corresponding value.
.AP Ttk_Padding padding in
.AP "Ttk_Padding *" padding_rtn out
Extra padding to add on the inside of a region.
.AP Ttk_Box parcel in
A rectangular region, allocated from a cavity.
.AP int relief in
One of the standard Tk relief options 
(TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, etc.).  
See \fBTk_GetReliefFromObj\fR.
.AP short right in
Extra padding (in pixles) to add to the right side of a region.
.AP Ttk_Side side in
One of \fBTTK_SIDE_LEFT\fR, \fBTTK_SIDE_TOP\fR, 
\fBTTK_SIDE_RIGHT\fR, or \fBTTK_SIDE_BOTTOM\fR.
.AP unsigned sticky in
A bitmask containing one or more of the bits
\fBTTK_STICK_W\fR (west, or left), 
\fBTTK_STICK_E\fR (east, or right, 
\fBTTK_STICK_N\fR (north, or top), and
\fBTTK_STICK_S\fR (south, or bottom).
\fBTTK_FILL_X\fR is defined as a synonym for (TTK_STICK_W|TTK_STICK_E),
\fBTTK_FILL_Y\fR is a synonym for (TTK_STICK_N|TTK_STICK_S),
and  \fBTTK_FILL_BOTH\fR and \fBTTK_STICK_ALL\fR
are synonyms for (TTK_FILL_X|TTK_FILL_Y).
See also: \fIgrid(n)\fR.
.AP Tk_Window tkwin in
Window whose screen geometry determines 
the conversion between absolute units and pixels.
.AP short top in
Extra padding at the top of a region.
.AP int width in
The width in pixels of a region.
.AP int x in
X coordinate of upper-left corner of region.
.AP int y in
Y coordinate of upper-left corner of region.
.BE

.SH "BOXES"
The \fBTtk_Box\fR structure represents a rectangular region of a window: 
.CS
typedef struct 	{
    int x;
    int y;
    int width;
    int height;
} Ttk_Box;
.CE
All coordinates are relative to the window.
.PP
\fBTtk_MakeBox\fR is a convenience routine that contsructs
a \fBTtk_Box\fR structure representing a region \fIwidth\fR pixels
wide, \fIheight\fR pixels tall, at the specified \fIx, y\fR coordinates.
.PP
\fBTtk_PadBox\fR returns a new box located inside the specified \fIparcel\fR,
shrunken according to the left, top, right, and bottom margins 
specified by \fIpadding\fR.
.PP
\fBTtk_ExpandBox\fR is the inverse of \fBTtk_PadBox\fR:
it returns a new box surrounding the specified \fIparcel\fR,
expanded  according to the left, top, right, and bottom margins 
specified by \fIpadding\fR.
.PP
\fBTtk_PackBox\fR allocates a parcel \fIwidth\fR by \fIheight\fR
pixels wide on the specified \fIside\fR of the \fIcavity\fR,
and shrinks the \fIcavity\fR accordingly.
.PP
\fBTtk_StickBox\fR places a box with the requested \fIwidth\fR
and \fIheight\fR inside the \fIparcel\fR according to the 
\fIsticky\fR bits.
.PP
\fBTtk_PlaceBox\fR combines \fBTtk_PackBox\fR and \fBTtk_StickBox\fR:
it allocates a parcel on the specified \fIside\fR of the \fIcavity\fR,
places a box of the requested size inside the parcel according to \fIsticky\fR,
and shrinks the \fIcavity\fR.
.PP
\fBTtk_AnchorBox\fR places a box with the requested \fIwidth\fR
and \fIheight\fR inside the \fIparcel\fR according to the
specified \fIanchor\fR option.
.PP
\fBTtk_BoxContains\fR tests if the specified \fIx, y\fR coordinate
lies within the rectangular region \fIbox\fR.
.SH "PADDDING"
The \fBTtk_Padding\fR structure is used to represent 
borders, internal padding, and external margins:
.CS
typedef struct {
    short left;
    short top;
    short right;
    short bottom;
} Ttk_Padding;
.CE
.PP 
\fBTtk_MakePadding\fR is a convenience routine that contsructs
a \fBTtk_Padding\fR structure with the specified left, top, right, and bottom
components.  
.PP
\fBTtk_UniformPadding\fR constructs a \fBTtk_Padding\fR structure
with all components equal to the specified \fIborder\fR.
.PP
\fBTtk_AddPadding\fR adds two \fBTtk_Padding\fRs together
and returns a combined padding containing the sum of the
individual padding components.
.PP
\fBTtk_RelievePadding\fR 
adds an extra 2 pixels of padding to \fIpadding\fR
according to the specified \fIrelief\fR.
If \fIrelief\fR is \fBTK_RELIEF_SUNKEN\fR, 
adds two pixels at the top and left
so the inner region is shifted down and to the left.
If it is \fBTK_RELIEF_RAISED\fR, adds two pixels
at the bottom and right so 
the inner region is shifted up and to the right.
Otherwise, adds 1 pixel on all sides.
This is typically used in element geometry procedures to simulate 
a "pressed-in" look for pushbuttons.

.SH "CONVERSION ROUTINES"
\fBTtk_GetPaddingFromObj\fR converts the string in \fIobjPtr\fR
to a \fBTtk_Padding\fR structure.
The string representation is a list of 
up to four length specifications 
\fI"left top right bottom"\fR.  
If fewer than four elements are specified, 
\fIbottom\fR defaults to \fItop\fR,
\fIright\fR defaults to \fIleft\fR, and 
\fItop\fR defaults to \fIleft\fR.
See \fBTk_GetPixelsFromObj(3)\fR for the syntax of length specifications.
.PP
\fBTtk_GetBorderFromObj\fR is the same as \fBTtk_GetPaddingFromObj\fR
except that the lengths are specified as integers 
(i.e., resolution-dependant values like \fI3m\fR are not allowed).
.PP
\fBTtk_GetStickyFromObj\fR converts the string in \fIobjPtr\fR
to a \fIsticky\fR bitmask.  The string contains zero or more
of the characters \fBn\fR, \fBs\fR, \fBe\fR, or \fBw\fR.

.SH "SEE ALSO"
Tk_GetReliefFromObj(3), Tk_GetPixelsFromObj(3), Tk_GetAnchorFromObj(3)

.SH "KEYWORDS"
geometry, padding, margins, box, region, sticky, relief