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

OPTIONS

48       The available command line options are:
49
50       -c, -center
51            Center the window on the display.
52
53       -nearmouse
54            Pop up the window near the mouse cursor.
55
56       -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
63       -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
68       -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
75       -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
82       -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
86       -file filename
87            Displays  the  file  filename.  All -t options will be ignored.  A
88            filename of `-' reads from standard input.
89
90       -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
97       -font fontname
98            Use fontname as the font.  This  option  is  only  available  when
99            using the X Window System.
100
101       -header string
102            Use string as the window title.
103
104       -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
109       -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
114       -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
119       -useslider
120            When displaying a file, always use a slider instead of determining
121            automatically whether a slider is necessary.
122
123       -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
127       -noframe
128            Do not display a frame around the contents.
129
130       -exclusive
131            Grab  the  keyboard/pointer and do not allow further input until a
132            button is pressed.
133
134       -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
138       -?, -h, -help
139            Display usage message and exit.
140

EXAMPLES

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
145        #! /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
152       A second example, which prompts for a hostname then starts  a  terminal
153       with an ssh session connected to the requested host.
154
155        #! /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

ENVIRONMENT

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

EXIT STATUS

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

SEE ALSO

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