mdw@git.distorted.org.uk Git - xtoys/blob - xmsg.1

   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).