xprompt.1

.TH XPROMPT 1
.SH NAME
xprompt \- read line utility for X
.SH SYNOPSIS
.B xprompt
.RB [ \-acdfips ]
.RB [ \-G
.IR gravity ]
.RB [ \-g
.IR geometry ]
.RB [ \-h
.IR histfile ]
.RB [ \-m
.IR monitor ]
.RB [ \-w
.IR windowid ]
.RI [ promptstr ]
.SH DESCRIPTION
.B 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.
.PP
If the argument
.I promptstr
is given, the prompt string
.I promptstr
appears at the beginning of the input field.
.PP
xprompt resembles dmenu, but they differ in a subtle point:
while dmenu completes the whole text, xprompt performs contextual completion.
.PP
The options are as follows:
.TP
.B \-a
Enables argument mode.
In this mode, xprompt looks for more arguments to complete after completing one argument.
.TP
.B \-c
Always show auto complete without having to press Tab.
.TP
.B \-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.
.TP
.B \-f
Enables filename completion.
When the
.B \-f
option is used, when no item from the standard input matches the current text,
.B xprompt
tries to complete a file name.
.TP
.BI "\-G " gravity
Specify the gravity,
that is, where in the screen or parent window to display xprompt.
.I 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.
.TP
.BI "\-g " geometry
Specifies the geometry in the form
.B <WIDTH>x<HEIGHT>[{-+}<XOFFSET>{-+}<YOFFSET>].
Replace
.B <WIDTH>
by the desired width,
.B <HEIGHT>
by the desired height, and so on.
A value of 0 sets a field to the default value.
So, for example,
.B -g 0x20+0+0
set the height to 20 pixels while maintaining other values to the default.
.B <XOFFSET>
and
.B <YOFFSET>
are optional and can be preceded by either a minus or a plus
(meaning negative or positive values).
So, for example,
.B -g 0x20
is the same as
.BR -g 0x20+0+0 .
.TP
.BI "\-h " file
Specifies the file to be used for reading and storing the history of typed texts.
.TP
.B \-i
Makes xprompt match items case insensitively.
.TP
.BI "\-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
.B \-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.
.TP
.B \-p
Enable password mode.
In this mode, the typed text is not echoed in the input field.
.TP
.B \-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.
.TP
.BI "\-w " windowid
Renders xprompt embedded into the window
.IR windowid .
.PP
Each item read from stdin has the following format:
.IP \(bu 2
.EX
ITEM := [TABS] WORD [TABS DESCRIPTION] NEWLINE
.EE
.PP
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.
.IP \(bu 2
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.
.IP \(bu 2
The word is a string listed for completion in the dropdown list that
appears when pressing Tab.
.IP \(bu 2
The second group of tabs separate the word from its description.
.IP \(bu 2
The description is a string describing what the word means.
.IP \(bu 2
The newline terminates the item specification.
.PP
.B xprompt
saves the input text from previous runs in a history file specified by the
.B -h
option or by the
.B XPROMPTHISTFILE
environment variable.
.SH USAGE
.B xprompt
is controlled by the keyboard.
Pressing Tab initiates the completion,
pressing Up or Down navigates through the history.
.PP
.B 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.
.PP
.B xprompt
can also be controlled via
.B Ctrl + Key
keybindings with the
.B XPROMPTCTRL
environment variable.
The default value for
.B XPROMPTCTRL
is
.BR \(dqvcmpn::::aebf::ukhdwAEBF::zZ:\(dq .
Each key or keybinding is assigned a operation like
.BR CTRLCANCEL ,
.BR CTRLNEXT ,
.BR CTRLRIGHT ,
etc.
The default value for each operation is listed bellow between parentheses.
.TP
.BR CTRLPASTE " (" Ctrl+V )
Paste from primary X selection.
.TP
.BR CTRLCOPY " (" Ctrl+C )
Copy selected text into primary X selection.
.TP
.BR CTRLENTER " (" Enter ", " Ctrl+M )
When completion is in operation, confirms text.
When completion is not in operation, or when the
.B \-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.
.TP
.BR CTRLPREV " (" Shift+Tab ", " Ctrl+P )
Selects the previous item in the completion dropdown list.
.TP
.BR CTRLNEXT " (" Tab ", " Ctrl+N )
Selects the next item in the completion dropdown list.
.TP
.BR CTRLPGUP " (" PgUp )
TODO.
.TP
.BR CTRLPGDOWN " (" PgDown )
TODO.
.TP
.BR CTRLUP " (" Up )
Select the previous entered text in the history.
.TP
.BR CTRLDOWN " (" Down )
Select the next entered text in the history.
.TP
.BR CTRLBOL " (" Home ", " Ctrl+A )
Move the cursor to the beginning of line.
.TP
.BR CTRLEOL " (" End ", " Ctrl+E )
Move the cursor to the end of line.
.TP
.BR CTRLLEFT " (" Left ", " Ctrl+B )
Move the cursor one character to the left.
.TP
.BR CTRLRIGHT " (" Right ", " Ctrl+F )
Move the cursor one character to the right.
.TP
.BR CTRLWLEFT " (" Ctrl+Left )
Move the cursor one word to the left.
.TP
.BR CTRLWRIGHT " (" Ctrl+Right )
Move the cursor one word to the right.
.TP
.BR CTRLDELBOL " (" Ctrl+U )
Delete from the cursor to the beginning of line.
.TP
.BR CTRLDELEOL " (" Ctrl+K )
Delete from the cursor to the end of line.
.TP
.BR CTRLDELLEFT " (" Backspace ", " Ctrl+H )
Delete one character to the left.
.TP
.BR CTRLDELRIGHT " (" Delete ", " Ctrl+D )
Delete one character to the right.
.TP
.BR CTRLDELWORD " (" Ctrl+W )
Delete one word to the left.
.TP
.BR CTRLSELBOL " (" Shift+Home )
Select text from cursor to beginning of line.
.TP
.BR CTRLSELEOL " (" Shift+End )
Select text from cursor to end of line.
.TP
.BR CTRLSELLEFT " (" Shift+Left )
Select text from cursor to one character to the left.
.TP
.BR CTRLSELRIGHT " (" Shift+Right )
Select text from cursor to one character to the right.
.TP
.BR CTRLSELWLEFT " (" Ctrl+Shift+Left )
Select text from cursor to one word to the left.
.TP
.BR CTRLSELWRIGHT " (" Ctrl+Shift+Right )
Select text from cursor to one word to the right.
.TP
.BR CTRLUNDO " (" Ctrl+Z )
Undo the last editing operation.
.TP
.BR CTRLREDO " (" Ctrl+Shift+Z )
Redo an editing operation.
.TP
.BR CTRLCANCEL " (" Esc )
When completion is in progress, exit completion without confirming text.
When completion is not in progress, exit xprompt without printing anything.
.PP
.B 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.
.SH ENVIRONMENT
The following environment variables affect the execution of
.BR xprompt .
.TP
.B XPROMPTHISTFILE
Specifies the file to be used for reading and storing the history of typed texts.
.TP
.B XPROMPTHISTSIZE
Specifies the number of entries to be kept in the history file.
.TP
.B 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 \(dqvcmpn::::aebf::ukhdwAEBF::zZ:\(dq,
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.
.TP
.B WORDDELIMITERS
A string of characters that delimits words.
By default it is a \(lq .,/:;\e<>'[]{}()&$?!\(rq.
.SH RESOURCES
.B xprompt
understands the following X resources.
.TP
.B xprompt.font
The font to drawn the text.
Multiple fonts can be added as fallback fonts;
they must be separated by a comma.
.TP
.B xprompt.background
The background color of the input text field,
and of the non-selected items in the dropdown completion list.
.TP
.B xprompt.foreground
The foreground color of the input text field,
and of the non-selected items in the dropdown completion list.
.TP
.B xprompt.description
The foreground color of the description of non-selected items in the dropdown completion list.
.TP
.B xprompt.hoverbackground
The background color of the hovered items in the dropdown completion list.
.TP
.B xprompt.hoverforeground
The background color of the hovered items in the dropdown completion list.
.TP
.B xprompt.hoverdescription
The foreground color of the description of hovered items in the dropdown completion list.
.TP
.B xprompt.selbackground
The background color of the selected items in the dropdown completion list.
.TP
.B xprompt.selforeground
The background color of the selected items in the dropdown completion list.
.TP
.B xprompt.seldescription
The foreground color of the description of selected items in the dropdown completion list.
.TP
.B xprompt.border
The color of the border around xprompt.
.TP
.B xprompt.separator
The color of the separator between the input field and the dropdown list.
.TP
.B xprompt.borderWidth
The size in pixels of the border around xprompt.
.TP
.B xprompt.separatorWidth
The size in pixels of the item separator.
.TP
.B xprompt.items
The number of items to be listed in the dropdown completion list.
.TP
.B 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,
.B 0x20+0+0
set the height to 20 pixels while maintaining other values to the default.
.TP
.B 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.
.SH EXAMPLES
Suppose a file
containing the following content,
where \(lq\et\(rq means a tab character.
.IP \(bu 2
.EX
git
\et	add\et    Add file contents to the index.
\et	rm\et     Remove files from the working tree and from the index.
\et	mv\et     Move or rename a file, a directory, or a symlink.
\et	commit\et Record changes to the repository.
man
\et	cat
\et	cut
\et	ed
\et	vi
open
.EE
.PP
By passing this file as stdin to
.BR xprompt ,
.B xprompt
will have the following behavior when pressing Tab.
.IP \(bu 2
If the input field is empty,
.B xprompt
will display a dropdown list with the following three entries after pressing Tab:
.IR git ,
.IR man ", and"
.IR open .
It will also display descriptions after each completion.
.IP \(bu 2
If the input field contains the word
.I git
at the beginning of the line,
.B xprompt
will display a dropdown list with the following four entries after pressing Tab:
.IR add ,
.IR rm ,
.IR mv ", and"
.IR commit .
.IP \(bu 2
If the input field contains the word
.I man
at the beginning of the line,
.B xprompt
will display a dropdown list with the following four entries after pressing Tab:
.IR cat ,
.IR cut ,
.IR ed ", and"
.IR vi .
.IP \(bu 2
If the input field contains the word
.I open
at the beginning of the line, and
.B xprompt
was invoked with the
.B -f
option, then
.B xprompt
will display a dropdown list with possible filenames after pressing Tab,
since no completion was specified at stdin.
.SH SEE ALSO
.IR dmenu (1),
.IR xmenu (1)
.SH BUGS
.B xprompt
steals the input focus from the currently focused window (and does not give it back).
This is necessary because
.B xprompt
needs the input focus for the X Input Method.  Since
.B xprompt
is an override-redirect window, it does not get the focus by regular means from the window manager
(because
.B xprompt
is not controlled by the window manager,
instead
.B xprompt
controls itself and has to get the focus by its own means).
.B xprompt
cannot be managed by the window manager because most window managers do not know how
.B xprompt
works or how it needs the entire focus for itself.