doc: add callback pointer in doc of function bar_item_new (plugin API reference)

4 files changed, 49 insertions, 21 deletions

diff --git a/doc/en/weechat_plugin_api.en.asciidoc b/doc/en/weechat_plugin_api.en.asciidoc
index 2b4ef5155..568b122c7 100644
--- a/doc/en/weechat_plugin_api.en.asciidoc
+++ b/doc/en/weechat_plugin_api.en.asciidoc
@@ -12583,7 +12583,7 @@ bar_item = weechat.bar_item_search("myitem")
 
 ==== bar_item_new
 
-_Updated in 0.4.2._
+_Updated in 0.4.2, 1.5._
 
 Create a new bar item.
 
@@ -12592,11 +12592,13 @@ Prototype:
 [source,C]
 ----
 struct t_gui_bar_item *weechat_bar_item_new (const char *name,
-                                             char *(*build_callback)(void *data,
+                                             char *(*build_callback)(const void *pointer,
+                                                                     void *data,
                                                                      struct t_gui_bar_item *item,
                                                                      struct t_gui_window *window,
                                                                      struct t_gui_buffer *buffer,
                                                                      struct t_hashtable *extra_info),
+                                             const void *build_callback_pointer,
                                              void *build_callback_data);
 ----
 
@@ -12605,6 +12607,7 @@ Arguments:
 * 'name': bar item name
 * 'build_callback': function called when bar item is built, arguments and
   return value:
+** 'const void *pointer': pointer
 ** 'void *data': pointer
 ** 'struct t_gui_bar_item *item': item pointer
 ** 'struct t_gui_window *window': window pointer (NULL when called for a root
@@ -12615,8 +12618,11 @@ Arguments:
 ** 'struct t_hashtable *extra_info': always NULL (argument is reserved for a
    future version) _(WeeChat ≥ 0.4.2)_
 ** return value: content of bar item
-* 'build_callback_data': pointer given to build callback, when it is called by
-  WeeChat
+* 'build_callback_pointer': pointer given to build callback, when it is called
+  by WeeChat
+* 'build_callback_data': pointer given to callback when it is called by
+  WeeChat; if not NULL, it must have been allocated with malloc (or similar
+  function) and it is automatically freed when the bar item is removed
 
 Return value:
 
@@ -12627,7 +12633,7 @@ C example:
 [source,C]
 ----
 char *
-my_build_callback (void *data,
+my_build_callback (const void *pointer, void *data,
                    struct t_gui_bar_item *item,
                    struct t_gui_window *window,
                    struct t_gui_buffer *buffer,
@@ -12638,7 +12644,7 @@ my_build_callback (void *data,
 
 struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                        &my_build_callback,
-                                                       NULL);
+                                                       NULL, NULL);
 ----
 
 Script (Python):
diff --git a/doc/fr/weechat_plugin_api.fr.asciidoc b/doc/fr/weechat_plugin_api.fr.asciidoc
index 193de6d99..3a7cc0327 100644
--- a/doc/fr/weechat_plugin_api.fr.asciidoc
+++ b/doc/fr/weechat_plugin_api.fr.asciidoc
@@ -12845,7 +12845,7 @@ bar_item = weechat.bar_item_search("myitem")
 
 ==== bar_item_new
 
-_Mis à jour dans la 0.4.2._
+_Mis à jour dans la 0.4.2, 1.5._
 
 Créer un nouvel objet de barre.
 
@@ -12854,11 +12854,13 @@ Prototype :
 [source,C]
 ----
 struct t_gui_bar_item *weechat_bar_item_new (const char *name,
-                                             char *(*build_callback)(void *data,
+                                             char *(*build_callback)(const void *pointer,
+                                                                     void *data,
                                                                      struct t_gui_bar_item *item,
                                                                      struct t_gui_window *window,
                                                                      struct t_gui_buffer *buffer,
                                                                      struct t_hashtable *extra_info),
+                                             const void *build_callback_pointer,
                                              void *build_callback_data);
 ----
 
@@ -12867,6 +12869,7 @@ Paramètres :
 * 'name' : nom de l'objet de barre
 * 'build_callback' : fonction appelée lorsque l'objet est construit, paramètres
   et valeur de retour :
+** 'const void *pointer' : pointeur
 ** 'void *data' : pointeur
 ** 'struct t_gui_bar_item *item' : pointeur vers l'objet de barre
 ** 'struct t_gui_window *window' : pointeur vers la fenêtre (NULL lors d'un
@@ -12877,8 +12880,12 @@ Paramètres :
 ** 'struct t_hashtable *extra_info' : toujours NULL (le paramètre est réservé
    pour une version future) _(WeeChat ≥ 0.4.2)_
 ** valeur de retour : contenu de l'objet de barre
+* 'build_callback_pointer' : pointeur donné au "callback" lorsqu'il est appelé
+  par WeeChat
 * 'build_callback_data' : pointeur donné au "callback" lorsqu'il est appelé par
-  WeeChat
+  WeeChat; si non NULL, doit avoir été alloué par malloc (ou une fonction
+  similaire) et est automatiquement libéré (par free) lorsque l'objet de barre
+  est supprimé
 
 Valeur de retour :
 
@@ -12889,7 +12896,7 @@ Exemple en C :
 [source,C]
 ----
 char *
-my_build_callback (void *data,
+my_build_callback (const void *pointer, void *data,
                    struct t_gui_bar_item *item,
                    struct t_gui_window *window,
                    struct t_gui_buffer *buffer,
@@ -12900,7 +12907,7 @@ my_build_callback (void *data,
 
 struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                        &my_build_callback,
-                                                       NULL);
+                                                       NULL, NULL);
 ----
 
 Script (Python) :
diff --git a/doc/it/weechat_plugin_api.it.asciidoc b/doc/it/weechat_plugin_api.it.asciidoc
index 2b2a8e72b..10de35c4b 100644
--- a/doc/it/weechat_plugin_api.it.asciidoc
+++ b/doc/it/weechat_plugin_api.it.asciidoc
@@ -13024,7 +13024,7 @@ bar_item = weechat.bar_item_search("myitem")
 ==== bar_item_new
 
 // TRANSLATION MISSING
-_Updated in 0.4.2._
+_Updated in 0.4.2, 1.5._
 
 Crea un nuovo elemento barra.
 
@@ -13033,11 +13033,13 @@ Prototipo:
 [source,C]
 ----
 struct t_gui_bar_item *weechat_bar_item_new (const char *name,
-                                             char *(*build_callback)(void *data,
+                                             char *(*build_callback)(const void *pointer,
+                                                                     void *data,
                                                                      struct t_gui_bar_item *item,
                                                                      struct t_gui_window *window,
                                                                      struct t_gui_buffer *buffer,
                                                                      struct t_hashtable *extra_info),
+                                             const void *build_callback_pointer,
                                              void *build_callback_data);
 ----
 
@@ -13046,6 +13048,7 @@ Argomenti:
 * 'name': nome dell'elemento barra
 * 'build_callback': funzione chiamata quando l'elemento barra viene
   compilato, argomenti e valore restituito:
+** 'const void *pointer': puntatore
 ** 'void *data': puntatore
 ** 'struct t_gui_bar_item *item': puntatore all'elemento barra
 // TRANSLATION MISSING
@@ -13059,8 +13062,12 @@ Argomenti:
 ** 'struct t_hashtable *extra_info': always NULL (argument is reserved for a
    future version) _(WeeChat ≥ 0.4.2)_
 ** valore restituito: contenuto dell'elemento barra
-* 'build_callback_data': puntatore fornito alla callback quando
+* 'build_callback_pointer': puntatore fornito alla callback quando
   chiamata da WeeChat
+// TRANSLATION MISSING
+* 'build_callback_data': puntatore fornito dalla callback quando chiamata da
+  WeeChat; if not NULL, it must have been allocated with malloc (or similar
+  function) and it is automatically freed when the bar item is removed
 
 Valore restituito:
 
@@ -13071,7 +13078,7 @@ Esempio in C:
 [source,C]
 ----
 char *
-my_build_callback (void *data,
+my_build_callback (const void *pointer, void *data,
                    struct t_gui_bar_item *item,
                    struct t_gui_window *window,
                    struct t_gui_buffer *buffer,
@@ -13082,7 +13089,7 @@ my_build_callback (void *data,
 
 struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                        &my_build_callback,
-                                                       NULL);
+                                                       NULL, NULL);
 ----
 
 Script (Python):
diff --git a/doc/ja/weechat_plugin_api.ja.asciidoc b/doc/ja/weechat_plugin_api.ja.asciidoc
index bf36f9611..d104eb519 100644
--- a/doc/ja/weechat_plugin_api.ja.asciidoc
+++ b/doc/ja/weechat_plugin_api.ja.asciidoc
@@ -12608,7 +12608,8 @@ bar_item = weechat.bar_item_search("myitem")
 
 ==== bar_item_new
 
-_バージョン 0.4.2 で更新。_
+// TRANSLATION MISSING
+_Updated in 0.4.2, 1.5._
 
 新しいバー要素を作成。
 
@@ -12617,11 +12618,13 @@ _バージョン 0.4.2 で更新。_
 [source,C]
 ----
 struct t_gui_bar_item *weechat_bar_item_new (const char *name,
-                                             char *(*build_callback)(void *data,
+                                             char *(*build_callback)(const void *pointer,
+                                                                     void *data,
                                                                      struct t_gui_bar_item *item,
                                                                      struct t_gui_window *window,
                                                                      struct t_gui_buffer *buffer,
                                                                      struct t_hashtable *extra_info),
+                                             const void *build_callback_pointer,
                                              void *build_callback_data);
 ----
 
@@ -12630,6 +12633,7 @@ struct t_gui_bar_item *weechat_bar_item_new (const char *name,
 * 'name': バー要素の名前
 * 'build_callback':
   バー要素を作成する際に呼び出す関数、引数と戻り値:
+** 'const void *pointer': ポインタ
 ** 'void *data': ポインタ
 ** 'struct t_gui_bar_item *item': 要素へのポインタ
 ** 'struct t_gui_window *window':
@@ -12640,8 +12644,12 @@ struct t_gui_bar_item *weechat_bar_item_new (const char *name,
 ** 'struct t_hashtable *extra_info': 常に NULL
    (この引数は将来のバージョン用に予約されています) _(WeeChat バージョン 0.4.2 以上で利用可)_
 ** 戻り値: バー要素の内容
-* 'build_callback_data': WeeChat
+* 'build_callback_pointer': WeeChat
   が build コールバックを呼び出す際にコールバックに渡すポインタ
+// TRANSLATION MISSING
+* 'build_callback_data': WeeChat がコールバックを呼び出す際にコールバックに渡すポインタ;
+  if not NULL, it must have been allocated with malloc (or similar function)
+  and it is automatically freed when the bar item is removed
 
 戻り値:
 
@@ -12652,7 +12660,7 @@ C 言語での使用例:
 [source,C]
 ----
 char *
-my_build_callback (void *data,
+my_build_callback (const void *pointer, void *data,
                    struct t_gui_bar_item *item,
                    struct t_gui_window *window,
                    struct t_gui_buffer *buffer,
@@ -12663,7 +12671,7 @@ my_build_callback (void *data,
 
 struct t_gui_bar_item *my_item = weechat_bar_item_new ("myitem",
                                                        &my_build_callback,
-                                                       NULL);
+                                                       NULL, NULL);
 ----
 
 スクリプト (Python) での使用例: