home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _9e8c0e1911e90785e33cdd25f37ffca0 < prev    next >
Encoding:
Text File  |  2004-06-01  |  8.6 KB  |  287 lines
  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)
  287.