.\" -*-nroff-*-
.TH xmsg 1 "20 December 2001" "Edgeware tools"
.SH NAME
xmsg \- pops up a message box
.SH SYNOPSIS
.B xmsg
.RI [ gtk-options ...]
.RB [ \-EIQWm ]
.RB [ \-d
.IR headline ]
.RB [ \-t
.IR title ]
.I message
.RI [ button ...]
.SH DESCRIPTION
The
.B xmsg
program pops up a pretty GTK message box, containing the listed buttons
(shown right to left along the bottom).  The button strings are listed,
one per argument, after the message.  If no buttons are requested, an
.B OK
button is provided anyway.
.PP
The user dismisses the message window by activating one of the buttons
or just closing the window using the window manager.  The
.B xsmg
program then writes a string to its standard output describing the
user's action and exits.  The string written is, by default, the label
of the activated button, though this can be overridden: see below.
.SS "Message specifications"
The
.I message
argument is usually just a text string to be displayed.  However, if the
.I message
is
.RB ` \- '
then, instead, the message to display is read from standard input.  If the
first character of
.I message
is
.RB ` ! '
then that character is removed.  (Hence, if you really wanted to show
the message
.RB ` \- ',
you need to pass
.RB ` !\- '.)
Conscientious script authors will prefix strings appropriately.
.PP
Pango markup may be used in message and headline strings if the
.B \-m
option is requested.
.SS "Button specifications"
A
.I button
argument has the form
.RI [ opt \fB: opt \fB: ...] \c
.RB [ ! ] \c
.IR label .
The
.I label
is either a text string, or a GTK stock-id (e.g.,
.BR gtk-ok ).
Mnemonic characters in button labels may be marked by prefixing them
with underscores.  Write two underscores if you really want a literal
underscore to appear.
.PP
Each
.I opt
may be one of the following.
.TP
.B default
This should be the default button, activated when the user presses the
.I enter
or
.I return
key.
.TP
.B cancel
This should be the cancel button, activated when the user presses the
.I escape
key or simply dismisses the window.
.TP
.BI = tag
If the user activates this button, output the
.I tag
rather than the button's label.
.PP
If no button is marked as the default, then the rightmost (first
specified) is chosen automatically; similarly, if there is no specified
cancel button then the last is chosen.  If several buttons are marked as
default or cancel buttons then the behaviour is unspecified.
.PP
Button options are usually processed while colons remain in the button
specification.  Processing stops early if an exclamation mark
.RB ` ! '
is reached.  For example,
.B default:!cancel:button
is parsed has specifying the
.B default
option and a label text of
.BR cancel:button .
.PP
If no
.I button
arguments are given,
.B xmsg
automatically provides an OK button (it actually uses the GTK
.B gtk-ok
stock button) but produces no output.
.SS Options
.TP
.BR \-E ", " \-I ", " \-Q ", " \-W
Mark the message window as, respectively, reporting an error, providing
information, asking a question, or giving a warning.
.TP
.BR "\-d, \-\-headline " headline
Write the
.I headline
above the main message, in larger and bolder text.
.TP
.B "\-m, \-\-markup"
Enable the use of Pango XML-like markup in the message and headline
strings.  See the Pango documentation for a description of the markup
tags available.
.TP
.BI "\-t, \-\-title " title
Sets the title for the window.  If you don't specify a title, the window
is labelled
.RB ` xmsg '.
.SH BUGS
None currently known.
.SH SEE ALSO
.BR gtk-options (7).
.SH AUTHOR
Mark Wooding (mdw@distorted.org.uk).