1PMQUERY(1)                  General Commands Manual                 PMQUERY(1)
2
3
4

NAME

6       pmconfirm, pmmessage, pmquery - general purpose dialog box
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

44       Command line options are available to specify font style, frame  style,
45       modality  and  one  of several different icons to be presented for tai‐
46       lored visual feedback to the user.
47
48       -c, -center
49            Center the window on the display.
50
51       -nearmouse
52            Pop up the window near the mouse cursor.
53
54       -b button-name
55            Displays a button with the label button-name.  If  button-name  is
56            the  empty  string,  the button in that position is not displayed.
57            If no -b options are present, the default is  a  button  with  the
58            label  Continue.   The  exit status associated with button-name is
59            zero.
60
61       -B button-name
62            Displays a button with the label button-name and specifies  it  as
63            the button to be activated when enter is pressed.  The exit status
64            associated with button-name is zero.
65
66       -buttons button,button,...
67            This option will create one button for each comma-separated button
68            option.   Each button consists of a label optionally followed by a
69            colon and an exit value.  The exit value will be returned if  that
70            button is selected.  The default exit value is 100 plus the button
71            number.  Buttons are numbered from the left starting with 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 the tool 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
136       -?, -h, -help
137            Display usage message and exit.
138

EXAMPLES

140       The  following  shell  script will display a window with an information
141       icon, asking the user a yes or no question with "Yes" as the default.
142
143        #! /bin/sh
144        case `pmquery -t "Really power down?" -b No -B Yes -icon question
145        in
146          Yes) shutdown;;
147          No) ;;
148        esac
149
150       A second example, which prompts for a hostname then starts  a  terminal
151       with an ssh session connected to the requested host.
152
153        #! /bin/sh
154        host=`pmquery -input -icon host -b Cancel -B OK \
155                      -header "Remote Terminal - Secure Shell"
156        [ "$host" = "Cancel" -o -z "$host" ] && exit
157        gnome-terminal -e "ssh $host"
158

ENVIRONMENT

160       pmquery  is  an  excellent  choice of utility for the PCP_XCONFIRM_PROG
161       Performance Co-Pilot configuration parameter (refer to pcp.conf(5)  for
162       details).
163
164       Note that PCP_XCONFIRM_PROG will be automatically set to pmquery inside
165       tools like pmchart, unless PCP_XCONFIRM_PROG  is  already  set  in  the
166       environment.
167

EXIT STATUS

169       If  it detects an error, pmquery always returns 1, so this value should
170       not be associated with a button.  Unless -button option  has  not  been
171       used, the return code will be zero on success.
172

SEE ALSO

174       pmchart(1) and pcp.conf(5).
175
176
177
178Performance Co-Pilot                                                PMQUERY(1)
Impressum