"Chat text completions" -- chat plugin for Tkabber.

I. The idea

This plugin adds support for "text completion" in Tkabber's chat
input windows, i.e. it's possible to make Tkabber offer you
possible completions of a current partially typed word in a chat
input window. Possible completions are looked up in both the
input window and the chat log window (also it's possible to
provide custom list of matches, see the "Customization"
section).

This feature is loosely modeled after the text completion
implementations found in Vim [1] and Emacs [2] text editors;
default text completion key bindings of this plugin are the same
as default key bindings for this feature in those editors (see
the "Using" section).

Note though, that while both Vim and Emacs offer you possible
completions in a "recently typed -- first" manner, this
plugin offers them in a dictionary-sorted order.


II. Using

At first, note that we'll use "Emacsish" notation of describing
keystrokes for the sake of brevity. For those who isn't familiar
with it here's a quick explanation:
* "C" stands for "Control" key (also known as "Ctrl").
* "M" stands for "Meta" key (also known as "Alt" on some
  computers/OSes).
* Any other key symbols stand for themselves.
* Key combinations (groups of keys that are required to be
  pressed simultaneously) are specified as a list of appropriate
  key symbols joined by dashes ("-"). For example, "C-M-a"
  stands for Control, Meta (Alt) and "a" keys pressed
  simultaneously.

There are two major modes of operation possible:
* Requesting menu with possible completions.
* Traversing the list of possible completions "in place".

Entering each mode is requested by pressing one of the available
keystrokes (discussed below) just after the first character(s)
of a word you want to complete.
For example, suppose the current chat log window and/or the
current input window contain these words: abba, abbot,
abbatisse. Now suppose you have just typed "ab" and want to
complete it -- type C-M-/ to get the menu listing top 20 words
starting from "ab" found in mentioned windows or type C-n to
enter the "in place" mode and get the first proposed completion
right at your insert cursor (with the completed part visually
emphasized). Any completion mode can be cancelled -- you return
to that piece of the word you started with.
The completion keybindings will be described just in a moment.

So, let's recap:
* Type some first letters of the word you want to complete,
* Engage one of the available completion modes.
* Pick the required completion or chancel the completion mode.

1. Using the completion menu

The menu presenting the first 20 completions can be by default
posted using C-M-/ gesture. Select whatever completion you're
happy with or cancel the menu by clicking outside of it or
pressing the <Escape> key. If you have selected a completion,
the word being completed in the input window will be replaced by
the selected completion. If you have cancelled the completion
menu no change will be made to the input window.

This gesture is modeled after the Emacs text editor.

2. Using the "in place" traversing of possible completions

This mode is modeled after the similar Vim text editor's
facility and so the C-n and C-p keystrokes are used. They switch
the input windows into the "completion mode" and insert the
first or the last completion from the list of proposed
completions at the insert cursor. The completed part of the
inserted word is highlighted.

Also the M-/ keystroke is equivalent to C-n -- this one is taken
from Emacs.

While being in the completion mode you can:
* Continue using the C-n (and/or M-/) and C-p keystrokes to
  iterate through the list of proposed completions "up" and
  "down", respectively.
* Hit the Return (Enter) key to accept the currently displayed
  completion and return to the normal editing mode.
* Hit the Escape key to remove the currently displayed
  completion and return to the normal mode. In other words this
  cancels the completon mode.

Hitting any other key not listed above (i.e. a key which doesn't
have special meaning in the completion mode) accepts the
currently displayed completion, returns the input window to the
normal mode, and then this keystroke is passed to the input
window so that if it would result in a printable character being
inserted this character will be inserted just after the
completed word.


III. Customization

1. Keystrokes

All the relevant bindings in Tkabber's chat input windows are
done via Tk virtual events [3] so they are easily customizable.
Here are these events and their default bindings:

* Event: <<ChatTextCompNext>>
  Default bindings: <Control-n>, <Alt-slash>, <Meta-slash>
  Action: show next possible completion "in place",
  activate the "in place" completion mode beforehang,
  if currently in the normal mode.

* Event: <<ChatTextCompPrev>>
  Default bindings: <Control-p>
  Action: same as above but shows the previous possible
  completion.

* Event: <<ChatTextCompAccept>>
  Default keybindings: <Return>
  Action: accept the completion currently proposed "in place"
  and return to normal mode.

* Event: <<ChatTextCompCancel>>
  Default keybindings: <Escape>
  Action: remove the completion currently proposed "in place"
  and return to normal mode.

* Event: <<ChatTextCompMenu>>
  Default keybindings: <Alt-Control-slash>, <Meta-Control-slash>
  Action: show menu with possible completions.


If you're not familiar with Tk [event] [3] and [bind] [4]
commands, here's a quick reference:

* To bind your keystroke to a virtual event use
  event add <<...event name...>> <...keystroke spec...>
  For example, to bind posting of the completion menu to the F5
  key, put this in the Tkabber's config file:
  event add <<ChatTextCompMenu>> <F5>

* To unbind existing binding from a virtual event use
  event delete <<...event name...>> <...keystroke spec...>
  For example to make the completion menu only be posted by the
  F5 key, add also this lines to the config file:
  event delete <<ChatTextCompMenu>> <Alt-Control-slash>
  event delete <<ChatTextCompMenu>> <Meta-Control-slash>

* To "substitute" (all) the default bindings for a virtual event
  by yours you can use something like this:
  event delete <<ChatTextCompMenu>>
  event add <<ChatTextCompMenu>> <F5>
  The first line kills all bindings for the virtual event, the
  second adds one new.

Be sure to read and understand [3] and [4] before proceeding!

Specification of keystrokes is explained in [4], all keysyms
known to Tk are listed in [5].

Note that due to a bug in the Windows port of Tk users of non-US
keymaps in this OS can have problems with these shortcuts.
Please read "Working around Tk Windows keyboard bug" below for
the (partial) solution to this problem.


2. Highlighting colors of "in place" completion

Two Tk option database resources are used, both are of class
"Chat":

* Resource: Chat.textCompletionForeground
  Default: black
  Meaning: foreground color of the "proposed" tail of the word
  being completed "in place".

* Resourec: Chat.textCompletionBackground
  Default: pink
  Meaning: same as above but for the background color.


3. Search pattern

The search pattern used to search for possible completions in Tk
Text widgets is available via the
::plugins::ctcomp::options(pattern) setting.

This is an ARE [6] pattern containing the "%s" token which is
replaced before searching by the part of the word being
completed. This pattern makes the searching engine to look for
"any word starting with the specified letters".

Note that you should think twice before changing this pattern:
for example the "in place" completion mode assumes that
completions start from the prefix being completed and if you,
say, change the pattern so that it will match in a middle of
words, you'll get unexpected results in this completion mode.


4. Hooks

This plugin has four "hooks" [7] that run when certain chat text
completion events occur. They can be used to fine-tune the
operation of this plugin. Beware though that using them requires
some knowledge of Tcl.

These hooks are:

* chat_text_completion_start_hook
  This hook is run when the plugin enters the "in place"
  completion mode and is about to show the first proposed
  completion.
  Two arguments are appended to the hook script before
  evaluation:
  * handle to the chat in which the completion
    mode is entered (usually referred to as "chatid").
  * word being completed.

  Primary intent of this hook (and its "mirror" hook
  chat_text_completion_end_hook) is to be used to provide some
  sort of additional visual hint to the user indicating active
  "in place" completion mode.

* chat_text_completion_end_hook
  This hook is run when the plugin leaves the "in place"
  completion mode.
  One argument is appended to the hook script before
  evaluation -- handle to the chat ("chatid").

* chat_text_completion_matches_hook
  This hook is run when the plugin builds a list of possible
  completions for the word being completed, just after the
  proposed completions have been gathered from the relevant
  input and chat log windows.
  Four arguments are appended to the hook script before
  evaluation:
  * handle to the chat in which the completion
    mode is entered ("chatid").
  * word being completed.
  * stack level containing the variable with proposed
    completions.
  * name of the variable holding a list with proposed
    completions.
  To modify this variable inside a proc use the [upvar] command,
  for example:

  proc gencomp {chatid what level compsName} {
    upvar $level $compsName comps
    lappend comps ${what}not ${what}sup
  }
  hook::add chat_text_completion_matches_hook gencomp

  Note that scripts handling this hook must not do any
  assumptions about the list of proposed completions they
  operate on (like sorted/unsorted, uniquennes of the words,
  etc).

  Also note that while any strings can be added to the list of
  possible completions using this hook, the "in place"
  completion mode assumes that each proposed completion starts
  from the word being completed; when this assumption is not
  honored, strange things may happen.

* chat_text_completion_menu_hook
  This hook is run just before the menu with proposed
  completions is shown to the user.
  Three arguments are appended to the hook script before
  evaluation:
  * handle to the chat in which the completion
    mode is entered ("chatid").
  * word being completed.
  * name of the menu window populated with proposed completions.

  This hook can be used to tweak the menu before it will be
  popped up.


IV. Limitations and bugs

Default keybindings <C-n> and <C-p> used by this plugin
effectively "hijack" the same keybindings built into the chat
input windows (they are used for moving forth and back through
the history of outgoing messages). The <C-up> and <C-down>
keybindings can be used for the input history management but if
you want to continue using <C-n> and <C-p> for this while using
this plugin, you should unbind <C-n> and <C-p> from the ctcomp
plugin (and possibly bind the relevant actions to some other
combinations of keys), like this:
# Take <C-n> and <C-p> away from ctcomp:
event delete <<ChatTextCompNext>> <Control-n>
event delete <<ChatTextCompPrev>> <Control-p>
# Use <M-n> and <M-p> to do the same actions:
event add <<ChatTextCompNext>> <Alt-n>
event add <<ChatTextCompPrev>> <Alt-p>

No "automatic" completion ("propose completions as I type" found
in certain text editing tools like Writer from the OpenOffice.org
suite or some mobile phones) is possible.

The same holds for the "in place" completion mode: typing a
regular keystroke terminates the completion mode, not narrows
the list of possible completions (this is Vim-like).

No guarantees of proper work are made if the user fiddles with
the searching regexp pattern. The same is true for the case when
the user modifies the list of proposed completion via the
relevant hook.

Not all completions will be shown in the completion menu if its
number exceeds the hard-coded limit.


V. Working around Tk Windows keyboard bug

Tk has unfortunate long-standing bug which prevents certain
key combinations involving "letter keys" from working with
"non-ASCII" keymaps (e.g. Russian keymap) in Windows.
For example, C-n, C-p, M-/ and C-M-/ work when the US keymap
is active but don't work when a Russian keymap is.

Users of Russian keymaps may add following lines to their
config.tcl file to work around this bug:

event add <<ChatTextCompNext>> <Control-ograve>
event add <<ChatTextCompNext>> <Alt-period>
event add <<ChatTextCompPrev>> <Control-ccedilla>
event add <<ChatTextCompMenu>> <Control-Alt-period>

This will make C-n, C-p and C-M-/ to work as expected on both US
and Russian ("QWERTY") keymaps.

Note that if you change the default bindings you may also need
to modify these "mirror" bindings. Please refer to the Russian
Tkabber wiki [8] for more info.


VI. Links

1. http://vim.sf.net
2. http://www.gnu.org/software/emacs/
3. http://www.tcl.tk/man/tcl8.4/TkCmd/event.htm
4. http://www.tcl.tk/man/tcl8.4/TkCmd/bind.htm
5. http://www.tcl.tk/man/tcl8.4/TkCmd/keysyms.htm
6. http://www.tcl.tk/man/tcl8.4/TclCmd/re_syntax.htm
7. http://tkabber.jabber.ru/files/doc/tkabber.html#s.extensibility
8. http://ru.tkabber.jabe.ru


# vim:tw=64:et