XPROMPT(1) General Commands Manual XPROMPT(1)

NAME

xprompt — prompt a user for input

SYNOPSIS

xprompt [X toolkit options] [-rlen #] [-ibw #] [-dmd ms]
[-echo { on | off | mask | dmask } ] [ -debug | -nodebug ]
[ -grab | -nograb ] [ -re | -nore ] [ -warp | -nowarp ]
[-pfn fontname] [-rfn fontname] [-tf filename] [ -h | --help ] [ -v | --version ] { -p prompt [-r reply] } [...]

DESCRIPTION

xprompt is a utility for the X Window System that is used by interactive scripts to prompt a user for one or more text inputs. It prints the corresponding response(s) to stdout, one per line. Xprompt pops up a window containing a prompt area and a reply area. Any reply area can optionally contain a default reply. If more than one prompt argument is given, only one is visible at a time but the user can scroll through the list of prompts to provide a response to each.

A reply is limited to a single line and may only be comprised of printable characters, as determined by isprint(3). A reply that contains no text is emitted as a newline.

When there is more than one prompt, the cursor-down key and the Return (Enter) key select the next prompt and the cursor-up key selects the previous prompt. The program exits normally by typing ^D or pressing any mouse button inside the reply area of the window. Most standard editing commands (e.g., Delete, Backspace, ^U, cursor movement) are available. These default key bindings may be changed.

If the user is being prompted for potentially sensitive information, such as a password, an initial "echo mode" can be selected to hide the reply text. The current echo mode can be changed by invoking the xp-toggle-echo-mode() action, which cycles through each of the echo modes. The current echo mode applies to all prompts. Refer to the -echo flag.

Normal text selection is not supported, however an entire reply can be selected (copied into CUT_BUFFER0 for subsequent pasting), regardless of the echo mode in effect. Also, the most recent text selection (e.g., in an xterm(1) window) can be pasted into the reply at the current cursor position, also regardless of the echo mode.

Xprompt can be aborted by typing ^C. In this case, no output is emitted and the program terminates with an exit status of 1.

The default is to position the window in the middle of the screen and to grab keyboard input so that the cursor does not need to be moved to the text area. If no height or width geometry is provided for the popup window, xprompt calculates it based on the length of the prompt, the reply length, and the fonts being used. If a height (or width) is provided, it is interpreted in terms of the character height (or width) in the reply font.

OPTIONS

The following command line flags are recognized:

-rlen number

The maximum reply length is number characters. Once this limit is reached, additional reply characters are ignored. The default is 40 characters.

-ibw number

The BorderWidth for the box bounding the text area is number. The default is 1.

-echo { on | off | mask | dmask }

If the echo mode is on (the default), reply text is echoed normally. If the mode is off, reply text is not echoed. If the mode is mask, each reply character is displayed as the mask character (default: "*"). If the mode is dmask (delayed mask), each reply character is displayed normally until either a timer expires or another character is typed (whichever occurs first), and then it is changed into the delayed mask character The duration of the delay is configurable by the -dmd flag or dmaskDuration resource.

-dmd ms

When echo mode is dmask, delay at most ms milliseconds before a normally echoed reply character is changed to the delayed mask character.

-debug

Print debugging output to stderr.

-nodebug

Turn off debugging output. This is the default.

-grab

The cursor may be anywhere but input is directed to the reply's text area. This is the default.

-nograb

The cursor must be in the reply's text area for input to be accepted.

-pfn fontname

The font to be used for the prompt string.

-rfn fontname

The font to be used for the reply string.

-re

After all prompts have been seen, the Return key causes the program to exit normally (i.e., it becomes a synonym for ^D).

-nore

No return-exit. The Return key will not terminate the program. This is the default.

-tf filename

A file containing text translations, one per line, to override the defaults. The resource textTranslations may also be used to specify translations.

-warp

Warp the cursor into the text area and return it to its original position before exiting.

-nowarp

Don't warp the cursor. This is the default.

-h
--help

Print a helpful usage blurb, then exit. This is the default if no command line options are given or in the event of incorrect usage.

-v
--version

Print version information, then exit.

-p prompt [-r reply]

Append the string prompt to the ordered list of prompts. If a reply string is given, use it as the default reply for this prompt, otherwise the reply text field will be empty.

Key Bindings and Actions

Xprompt defines (and redefines) key bindings for user convenience and in aid of the variety of echo modes it supports. It is possible to rebind keys, or sequences of keys, by changing the translations resources for events. This should be done with care because standard Text Widget actions may not work correctly. Some actions have several equivalent bindings.

Edit actions always act on the currently selected reply and are effective regardless of the echo mode.

Xprompt recognizes the following functions, shown with their default bindings:

Cursor navigation:

Ctrl<Key>A:         xp-beginning-of-line()
Ctrl<Key>E:         xp-end-of-line()
<Key>Left:          xp-backward-char()
<Key>Right:         xp-forward-char()

Prompt navigation:

Ctrl<Key>J:         xp-next-prompt()
Ctrl<Key>M:         xp-next-prompt()
<Key>Linefeed:      xp-next-prompt()
<Key>Down:          xp-next-prompt()
<Key>Up:            xp-previous-prompt()
<Key>Return:        xp-next-prompt-or-finish()

Control:

Ctrl<Key>C:         xp-abort()
Ctrl<Key>D:         xp-finish-prompt()
Ctrl<Key>L:         xp-redraw-display()
Ctrl<Key>T:         xp-toggle-echo-mode()

Edit:

Ctrl<Key>H:         xp-erase-char()
Ctrl<Key>K:         xp-kill-to-end-of-line()
Ctrl<Key>W:         xp-erase-word()
Ctrl<Key>U:         xp-erase-line()
<Key>BackSpace:     xp-erase-char()
<Key>Delete:        xp-delete-char()

Copy/Paste:

<Btn1Up>:           xp-select-reply()
<Btn1Down>:         xp-ignore()
<Btn2Down>:         xp-paste-selection()

Ignored:

<Btn3Up>:           xp-ignore()
<Btn3Down>:         xp-ignore()
<Btn1Motion>:       xp-ignore()
<Btn2Motion>:       xp-ignore()
<Btn3Motion>:       xp-ignore()

Reply characters (printable):

<Key>:              xp-insert-char()

The function of an action is usually evident from its name. A few actions merit additional explanation [with their default binding]:

xp-abort()

Terminate immediately with an exit status of 1. [Ctrl<Key>C]

xp-toggle-echo-mode()

Cycle to the next echo mode, retaining the text in the current reply and moving the input cursor to the end of the reply. [Ctrl<Key>T]

xp-paste-selection()

Insert the contents of CUT_BUFFER0, respecting the maximum reply length. [<Btn2Down>]

xp-select-reply()

Copy the contents of the reply buffer to CUT_BUFFER0 (e.g., so that it can be pasted into some other window). [<Btn1Up>]

xp-erase-line()

Erase the entire reply. [Ctrl<Key>U]

xp-kill-to-end-of-line()

Erase the reply from the current cursor position to the end, and save the erased text in CUT_BUFFER0. [Ctrl<Key>K]

xp-erase-word()

Delete any whitespace characters immediately to the left of the cursor, then any sequence of non-whitespace characters. [Ctrl<Key>W]

xp-erase-char()

Delete the reply character immediately to the left of the cursor.

xp-delete-char()

Delete the reply character under the cursor.

xp-finish-prompt()

Print all replies and the terminate with an exit status of 0. [Ctrl<Key>D, <Btn1Down>, <Btn2Down>, and <Btn3Down>]

xp-next-prompt()

Display the next prompt. The list of prompts is circular, so the first prompt is displayed after the last. [Ctrl<Key>J, Ctrl<Key>M, <Key>Down, and <Key>Linefeed]

xp-next-prompt-or-finish()

If all prompts have been seen and returnExit is TRUE, call xp-finish-prompt(), otherwise call xp-next-prompt(). [<Key>Return]

xp-previous-prompt()

Display the previous prompt. The last prompt is previous to the first. [<Key>Up]

xp-insert-char()

Insert this character (without interpretation) at the reply's current insertion point. [<Key>]

X DEFAULTS

The standard X toolkit options and resources are accepted. For example, the default font can be changed by the standard -fn fontname flag or by the resource XPrompt*Font.

In addition, the following resources are understood:

Rlen (class Integer)

The maximum length of the reply.

debug (class Boolean)

If TRUE, enable debugging output.

dmaskDuration (class Integer)

The delay in ms for echo mode dmask.

echo (class String)

The initial echo mode, as one of the -echo flag parameters.

insideborderWidth (class BorderWidth)

The border width for the box bounding the text area.

Grab (class Boolean)

If TRUE keyboard input should be focussed on the text area regardless of where the cursor is.

echoMaskChar (class String)

The character to display when the echo mode is mask.

echoDmaskChar (class String)

The character to display when the echo mode is dmask.

echoFont (class Font)

The font to use for the reply string, overriding XPrompt*Font.

promptFont (class Font)

The font to use for the prompt string, overriding XPrompt*Font.

returnExit (class Boolean)

If TRUE, the Return key allows normal termination if all prompts have been seen.

textTranslations (class String)

Text widget translations.

textTranslationFile (class String)

The name of a file containing text widget translations.

Warp (class Boolean)

Warp the cursor into the text area, if TRUE.

EXAMPLE

The following demonstrates how xprompt can be used by a shell script to grab multi-reply output: 

reply=`xprompt -p "Prompt1" -p "Prompt2" -p "Prompt3"`

IFS="
"

set $reply

echo "First reply is: $1"
echo "Second reply is: $2"
echo "Third reply is: $3"

EXIT STATUS

xprompt exits 0 on success, and 1 if the program is aborted or an error occurs.

SEE ALSO

sh(1), getpass(3), readline(3).

LICENSE

Originally released under an MIT license variant. Subsequent versions also use the BSD-2-Clause license. Refer to the distribution's LICENSE file and source code for details.

BUGS

The user is responsible for ensuring that a proper window size is chosen. The masking characters cannot be specified on the command line, only by resources. While the delay mask duration is given in milliseconds, this will only be an approximation of the actual delay. Although some care is taken to keep potentially sensitive reply text private, such as by disabling core dumps, xprompt does not offer a high degree of security. Text that has been echoed in one of the privacy modes can still be selected for pasting, at which point it is vulnerable to being seen or copied, even long after xprompt has terminated. Accidentally toggling the echo mode will instantly "unhide" text.

AUTHOR

Originally written circa 1989 by:
Barry Brachman <brachman@cs.ubc.ca>
Dept. of Computer Science
University of British Columbia
with valuable suggestions by Rick Morrison and Bob Mende. Conversion to X11R5 by Casey Leedom.

Updated 30 years after its original release by Barry Brachman <brachman@dss.ca>.
The latest release is available at https://www.dss.ca/dss/tech/src/xprompt.

xprompt version 2.0.3 24-Oct-2019 XPROMPT(1)

$Id: xprompt.1.xml 3100 2019-10-24 00:13:47Z brachman $