.TH "GXMESSAGE" "1" "May 25th, 2015" "" ""
.\"
.\"
.\"
.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.
.PP
The GNU Info entry for gxmessage contains detailed information and examples.
.\"
.\"
.\"
.SH "OPTIONS"
.PP
\fBgxmessage\fR accepts any option \fBxmessage\fR would, although some
(such as \fB-bw\fR and \fB-xrm\fR) are silently ignored.
.TP
\fB-bg\fR \fICOLOR\fR
.br
Sets the background color of the message to \fICOLOR\fR. Examples: red,
"#c90", "#446a7e".
.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 (0..255) 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-fg\fR \fICOLOR\fR
.br
Sets the message text color to \fICOLOR\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 GTK's font specification system. For
example, \fB-font "serif italic 14"\fR. (GTK'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 and/or position. Examples:
.EX
-geometry 400x200
-geometry 400x200+600+100
-geometry +600+100
.EE
.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-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.
.\"
.\"
.\"
.SH "GXMESSAGE SPECIFIC OPTIONS"
.PP
The following options are specific to \fBgxmessage\fR and are not compatible
with \fBxmessage\fR.
.TP
\fB-borderless\fR
.br
Opens the \fBgxmessage\fR window without the usual window frame.
.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.
.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
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.
.TP
\fB-noescape\fR
.br
Prevents the window closing if the ESC key is pressed. This option only works
if a file named /usr/share/gxmessage/allow_noescape exists.
.TP
\fB-nofocus\fR
.br
Prevents the \fBgxmessage\fR window from receiving focus when it opens.
.TP
\fB-ontop\fR
.br
Attempts to keep the \fBgxmessage\fR window in front of other windows.
.TP
\fB-sticky\fR
.br
Causes the \fBgxmessage\fR window to appear on all workspaces.
.TP
\fB-version\fR
.br
Displays the program's version number and Copyright details, then exits.
.TP
\fB-wrap\fR
.br
Causes lines to wrap rather than exceed the width of the window.
.\"
.\"
.\"
.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
If a button is pressed, the program returns the value assigned to that button.
The default "okay" button returns 0.
.PP
If a timeout event occurs, the program returns 0.
.PP
If an error occurs, or if the window is closed without a button-press or
timeout event, the program exits with code 1. Pressing the ESC key also causes
the program to exit with code 1.
.\"
.\"
.\"
.SH "COMPATIBILITY WITH XMESSAGE"
.PP
Fall back to \fBxmessage\fR if \fBgxmessage\fR isn't available:
.EX
#! /bin/sh
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="fixed"
$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-noescape\fR, \fB-ontop\fR,
\fB-sticky\fR, \fB-version\fR, \fB-h\fR, \fB-?\fR
.EE
.\"
.\"
.\"
.SH "BUGS"
.PP
For some reason, opening the gxmessage window with no button set to be the
default causes GTK to emit a "beep" sound.
.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)
.PP
The GNU Info entry for gxmessage contains detailed information and examples.
.\"
.\"
.\"
.SH "AUTHORS"
.PP
Timothy Musson <trmusson@gmail.com>
.\"
.\"
.\"
.SH "COPYRIGHT NOTICE"
Copyright \(co 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2012, 2015 Timothy Richard Musson
.PP
Copying and distribution of this file, with or without modification, are
permitted provided the copyright notice and this notice are preserved.