.TH "GXMESSAGE" "1" "May 22nd, 2005" "" ""
.\"
.\"
.\"
.de EX        \" begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE        \" end example
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.\"
.\"
.\"
.SH "NAME"
gxmessage - a GTK-based xmessage clone
.\"
.\"
.\"
.SH "SYNOPSIS"
\fBgxmessage\fR [\fIOPTIONS\fR] \fBmessage\fR ...
.br
\fBgxmessage\fR [\fIOPTIONS\fR] -file \fIFILENAME\fR
.\"
.\"
.\"
.SH "DESCRIPTION"
.PP 
\fBgxmessage\fR opens a window to display a message obtained from the command
line, from a file, or from \fIstdin\fR. The window includes a row of buttons,
each of which causes the program to exit with a different return code.
.\"
.\"
.\"
.SH "OPTIONS"
.PP
\fBgxmessage\fR should accept any option \fBxmessage\fR would, although some
(such as \fB-bw\fR and \fB-xrm\fR) are silently ignored. Options supported
by \fBgxmessage\fR are as follows:
.TP
\fB-bg\fR \fICOLOUR\fR
.br
Sets the background colour of the message to \fICOLOUR\fR. Examples: red,
"#c90", "#446a7e".
.TP
\fB-borderless\fR
.br
Opens the \fBgxmessage\fR window without the usual window frame. This option
is not compatible with \fBxmessage\fR.
.TP
\fB-buttons\fR \fIBUTTON_LIST\fR
.br
Defines the buttons to be created. \fIBUTTON_LIST\fR is a comma-separated list
of \fILABEL\fR\fB:\fR\fIVALUE\fR pairs, one for each button. The \fILABEL\fR is
the text that appears on the button. The \fIVALUE\fR is the code the program
will exit with if that button is pressed. Commas and colons can be escaped
using backslashes (\\). As well as ordinary text, the \fILABEL\fR can specify
a GTK "stock" button, like "GTK_STOCK_CANCEL", or it can include an underscore
(_) to specify a keyboard accelerator. If \fIVALUE\fRs are omitted, they
default to 101, 102, 103, etc., in order. If no \fB-buttons\fR option is given,
\fIBUTTON_LIST\fR defaults to \fB"okay:0"\fR.
.EX
gxmessage -buttons "Foo:42,Bar:63" "Example"
echo $?

gxmessage -buttons "_Foo,_Bar" "Example"
echo $?

gxmessage "Example"
echo $?

gxmessage -buttons "GTK_STOCK_OK:0" "Example"
echo $?

gxmessage -buttons "Hello\\, world" "Example"
.EE
.TP
\fB-center\fR
.br
Opens the \fBgxmessage\fR window in the middle of the screen.
.TP
\fB-default\fR \fILABEL\fR
.br
Opens the \fBgxmessage\fR window with input focused on the specified button.
\fILABEL\fR is one of the \fILABEL\fRs in \fIBUTTON_LIST\fR (see
\fB-buttons\fR, above).
.TP
\fB-display\fR \fIDISPLAY\fR
.br
Specifies the X display to use.
.TP
\fB-encoding\fR \fICHARSET\fR
.br
Specifies the encoding of the message text. By default, the message text is
assumed to match the encoding of the current locale. This option is not
compatible with \fBxmessage\fR.
.TP
\fB-entry\fR
.br
Adds a text entry box to the \fBgxmessage\fR window. When the window closes,
any text in the entry box will be copied to \fIstdout\fR. This option is not
compatible with \fBxmessage\fR and can't be used at the same time as the
\fB-print\fR option.
.TP
\fB-entrytext\fR \fITEXT\fR
.br
Same as \fB-entry\fR, but sets the default entry box contents to \fITEXT\fR.
This option is not compatible with \fBxmessage\fR.
.TP
\fB-fg\fR \fICOLOUR\fR
.br
Sets the message text colour to \fICOLOUR\fR.
.TP
\fB-file\fR \fIFILENAME\fR
.br
Causes the named file to be used as the message source. If a dash (-) is used
in place of \fIFILENAME\fR, the message will be read from \fIstdin\fR.
.TP
\fB-fn\fR | \fB-font\fR \fIFONT\fR
.br
Specifies the message font, using GTK2's font specification system. For
example, \fB-font "serif italic 14"\fR. (GTK2's font system is not compatible
with \fBxmessage\fR. See the Compatibility section, below, for a workaround.)
.TP
\fB-geometry\fR \fIGEOMETRY\fR
.br
Sets the window's size (position is ignored by \fBgxmessage\fR). Example:
\fB-geometry 400x200\fR
.TP
\fB-help\fR
.br
Displays basic usage information then exits.
.TP
\fB-iconic\fR
.br
Opens the \fBgxmessage\fR window in its iconized (minimized) state.
.TP
\fB-name\fR \fINAME\fR
.br
Sets the \fBgxmessage\fR window's name to \fINAME\fR.
.TP
\fB-nearmouse\fR
.br
Opens the \fBgxmessage\fR window near the mouse pointer.
.TP
\fB-nofocus\fR
.br
Prevents the \fBgxmessage\fR window from receiving focus when it opens.
This option is not compatible with \fBxmessage\fR.
.TP
\fB-print\fR
.br
Writes the \fILABEL\fR of the selected button to \fIstdout\fR.
.TP
\fB-timeout\fR \fISECONDS\fR
.br
Automatically closes the \fBgxmessage\fR window with an exit code of 0 if no
button is pressed within \fISECONDS\fR seconds. (The \fB-entry\fR and
\fB-entrytext\fR options cause \fB-timeout\fR to be ignored.)
.TP
\fB-title\fR \fITITLE\fR
.br
Sets the \fBgxmessage\fR window's title to \fITITLE\fR.
.TP
\fB-version\fR
.br
Displays the program's version number then exits. This option is not
compatible with \fBxmessage\fR.
.TP
\fB-wrap\fR
.br
Causes lines to wrap rather than exceed the width of the window. This option
is not compatible with \fBxmessage\fR.
.\"
.\"
.\"
.SH "GTK DEFAULTS"
.PP
The program's default appearance can be adjusted using GTK resource files.
The main text display widget is named \fBgxmessage-textview\fR.
The text entry widget is named \fBgxmessage-entry\fR.
.EX
# Example: ~/.gtkrc-2.0

style "gxmsg" {
    text[NORMAL]   = "#cc9900"
    base[NORMAL]   = "#660000"
    text[SELECTED] = "#660000"
    base[SELECTED] = "#cc9900"
    font_name      = "monospace"
}
widget "*.gxmessage-textview" style  "gxmsg"
widget "*.gxmessage-entry"    style  "gxmsg"
.EE
.\"
.\"
.\"
.SH "EXIT STATUS"
.PP
The program returns code 1 if an error occurs, or if the window is closed
without a button-press or timeout event.
.\"
.\"
.\"
.SH "COMPATIBILITY WITH XMESSAGE"
.PP
Fall back to \fBxmessage\fR if \fBgxmessage\fR isn't available:
.EX
#!/bin/bash
XMESSAGE=$(which gxmessage) || XMESSAGE=xmessage
$XMESSAGE "hello, world"
.EE
.PP
If you specify fonts, check which program you're using:
.EX
font="monospace 14"
[ "$XMESSAGE" = xmessage ] && font=""
$XMESSAGE ${font:+-fn "$font"} "hello, world"
.EE
.PP
Don't use double-dashed command line options:
.EX
$XMESSAGE "hello, world" -buttons good
$XMESSAGE "hello, world" \-\-buttons bad
.EE
.PP
Don't use the \fBgxmessage\fR-specific options:
.EX
\fB-entry\fR, \fB-entrytext\fR, \fB-borderless\fR, \fB-wrap\fR,
\fB-encoding\fR, \fB-nofocus\fR, \fB-version\fR, \fB-h\fR, \fB-?\fR
.EE
.\"
.\"
.\"
.SH "BUGS"
.PP
The position component of \fB-geometry\fR values is ignored by \fBgxmessage\fR.
.PP
If you discover other bugs in the most recent version of \fBgxmessage\fR,
please get in touch.
.\"
.\"
.\"
.SH "SEE ALSO"
.PP
\fIxmessage\fR(1), \fIzenity\fR(1), \fIdialog\fR(1)
.\"
.\"
.\"
.SH "AUTHORS"
.PP 
Timothy Musson <trmusson@ihug.co.nz>