Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996, Expert Interface Technologies |
2 | # See the file "license.terms" for information on usage and redistribution | |
3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | # | |
5 | # The file man.macros and some of the macros used by this file are | |
6 | # copyrighted: (c) 1990 The Regents of the University of California. | |
7 | # (c) 1994-1995 Sun Microsystems, Inc. | |
8 | # The license terms of the Tcl/Tk distrobution are in the file | |
9 | # license.tcl. | |
10 | ||
11 | =head1 NAME | |
12 | ||
13 | Tk::Compound - Create multi-line compound images. | |
14 | ||
15 | =for category Tk Image Classes | |
16 | ||
17 | S< >use Tk::Compound; | |
18 | S< >I<$image> = I<$widget>-E<gt>B<Compound>?(I<name>??,I<options>?) | |
19 | S< >I<$image>-E<gt>B<Line>?(I<options>?) | |
20 | S< >I<$image>-E<gt>B<Text>?(I<options>?) | |
21 | S< >I<$image>-E<gt>B<Bitmap>?(I<options>?) | |
22 | S< >I<$image>-E<gt>B<Image>?(I<options>?) | |
23 | S< >I<$image>-E<gt>B<Space>?(I<options>?) | |
24 | ||
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | Compound image types can be used to create images that consists of | |
29 | multiple horizontal lines; each line is composed of a series of items | |
30 | (texts, bitmaps, images or spaces) arranged from left to | |
31 | right. Compound images are mainly used to embed complex drawings into | |
32 | widgets that support the B<-image> option. As shown in the EXAMPLE | |
33 | section below, a compound image can be used to display a bitmap and a | |
34 | text string simutaneously in a Tk B<Button> widget. | |
35 | ||
36 | Compound images can only be used on windows on the same display as, and | |
37 | with the same pixel depth and visual as the I<$widget> used to create them. | |
38 | ||
39 | =head1 CREATING COMPOUND IMAGES | |
40 | ||
41 | Compounds are created using I<$widget>-E<gt>B<Compound>. | |
42 | Compounds support the following I<options>: | |
43 | ||
44 | =over 4 | |
45 | ||
46 | =item B<-background> =E<gt> I<color> | |
47 | ||
48 | Specifies the background color of the compound image. This color is | |
49 | also used as the default background color for the bitmap items in the | |
50 | compound image. | |
51 | ||
52 | =item B<-borderwidth> =E<gt> I<pixels> | |
53 | ||
54 | Specifies a non-negative value indicating the width of the 3-D border | |
55 | drawn around the compound image. | |
56 | ||
57 | =item B<-font> =E<gt> I<font> | |
58 | ||
59 | Specifies the default font for the text items in the compound image. | |
60 | ||
61 | =item B<-foreground> =E<gt> I<color> | |
62 | ||
63 | Specifies the default foreground color for the bitmap and text items | |
64 | in the compound image. | |
65 | ||
66 | =item B<-padx> =E<gt> I<value> | |
67 | ||
68 | Specifies a non-negative value indicating how much extra space to | |
69 | request for the compound image in the X-direction. The I<value> may | |
70 | have any of the forms acceptable to B<Tk_GetPixels(3)>. | |
71 | ||
72 | =item B<-pady> =E<gt> I<value> | |
73 | ||
74 | Specifies a non-negative value indicating how much extra space to | |
75 | request for the compound image in the Y-direction. | |
76 | ||
77 | =item B<-relief> =E<gt> I<value> | |
78 | ||
79 | Specifies the 3-D effect desired for the background of the compound | |
80 | image. Acceptable values are B<raised>, B<sunken>, B<flat>, | |
81 | B<ridge>, and B<groove>. | |
82 | ||
83 | =item B<-showbackground> =E<gt> I<value> | |
84 | ||
85 | Specifies whether the background and the 3D borders should be drawn. | |
86 | Must be a valid boolean value. By default the background is not drawn | |
87 | and the compound image appears to have a transparent background. | |
88 | ||
89 | ||
90 | =back | |
91 | ||
92 | =head1 IMAGE COMMAND | |
93 | ||
94 | When a compound image is created, Tk also creates a new object. | |
95 | This object supports the B<configure> and B<cget> methods | |
96 | described in L<Tk::options> which can be used to enquire and | |
97 | modify the options described above. | |
98 | ||
99 | The object also supports the following methods: | |
100 | ||
101 | =over 4 | |
102 | ||
103 | =item I<$compound>-E<gt>B<Line>?(I<option => value ...>)? | |
104 | ||
105 | Creates a new line at the bottom of the compound image. Lines support | |
106 | the following I<options>: | |
107 | ||
108 | =over 4 | |
109 | ||
110 | =item B<-anchor> value | |
111 | ||
112 | Specifies how the line should be aligned along the horizontal axis. | |
113 | When the values are B<w>, B<sw> or B<nw>, the line is aligned | |
114 | to the left. When the values are B<c>, B<s> or B<n>, the line | |
115 | is aligned to the middle. When the values are B<e>, B<se> or | |
116 | B<ne>, the line is aligned to the right. | |
117 | ||
118 | =item B<-padx> =E<gt> I<value> | |
119 | ||
120 | Specifies a non-negative value indicating how much extra space to | |
121 | request for this line in the X-direction. | |
122 | ||
123 | =back | |
124 | ||
125 | =item I<$compound>-E<gt>I<Itemtype>?(I<option => value ...>)? | |
126 | ||
127 | Creates a new item of the type I<Itemtype> at the end of the last | |
128 | line of the compound image. All types of items support | |
129 | these following common I<options>: | |
130 | ||
131 | =over 4 | |
132 | ||
133 | =item B<-anchor> value | |
134 | ||
135 | Specifies how the item should be aligned along the vertical axis. When | |
136 | the values are B<n>, B<nw> or B<ne>, the item is aligned to | |
137 | the top of the line. When the values are B<c>, B<w> or B<e>, | |
138 | the item is aligned to the middle of the line. When the values are | |
139 | B<s>, B<se> or B<sw>, the item is aligned to the bottom of | |
140 | the line. | |
141 | ||
142 | =item B<-padx> =E<gt> I<value> | |
143 | ||
144 | Specifies a non-negative value indicating how much extra space to | |
145 | request for this item in the X-direction. | |
146 | ||
147 | =item B<-pady> =E<gt> I<value> | |
148 | ||
149 | Specifies a non-negative value indicating how much extra space to | |
150 | request for this item in the Y-direction. | |
151 | ||
152 | =item I<item-type> can be any of the following: | |
153 | ||
154 | =back | |
155 | ||
156 | =item I<$compound>-E<gt>B<Bitmap>?(I<option => value ...>)? | |
157 | ||
158 | Creates a new bitmap item of at the end of the last | |
159 | line of the compound image. Additional I<options> accepted by the | |
160 | bitmap type are: | |
161 | ||
162 | =over 4 | |
163 | ||
164 | =item B<-background> =E<gt> I<color> | |
165 | ||
166 | Specifies the background color of the bitmap item. | |
167 | ||
168 | =item B<-bitmap> =E<gt> I<name> | |
169 | ||
170 | Specifies a bitmap to display in this item, in any of the forms | |
171 | acceptable to B<Tk_GetBitmap(3)>. | |
172 | ||
173 | =item B<-foreground> =E<gt> I<color> | |
174 | ||
175 | Specifies the foreground color of the bitmap item. | |
176 | ||
177 | =back | |
178 | ||
179 | =item I<$compound>-E<gt>B<Image>?(I<option => value ...>)? | |
180 | ||
181 | Creates a new image item of at the end of the last | |
182 | line of the compound image. Additional I<options> accepted by the | |
183 | image type are: | |
184 | ||
185 | =over 4 | |
186 | ||
187 | =item B<-image> =E<gt> I<name> | |
188 | ||
189 | Specifies an image to display in this item. I<name> | |
190 | must have been created with the B<image create> command. | |
191 | ||
192 | =back | |
193 | ||
194 | =item I<$compound>-E<gt>B<Space>?(I<option => value ...>)? | |
195 | ||
196 | Creates a new space item of at the end of the last line of the | |
197 | compound image. Space items do not display anything. They just acts as | |
198 | space holders that add additional spaces between items inside a | |
199 | compound image. Additional I<options> accepted by the image type | |
200 | are: | |
201 | ||
202 | =over 4 | |
203 | ||
204 | =item B<-width> =E<gt> I<value> | |
205 | ||
206 | Specifies the width of this space. The I<value> may have any of the | |
207 | forms acceptable to B<Tk_GetPixels(3)>. | |
208 | ||
209 | =item B<-height> =E<gt> I<value> | |
210 | ||
211 | Specifies the height of this space. The I<value> may have any of | |
212 | the forms acceptable to B<Tk_GetPixels(3)>. | |
213 | ||
214 | =back | |
215 | ||
216 | =item I<$compound>-E<gt>B<Text>?(I<option => value ...>)? | |
217 | ||
218 | Creates a new text item of at the end of the last line of the compound | |
219 | image. Additional I<options> accepted by the text type are: | |
220 | ||
221 | =over 4 | |
222 | ||
223 | =item B<-background> =E<gt> I<color> | |
224 | ||
225 | Specifies the background color of the text item. | |
226 | ||
227 | =item B<-font> =E<gt> I<name> | |
228 | ||
229 | Specifies the font to be used for this text item. | |
230 | ||
231 | =item B<-foreground> =E<gt> I<color> | |
232 | ||
233 | Specifies the foreground color of the text item. | |
234 | ||
235 | =item B<-justify> I<value> | |
236 | ||
237 | When there are multiple lines of text displayed in a text item, this | |
238 | option determines how the lines line up with each other. I<value> | |
239 | must be one of B<left>, B<center>, or B<right>. B<Left> | |
240 | means that the lines' left edges all line up, B<center> means that | |
241 | the lines' centers are aligned, and B<right> means that the lines' | |
242 | right edges line up. | |
243 | ||
244 | =item B<-text> =E<gt> I<string> | |
245 | ||
246 | Specifies a text string to display in this text item. | |
247 | ||
248 | =item B<-underline> I<value> | |
249 | ||
250 | Specifies the integer index of a character to underline in the text | |
251 | item. 0 corresponds to the first character of the text displayed in | |
252 | the text item, 1 to the next character, and so on. | |
253 | ||
254 | =item B<-wraplength> I<value> | |
255 | ||
256 | This option specifies the maximum line length of the label string on | |
257 | this text item. If the line length of the label string exceeds this | |
258 | length, it is wrapped onto the next line, so that no line is longer | |
259 | than the specified length. The value may be specified in any of the | |
260 | standard forms for screen distances. If this value is less than or | |
261 | equal to 0 then no wrapping is done: lines will break only at newline | |
262 | characters in the text. | |
263 | ||
264 | =back | |
265 | ||
266 | =back | |
267 | ||
268 | =head1 EXAMPLE | |
269 | ||
270 | The following example creates a compound image with a bitmap and a | |
271 | text string and places this image into a B<Button(n)> | |
272 | widget. Notice that the image must be created using the widget | |
273 | that it resides in. | |
274 | ||
275 | my $b = $parent->Button; | |
276 | my $c = $b->Compound; | |
277 | $b->configure(-image => $c); | |
278 | $c->Line; | |
279 | $c->Bitmap(-bitmap => 'warning'); | |
280 | $c->Space(-width => 8); | |
281 | $c->Text(-text => "Warning", -underline => 0); | |
282 | $b->pack; | |
283 | ||
284 | =head1 KEYWORDS | |
285 | ||
286 | image(n), Tix(n) |