xmessage(1)

NAME
xmsg - X window system message display program.

SYNOPSIS
xmsg [-options ...] -m <message>

NOTE
The xmsg command is identical in behaviour to the X11R4 version of xmessage but it also builds/installs/runs with X11R5, so it allows you to have the R4 behaviour on R5 machines. The behaviour of the standard R5 version of xmessage is significantly different from, and incompatible with, the R4 version. For the rest of this man page, where you see "xmessage", substitute "xmsg".

DESCRIPTION
Xmsg opens a window on the screen that will contain the text of a message from either the command line or stdin. This text may have a scroll bar along the left side to allow the user to browse through relatively long messages. Along the lower edge of the message is list of words with boxes around them. Clicking the left mouse button on any of these "buttons" (words with boxes around them) will cause the message to go away. If there is more than one "button" then some state will be returned to the invoker of the xmessage process via a change of the exit status of the program.

This program serves two functions. Firstly, it can be a method for shell scripts to present the user with information much as 'echo' allows in a tty environment, as well as allowing the user to answer simple questions. Secondly it allows much of the functionality of 'cat' again in a windowing versus tty environment.

It should be noted that this program is intended for short messages, and will be quite slow when asked to handle long files from stdin. Although xmessage can accept input from stdin, this input is not allowed to come from a tty. If this is attempted, an error message will be printed. If xmessage is executed with an incorrect argument then it will print a usage message to standard output, as well as to an xmessage window.

COMMAND LINE OPTIONS

These are the command line options that xmessage understands. Please note that some of these are inherited from the XToolkit and as the list of default toolkit options changes xmessage will follow.

-printlabel
    This will cause the program to print the label of the button pressed to standard output (stdout). I envision this to be useful when popping up a message to a friend, as in: "ready to go to lunch". This allows you to know if he clicked the "yes" or the "no" button.

-noscroll (-nsb)
    The scroll bar is active on the text window by default; this causes it to be removed.

-buttons <button> <button> ...
    This option will cause xmessage to create one button for each argument that follows it until something starts with a '-'. The string passed to the button is the name of the Command button widget created and will be the default text displayed to the user. Since this is the name of the widget it may be used to change any of the Xresources associated with that button.

-message <word> <word> ...
    This must be the last argument in the command list, as every argument after this one is assumed to be part of the message. There is no limit to the length of this message.

-geometry (height)x(width)+(x_offset)+(y_offset)
    Sets the size and location of the window created by xmessage.

-bw <pixels>

-borderwidth <pixels>
    Specifies the width of the border for all windows in xmessage.

-bd <color>

-bordercolor <color>
    Specifies the color of the borders of all windows in xmessage.

-fg <color>

-foreground <color>
    Specifies the foreground color to be used.

-bg <color>

-background <color>
    Specifies the background color to be used.

-fn <font>

-font <font>
    Specifies the font to use for all buttons and text.

-display <host:display[.screen]>
    Specifies a display to use other than the default specified by the DISPLAY environment variable.

-name <name>
    Specifies the name to use when retrieving resources.

-title <title>
    Specifies the title of this application.

-xrm <resource>
    Allows a resource to be specified on the command line.

WIDGET AND RESOURCE NAMES
Resource management is an important part of X Toolkit applications, and xmessage is no exception. All objects in xmessage can have many of their distinguishing characteristics changed by changing the resources associated with them. Below is a brief list of the resources and what they modify.

foreground
    - foreground color

background
    - background color

width & height
    - size

borderWidth
    - border width

borderColor
    - border color

In order to change the default values for the widget resources you need to have the names; thus, below I have specified the names of some of the most common widgets.

xmessage - (argv[0])
    - shell widget that contains everything displayed.

text
    - the text window.

<button name>
    - each of the buttons. "okay" is default.

You can also reference Widgets by class. The important classes for this application are: Command and Text.

Here are a few examples of how to string all this information together into a resource specification that can be used on the command line with the -xrm flag, or added to your .Xresources file.

xmessage*Command.foreground: Blue
    All command buttons will be blue.

xmessage*foreground: Blue
    Everything in the xmessage window has a blue foreground.

xmessage*Text.border: Red
    The text widget has a red border.

In addition Xmessage has a few specific application resources that allow customizations that are specific to xmessage.

ScrollText
    A Boolean resource that determines whether you are allowed to scroll the text widget. The default value is TRUE.

printLabel
    A Boolean resource that determines whether or not the label of the button pressed to exit the program is printed. Default value is FALSE.

ERROR MESSAGES
Xmessage errors may be printed into their own xmessage window. This invocation of xmessage has a different name. This allows its resources to be specified separately. The name of xmessage error program is xmessage_error.

EXIT STATUS
Xmessage will exit with status zero (0) when there is only one button in the list, and it is clicked to exit. If there is more than one button in the list then the exit status will correspond to the number of the button pressed, starting at one (1) for the first button, and counting up. Zero (0) is not used because no button should have a preferred place over the others.

WATERLOO DIFFERENCES
See the NOTE section at the beginning of this man page.

SEE ALSO
X(1), X(8C), xmessage(1), echo(1), cat(1)

BUGS
There must be some, somewhere.

AUTHORS
Copyright 1988 by Massachusetts Institute of Technology.
Chris Peterson, MIT Project Athena