Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1990-1994 The Regents of the University of California. |
2 | # Copyright (c) 1994-1996 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # | |
6 | # | |
7 | ||
8 | =head1 NAME | |
9 | ||
10 | Tk::Message - Create and manipulate Message widgets | |
11 | ||
12 | =for category Tk Widget Classes | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | I<$message> = I<$parent>-E<gt>B<Message>(?I<options>?); | |
17 | ||
18 | =head1 STANDARD OPTIONS | |
19 | ||
20 | B<-anchor> B<-font> B<-highlightthickness> B<-takefocus> | |
21 | B<-background> B<-foreground> B<-padx> B<-text> | |
22 | B<-borderwidth> B<-highlightbackground> B<-pady> B<-textvariable> | |
23 | B<-cursor> B<-highlightcolor> B<-relief> B<-width> | |
24 | ||
25 | See L<Tk::options> for details of the standard options. | |
26 | ||
27 | =head1 WIDGET-SPECIFIC OPTIONS | |
28 | ||
29 | =over 4 | |
30 | ||
31 | =item Name: B<aspect> | |
32 | ||
33 | =item Class: B<Aspect> | |
34 | ||
35 | =item Switch: B<-aspect> | |
36 | ||
37 | Specifies a non-negative integer value indicating desired | |
38 | aspect ratio for the text. The aspect ratio is specified as | |
39 | 100*width/height. 100 means the text should | |
40 | be as wide as it is tall, 200 means the text should | |
41 | be twice as wide as it is tall, 50 means the text should | |
42 | be twice as tall as it is wide, and so on. | |
43 | Used to choose line length for text if B<width> option | |
44 | isn't specified. | |
45 | Defaults to 150. | |
46 | ||
47 | =item Name: B<justify> | |
48 | ||
49 | =item Class: B<Justify> | |
50 | ||
51 | =item Switch: B<-justify> | |
52 | ||
53 | Specifies how to justify lines of text. | |
54 | Must be one of B<left>, B<center>, or B<right>. Defaults | |
55 | to B<left>. | |
56 | This option works together with the B<anchor>, B<aspect>, | |
57 | B<padX>, B<padY>, and B<width> options to provide a variety | |
58 | of arrangements of the text within the window. | |
59 | The B<aspect> and B<width> options determine the amount of | |
60 | screen space needed to display the text. | |
61 | The B<anchor>, B<padX>, and B<padY> options determine where this | |
62 | rectangular area is displayed within the widget's window, and the | |
63 | B<justify> option determines how each line is displayed within that | |
64 | rectangular region. | |
65 | For example, suppose B<anchor> is B<e> and B<justify> is | |
66 | B<left>, and that the message window is much larger than needed | |
67 | for the text. | |
68 | The the text will displayed so that the left edges of all the lines | |
69 | line up and the right edge of the longest line is B<padX> from | |
70 | the right side of the window; the entire text block will be centered | |
71 | in the vertical span of the window. | |
72 | ||
73 | =item Name: B<width> | |
74 | ||
75 | =item Class: B<Width> | |
76 | ||
77 | =item Switch: B<-width> | |
78 | ||
79 | Specifies the length of lines in the window. | |
80 | The value may have any of the forms acceptable to B<Tk_GetPixels>. | |
81 | If this option has a value greater than zero then the B<aspect> | |
82 | option is ignored and the B<width> option determines the line | |
83 | length. | |
84 | If this option has a value less than or equal to zero, then | |
85 | the B<aspect> option determines the line length. | |
86 | ||
87 | =back | |
88 | ||
89 | =head1 DESCRIPTION | |
90 | ||
91 | The B<Message> method creates a new window (given by the | |
92 | $widget argument) and makes it into a message widget. | |
93 | Additional | |
94 | options, described above, may be specified on the command line | |
95 | or in the option database | |
96 | to configure aspects of the message such as its colors, font, | |
97 | text, and initial relief. The B<message> command returns its | |
98 | $widget argument. At the time this command is invoked, | |
99 | there must not exist a window named $widget, but | |
100 | $widget's parent must exist. | |
101 | ||
102 | A message is a widget that displays a textual string. A message | |
103 | widget has three special features. First, it breaks up | |
104 | its string into lines in order to produce a given aspect ratio | |
105 | for the window. The line breaks are chosen at word boundaries | |
106 | wherever possible (if not even a single word would fit on a | |
107 | line, then the word will be split across lines). Newline characters | |
108 | in the string will force line breaks; they can be used, for example, | |
109 | to leave blank lines in the display. | |
110 | ||
111 | The second feature of a message widget is justification. The text | |
112 | may be displayed left-justified (each line starts at the left side of | |
113 | the window), centered on a line-by-line basis, or right-justified | |
114 | (each line ends at the right side of the window). | |
115 | ||
116 | The third feature of a message widget is that it handles control | |
117 | characters and non-printing characters specially. Tab characters | |
118 | are replaced with enough blank space to line up on the next | |
119 | 8-character boundary. Newlines cause line breaks. Other control | |
120 | characters (ASCII code less than 0x20) and characters not defined | |
121 | in the font are displayed as a four-character sequence B<\x>I<hh> where | |
122 | I<hh> is the two-digit hexadecimal number corresponding to | |
123 | the character. In the unusual case where the font doesn't contain | |
124 | all of the characters in ``0123456789abcdef\x'' then control | |
125 | characters and undefined characters are not displayed at all. | |
126 | ||
127 | =head1 WIDGET METHODS | |
128 | ||
129 | The B<Message> method creates a widget object. | |
130 | This object supports the B<configure> and B<cget> methods | |
131 | described in L<Tk::options> which can be used to enquire and | |
132 | modify the options described above. | |
133 | The widget also inherits all the methods provided by the generic | |
134 | L<Tk::Widget|Tk::Widget> class. | |
135 | ||
136 | =head1 DEFAULT BINDINGS | |
137 | ||
138 | When a new message is created, it has no default event bindings: | |
139 | messages are intended for output purposes only. | |
140 | ||
141 | =head1 BUGS | |
142 | ||
143 | Tabs don't work very well with text that is centered or right-justified. | |
144 | The most common result is that the line is justified wrong. | |
145 | ||
146 | =head1 KEYWORDS | |
147 | ||
148 | message, widget | |
149 | ||
150 | =cut | |
151 |