Provided by: iwidgets4-doc_4.1.1-2.1_all bug

NAME

       iwidgets::messagebox - Create and manipulate a messagebox text widget

SYNOPSIS

       iwidgets::messagebox pathName ?options?

INHERITANCE

       itk::Widget <- iwidgets::Labeledwidget <- iwidgets::Scrolledwidget <- iwidgets::Messagebox

STANDARD OPTIONS

       activeBackground  activeForeground    background  borderWidth
       cursor            exportSelection     font        foreground
       highlightColor    highlightThickness  padX        padY
       relief            setGrid

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

ASSOCIATED OPTIONS

       labelBitmap     labelFont      labelImage      labelMargin
       labelPos        labelText      labelVariable

       See the "labeledwidget" class manual entry for details on the above associated options.

       activeRelief    elementBorderWidth             jumptroughColor

       See the "scrollbar" widget manual entry for details on the above associated options.

       height          hscrollMode    sbWidth         scrollMargin
       textBackground  visibleItems   vscrollMode     width

       See the "scrolledtext" widget manual entry for details on the above associated options.

       spacing1        spacing2       spacing3

       See the "text" widget manual entry for details on the above associated options.

WIDGET-SPECIFIC OPTIONS

       Name:           fileName
       Class:          FileName
       Command-Line Switch:           -filename

              Specifies the filename to be displayed in the file selection dialog when it pops up
              during a save of the messagebox contents operation.

       Name:           maxLines
       Class:          MaxLines
       Command-Line Switch:           -maxlines

              Specifies the maximum number of lines allowed in the text area of  the  messagebox.
              When  this  limit  is  reached, the oldest line will be deleted such that the total
              number of lines remains maxlines.

       Name:           saveDir
       Class:          SaveDir
       Command-Line Switch:           -savedir

              Specifies the default directory to display when the file selection dialog  pops  up
              during  a  save  of  the  messagebox  contents  operation. If this parameter is not
              specified, then the files in the current working directory are displayed.

_________________________________________________________________________________________________

DESCRIPTION

       The iwidgets::messagebox command creates a  scrolled  information  messages  area  widget.
       Message  types  can  be  user  defined  and configured.  Their options include foreground,
       background, font, bell, and their display mode of on or off.  This allows message types to
       defined  as  needed,  removed  when  no longer so, and modified when necessary.  An export
       method is provided for file I/O.

       The number of lines displayed may be limited with the default being 1000. When this  limit
       is  reached,  the oldest line is removed.  A popup menu which appears when the right mouse
       button has been pressed in the message area has been  predefined.   The  contents  of  the
       popup  menu  by  default  support  clearing  the  area  and saving its contents to a file.
       Additional operations may be defined or existing operations removed by using the component
       command to access the popup menu.

MESSAGE TYPES

       The  display  characteristics  of  messages issued to the messagebox vary with the message
       type.  Types are defined by the user and they may be added, removed, and configured.   The
       options of the message type control the display include the following:

       -background color
              Color  specifies  the  background  color  to use for characters associated with the
              message type.  It may have any of the forms accepted by Tk_GetColor.

       -bell boolean
              Specifies whether or not to ring the bell whenenver  a  message  of  this  type  is
              issued.   Boolean may have any of the forms accepted by Tk_GetBoolean.  The default
              is 0.

       -font fontName
              FontName is the name of a font to use for drawing characters.  It may have  any  of
              the forms accepted by Tk_GetFontStruct.

       -foreground color
              Color  specifies  the  foreground  color  to use for characters associated with the
              message type.  It may have any of the forms accepted by Tk_GetColor.

       -show boolean
              Specifies whether of not to display this message type  when  issued.   Boolean  may
              have any of the forms accepted by Tk_GetBoolean.  The default is 1.

METHODS

       The  iwidgets::messagebox  command creates a new Tcl command whose name is pathName.  This
       command may be used to invoke various operations on the  widget.   It  has  the  following
       general  form:  pathName  option  ?arg  arg  ...?  Option and the args determine the exact
       behavior of the command.  The following commands are possible for messagebox widgets:

WIDGET-SPECIFIC METHODS

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

       pathName clear
              Clear the messagebox of all messages.

       pathName export filename
              Write  text  to  a  file.   If filename exists then contents are replaced with text
              widget contents.

       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  corresponding  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 iwidgets::messagebox command.

       pathName type option msgtype ?arg arg ...?
              This  command  is  used to manipulate message types.  The behavior of  the  command
              depends  on the option argument that follows the type keyword.  The following forms
              of the command are supported:

              pathName type add msgtype ?option value ...?
                     Adds a new message type given by msgtype with the display properties defined
                     by the option value pairs.  See MESSAGE TYPES for information on the options
                     that are supported.

              pathName type cget msgtype option
                     Returns the value of a configuration option for  a  message  type.   Msgtype
                     identifies the message type, and option specifies a particular configuration
                     option, which must be one of the ones listed in the section MESSAGE TYPES.

              pathName type configure msgtype ?option value ...?
                     Query or modify the configuration options for a message type.  If no  option
                     is specified, returns a list describing all of the available options for the
                     message type msgtype.  If option  is  specified  with  no  value,  then  the
                     command  returns  a  list  describing  the one named option.  If one or more
                     option-value pairs are  specified,  then  the  command  modifies  the  given
                     option(s)  to  have the given value(s);  in this case the command returns an
                     empty string.  See MESSAGE TYPES for information on  the  options  that  are
                     supported.   pathName  type  remove msgtype Removes an existing message type
                     given by msgtype.

       pathName issue string ?level? ?tags?
              Print a string to the text area at the given level and  with  any  additional  tags
              specified.

COMPONENTS

       Name:           itemMenu
       Class:          Menu

              This is the popup menu that gets displayed when you right-click in the text area of
              the messagebox.  Its contents may be modified via the component command.

       Name:           text
       Class:          Scrolledtext

              The text component is the  scrolledtext  widget.   See  the  "scrolledtext"  widget
              manual entry for details on the text component item.

EXAMPLE

        package require Iwidgets 4.0
        iwidgets::messagebox .mb -hscrollmode dynamic \
           -labeltext "Messages" -labelpos n \
           -height 120 -width 550 -savedir "/tmp" -textbackground #d9d9d9

        pack .mb -padx 5 -pady 5 -fill both -expand yes

        .mb type add ERROR -background red -foreground white -bell 1
        .mb type add WARNING -background yellow -foreground black
        .mb type add INFO -background white -foreground black

        .mb issue "This is an error message in red with a beep" ERROR
        .mb issue "This warning message in yellow" WARNING
        .mb issue "This is an informational message" INFO

AUTHOR

       Alfredo Jahn V Mark L. Ulferts

KEYWORDS

       messagebox, scrolledtext, text, widget