--- name: "gxmessage" section: "1" platform: "linux" package: "gxmessage" version: "4.1.1-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/gxmessage" --- # gxmessage(1) a GTK-based xmessage clone ## NAME gxmessage - a GTK-based xmessage clone ## SYNOPSIS **gxmessage** \[*OPTIONS*\] **message** ...\ **gxmessage** \[*OPTIONS*\] -file *FILENAME* ## DESCRIPTION **gxmessage** opens a window to display a message obtained from the command line, from a file, or from *stdin*. The window includes a row of buttons, each of which causes the program to exit with a different return code. Pressing *CTRL-F* brings up a search bar to help find words in the displayed message. *CTRL-G* and *CTRL-SHIFT-G* find Next and Previous matches respectively. The GNU Info entry for gxmessage contains detailed information and examples. ## OPTIONS **gxmessage** accepts any option **xmessage** would, although some (such as **-bw** and **-xrm**) are silently ignored. - **-bg** *COLOR* Sets the background color of the message to *COLOR*. Examples: red, "#c90", "#446a7e". - **-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 appears on the button. The *VALUE* (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 *LABEL* can include an underscore (\_) to specify a keyboard accelerator. If *VALUE*s are omitted, they default to 101, 102, 103, etc., in order. If no **-buttons** option is given, *BUTTON\_LIST* defaults to **"okay:0"**. ``` gxmessage -buttons "Foo:42,Bar:63" "Example" echo $? gxmessage -buttons "_Foo,_Bar" "Example" echo $? gxmessage "Example" echo $? gxmessage -buttons "Hello\, world" "Example" ``` - **-default** *LABEL* Opens the **gxmessage** window with input focused on the specified button. *LABEL* is one of the *LABEL*s in *BUTTON\_LIST* (see **-buttons**, above). - **-display** *DISPLAY* Opens the window on the X11 display *DISPLAY* (for example, **:1**). This forces GTK to use its X11 backend, so under Wayland it works only if an X server such as XWayland is available. - **-fg** *COLOR* Sets the message text color to *COLOR*. - **-file** *FILENAME* Causes the named file to be used as the message source. If a dash (-) is used in place of *FILENAME*, the message will be read from *stdin*. - **-fn** \| **-font** *FONT* Specifies the message font, using GTK's font specification system. For example, **-font "serif italic 14"**. (GTK's font system is not compatible with **xmessage**. See the Compatibility section, below, for a workaround.) - **-geometry** *GEOMETRY* Sets the window's size. Example: ``` -geometry 400x200 ``` Either dimension may be given alone (**-geometry 400** or **-geometry x200**); the other is then chosen to fit the message. - **-help** Displays basic usage information then exits. - **-iconic** Opens the **gxmessage** window in its iconized (minimized) state. - **-print** Writes the *LABEL* of the selected button to *stdout*. - **-timeout** *SECONDS* Automatically closes the **gxmessage** window with an exit code of 0 if no button is pressed within *SECONDS* seconds. (The **-entry** and **-entrytext** options cause **-timeout** to be ignored.) - **-title** *TITLE* Sets the **gxmessage** window's title to *TITLE*. ## GXMESSAGE SPECIFIC OPTIONS The following options are specific to **gxmessage** and are not compatible with **xmessage**. - **-borderless** Opens the **gxmessage** window without the usual window frame. - **-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 **gxmessage** window. When the window closes, any text in the entry box will be copied to *stdout*. This option can't be used at the same time as the **-print** option. - **-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. - **-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. ## HISTORIC OPTIONS The following options were supported under GTK2 and GTK3, but no longer have any effect. This is due to changes in modern desktop environments. - **-center**, **-nearmouse**, **-nofocus**, **-ontop**, **-sticky**, **-name** *NAME* ## EXIT STATUS 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. Pressing the ESC key also causes the program to exit with code 1. ## COMPATIBILITY WITH XMESSAGE Fall back to **xmessage** if **gxmessage** isn't available: ``` #!/bin/sh if command -v gxmessage >/dev/null 2>&1; then XMESSAGE=gxmessage else XMESSAGE=xmessage fi "$XMESSAGE" "hello, world" ``` If you specify fonts, check which program you're using: ``` 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 Command line programs commonly treat the character sequence **--** as an end-of-options indicator. Neither xmessage nor gxmessage support this. If there's any chance your message text could be mistaken for a command line option, a work-around is to pad that text with a space character: ``` gxmessage Please do not '-center ' me ``` If you discover other bugs in the most recent version of **gxmessage**, please get in touch. ## SEE ALSO [*xmessage*(1)](/xmessage/1.md), [*zenity*(1)](/zenity/1.md), [*dialog*(1)](/dialog/1.md) The GNU Info entry for gxmessage contains detailed information and examples. ## AUTHORS Timothy Musson \ ## COPYRIGHT NOTICE Copyright © 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2012, 2015, 2026 Timothy Richard Musson Copying and distribution of this file, with or without modification, are permitted provided the copyright notice and this notice are preserved.