multiselect.1

.TH multiselect 1 "September 14, 2019"

.
.
.
.SH NAME
multiselect - a multiple selections server for X11

.
.
.
.SH SYNOPSIS

.B multiselect
[\fI-d\fP]
[\fI-i\fP]
[\fI-k (F1|F2)\fP]
[\fI-f\fP]
[\fI-p\fP]
[\fI-t sep\fP]
[\fI-e ext\fP]
[-|\fIstring ...\fP]

.
.
.
.SH DESCRIPTION

Store multiple strings the user can choose among when pasting.

The strings can be:

.IP "  * " 4
the commandline arguments; e.g., \fImultiselect first second third\fP

.IP "  * "
the lines of a text file passed as standard input:
\fImultiselect - < file\fP

.IP "  * "
added at run-time with ctrl-shift-z, or F2 if enabled by \fI-k\fP

.P

When the user pastes (e.g., by middle-clicking), these strings are shown. One
of them can be pasted by either clicking on it, selecting with the cursor keys
and pressing 'Enter', or by pressing a key between 1-9 and a-z.

Pressing 'z' or F2 or clicking the V square adds the current selection to the
list. Pressing Delete or Backspace deletes the string under the cursor.
Pressing 's' or F3 delete the last string, 'd' or F4 delete all of them.
Pressing any other key or clicking on the header causes no string to be pasted.
Pressing 'q' or clicking on the X square terminate \fImultiselect\fP.

.
.
.
.SH ARGUMENTS

.TP
.B -d
keep running even after after the user select another string, to add it
by cntr-shift-z or by F2 if enabled by \fI-k F2\fP

.TP
.BI -k " (F1|F2|F5)
enable function keys even when the string selection menu is not on screen:
\fIF1\fP opens it, \fIF2\fP adds a new string, \fIF5\fP terminates;
implies \fI-d\fP

.TP
.B -f
send the selection even when the menu has been opened by \fIF1\fP rather than
pasting; achieved by sending a fake middle mouse click to the root window

.TP
.B -c
add a string as soon as it is selected, without pressing \fIctrl-shift x\fP or
\fIF2\fP

.TP
.B -i
the next or previous string is pasted immediately after pressing the up and
down cursor keys, without the need to press 'Enter'

.TP
.BI -t " sep
everything up to the first \fIsep\fP character in each string is displayed in
the menu but not pasted; see \fILABELS\fP, below

.TP
.B -p
paste mode: send the selection as soon as the user chooses it;
see \fICLICK MODE AND PASTE MODE\fP, below

.TP
.BI -e " external
call an external program to do the actual pasting; it is called as \fIexternal
test requestor text\fP; if it returns 0, it is called again with arguments
\fIexternal paste requestor text\fP; otherwise, the selected string is pasted
as usual

.TP
.B -h
help text

.
.
.
.SH USAGE

The typical application of \fImultiselect\fP is to post data stored in a file
to a web form. When several fields are present, a large number of
select-and-paste steps are required: select the first field, paste in the form;
select the second and paste; select the third and so on.

If the fields can be extracted and put each on a line of another file, calling
\fPmultiselect\fP on that file selects all fields at the same time. What
remains to be done is only to paste each on the appropriate field of the web
form. The same if \fPmultiselect\fP can be called with the fields as its
commandline argument.

Strings can be added and removed at runtime. When the menu is shown by
middle-clicking or pressing \fIF1\fP (if enabled by \fI-k F1\fP), the keys for
adding the current selection are 'z' and \fIF2\fP, for deleting the string
under the cursor are Backspace and Delete, for deleting the last string are 's'
and \fIF3\fP, for deleting all strings are 'd' and \fIF4\fP. When the menu is
not shown, ctrl-shift-z adds the current selection to the list if enabled by
\fI-f\fP. The same does \fIF2\fP if enabled by \fI-k F2\fP.

.
.
.
.SH BATCH EXAMPLE

The following file is to be posted to a web form that has a text field for the
name, surname, address, city and state of residence.

.nf
John,Smith,2030 Blue Av.,Simonville,IL
Lucas,Ortega,99 Green St.,Springfield,OH
Robert,Pierre,1 Yellow Blvd.,Mongtown,NY
.fi

Instead of selecting and pasting each field of each person, a script can run
\fImultiselect\fP on the data of each person, like this:

.nf
\fI
    cat data.txt | \\
    while read A;
    do
        echo "$A" | tr ',' '\\n' | multiselect -
    done
\fP
.fi

The result is:

.nf
\fI
    selected strings:
       1: John
       2: Smith
       3: 2030 Blue Av.
       4: Simonville
       5: IL

    middle-click and press 1-5 to paste one
\fP
.fi

The data of the first person is ready: to paste the name, middle-click on the
text field for the name in the web form and press '1'. For the surname,
middle-click on the text field for the surname and press '2', and so on. When
the form is full and submitted, a further middle-click followed by key 'q'
terminates \fImultiselect\fP so that the script proceeds to the second line.

.
.
.
.SH INTERACTIVE EXAMPLE

The strings "John Smith", "2030 Blue Ave" and "Simonville IL" are scattered
around a text file, hard to be found by scripts.

Open the text file and start \fImultiselect\fP with argument \fI-d\fP or
\fI-kF2\fP.

Select "John Smith" in the text file and press ctrl-shift-z. Then, select "2030
Blue Ave" and press ctrl-shift-z. Finally, select "Simonville IL" and press
ctrl-shift-z. The \fIF2\fP key is alternative to ctrl-shift-z if enabled by
\fI-k F2\fP.

The strings are now ready to be pasted: middle-click on the text field for the
name and press '1', middle-click on the field for the address and press '2',
middle-click on the field for the city and press '3', as above.

.
.
.
.SH LABELS

Giving \fI-t' '\fP makes the first word of each string a label that is
displayed when middle-clicking but not pasted. An example is:

.nf
\fI
    multiselect -t' ' 'name: John' 'surname: Smith' 'address: Unknown'
\fP
.fi

The three strings are displayed in full when middle clicking:

.nf
\fI
    name: John
    surname: Smith
    address: Unknown
\fP
.fi

Pressing \fI1\fP only pastes \fIJohn\fP,
pressing \fI2\fP only pastes \fISmith\fP, etc.

Every single character can be used in place of the space except the null
character \fI\\0\fP. The strings are displayed in full, but only what follows
the first first occurrence of the character is pasted. If a string does not
contain the character at all is pasted in full, as if it had no label.

.
.
.
.SH CLICK MODE AND PASTE MODE

Some clients do not use a string if received after a certain time has been
passed since their initial request. The effect is that middle-click causes the
\fImultiselect\fP window to be appear, but the string chosen is ignored by the
client that requested it.

The default mechanism to prevent this behavior is to refuse any request for the
selection that originates from the client. When a string is chosen, the client
is sent a middle button click. This causes it to send a new request for the
selection, which is sent this time.

The previous mechanism was to send the selection as soon as the user chooses
it. The effect was that some clients ignored the string if the choice took more
than a certain time (e.g., half a second). On the other hand, the old behavior
works on clients that do not paste the selection on a middle button click. This
is why this mechanism is still available, passing \fI-p\fP. Yet, it does
usually not work when opening the menu selection list by \fIF1\fP.

\" how firefox is dealt with in the old mechanism:
\"
\" firefox discards pasted text if it arrives more than half a second later
\" than when requested (e.g., by middle click); this is the
\" \fIkClipboardTimeout\fP constant in the firefox source code, set to
\" \fI500000\fP microseconds; it cannot be changed by configuration options,
\" which means that the time for choosing the string to paste in
\" \fImultiselect\fP is only half a second; in order to facilitate dealing with
\" this drawback of firefox, \fImultiselect\fP detects a timeout in firefox and
\" pastes the chosen string on the following request; this means that if
\" middle-click + '1' does not work, a further middle-click may complete
\" pasting (without pressing '1' again)