doc/message.n

   1 '\"
   2 '\" Copyright (c) 1990-1994 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
   4 '\" Copyright (c) 1996-1999 Christian Werner
   5 '\"
   6 '\" See the file "license.terms" for information on usage and redistribution
   7 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   8 '\"
   9 .so man.macros
  10 .TH message n 8.0 Ck "Ck Built-In Commands"
  11 .BS
  12 '\" Note:  do not modify the .SH NAME line immediately below!
  13 .SH NAME
  14 message \- Create and manipulate message widgets
  15 .SH SYNOPSIS
  16 \fBmessage\fI \fIpathName \fR?\fIoptions\fR?
  17 .SH "STANDARD OPTIONS"
  18 .LP
  19 .nf
  20 .ta 4c 8c 12c
  21 \fBanchor\fR    \fBbackground\fR        \fBtakeFocus\fR \fBtextVariable\fR
  22 \fBattributes\fR        \fBforeground\fR        \fBtext\fR
  23 .fi
  24 .LP
  25 See the ``options'' manual entry for details on the standard options.
  26 .SH "WIDGET-SPECIFIC OPTIONS"
  27 .ta 4c
  28 .LP
  29 .nf
  30 Name:   \fBaspect\fR
  31 Class:  \fBAspect\fR
  32 Command-Line Switch:    \fB\-aspect\fR
  33 .fi
  34 .IP
  35 Specifies a non-negative integer value indicating desired
  36 aspect ratio for the text.  The aspect ratio is specified as
  37 100*width/height.  100 means the text should
  38 be as wide as it is tall, 200 means the text should
  39 be twice as wide as it is tall, 50 means the text should
  40 be twice as tall as it is wide, and so on.
  41 Used to choose line length for text if \fBwidth\fR option
  42 isn't specified. Defaults to 320.
  43 .LP
  44 .nf
  45 Name:   \fBjustify\fR
  46 Class:  \fBJustify\fR
  47 Command-Line Switch:    \fB\-justify\fR
  48 .fi
  49 .IP
  50 Specifies how to justify lines of text.
  51 Must be one of \fBleft\fR, \fBcenter\fR, or \fBright\fR.  Defaults
  52 to \fBleft\fR.
  53 This option works together with the \fBanchor\fR, \fBaspect\fR,
  54 and \fBwidth\fR options to provide a variety
  55 of arrangements of the text within the window.
  56 The \fBaspect\fR and \fBwidth\fR options determine the amount of
  57 screen space needed to display the text.
  58 The \fBanchor\fR option determines where this
  59 rectangular area is displayed within the widget's window, and the
  60 \fBjustify\fR option determines how each line is displayed within that
  61 rectangular region.
  62 For example, suppose \fBanchor\fR is \fBe\fR and \fBjustify\fR is
  63 \fBleft\fR, and that the message window is much larger than needed
  64 for the text.
  65 The the text will displayed so that the left edges of all the lines
  66 line up; the entire text block will be centered in the vertical span
  67 of the window.
  68 .LP
  69 .nf
  70 Name:   \fBwidth\fR
  71 Class:  \fBWidth\fR
  72 Command-Line Switch:    \fB\-width\fR
  73 .fi
  74 .IP
  75 Specifies the length of lines in the window in screen columns.
  76 If this option has a value greater than zero then the \fBaspect\fR
  77 option is ignored and the \fBwidth\fR option determines the line
  78 length.
  79 If this option has a value equal to zero, then the \fBaspect\fR option
  80 determines the line length.
  81 .BE
  82
  83 .SH DESCRIPTION
  84 .PP
  85 The \fBmessage\fR command creates a new window (given by the
  86 \fIpathName\fR argument) and makes it into a message widget.
  87 Additional
  88 options, described above, may be specified on the command line
  89 or in the option database
  90 to configure aspects of the message such as its colors, attributes,
  91 and text.  The \fBmessage\fR command returns its
  92 \fIpathName\fR argument.  At the time this command is invoked,
  93 there must not exist a window named \fIpathName\fR, but
  94 \fIpathName\fR's parent must exist.
  95 .PP
  96 A message is a widget that displays a textual string.  A message
  97 widget has three special features.  First, it breaks up
  98 its string into lines in order to produce a given aspect ratio
  99 for the window.  The line breaks are chosen at word boundaries
 100 wherever possible (if not even a single word would fit on a
 101 line, then the word will be split across lines).  Newline characters
 102 in the string will force line breaks;  they can be used, for example,
 103 to leave blank lines in the display.
 104 .PP
 105 The second feature of a message widget is justification.  The text
 106 may be displayed left-justified (each line starts at the left side of
 107 the window), centered on a line-by-line basis, or right-justified
 108 (each line ends at the right side of the window).
 109 .PP
 110 The third feature of a message widget is that it handles control
 111 characters and non-printing characters specially.  Tab characters
 112 are replaced with enough blank space to line up on the next
 113 8-character boundary.  Newlines cause line breaks.  Other control
 114 characters (ASCII code less than 0x20) and characters not defined
 115 in the font are displayed as a four-character sequence \fB\ex\fIhh\fR where
 116 \fIhh\fR is the two-digit hexadecimal number corresponding to
 117 the character.
 118
 119 .SH "WIDGET COMMAND"
 120 .PP
 121 The \fBmessage\fR command creates a new Tcl command whose
 122 name is \fIpathName\fR.  This
 123 command may be used to invoke various
 124 operations on the widget.  It has the following general form:
 125 .DS C
 126 \fIpathName option \fR?\fIarg arg ...\fR?
 127 .DE
 128 \fIOption\fR and the \fIarg\fRs
 129 determine the exact behavior of the command.  The following
 130 commands are possible for message widgets:
 131 .TP
 132 \fIpathName \fBcget\fR \fIoption\fR
 133 Returns the current value of the configuration option given
 134 by \fIoption\fR.
 135 \fIOption\fR may have any of the values accepted by the \fBmessage\fR
 136 command.
 137 .TP
 138 \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
 139 Query or modify the configuration options of the widget.
 140 If no \fIoption\fR is specified, returns a list describing all of
 141 the available options for \fIpathName\fR. If \fIoption\fR is specified
 142 with no \fIvalue\fR, then the command returns a list describing the
 143 one named option (this list will be identical to the corresponding
 144 sublist of the value returned if no \fIoption\fR is specified).  If
 145 one or more \fIoption\-value\fR pairs are specified, then the command
 146 modifies the given widget option(s) to have the given value(s);  in
 147 this case the command returns an empty string.
 148 \fIOption\fR may have any of the values accepted by the \fBmessage\fR
 149 command.
 150
 151 .SH "DEFAULT BINDINGS"
 152 .PP
 153 When a new message is created, it has no default event bindings:
 154 messages are intended for output purposes only.
 155
 156 .SH BUGS
 157 .PP
 158 Tabs don't work very well with text that is centered or right-justified.
 159 The most common result is that the line is justified wrong.
 160
 161 .SH KEYWORDS
 162 message, widget