GXMESSAGE(1)

✨ gxmessage 💖 the GTK xmessage clone that SERVES ✨

okay bestie, so you know xmessage? the little popup window thing? yeah. gxmessage is that, but GTK, and honestly it's giving main character energy. it's a manual page for the gxmessage command, section 1 of the manual, and i'm about to tell you EVERYTHING about it. no gatekeeping here 🫶

---

🌸 SYNOPSIS 🌸

like, here's how you actually call it:

gxmessage [OPTIONS] message ...
gxmessage [OPTIONS] -file FILENAME

---

🦋 DESCRIPTION 🦋

so gxmessage opens a whole window to display a message. and the message can come from the command line, from a file, or from stdin. she's flexible like that 💅

and inside that window? a row of buttons. every button makes the program exit with a different return code, which is the whole point — you press a button, you get a number back. iconic behaviour tbh.

the GNU Info entry for gxmessage has the detailed info and examples, if you want the extended lore. iykyk 📖

---

✨ OPTIONS ✨

gxmessage accepts any option xmessage would, no cap. although some of them — like -bw and -xrm — are just... silently ignored. they get the vibe check and fail it. 🙈

• -bg COLOR — sets the background color of the message to COLOR. examples: red, "#c90", "#446a7e". cute!
• -buttons BUTTON_LIST — defines the buttons to be created. BUTTON_LIST is a comma-separated list of LABEL:VALUE pairs, one for each button. the LABEL is the text that shows up on the button. the VALUE (0..255) is the code the program will exit with if that button gets pressed. commas and colons can be escaped using backslashes (\). and — plot twist — as well as ordinary text, the LABEL can specify a GTK "stock" button, like "GTK_STOCK_CANCEL", or it can include an underscore (_) to specify a keyboard accelerator. if VALUEs are omitted, they default to 101, 102, 103, etc., in order. and if no -buttons option is given at all, BUTTON_LIST defaults to "okay:0". the examples, bestie:

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"

• -center — opens the gxmessage window smack in the middle of the screen. centered. balanced. zen. 🧘
• -default LABEL — opens the window with the input focused on the specified button. LABEL is one of the LABELs in BUTTON_LIST (peep -buttons above 👆).
• -display DISPLAY — specifies the X display to use.
• -fg COLOR — sets the message text color to COLOR.
• -file FILENAME — makes the named file the message source. if you use a dash (-) in place of FILENAME, the message gets read from stdin. slay.
• -fn | -font FONT — specifies the message font, using GTK's font specification system. for example, -font "serif italic 14". heads up though — GTK's font system is not compatible with xmessage. check the Compatibility section below for the workaround 🫠
• -geometry GEOMETRY — sets the window's size and/or position. examples:

-geometry 400x200
-geometry 400x200+600+100
-geometry +600+100

• -help — displays basic usage information, then dips out.
• -iconic — opens the window in its iconized (minimized) state. she's shy 🫣
• -name NAME — sets the window's name to NAME.
• -nearmouse — opens the window near the mouse pointer. following you around fr fr 🐭
• -print — writes the LABEL of the selected button to stdout.
• -timeout SECONDS — automatically closes the window with an exit code of 0 if no button is pressed within SECONDS seconds. ⏰ (tho the -entry and -entrytext options cause -timeout to be ignored. rude.)
• -title TITLE — sets the window's title to TITLE.

---

💖 GXMESSAGE SPECIFIC OPTIONS 💖

these ones are exclusive to gxmessage — they are not compatible with xmessage. so don't go trying them over there, bestie, it won't work.

• -borderless — opens the window without the usual window frame. no frame, no notes 💅
• -encoding CHARSET — specifies the encoding of the message text. by default, the message text is assumed to match the encoding of the current locale.
• -entry — adds a text entry box to the window. when the window closes, any text in the entry box gets copied to stdout. 🎀 this option can't be used at the same time as the -print option — pick a lane, girl.
• -entrytext TEXT — same as -entry, but sets the default entry box contents to TEXT.
• -noescape — prevents the window closing if the ESC key is pressed. ⚠️ this option only works if a file named /usr/share/gxmessage/allow_noescape exists. like, it literally will not do anything otherwise.
• -nofocus — prevents the window from receiving focus when it opens.
• -ontop — attempts to keep the window in front of other windows. main character energy, cannot be ignored ✨
• -sticky — causes the window to appear on all workspaces.
• -version — displays the program's version number and Copyright details, then exits.
• -wrap — causes lines to wrap rather than exceed the width of the window. because nobody likes horizontal scrolling 😭

---

🌈 GTK DEFAULTS 🌈

the program's default appearance can be adjusted using GTK resource files. the main text display widget is named gxmessage-textview. the text entry widget is named gxmessage-entry.

# 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"

customize away, gorgeous 💜

---

👑 EXIT STATUS 👑

so here's the tea on what code you get back:

• if a button is pressed, the program returns the value assigned to that button. the default "okay" button returns 0.
• if a timeout event occurs, the program returns 0.
• if an error occurs, or if the window is closed without a button-press or timeout event, the program exits with code 1. and — plot twist — pressing the ESC key also causes the program to exit with code 1. 😭

---

🎀 COMPATIBILITY WITH XMESSAGE 🎀

want to fall back to xmessage if gxmessage isn't available? here's the move:

#! /bin/sh
XMESSAGE=$(which gxmessage) || XMESSAGE=xmessage
$XMESSAGE "hello, world"

if you specify fonts, you gotta check which program you're actually using, bestie:

font="monospace 14"
[ "$XMESSAGE" = xmessage ] && font="fixed"
$XMESSAGE ${font:+-fn "$font"} "hello, world"

🚫 don't use double-dashed command line options:

$XMESSAGE "hello, world" -buttons good
$XMESSAGE "hello, world" --buttons bad

🚫 don't use the gxmessage-specific options:

-entry, -entrytext, -borderless, -wrap,
-encoding, -nofocus, -noescape, -ontop,
-sticky, -version, -h, -?

---

💀 BUGS 💀

for some reason, opening the gxmessage window with no button set to be the default causes GTK to emit a "beep" sound. like. why. nobody asked. 🙃

if you discover other bugs in the most recent version of gxmessage, please get in touch! she wants to hear from you 🫶

---

🔥 SEE ALSO 🔥

xmessage(1), zenity(1), dialog(1)

the GNU Info entry for gxmessage contains detailed information and examples. (yes, i said it twice. it's important, okay?)

---

🌸 AUTHORS 🌸

Timothy Musson <trmusson@gmail.com>

---

💜 COPYRIGHT NOTICE 💜

Copyright © 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2012, 2015 Timothy Richard Musson

copying and distribution of this file, with or without modification, are permitted provided the copyright notice and this notice are preserved.

---

and that's the whole page, bestie!! 🎉 this one's from May 25th, 2015, GXMESSAGE(1), and it ATE. go forth and pop up some windows 💖✨🎀