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

EXAMPLES

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

ENVIRONMENT

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

EXIT STATUS

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

SEE ALSO

171       pmchart(1), xconfirm(1), xmessage(1), pcp.conf(5).
172
173
174
175Performance Co-Pilot                                                PMQUERY(1)
Impressum