1PMQUERY(1) General Commands Manual PMQUERY(1)
2
3
4
6 pmconfirm, pmmessage, pmquery - general purpose dialog box
7
9 pmconfirm [-c] [-b button-name] [-B default-button-name] [-t string]
10 [-file filename] [-icon icontype] [-font font] [-header titlebar-
11 string] [-useslider] [-noslider] [-noframe] [-exclusive]
12
13 pmmessage [-buttons label1[:value1][,label2[:value2][,...]]] [-center]
14 [-nearmouse] [-default button] [-file filename] [-print] [-timeout sec]
15 message...
16
17 pmquery [-input] [all above options...] [message...]
18
20 pmquery provides a command-line-option compatible implementation of the
21 xconfirm and xmessage tools, using a look-and-feel that is consistent
22 with pmchart. Several extensions to the functionality of the original
23 tools have been made, in order to improve their specific utility for
24 pmchart, but wherever possible the original semantics remain.
25
26 pmconfirm displays a line of text for each -t argument specified (or a
27 file when the -file argument is used), and a button for each -b argu‐
28 ment specified. When one of the buttons is pressed, the label of that
29 button is written to pmquery's standard output. This provides a means
30 of communication/feedback from within shell scripts and a means to dis‐
31 play useful information to a user from an application.
32
33 pmmessage displays a window containing a message from the command line,
34 a file, or standard input. It additionally allows buttons to be asso‐
35 ciated with an exit status, and only optionally will write the label of
36 the button to standard output.
37
38 pmquery extends the above tools to additionally support limited user
39 input, as free form text. In this -input mode, any text entered will
40 be output when the default button is pressed. A default text can be
41 entered using the same mechanisms as the other tools.
42
43 Command line options are available to specify font style, frame style,
44 modality and one of several different icons to be presented for tai‐
45 lored visual feedback to the user.
46
47 -c or -center
48 Center the window on the display.
49
50 -nearmouse
51 Pop up the window near the mouse cursor.
52
53 -b button-name
54 Displays a button with the label button-name. If button-name is
55 the empty string, the button in that position is not displayed.
56 If no -b arguments are present, the default is a button with the
57 label Continue. The exit status associated with button-name is
58 zero.
59
60 -B button-name
61 Displays a button with the label button-name and specifies it as
62 the button to be activated when enter is pressed. The exit status
63 associated with button-name is zero.
64
65 -buttons button,button,...
66 This option will create one button for each comma-separated button
67 argument. Each button consists of a label optionally followed by
68 a colon and an exit value. The exit value will be returned if
69 that button is selected. The default exit value is 100 plus the
70 button number. Buttons are numbered from the left starting with
71 one.
72
73 -default label
74 Defines the button with a matching label to be the default. If
75 not specified there is no default. The corresponding resource is
76 defaultButton. Pressing Return anywhere in the xmessage window
77 will activate the default button. The default button has a wider
78 border than the others.
79
80 -t message
81 Displays message. Any number of strings can be listed on the com‐
82 mand line (each must be preceded with the -t option).
83
84 -file filename
85 Displays the file filename. All -t options will be ignored. A
86 filename of `-' reads from standard input.
87
88 -icon icontype
89 Displays the icon icontype where icontype is one of: info, error,
90 question, warning, critical. action is also accepted as a synonym
91 for error for backward compatibility. pmquery introduces the
92 additional archive and host icon types as well as the original
93 xconfirm types listed earlier.
94
95 -font fontname
96 Use fontname as the font. This option is only available when
97 using the X Window System.
98
99 -header string
100 Use string as the window title.
101
102 -print
103 This causes the program to write the label of the button pressed
104 to standard output. It is the default behaviour for pmconfirm and
105 pmquery.
106
107 -noprint
108 This causes the program to not write the label of the button
109 pressed to standard output. It is the default behaviour for
110 pmmessage.
111
112 -geometry geometry-string
113 This provides xconfirm with an X-compatible geometry string speci‐
114 fication. This option is only available when using the X Window
115 System.
116
117 -useslider
118 When displaying a file, always use a slider instead of determining
119 automatically whether a slider is necessary.
120
121 -noslider
122 Do not create a slider, and clip text to the window size, instead
123 of determining automatically whether a slider is necessary..
124
125 -noframe
126 Do not display a frame around the contents.
127
128 -exclusive
129 Grab the keyboard/pointer and do not allow further input until a
130 button is pressed.
131
132 -timeout secs
133 Exit with status 0 after secs seconds if the user has not clicked
134 on a button yet. The corresponding resource is timeout.
135
137 The following shell script will display a window with an information
138 icon, asking the user a yes or no question with "Yes" as the default.
139
140 #! /bin/sh
141 case `pmquery -t "Really power down?" -b No -B Yes -icon question
142 in
143 Yes) shutdown;;
144 No) ;;
145 esac
146
147 A second example, which prompts for a hostname then starts a terminal
148 with an ssh session connected to the requested host.
149
150 #! /bin/sh
151 host=`pmquery -input -icon host -b Cancel -B OK \
152 -header "Remote Terminal - Secure Shell"
153 [ "$host" = "Cancel" -o -z "$host" ] && exit
154 gnome-terminal -e "ssh $host"
155
157 pmquery is an excellent choice of utility for the "PCP_XCONFIRM_PROG"
158 Performance Co-Pilot configuration parameter (refer to pcp.conf(5) for
159 details).
160
161 Note that PCP_XCONFIRM_PROG will be automatically set to pmquery inside
162 tools like pmchart, unless PCP_XCONFIRM_PROG is already set in the
163 environment.
164
166 If it detects an error, pmquery always returns 1, so this value should
167 not be associated with a button. Unless -button option has not been
168 used, the return code will be zero on success.
169
171 pmchart(1), xconfirm(1), xmessage(1), pcp.conf(5).
172
173
174
175Performance Co-Pilot PMQUERY(1)