1PMQUERY(1) General Commands Manual PMQUERY(1)
2
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 pmmessage [-buttons label1[:value1][,label2[:value2][,...]]] [-center]
14 [-nearmouse] [-default button] [-file filename] [-print] [-timeout sec]
15 message...
16 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 pmconfirm displays a line of text for each -t option specified (or a
27 file when the -file option is used), and a button for each -b option
28 specified. When one of the buttons is pressed, the label of that but‐
29 ton is written to pmquery's standard output. This provides a means of
30 communication/feedback from within shell scripts and a means to display
31 useful information to a user from an application.
32 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 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 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
48 The available command line options are:
49 -c, -center
51 Center the window on the display.
52 -nearmouse
54 Pop up the window near the mouse cursor.
55 -b button-name
57 Displays a button with the label button-name. If button-name is
58 the empty string, the button in that position is not displayed.
59 If no -b options are present, the default is a button with the
60 label Continue. The exit status associated with button-name is
61 zero.
62 -B button-name
64 Displays a button with the label button-name and specifies it as
65 the button to be activated when enter is pressed. The exit status
66 associated with button-name is zero.
67 -buttons button,button,...
69 This option will create one button for each comma-separated button
70 option. Each button consists of a label optionally followed by a
71 colon and an exit value. The exit value will be returned if that
72 button is selected. The default exit value is 100 plus the button
73 number. Buttons are numbered from the left starting with one.
74 -default label
76 Defines the button with a matching label to be the default. If
77 not specified there is no default. The corresponding resource is
78 defaultButton. Pressing Return anywhere in the xmessage window
79 will activate the default button. The default button has a wider
80 border than the others.
81 -t message
83 Displays message. Any number of strings can be listed on the com‐
84 mand line (each must be preceded with the -t option).
85 -file filename
87 Displays the file filename. All -t options will be ignored. A
88 filename of `-' reads from standard input.
89 -icon icontype
91 Displays the icon icontype where icontype is one of: info, error,
92 question, warning, critical. action is also accepted as a synonym
93 for error for backward compatibility. pmquery introduces the
94 additional archive and host icon types as well as the original
95 xconfirm types listed earlier.
96 -font fontname
98 Use fontname as the font. This option is only available when
99 using the X Window System.
100 -header string
102 Use string as the window title.
103 -print
105 This causes the program to write the label of the button pressed
106 to standard output. It is the default behaviour for pmconfirm and
107 pmquery.
108 -noprint
110 This causes the program to not write the label of the button
111 pressed to standard output. It is the default behaviour for
112 pmmessage.
113 -geometry geometry-string
115 This provides the tool with an X-compatible geometry string speci‐
116 fication. This option is only available when using the X Window
117 System.
118 -useslider
120 When displaying a file, always use a slider instead of determining
121 automatically whether a slider is necessary.
122 -noslider
124 Do not create a slider, and clip text to the window size, instead
125 of determining automatically whether a slider is necessary..
126 -noframe
128 Do not display a frame around the contents.
129 -exclusive
131 Grab the keyboard/pointer and do not allow further input until a
132 button is pressed.
133 -timeout secs
135 Exit with status 0 after secs seconds if the user has not clicked
136 on a button yet. The corresponding resource is timeout.
137 -?, -h, -help
139 Display usage message and exit.
140
142 The following shell script will display a window with an information
143 icon, asking the user a yes or no question with "Yes" as the default.
144 #! /bin/sh
146 case `pmquery -t "Really power down?" -b No -B Yes -icon question
147 in
148 Yes) shutdown;;
149 No) ;;
150 esac
151 A second example, which prompts for a hostname then starts a terminal
153 with an ssh session connected to the requested host.
154 #! /bin/sh
156 host=`pmquery -input -icon host -b Cancel -B OK \
157 -header "Remote Terminal - Secure Shell"
158 [ "$host" = "Cancel" -o -z "$host" ] && exit
159 gnome-terminal -e "ssh $host"
160
162 pmquery is an excellent choice of utility for the PCP_XCONFIRM_PROG
163 Performance Co-Pilot configuration parameter (refer to pcp.conf(5) for
164 details).
165 Note that PCP_XCONFIRM_PROG will be automatically set to pmquery inside
167 tools like pmchart, unless PCP_XCONFIRM_PROG is already set in the
168 environment.
169
171 If it detects an error, pmquery always returns 1, so this value should
172 not be associated with a button. Unless -button option has not been
173 used, the return code will be zero on success.
174
176 pmchart(1) and pcp.conf(5).
177Performance Co-Pilot PMQUERY(1)