imported itcl 3.2.1ITCL3_2_1

1 files changed, 277 insertions, 0 deletions

diff --git a/itcl/iwidgets/doc/messagebox.n b/itcl/iwidgets/doc/messagebox.n
new file mode 100644
index 00000000000..829910890de
--- /dev/null
+++ b/itcl/iwidgets/doc/messagebox.n
@@ -0,0 +1,277 @@
+'\"
+'\" Copyright (c) 1995 DSC Technologies Corporation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\"
+'\" @(#) messagebox.n 1.21 94/12/17 16:04:44
+'\" 
+.so man.macros
+.HS iwidgets::messagebox iwid
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+iwidgets::messagebox \- Create and manipulate a messagebox text widget
+.SH SYNOPSIS
+\fBiwidgets::messagebox\fI \fIpathName \fR?\fIoptions\fR?
+.SH "INHERITANCE"
+itk::Widget <- iwidgets::Labeledwidget <- iwidgets::Scrolledwidget <- iwidgets::Messagebox
+.SH "STANDARD OPTIONS"
+.LP
+.nf
+.ta 4c 8c 12c
+\fB
+activeBackground  activeForeground    background  borderWidth
+cursor            exportSelection     font        foreground
+highlightColor    highlightThickness  padX        padY
+relief            setGrid\fR
+.fi
+.LP
+See the "options" manual entry for details on the standard options.
+.SH "ASSOCIATED OPTIONS"
+.LP
+.nf
+.ta 4c 8c 12c
+\fBlabelBitmap\fR	\fBlabelFont\fR	\fBlabelImage\fR	\fBlabelMargin\fR
+\fBlabelPos\fR	\fBlabelText\fR	\fBlabelVariable\fR
+.fi
+.LP
+See the "labeledwidget" class manual entry for details on the above
+associated options.
+.LP
+.nf
+.ta 4c 8c 12c
+\fBactiveRelief\fR	\fBelementBorderWidth\fR	\fBjump\fR	\fBtroughColor\fR
+.fi
+.LP
+See the "scrollbar" widget manual entry for details on the above
+associated options.
+.LP
+.nf
+.ta 4c 8c 12c
+\fBheight\fR	\fBhscrollMode\fR	\fBsbWidth\fR	\fBscrollMargin\fR
+\fBtextBackground\fR	\fBvisibleItems\fR	\fBvscrollMode\fR	\fBwidth\fR
+.fi
+.LP
+See the "scrolledtext" widget manual entry for details on the above
+associated options.
+.LP
+.nf
+.ta 4c 8c 12c
+\fBspacing1\fR	\fBspacing2\fR	\fBspacing3\fR
+.fi
+.LP
+See the "text" widget manual entry for details on the above
+associated options.
+
+.SH "WIDGET-SPECIFIC OPTIONS"
+.LP
+.nf
+Name:	\fBfileName\fR
+Class:	\fBFileName\fR
+Command-Line Switch:	\fB-filename\fR
+.fi
+.IP
+Specifies the filename to be displayed in the file selection dialog when 
+it pops up during a save of the messagebox contents operation.
+.LP
+.nf
+Name:	\fBmaxLines\fR
+Class:	\fBMaxLines\fR
+Command-Line Switch:	\fB-maxlines\fR
+.fi
+.IP
+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 \fImaxlines\fR.
+.LP
+.nf
+Name:	\fBsaveDir\fR
+Class:	\fBSaveDir\fR
+Command-Line Switch:	\fB-savedir\fR
+.fi
+.IP
+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.
+.LP
+.BE
+
+.SH DESCRIPTION
+.PP
+The \fBiwidgets::messagebox\fR 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.
+
+.PP
+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.
+
+.SH "MESSAGE TYPES"
+.PP
+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:
+.TP
+\fB\-background \fIcolor\fR
+\fIColor\fR specifies the background color to use for characters
+associated with the message type.
+It may have any of the forms accepted by \fBTk_GetColor\fR.
+.TP
+\fB\-bell \fIboolean\fR
+Specifies whether or not to ring the bell whenenver a message of this
+type is issued.  \fIBoolean\fR may have any of the forms accepted by 
+\fBTk_GetBoolean\fR.  The default is 0.
+.TP
+\fB-font\ \fIfontName\fR
+\fIFontName\fR is the name of a font to use for drawing
+characters.  It may have any of the forms accepted
+by Tk_GetFontStruct.
+.TP
+\fB\-foreground \fIcolor\fR
+\fIColor\fR specifies the foreground color to use for characters
+associated with the message type.
+It may have any of the forms accepted by \fBTk_GetColor\fR.
+.TP
+\fB\-show \fIboolean\fR
+Specifies whether of not to display this message type when issued.
+\fIBoolean\fR may have any of the forms accepted by 
+\fBTk_GetBoolean\fR.  The default is 1.
+
+.SH "METHODS"
+.PP
+The \fBiwidgets::messagebox\fR command creates a new Tcl command whose
+name is \fIpathName\fR.  This
+command may be used to invoke various
+operations on the widget.  It has the following general form:
+.DS C
+\fIpathName option \fR?\fIarg arg ...\fR?
+.DE
+\fIOption\fR and the \fIarg\fRs
+determine the exact behavior of the command.  The following
+commands are possible for messagebox widgets:
+
+.SH "WIDGET-SPECIFIC METHODS"
+.TP
+\fIpathName \fBcget\fR \fIoption\fR
+Returns the current value of the configuration option given
+by \fIoption\fR.
+\fIOption\fR may have any of the values accepted by the \fBiwidgets::messagebox\fR
+command.
+.TP
+\fIpathName \fBclear\fR
+Clear the messagebox of all messages.
+.TP
+\fIpathName \fBexport\fR \fIfilename\fR
+Write text to a file.  If \fIfilename\fR exists then
+contents are replaced with text widget contents.
+.TP
+\fIpathName\fR \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
+Query or modify the configuration options of the widget.
+If no \fIoption\fR is specified, returns a list describing all of
+the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
+information on the format of this list).  If \fIoption\fR is specified
+with no \fIvalue\fR, 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 \fIoption\fR is specified).  If
+one or more \fIoption\-value\fR 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.
+\fIOption\fR may have any of the values accepted by the \fBiwidgets::messagebox\fR
+command.
+.TP
+\fIpathName \fBtype\fR \fIoption\fR \fImsgtype\fR ?\fIarg arg ...\fR?
+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:
+.RS
+.TP
+.TP
+\fIpathName \fBtype add\fR \fImsgtype\fR ?\fIoption value ...\fR?
+Adds a new message type given by \fImsgtype\fR with the display
+properties defined by the option value pairs.  
+See MESSAGE TYPES for information on the options that
+are supported.
+.TP
+\fIpathName \fBtype cget\fR \fImsgtype option\fR
+Returns the value of a configuration option for a message type.
+\fIMsgtype\fR identifies the message type, and \fIoption\fR
+specifies a particular configuration option, which must be one of
+the ones listed in the section MESSAGE TYPES.
+.TP
+\fIpathName \fBtype configure \fImsgtype\fR ?\fIoption value ...\fR?
+Query or modify the configuration options for a message type.
+If no \fIoption\fR is specified, returns a list describing all of
+the available options for the message type \fImsgtype\fR.
+If \fIoption\fR is specified with no \fIvalue\fR, then the command
+returns a list describing the one named option.
+If one or more \fIoption\-value\fR 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.
+\fIpathName \fBtype remove\fR \fImsgtype\fR 
+Removes an existing message type given by \fImsgtype\fR.
+.RE
+.TP
+\fIpathName \fBissue\fR \fIstring\fR \fI?level?\fR \fI?tags?\fR
+Print a \fIstring\fR to the text area at the given level and with
+any additional tags specified.
+
+.SH "COMPONENTS"
+.LP
+.nf
+Name:	\fBitemMenu\fR
+Class:	\fBMenu\fR
+.fi
+.IP
+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.
+.LP
+.nf
+Name:	\fBtext\fR
+Class:	\fBScrolledtext\fR
+.fi
+.IP
+The text component is the scrolledtext widget.  See the "scrolledtext" widget 
+manual entry for details on the text component item.
+.fi
+
+.SH EXAMPLE
+.DS
+ 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
+.DE
+.SH AUTHOR
+Alfredo Jahn V
+.DE
+Mark L. Ulferts
+.LP
+.SH KEYWORDS
+messagebox, scrolledtext, text, widget
+