| 1 | .\" -*-nroff-*- |
| 2 | .TH xmsg 1 "20 December 2001" "Edgeware tools" |
| 3 | .SH NAME |
| 4 | xmsg \- pops up a message box |
| 5 | .SH SYNOPSIS |
| 6 | .B xmsg |
| 7 | .RI [ gtk-options ...] |
| 8 | .RB [ \-EIQWm ] |
| 9 | .RB [ \-d |
| 10 | .IR headline ] |
| 11 | .RB [ \-t |
| 12 | .IR title ] |
| 13 | .I message |
| 14 | .RI [ button ...] |
| 15 | .SH DESCRIPTION |
| 16 | The |
| 17 | .B xmsg |
| 18 | program pops up a pretty GTK message box, containing the listed buttons |
| 19 | (shown right to left along the bottom). The button strings are listed, |
| 20 | one per argument, after the message. If no buttons are requested, an |
| 21 | .B OK |
| 22 | button is provided anyway. |
| 23 | .PP |
| 24 | The user dismisses the message window by activating one of the buttons |
| 25 | or just closing the window using the window manager. The |
| 26 | .B xsmg |
| 27 | program then writes a string to its standard output describing the |
| 28 | user's action and exits. The string written is, by default, the label |
| 29 | of the activated button, though this can be overridden: see below. |
| 30 | .SS "Message specifications" |
| 31 | The |
| 32 | .I message |
| 33 | argument is usually just a text string to be displayed. However, if the |
| 34 | .I message |
| 35 | is |
| 36 | .RB ` \- ' |
| 37 | then, instead, the message to display is read from standard input. If the |
| 38 | first character of |
| 39 | .I message |
| 40 | is |
| 41 | .RB ` ! ' |
| 42 | then that character is removed. (Hence, if you really wanted to show |
| 43 | the message |
| 44 | .RB ` \- ', |
| 45 | you need to pass |
| 46 | .RB ` !\- '.) |
| 47 | Conscientious script authors will prefix strings appropriately. |
| 48 | .PP |
| 49 | Pango markup may be used in message and headline strings if the |
| 50 | .B \-m |
| 51 | option is requested. |
| 52 | .SS "Button specifications" |
| 53 | A |
| 54 | .I button |
| 55 | argument has the form |
| 56 | .RI [ opt \fB: opt \fB: ...] \c |
| 57 | .RB [ ! ] \c |
| 58 | .IR label . |
| 59 | The |
| 60 | .I label |
| 61 | is either a text string, or a GTK stock-id (e.g., |
| 62 | .BR gtk-ok ). |
| 63 | Mnemonic characters in button labels may be marked by prefixing them |
| 64 | with underscores. Write two underscores if you really want a literal |
| 65 | underscore to appear. |
| 66 | .PP |
| 67 | Each |
| 68 | .I opt |
| 69 | may be one of the following. |
| 70 | .TP |
| 71 | .B default |
| 72 | This should be the default button, activated when the user presses the |
| 73 | .I enter |
| 74 | or |
| 75 | .I return |
| 76 | key. |
| 77 | .TP |
| 78 | .B cancel |
| 79 | This should be the cancel button, activated when the user presses the |
| 80 | .I escape |
| 81 | key or simply dismisses the window. |
| 82 | .TP |
| 83 | .BI = tag |
| 84 | If the user activates this button, output the |
| 85 | .I tag |
| 86 | rather than the button's label. |
| 87 | .PP |
| 88 | If no button is marked as the default, then the rightmost (first |
| 89 | specified) is chosen automatically; similarly, if there is no specified |
| 90 | cancel button then the last is chosen. If several buttons are marked as |
| 91 | default or cancel buttons then the behaviour is unspecified. |
| 92 | .PP |
| 93 | Button options are usually processed while colons remain in the button |
| 94 | specification. Processing stops early if an exclamation mark |
| 95 | .RB ` ! ' |
| 96 | is reached. For example, |
| 97 | .B default:!cancel:button |
| 98 | is parsed has specifying the |
| 99 | .B default |
| 100 | option and a label text of |
| 101 | .BR cancel:button . |
| 102 | .PP |
| 103 | If no |
| 104 | .I button |
| 105 | arguments are given, |
| 106 | .B xmsg |
| 107 | automatically provides an OK button (it actually uses the GTK |
| 108 | .B gtk-ok |
| 109 | stock button) but produces no output. |
| 110 | .SS Options |
| 111 | .TP |
| 112 | .BR \-E ", " \-I ", " \-Q ", " \-W |
| 113 | Mark the message window as, respectively, reporting an error, providing |
| 114 | information, asking a question, or giving a warning. |
| 115 | .TP |
| 116 | .BR "\-d, \-\-headline " headline |
| 117 | Write the |
| 118 | .I headline |
| 119 | above the main message, in larger and bolder text. |
| 120 | .TP |
| 121 | .B "\-m, \-\-markup" |
| 122 | Enable the use of Pango XML-like markup in the message and headline |
| 123 | strings. See the Pango documentation for a description of the markup |
| 124 | tags available. |
| 125 | .TP |
| 126 | .BI "\-t, \-\-title " title |
| 127 | Sets the title for the window. If you don't specify a title, the window |
| 128 | is labelled |
| 129 | .RB ` xmsg '. |
| 130 | .SH BUGS |
| 131 | None currently known. |
| 132 | .SH SEE ALSO |
| 133 | .BR gtk-options (7). |
| 134 | .SH AUTHOR |
| 135 | Mark Wooding (mdw@distorted.org.uk). |