.SH NAME
xmsg \- pops up a message box
.SH SYNOPSIS
-.ll +5i
.B xmsg
-.RB [ \-\-display
-.IR display ]
-.RB [ \-f ]
+.RI [ gtk-options ...]
+.RB [ \-EIQWm ]
+.RB [ \-d
+.IR headline ]
.RB [ \-t
.IR title ]
-.RB [ \-c | \-d
-.IR button ]
-.if n \{\
-.br
-\h'1i'
-..
-\}
.I message
.RI [ button ...]
-.ll -5i
.SH DESCRIPTION
The
.B xmsg
.B OK
button is provided anyway.
.PP
-A button may be selected as being the default (i.e., may be chosen by
-pressing
-.IR enter ),
-using the
-.B \-d
-option: the argument must either match a button name, or be an index
-(zero-based) of the requested button. If you don't select a default,
-the first (rightmost) button becomes the default anyway.
+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
-Similarly, a button may be selected as being the `cancel' action (i.e.,
-may be chosen by closing the window or pressing
-.IR escape ),
-using
-the
-.B \-c
-option. Again, the argument must either match a button name or be an
-index of a button. If you don't select a cancel button, the last
-(leftmost) button because the cancel button.
+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
-If there is more than one button, the name of the selected button is
-printed on standard output when the program exits.
+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 5
-.BI "\-\-display " display
-Attempt to connect to
-.I display
-rather than the display named in the usual environment variable.
-.TP 5
-.B "\-f, \-\-focus "
-Sets a magical property to ensure that the window acquires the focus
-under a customized
-.BR fvwm (3)
-version I don't use any more.
-.TP 5
+.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 '.
-.TP 5
-.BI "\-c, \-\-cancel " button
-Selects the given
-.I button
-as being the cancel button.
-.TP 5
-.BI "\-d, \-\-default " button
-Selects the given
-.I button
-as being the default button.
-.SH AUTHOR
-Mark Wooding (mdw@nsict.org).
.SH BUGS
None currently known.
+.SH SEE ALSO
+.BR gtk-options (7).
+.SH AUTHOR
+Mark Wooding (mdw@distorted.org.uk).
~mdw / xtoys / blobdiff