tk4.2 User Commands - message






NAME

     message - Create and manipulate message widgets


SYNOPSIS

     message pathName ?options?


STANDARD OPTIONS

     -anchor         -font          -highlightthickness-takefocus
     -background     -foreground    -padx           -text
     -borderwidth    -highlightbackground           -pady-textvariable
     -cursor         -highlightcolor                -relief-width

     See the options manual entry for  details  on  the  standard
     options.


WIDGET-SPECIFIC OPTIONS

     Command-Line Name:-aspect
     Database Name:  aspect
     Database Class: Aspect

          Specifies  a  non-negative  integer  value   indicating
          desired aspect ratio for the text.  The aspect ratio is
          specified as  100*width/height.   100  means  the  text
          should  be  as  wide  as it is tall, 200 means the text
          should be twice as wide as it is  tall,  50  means  the
          text  should be twice as tall as it is wide, and so on.
          Used to choose line length for  text  if  width  option
          isn't specified.  Defaults to 150.

     Command-Line Name:-justify
     Database Name:  justify
     Database Class: Justify

          Specifies how to justify lines of text.  Must be one of
          left, center, or right.  Defaults to left.  This option
          works together with the anchor, aspect, padX, padY, and
          width  options  to provide a variety of arrangements of
          the text within  the  window.   The  aspect  and  width
          options  determine the amount of screen space needed to
          display the text.  The anchor, padX, and  padY  options
          determine  where  this  rectangular  area  is displayed
          within the widget's  window,  and  the  justify  option
          determines  how each line is displayed within that rec-
          tangular region.  For example, suppose anchor is e  and
          justify  is  left,  and that the message window is much
          larger than needed for the text.   The  the  text  will
          displayed  so that the left edges of all the lines line
          up and the right edge of the longest line is padX  from
          the  right  side  of the window;  the entire text block
          will be centered in the vertical span of the window.

     Command-Line Name:-width
     Database Name:  width
     Database Class: Width

          Specifies the length of lines in the window.  The value
          may  have  any of the forms acceptable to Tk_GetPixels.
          If this option has a value greater than zero  then  the
          aspect  option  is  ignored and the width option deter-
          mines the line length.  If this option has a value less
          than  or  equal  to zero, then the aspect option deter-
          mines the line length.





DESCRIPTION

     The message command creates a new window (given by the path-
     Name  argument)  and  makes it into a message widget.  Addi-
     tional options, described above, may  be  specified  on  the
     command  line or in the option database to configure aspects
     of the message such as its colors, font, text,  and  initial
     relief.   The message command returns its pathName argument.
     At the time this command is invoked, there must not exist  a
     window named pathName, but pathName's parent must exist.

     A message is a widget that displays  a  textual  string.   A
     message widget has three special features.  First, it breaks
     up its string into lines in order to produce a given  aspect
     ratio  for  the  window.  The line breaks are chosen at word
     boundaries wherever possible (if  not  even  a  single  word
     would  fit  on  a  line,  then the word will be split across
     lines).  Newline characters in the string  will  force  line
     breaks;  they can be used, for example, to leave blank lines
     in the display.

     The second feature of a  message  widget  is  justification.
     The  text  may be displayed left-justified (each line starts
     at the left side of the window), centered on a  line-by-line
     basis,  or right-justified (each line ends at the right side
     of the window).

     The third feature of a message widget  is  that  it  handles
     control  characters  and  non-printing characters specially.
     Tab characters are replaced with enough blank space to  line
     up  on  the  next 8-character boundary.  Newlines cause line
     breaks.  Other control  characters  (ASCII  code  less  than
     0x20)  and  characters not defined in the font are displayed
     as a four-character sequence \xhh where hh is the  two-digit
     hexadecimal  number  corresponding to the character.  In the
     unusual case where the font doesn't contain all of the char-
     acters in ``0123456789abcdef\x'' then control characters and
     undefined characters are not displayed at all.


WIDGET COMMAND

     The message command creates a new Tcl command whose name  is
     pathName.  This command may be used to invoke various opera-
     tions on the widget.  It has the following general form:
          pathName option ?arg arg ...?
     Option and the args determine the exact behavior of the com-
     mand.  The following commands are possible for message widg-
     ets:

     pathName cget option
          Returns the current value of the  configuration  option
          given  by  option.   Option  may have any of the values
          accepted by the message command.

     pathName configure ?option? ?value option value ...?
          Query  or  modify  the  configuration  options  of  the
          widget.   If  no  option  is  specified, returns a list
          describing all of the available  options  for  pathName
          (see  Tk_ConfigureInfo for information on the format of
          this list).  If option is specified with no value, then
          the  command  returns  a  list describing the one named
          option (this list will be identical to the  correspond-
          ing  sublist  of  the  value  returned  if no option is
          specified).  If one or more  option - value  pairs  are
          specified,  then  the command modifies the given widget
          option(s) to have the given value(s);  in this case the
          command  returns  an empty string.  Option may have any
          of the values accepted by the message command.



DEFAULT BINDINGS

     When a new message is created, it has no default event bind-
     ings:  messages are intended for output purposes only.



BUGS

     Tabs don't work very well with  text  that  is  centered  or
     right-justified.  The most common result is that the line is
     justified wrong.



KEYWORDS

     message, widget