| 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) |