core: add info about position where mouse button is released in hook_focus (for mouse gestures)

11 files changed, 182 insertions, 74 deletions

diff --git a/doc/de/autogen/plugin_api/infolists.txt b/doc/de/autogen/plugin_api/infolists.txt
index 361991ade..18e7b7965 100644
--- a/doc/de/autogen/plugin_api/infolists.txt
+++ b/doc/de/autogen/plugin_api/infolists.txt
@@ -48,7 +48,7 @@
 
 | weechat | hotlist | Liste der Buffer in Hotlist | - | -
 
-| weechat | key | Auflistung der Tastenzuweisungen | - | Kontext ("default" oder "search") (optional)
+| weechat | key | Auflistung der Tastenzuweisungen | - | context ("default", "search", "cursor" or "mouse") (optional)
 
 | weechat | nicklist | Nicks in Nickliste für einen Buffer | Buffer Pointer | nick_xxx oder group_xxx um nur den Nick/Group xxx abzufragen (optional)
 
diff --git a/doc/de/autogen/user/weechat_commands.txt b/doc/de/autogen/user/weechat_commands.txt
index 7bc8f8413..5d459af5e 100644
--- a/doc/de/autogen/user/weechat_commands.txt
+++ b/doc/de/autogen/user/weechat_commands.txt
@@ -350,6 +350,7 @@ For context "mouse" (possible in context "cursor" too), key has format: "@area:k
    bar(xxx): bar "xxx"
     item(*): any bar item
   item(xxx): bar item "xxx"
+The key can start or end with '*' to match many mouse events.
 
 Examples:
   key alt-x to toggle nicklist bar:
diff --git a/doc/en/autogen/plugin_api/infolists.txt b/doc/en/autogen/plugin_api/infolists.txt
index 237da84da..90f17b1dc 100644
--- a/doc/en/autogen/plugin_api/infolists.txt
+++ b/doc/en/autogen/plugin_api/infolists.txt
@@ -48,7 +48,7 @@
 
 | weechat | hotlist | list of buffers in hotlist | - | -
 
-| weechat | key | list of key bindings | - | context ("default" or "search") (optional)
+| weechat | key | list of key bindings | - | context ("default", "search", "cursor" or "mouse") (optional)
 
 | weechat | nicklist | nicks in nicklist for a buffer | buffer pointer | nick_xxx or group_xxx to get only nick/group xxx (optional)
 
diff --git a/doc/en/autogen/user/weechat_commands.txt b/doc/en/autogen/user/weechat_commands.txt
index 29fd1b6cf..cbba23932 100644
--- a/doc/en/autogen/user/weechat_commands.txt
+++ b/doc/en/autogen/user/weechat_commands.txt
@@ -350,6 +350,7 @@ For context "mouse" (possible in context "cursor" too), key has format: "@area:k
    bar(xxx): bar "xxx"
     item(*): any bar item
   item(xxx): bar item "xxx"
+The key can start or end with '*' to match many mouse events.
 
 Examples:
   key alt-x to toggle nicklist bar:
diff --git a/doc/en/weechat_plugin_api.en.txt b/doc/en/weechat_plugin_api.en.txt
index de7470bf1..159df6a8b 100644
--- a/doc/en/weechat_plugin_api.en.txt
+++ b/doc/en/weechat_plugin_api.en.txt
@@ -3267,9 +3267,12 @@ Arguments:
 *** 'buffer': buffer
 *** 'time': time
 ** 'keys': string with list of keys (format: "key1,key2,key3")
+** 'keys_sorted': string with list of sorted keys (format: "key1,key2,key3")
 ** 'values': string with list of values (format: "value1,value2,value3")
 ** 'keys_values': string with list of keys and values
    (format: "key1:value1,key2:value2,key3:value3")
+** 'keys_values_sorted': string with list of keys and values (sorted by keys)
+   (format: "key1:value1,key2:value2,key3:value3")
 
 Return value:
 
@@ -8253,34 +8256,65 @@ Arguments:
   value:
 ** 'void *data': pointer
 ** 'struct t_hashtable *info': hashtable with info on focus and strings returned
-   by other calls to focus callbacks (with higher priority); keys and values
-   are of type "string"; info on focus (filled by WeeChat) are:
-*** '_x': column of focus on screen (first column on the left is "0")
-*** '_y': line of focus on screen (first line on top is "0")
-*** '_window': pointer of window with focus ("0x0" for a bar of type "root"
-    or for unknown area)
-*** '_window_number': number of window with focus (not set for a bar of type
-    "root" or for unknown area)
-*** '_buffer': pointer of buffer with focus ("0x0" for a bar of type "root"
-    or for unknown area)
-*** '_buffer_number': number of buffer with focus (not set for a bar of type
-    "root" or for unknown area)
-*** '_buffer_plugin': plugin name of buffer with focus (not set for a bar of
-    type "root" or for unknown area)
-*** '_buffer_name': name of buffer with focus (not set for a bar of type "root"
-    or for unknown area)
-*** '_bar_name': name of bar with focus (NULL for chat area or for unknown
-    area)
-*** '_bar_item_name': name of bar item with focus (NULL if focus is not in a
-    bar or if focus is after the end of last bar item)
-*** '_item_line': line with focus in bar item (first line of bar item is "0")
-*** '_item_col': column with focus in bar item (first column of bar item is "0")
+   by other calls to focus callbacks (with higher priority) (see table below)
 ** return value: either "info" pointer (hashtable completed), or pointer to a
    new hashtable (created by callback, with keys and values of type "string"),
    this new hashtable content will be added to 'info' for other calls to focus
    callbacks
 * 'callback_data': pointer given to callback when it is called by WeeChat
 
+[IMPORTANT]
+For a mouse gesture, your callback will be called two times: first time when
+button is pressed (here the area always matches your area), second time when
+button is released, and then the area may not match your area: so you must
+*always* test in your callback if area is matching before using info in
+hashtable.
+
+Content of hashtable sent to callback (keys and values are of type "string"):
+
+[width="100%",cols="4m,6,8,8",options="header"]
+|========================================
+| Key ^(1)^      | Description             | Value                                  | Value if N/A
+| _x             | column on screen      2+| "0" ... "n"
+| _y             | line on screen        2+| "0" ... "n"
+| _window        | pointer of window       | "0x12345678"                           | "0x0"
+| _window_number | number of window        | "1" ... "n"                            | "*"
+| _chat          | chat area indicator     | "0" or "1"                             | "0"
+| _buffer        | pointer of buffer       | "0x12345678"                           | "0x0"
+| _buffer_number | number of buffer        | "1" ... "n"                            | ""
+| _buffer_plugin | plugin name of buffer   | "core", "irc", ...                     | ""
+| _buffer_name   | name of buffer          | "weechat", "freenode.#weechat", ...    | ""
+| _bar_name      | name of bar             | "title", "nicklist", ...               | ""
+| _bar_filling   | filling of bar          | "horizontal", "vertical", ...          | ""
+| _bar_item_name | name of bar item        | "buffer_nicklist", ...                 | ""
+| _item_line     | line in bar item        | "0" ... "n"                            | "-1"
+| _item_col      | column in bar item      | "0" ... "n"                            | "-1"
+| _key           | key or mouse event    2+| "button1", "button2-gesture-left", ...
+|========================================
+
+[NOTE]
+^(1)^ There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", ...)
+with info on second point (useful only for mouse gestures, to know where mouse
+button has been released).
+
+Extra info for bar item "buffer_nicklist":
+
+[width="70%",cols="3m,3,8",options="header"]
+|========================================
+| Key            | Plugin ^(1)^ | Description
+| nick           | core         | nick name
+| prefix         | core         | prefix for nick
+| group          | core         | group name
+| host           | irc          | host for nick (if known)
+| server         | irc          | internal name of server
+| channel        | irc          | channel name
+|========================================
+
+[NOTE]
+^(1)^ The name of plugin which defines a hook_focus to return info for this bar
+item (so for example if plugin is "irc", such info will be available only on
+irc buffers).
+
 Return value:
 
 * pointer to new hook, NULL if error occured
diff --git a/doc/fr/autogen/plugin_api/infolists.txt b/doc/fr/autogen/plugin_api/infolists.txt
index 0244c2c61..f65d8c737 100644
--- a/doc/fr/autogen/plugin_api/infolists.txt
+++ b/doc/fr/autogen/plugin_api/infolists.txt
@@ -48,7 +48,7 @@
 
 | weechat | hotlist | liste des tampons dans la hotlist | - | -
 
-| weechat | key | liste des associations de touches | - | contexte ("default" ou "search") (optionnel)
+| weechat | key | liste des associations de touches | - | contexte ("default", "search", "cursor" ou "mouse") (optionnel)
 
 | weechat | nicklist | pseudos dans la liste des pseudos pour un tampon | pointeur vers le tampon | nick_xxx ou group_xxx pour avoir seulement le pseudo/groupe xxx (optionnel)
 
diff --git a/doc/fr/autogen/user/weechat_commands.txt b/doc/fr/autogen/user/weechat_commands.txt
index b7fc0869e..ed6ff1fbb 100644
--- a/doc/fr/autogen/user/weechat_commands.txt
+++ b/doc/fr/autogen/user/weechat_commands.txt
@@ -350,6 +350,7 @@ Pour le contexte "mouse" (possible aussi pour le contexte "cursor"), la touche a
    bar(xxx): la barre "xxx"
     item(*): n'importe quel objet de barre
   item(xxx): l'objet de barre "xxx"
+La touche peut commencer ou se terminer par '*' pour plusieurs évènements de la souris.
 
 Exemples:
   touche alt-x pour activer/désactiver la liste des pseudos:
diff --git a/doc/fr/weechat_plugin_api.fr.txt b/doc/fr/weechat_plugin_api.fr.txt
index 2454498c3..6605a2ff4 100644
--- a/doc/fr/weechat_plugin_api.fr.txt
+++ b/doc/fr/weechat_plugin_api.fr.txt
@@ -3299,9 +3299,13 @@ Paramètres :
 *** 'buffer' : buffer
 *** 'time' : heure
 ** 'keys' : chaîne avec la liste des clés (format : "clé1,clé2,clé3")
+** 'keys_sorted' : chaîne avec la liste triée des clés (format :
+   "clé1,clé2,clé3")
 ** 'values' : chaîne avec la liste des valeurs (format : "valeur1,valeur2,valeur3")
 ** 'keys_values' : chaîne avec la liste des clés et valeurs
    (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")
+** 'keys_values_sorted' : chaîne avec la liste des clés et valeurs (triée sur
+   les clés) (format : "clé1:valeur1,clé2:valeur2,clé3:valeur3")
 
 Valeur en retour :
 
@@ -8381,36 +8385,12 @@ Paramètres :
 
 * 'area' : "chat" pour la zone de discussion, ou un nom d'objet de barre
   (priorité autorisée, voir la note sur la <<hook_priority,priorité>>)
-* 'callback' : fonction appelée quand le focus est fait paramètres et valeur de
+* 'callback' : fonction appelée quand le focus est fait, paramètres et valeur de
   retour :
 ** 'void *data' : pointeur
 ** 'struct t_hashtable *info' : hashtable avec les informations sur le focus et
    les chaînes retournées par les autres appels aux "callbacks" de focus (avec
-   plus haute priorité); les clés et valeurs sont de type "string"; les
-   informations sur le focus (remplies par WeeChat) sont :
-*** '_x' : colonne du focus sur l'écran (la première colonne sur la gauche
-    est "0")
-*** '_y' : ligne du focus sur l'écran (la première ligne en haut est "0")
-*** '_window' : pointeur de la fenêtre avec le focus ("0x0" pour une barre de
-    type "root" ou pour une zone inconnue)
-*** '_window_number' : numéro de la fenêtre avec le focus (non défini pour une
-    barre de type "root" ou pour une zone inconnue)
-*** '_buffer' : pointeur du tampon avec le focus ("0x0" pour une barre de type
-    "root" ou pour une zone inconnue)
-*** '_buffer_number' : numéro du tampon avec le focus (non défini pour une barre
-    de type "root" ou pour une zone inconnue)
-*** '_buffer_plugin' : nom d'extension du tampon avec le focus (non défini pour
-    une barre de type "root" ou pour une zone inconnue)
-*** '_buffer_name' : nom du tampon avec le focus (non défini pour une barre de
-    type "root" ou pour une zone inconnue)
-*** '_bar_name' : nom de la barre avec le focus (NULL pour la zone de discussion
-    ("chat") ou pour une zone inconnue)
-*** '_bar_item_name' : nom de l'objet de barre avec le focus (NULL si le focus
-    n'est pas dans une barre ou si le focus est après le dernier objet de barre)
-*** '_item_line' : ligne avec le focus dans l'objet de barre (la première ligne
-    de l'objet de barre est "0")
-*** '_item_col' : colonne avec le focus dans l'objet de barre (la première
-    colonne de l'objet de barre est "0")
+   plus haute priorité) (voir le tableau ci-dessous)
 ** valeur de retour : soit le pointeur vers la hashtable "info" (avec la
    hashtable complétée), ou un pointeur vers une nouvelle hashtable (créée par
    le "callback", avec clés et valeurs de type "string"), le contenu de cette
@@ -8419,6 +8399,60 @@ Paramètres :
 * 'callback_data' : pointeur donné au "callback" lorsqu'il est appelé par
    WeeChat
 
+[IMPORTANT]
+Pour un geste de souris, votre "callback" sera appelé deux fois : la première
+lorsque le bouton est pressé (ici la zone correspond à vôtre zone), la seconde
+fois lorsque le bouton est relâché, et la zone peut ne pas correspondre à la
+vôtre : donc vous devez *toujours* tester dans le "callback" si la zone
+correspond avant d'utiliser les informations de la hashtable.
+
+Contenu de la hashtable envoyée au "callback" (les clés et valeurs sont de type
+"string) :
+
+[width="100%",cols="4m,6,8,8",options="header"]
+|========================================
+| Clé ^(1)^      | Description                     | Valeur                                 | Valeur si non applicable
+| _x             | colonne sur l'écran           2+| "0" ... "n"
+| _y             | ligne sur l'écran             2+| "0" ... "n"
+| _window        | pointeur de la fenêtre          | "0x12345678"                           | "0x0"
+| _window_number | numéro de la fenêtre            | "1" ... "n"                            | "*"
+| _chat          | indicateur zone "chat"          | "0" ou "1"                             | "0"
+| _buffer        | pointeur du tampon              | "0x12345678"                           | "0x0"
+| _buffer_number | numéro du tampon                | "1" ... "n"                            | ""
+| _buffer_plugin | nom d'extension du tampon       | "core", "irc", ...                     | ""
+| _buffer_name   | nom du tampon                   | "weechat", "freenode.#weechat", ...    | ""
+| _bar_name      | nom de la barre                 | "title", "nicklist", ...               | ""
+| _bar_filling   | remplissage de la barre         | "horizontal", "vertical", ...          | ""
+| _bar_item_name | nom de l'objet de barre         | "buffer_nicklist", ...                 | ""
+| _item_line     | ligne dans l'objet de barre     | "0" ... "n"                            | "-1"
+| _item_col      | colonne dans l'objet de barre   | "0" ... "n"                            | "-1"
+| _key           | touche ou évènement souris    2+| "button1", "button2-gesture-left", ...
+|========================================
+
+[NOTE]
+^(1)^ Il y a les mêmes clés suffixées par "2" (c'est-à-dire : "_x2", "_y2",
+"_window2", ...) avec l'information sur le second point (pratique seulement
+pour les gestes de souris, pour savoir où le bouton de la souris a été
+relâché).
+
+Informations additionnelles pour l'objet de barre "buffer_nicklist":
+
+[width="70%",cols="3m,3,8",options="header"]
+|========================================
+| Clé            | Extension ^(1)^ | Description
+| nick           | core            | pseudonyme
+| prefix         | core            | préfixe du pseudonyme
+| group          | core            | nom du groupe
+| host           | irc             | nom d'hôte pour le pseudonyme (si connu)
+| server         | irc             | nom interne du serveur
+| channel        | irc             | nom du canal
+|========================================
+
+[NOTE]
+^(1)^ Le nom de l'extension qui définit un hook_focus pour retourner des infos
+pour cet objet de barre (donc par exemple si l'extension est "irc", ces infos
+ne seront disponibles que sur les tampons irc).
+
 Valeur de retour :
 
 * pointeur vers le nouveau "hook", NULL en cas d'erreur
diff --git a/doc/it/autogen/plugin_api/infolists.txt b/doc/it/autogen/plugin_api/infolists.txt
index 756b288a8..cff831ebb 100644
--- a/doc/it/autogen/plugin_api/infolists.txt
+++ b/doc/it/autogen/plugin_api/infolists.txt
@@ -48,7 +48,7 @@
 
 | weechat | hotlist | elenco dei buffer nella hotlist | - | -
 
-| weechat | key | elenco di tasti associati | - | contesto ("default" oppure "search") (opzionale)
+| weechat | key | elenco di tasti associati | - | context ("default", "search", "cursor" or "mouse") (optional)
 
 | weechat | nicklist | nick nella lista nick per un buffer | puntatore al buffer | nick_xxx o group_xxx per ottenere solo xxx di nick/group (opzionale)
 
diff --git a/doc/it/autogen/user/weechat_commands.txt b/doc/it/autogen/user/weechat_commands.txt
index 579ce833a..ae71503c5 100644
--- a/doc/it/autogen/user/weechat_commands.txt
+++ b/doc/it/autogen/user/weechat_commands.txt
@@ -350,6 +350,7 @@ For context "mouse" (possible in context "cursor" too), key has format: "@area:k
    bar(xxx): bar "xxx"
     item(*): any bar item
   item(xxx): bar item "xxx"
+The key can start or end with '*' to match many mouse events.
 
 Examples:
   key alt-x to toggle nicklist bar:
diff --git a/doc/it/weechat_plugin_api.it.txt b/doc/it/weechat_plugin_api.it.txt
index ff4cb3f04..aff4db708 100644
--- a/doc/it/weechat_plugin_api.it.txt
+++ b/doc/it/weechat_plugin_api.it.txt
@@ -3257,9 +3257,14 @@ Argomenti:
 *** 'buffer': buffer
 *** 'time': tempo
 ** 'keys': stringa con la lista di chiavi (formato: "chiave1,chiave2,chiave3")
+// TRANSLATION MISSING
+** 'keys_sorted': string with list of sorted keys (format: "chiave1,chiave2,chiave3")
 ** 'values': stringa  con la lista di valori (formato: "valore1,valore2,valore3")
 ** 'keys_values': stringa con la lista di valori e chiavi
    (formato: "chiave1:valore1,chiave2:valore2,chiave3:valore3")
+// TRANSLATION MISSING
+** 'keys_values_sorted': string with list of keys and values (sorted by keys)
+   (format: "chiave1:valore1,chiave2:valore2,chiave3:valore3")
 
 Valore restituito:
 
@@ -8308,34 +8313,65 @@ Argomenti:
   value:
 ** 'void *data': pointer
 ** 'struct t_hashtable *info': hashtable with info on focus and strings returned
-   by other calls to focus callbacks (with higher priority); keys and values
-   are of type "string"; info on focus (filled by WeeChat) are:
-*** '_x': column of focus on screen (first column on the left is "0")
-*** '_y': line of focus on screen (first line on top is "0")
-*** '_window': pointer of window with focus ("0x0" for a bar of type "root"
-    or for unknown area)
-*** '_window_number': number of window with focus (not set for a bar of type
-    "root" or for unknown area)
-*** '_buffer': pointer of buffer with focus ("0x0" for a bar of type "root"
-    or for unknown area)
-*** '_buffer_number': number of buffer with focus (not set for a bar of type
-    "root" or for unknown area)
-*** '_buffer_plugin': plugin name of buffer with focus (not set for a bar of
-    type "root" or for unknown area)
-*** '_buffer_name': name of buffer with focus (not set for a bar of type "root"
-    or for unknown area)
-*** '_bar_name': name of bar with focus (NULL for chat area or for unknown
-    area)
-*** '_bar_item_name': name of bar item with focus (NULL if focus is not in a
-    bar or if focus is after the end of last bar item)
-*** '_item_line': line with focus in bar item (first line of bar item is "0")
-*** '_item_col': column with focus in bar item (first column of bar item is "0")
+   by other calls to focus callbacks (with higher priority) (see table below)
 ** return value: either "info" pointer (hashtable completed), or pointer to a
    new hashtable (created by callback, with keys and values of type "string"),
    this new hashtable content will be added to 'info' for other calls to focus
    callbacks
 * 'callback_data': pointer given to callback when it is called by WeeChat
 
+[IMPORTANT]
+For a mouse gesture, your callback will be called two times: first time when
+button is pressed (here the area always matches your area), second time when
+button is released, and then the area may not match your area: so you must
+*always* test in your callback if area is matching before using info in
+hashtable.
+
+Content of hashtable sent to callback (keys and values are of type "string"):
+
+[width="100%",cols="4m,6,8,8",options="header"]
+|========================================
+| Key ^(1)^      | Description             | Value                                  | Value if N/A
+| _x             | column on screen      2+| "0" ... "n"
+| _y             | line on screen        2+| "0" ... "n"
+| _window        | pointer of window       | "0x12345678"                           | "0x0"
+| _window_number | number of window        | "1" ... "n"                            | "*"
+| _chat          | chat area indicator     | "0" or "1"                             | "0"
+| _buffer        | pointer of buffer       | "0x12345678"                           | "0x0"
+| _buffer_number | number of buffer        | "1" ... "n"                            | ""
+| _buffer_plugin | plugin name of buffer   | "core", "irc", ...                     | ""
+| _buffer_name   | name of buffer          | "weechat", "freenode.#weechat", ...    | ""
+| _bar_name      | name of bar             | "title", "nicklist", ...               | ""
+| _bar_filling   | filling of bar          | "horizontal", "vertical", ...          | ""
+| _bar_item_name | name of bar item        | "buffer_nicklist", ...                 | ""
+| _item_line     | line in bar item        | "0" ... "n"                            | "-1"
+| _item_col      | column in bar item      | "0" ... "n"                            | "-1"
+| _key           | key or mouse event    2+| "button1", "button2-gesture-left", ...
+|========================================
+
+[NOTE]
+^(1)^ There are same keys suffixed with "2" (ie: "_x2", "_y2", "_window2", ...)
+with info on second point (useful only for mouse gestures, to know where mouse
+button has been released).
+
+Extra info for bar item "buffer_nicklist":
+
+[width="70%",cols="3m,3,8",options="header"]
+|========================================
+| Key            | Plugin | Description
+| nick           | core   | nick name
+| prefix         | core   | prefix for nick
+| group          | core   | group name
+| host           | irc    | host for nick (if known)
+| server         | irc    | internal name of server
+| channel        | irc    | channel name
+|========================================
+
+[NOTE]
+^(1)^ The name of plugin which defines a hook_focus to return info for this bar
+item (so for example if plugin is "irc", such info will be available only on
+irc buffers).
+
 Valore restituito:
 
 * pointer to new hook, NULL if error occured