Home

XPROMPT(1)

NAME

xprompt - read line utility for X

SYNOPSIS

xprompt [-dfips] [-G gravity] [-g geometry] [-h histfile] [-m monitor] [-w windowid] [promptstr]

DESCRIPTION

xprompt is a prompt for X, it displays a text input field where the user can type in a text subject to tab-completion. When the user presses Return, the typed text is printed to the stdout. When the user presses Tab, a dropdown menu appears showing the items from the stdin that matches the word to be completed. It can read a list of newline-separated items from stdin.

If the argument promptstr is given, the prompt string promptstr appears at the beginning of the input field.

xprompt resembles dmenu, but they differ in a subtle point: while dmenu completes the whole text, xprompt performs contextual completion.

The options are as follows:

• -d

  Rather than complete item names, complete item descriptions. Item names are hidden and only descriptions are listed on the dropdown list. When clicking Enter, the hidden item name is printed to stdout.

• -f

  Enables filename completion. When the -f option is used, when no item from the standard input matches the current text, xprompt tries to complete a file name.

• -G gravity

  Specify the gravity, that is, where in the screen or parent window to display xprompt. gravity can be "N" for NorthGravity (display on the top center of the screen); "SE" for SouthEastGravity (display on the bottom right corner of the screen); "C" for CenterGravity (display on the center of the screen); etc.

• -g geometry

  Specifies the geometry in the form <WIDTH>x<HEIGHT>[{-+}<XOFFSET>{-+}<YOFFSET>]. Replace <WIDTH> by the desired width, <HEIGHT> by the desired height, and so on. A value of 0 sets a field to the default value. So, for example, -g 0x20+0+0 set the height to 20 pixels while maintaining other values to the default. <XOFFSET> and <YOFFSET> are optional and can be preceded by either a minus or a plus (meaning negative or positive values). So, for example, -g 0x20 is the same as -g0x20+0+0**.**

• -h file

  Specifies the file to be used for reading and storing the history of typed texts.

• -i

  Makes xprompt match items case insensitively.

• -m monitor

  Makes xprompt be displayed on the monitor specified. Monitor numbers start from 0. Without this option, when xprompt is not embedded (i.e., without the -w option), xprompt is displayed on the same monitor of the focused window, or (if there is no focused window) on the monitor where the mouse is on.

• -p

  Enable password mode. In this mode, the typed text is not echoed in the input field.

• -s

  Makes a single Enter or Esc keypress or mouse click on a item exit xprompt, regardless of a completion be in action. Without this option, when a completion is in action, a Enter or Esc keypress or a mouse click first exits the completion, and a second keypress exits xprompt.

• -w windowid

  Renders xprompt embedded into the window windowid.

Each item read from stdin has the following format:

ITEM := [TABS] WORD [TABS DESCRIPTION] NEWLINE

That means that each item is composed by zero or more tabs, followed by a text, followed by more tabs, followed by a description, followed by newline. Brackets group optional elements.

The initial tabs indicate the item hierarchy. An item without initial tabs is listed for completion at the beginning of the input field. An item with one tab is listed for completion for the second word in the input field. And so on.

The word is a string listed for completion in the dropdown list that appears when pressing Tab.

The second group of tabs separate the word from its description.

The description is a string describing what the word means.

The newline terminates the item specification.

xmenu saves the input text from previous runs in a history file specified by the -h option or by the XPROMPTHISTFILE environment variable.

USAGE

xprompt is controlled by the keyboard. Pressing Tab initiates the completion, pressing Up or Down navigates through the history.

xprompt supports XIM-based input methods with on-the-spot pre-editing. When the input method is in progress, the pre-edited text is underlined.

xprompt can also be controlled via Ctrl + Key keybindings with the XPROMPTCTRL environment variable. The default value for XPROMPTCTRL is vcmpn::::aebf::ukhdwAEBF::zZ: . Each key or keybinding is assigned a operation like CTRLCANCEL, CTRLNEXT, CTRLRIGHT, etc. The default value for each operation is listed bellow between parentheses.

• CTRLPASTE ( Ctrl+V )

  Paste from primary X selection.

• CTRLCOPY ( Ctrl+C )

  Copy selected text into primary X selection.

• CTRLENTER ( Enter , Ctrl+M )

  When completion is in operation, confirms text. When completion is not in operation, or when the -s option is supplied, prints the input text to stdout, and writes it to the history file, if the input text is different from the last entry in the history file.

• CTRLPREV ( Shift+Tab , Ctrl+P )

  Selects the previous item in the completion dropdown list.

• CTRLNEXT ( Tab , Ctrl+N )

  Selects the next item in the completion dropdown list.

• CTRLPGUP ( PgUp )

  TODO.

• CTRLPGDOWN ( PgDown )

  TODO.

• CTRLUP ( Up )

  Select the previous entered text in the history.

• CTRLDOWN ( Down )

  Select the next entered text in the history.

• CTRLBOL ( Home , Ctrl+A )

  Move the cursor to the beginning of line.

• CTRLEOL ( End , Ctrl+E )

  Move the cursor to the end of line.

• CTRLLEFT ( Left , Ctrl+B )

  Move the cursor one character to the left.

• CTRLRIGHT ( Right , Ctrl+F )

  Move the cursor one character to the right.

• CTRLWLEFT ( Ctrl+Left )

  Move the cursor one word to the left.

• CTRLWRIGHT ( Ctrl+Right )

  Move the cursor one word to the right.

• CTRLDELBOL ( Ctrl+U )

  Delete from the cursor to the beginning of line.

• CTRLDELEOL ( Ctrl+K )

  Delete from the cursor to the end of line.

• CTRLDELLEFT ( Backspace , Ctrl+H )

  Delete one character to the left.

• CTRLDELRIGHT ( Delete , Ctrl+D )

  Delete one character to the right.

• CTRLDELWORD ( Ctrl+W )

  Delete one word to the left.

• CTRLSELBOL ( Shift+Home )

  Select text from cursor to beginning of line.

• CTRLSELEOL ( Shift+End )

  Select text from cursor to end of line.

• CTRLSELLEFT ( Shift+Left )

  Select text from cursor to one character to the left.

• CTRLSELRIGHT ( Shift+Right )

  Select text from cursor to one character to the right.

• CTRLSELWLEFT ( Ctrl+Shift+Left )

  Select text from cursor to one word to the left.

• CTRLSELWRIGHT ( Ctrl+Shift+Right )

  Select text from cursor to one word to the right.

• CTRLUNDO ( Ctrl+Z )

  Undo the last editing operation.

• CTRLREDO ( Ctrl+Shift+Z )

  Redo an editing operation.

• CTRLCANCEL ( Esc )

  When completion is in progress, exit completion without confirming text. When completion is not in progress, exit xprompt without printing anything.

xprompt can also be controlled with the mouse. Clicking on a item selects it. Clicking on the input field with the left button moves the cursor. Clicking on the input field with the middle button pastes from the primary selection. Clicking on the input field with the left button and moving the mouse selects text. Clicking on the input field with the left button twice selects a word. Clicking on the input field with the left button three times selects the whole text.

ENVIRONMENT

The following environment variables affect the execution of xprompt.

• XPROMPTHISTFILE

  Specifies the file to be used for reading and storing the history of typed texts.

• XPROMPTHISTSIZE

  Specifies the number of entries to be kept in the history file.

• XPROMPTCTRL

  This environment variable is set to a list of alphabetic characters, each character specify a ctrl sequence for a input operation in the order listed in the section USAGE. For example, by default, XPROMPTCTRL is "vcmpn::::aebf::ukhdwAEBF::zZ:", it means that pressing Ctrl+V enters CTRLPASTE, Ctrl+C enters CTRLCOPY, Ctrl+M enters CTRLENTER, etc. A colon specifies that no Ctrl + Key sequence implements such operation.

• WORDDELIMITERS

  A string of characters that delimits words. By default it is a “ .,/:;\<>'[]{}()&$?!”.

RESOURCES

xprompt understands the following X resources.

• xprompt.font

  The font to drawn the text. Multiple fonts can be added as fallback fonts; they must be separated by a comma.

• xprompt.background

  The background color of the input text field, and of the non-selected items in the dropdown completion list.

• xprompt.foreground

  The foreground color of the input text field, and of the non-selected items in the dropdown completion list.

• xprompt.description

  The foreground color of the description of non-selected items in the dropdown completion list.

• xprompt.hoverbackground

  The background color of the hovered items in the dropdown completion list.

• xprompt.hoverforeground

  The background color of the hovered items in the dropdown completion list.

• xprompt.hoverdescription

  The foreground color of the description of hovered items in the dropdown completion list.

• xprompt.selbackground

  The background color of the selected items in the dropdown completion list.

• xprompt.selforeground

  The background color of the selected items in the dropdown completion list.

• xprompt.seldescription

  The foreground color of the description of selected items in the dropdown completion list.

• xprompt.border

  The color of the border around xprompt.

• xprompt.separator

  The color of the separator between the input field and the dropdown list.

• xprompt.borderWidth

  The size in pixels of the border around xprompt.

• xprompt.separatorWidth

  The size in pixels of the item separator.

• xprompt.items

  The number of items to be listed in the dropdown completion list.

• xprompt.geometry

  The geometry in the form <WIDTH>x<HEIGHT>+<XOFFSET>+<YOFFSET>. Replace <WIDTH> by the desired width, <HEIGHT> by the desired height, and so on. A value of 0 sets a field to the default value. So, for example, 0x20+0+0 set the height to 20 pixels while maintaining other values to the default.

• xprompt.gravity

  Where in the screen or parent window to display xprompt. It can be "N" for NorthGravity (display on the top center of the screen); "SE" for SouthEastGravity (display on the bottom right corner of the screen); "C" for CenterGravity (display on the center of the screen); etc.

EXAMPLES

Suppose a file containing the following content, where “\t” means a tab character.

git
\t	add\t    Add file contents to the index.
\t	rm\t     Remove files from the working tree and from the index.
\t	mv\t     Move or rename a file, a directory, or a symlink.
\t	commit\t Record changes to the repository.
man
\t	cat
\t	cut
\t	ed
\t	vi
open

By passing this file as stdin to xprompt, xprompt will have the following behavior when pressing Tab.

If the input field is empty, xprompt will display a dropdown list with the following three entries after pressing Tab: git, man , and open. It will also display descriptions after each completion.

If the input field contains the word git at the beginning of the line, xprompt will display a dropdown list with the following four entries after pressing Tab: add, rm, mv , and commit.

If the input field contains the word man at the beginning of the line, xprompt will display a dropdown list with the following four entries after pressing Tab: cat, cut, ed , and vi.

If the input field contains the word open at the beginning of the line, and xprompt was invoked with the -f option, then xprompt will display a dropdown list with possible filenames after pressing Tab, since no completion was specified at stdin.

SEE ALSO

dmenu(1), xmenu(1)