[Tkabber-dev] r2028 - in trunk/tkabber: . doc

tkabber-svn at jabber.ru tkabber-svn at jabber.ru
Thu Dec 26 21:07:19 MSK 2013


Author: sergei
Date: 2013-12-26 21:07:18 +0400 (Thu, 26 Dec 2013)
New Revision: 2028

Modified:
   trunk/tkabber/ChangeLog
   trunk/tkabber/README
   trunk/tkabber/doc/tkabber.html
   trunk/tkabber/doc/tkabber.xml
Log:
	* README, doc/tkabber.html, doc/tkabber.xml: Added a few hooks
	  description.


Modified: trunk/tkabber/ChangeLog
===================================================================
--- trunk/tkabber/ChangeLog	2013-12-25 10:46:59 UTC (rev 2027)
+++ trunk/tkabber/ChangeLog	2013-12-26 17:07:18 UTC (rev 2028)
@@ -1,3 +1,8 @@
+2013-12-26  Sergei Golovan  <sgolovan at nes.ru>
+
+	* README, doc/tkabber.html, doc/tkabber.xml: Added a few hooks
+	  description.
+
 2013-12-25  Sergei Golovan  <sgolovan at nes.ru>
 
 	* plugins/iq/version.tcl: Recognize Windows 8.1 (as Windows NT 6.3).

Modified: trunk/tkabber/README
===================================================================
--- trunk/tkabber/README	2013-12-25 10:46:59 UTC (rev 2027)
+++ trunk/tkabber/README	2013-12-26 17:07:18 UTC (rev 2028)
@@ -126,28 +126,30 @@
        7.3.7.  Miscellany . . . . . . . . . . . . . . . . . . . . . . 41
      7.4.  Final-Load . . . . . . . . . . . . . . . . . . . . . . . . 41
    8.  Extensibility  . . . . . . . . . . . . . . . . . . . . . . . . 42
-     8.1.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 43
-     8.2.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 45
-     8.3.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 45
-     8.4.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 46
-     8.5.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 47
-   9.  User Interface basics  . . . . . . . . . . . . . . . . . . . . 48
-     9.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . . . 48
-   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 52
-     A.1.  Main changes in 1.0  . . . . . . . . . . . . . . . . . . . 52
-     A.2.  Main changes in 0.11.1 . . . . . . . . . . . . . . . . . . 52
-     A.3.  Main changes in 0.11.0 . . . . . . . . . . . . . . . . . . 53
-     A.4.  Main changes in 0.10.0 . . . . . . . . . . . . . . . . . . 53
-     A.5.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 54
-     A.6.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 55
-     A.7.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 55
-     A.8.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 56
-     A.9.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 56
-   Appendix B.  Tk option database resources  . . . . . . . . . . . . 57
-   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 61
-   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 62
-   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 63
-   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 64
+     8.1.  Message Hooks  . . . . . . . . . . . . . . . . . . . . . . 43
+     8.2.  Chat Hooks . . . . . . . . . . . . . . . . . . . . . . . . 44
+     8.3.  Login Hooks  . . . . . . . . . . . . . . . . . . . . . . . 45
+     8.4.  Presence Hooks . . . . . . . . . . . . . . . . . . . . . . 46
+     8.5.  Info/Query Hook  . . . . . . . . . . . . . . . . . . . . . 46
+     8.6.  Roster Hooks . . . . . . . . . . . . . . . . . . . . . . . 47
+     8.7.  Miscellaneous Hooks  . . . . . . . . . . . . . . . . . . . 47
+   9.  User Interface basics  . . . . . . . . . . . . . . . . . . . . 49
+     9.1.  Searching  . . . . . . . . . . . . . . . . . . . . . . . . 49
+   Appendix A.  Releases History  . . . . . . . . . . . . . . . . . . 53
+     A.1.  Main changes in 1.0  . . . . . . . . . . . . . . . . . . . 53
+     A.2.  Main changes in 0.11.1 . . . . . . . . . . . . . . . . . . 53
+     A.3.  Main changes in 0.11.0 . . . . . . . . . . . . . . . . . . 54
+     A.4.  Main changes in 0.10.0 . . . . . . . . . . . . . . . . . . 54
+     A.5.  Main changes in 0.9.9  . . . . . . . . . . . . . . . . . . 55
+     A.6.  Main changes in 0.9.8  . . . . . . . . . . . . . . . . . . 56
+     A.7.  Main changes in 0.9.7beta  . . . . . . . . . . . . . . . . 56
+     A.8.  Main changes in 0.9.6beta  . . . . . . . . . . . . . . . . 57
+     A.9.  Main changes in 0.9.5beta  . . . . . . . . . . . . . . . . 57
+   Appendix B.  Tk option database resources  . . . . . . . . . . . . 58
+   Appendix C.  Documentation TODO  . . . . . . . . . . . . . . . . . 62
+   Appendix D.  Acknowledgements  . . . . . . . . . . . . . . . . . . 63
+   Appendix E.  Copyrights  . . . . . . . . . . . . . . . . . . . . . 64
+   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 65
 
 
 
@@ -162,8 +164,6 @@
 
 
 
-
-
 Shchepin, et al.                                                [Page 3]
 

                                Tkabber 1.0                  January 2014
@@ -2368,7 +2368,7 @@
    hook::add draw_message_hook ...::handle_info 10
    hook::add draw_message_hook ...::draw_timestamp 15
    hook::add draw_message_hook    ::logger::log_message 15
-   hook::add draw_message_hook      muc::set_message_timestamp 15
+   hook::add draw_message_hook ...::set_message_timestamp 15
    hook::add draw_message_hook ...::add_number_of_messages_to_title 18
    hook::add draw_message_hook ...::chat_message_notify19
    hook::add draw_message_hook ...::handle_server_message 20
@@ -2391,16 +2391,16 @@
    Now let's look at the different kind of hooks that _Tkabber_ knows
    about.
 
-8.1.  Chat Hooks
+8.1.  Message Hooks
 
-   When _Tkabber_ decides that it needs to open a (tabbed) window for a
-   chat or groupchat, two hooks are run:
+   When _Tkabber_ receives a message stanza it calls two hooks:
 
-   open_chat_pre_hook  $chatid $type
-   open_chat_post_hook $chatid $type
+   rewrite_message_hook \
+       xlib from id type is_subject subject body err thread priority x
+   process_message_hook \
+       $xlib $from $id $type $is_subject $subject $body $err $thread \
+       $priority $x
 
-   Both hooks are given two parameters: the chatid (ID of the chat or
-   conference room window, you always can obtain JID using
 
 
 
@@ -2409,6 +2409,27 @@
                                Tkabber 1.0                  January 2014
 
 
+   The first hook takes eleven variable names as arguments, so the
+   calling procedures can rewrite them.  This means that a procedure in
+   this hook should call "upvar 2 $varbody body" and use the "body"
+   variable to change the actual message body.  For example, this allows
+   _Tkabber_ to put decrypted message into the "body" variable if it is
+   encrypted.
+
+   The second hook does the job of showing message to the user (or doing
+   something else with it if it's a special message like part of an in-
+   band file transfer.
+
+8.2.  Chat Hooks
+
+   When _Tkabber_ decides that it needs to open a (tabbed) window for a
+   chat or groupchat, two hooks are run:
+
+   open_chat_pre_hook  $chatid $type
+   open_chat_post_hook $chatid $type
+
+   Both hooks are given two parameters: the chatid (ID of the chat or
+   conference room window, you always can obtain JID using
    "chat::get_jid" and connection token using "chat::get_xlib"
    routines); and, and the type of chat (either ""chat"" or
    ""groupchat"").
@@ -2437,6 +2458,13 @@
    list of additional payload elements.  (This last parameter isn't
    documented in this version of the documentation.)
 
+
+
+Shchepin, et al.                                               [Page 44]
+

+                               Tkabber 1.0                  January 2014
+
+
    Chat windows have menubuttons, and two hooks are used to add items in
    menu:
 
@@ -2458,13 +2486,6 @@
    completions is stored; index of position where completion must be
    inserted; and content of text widget where completion is requested.
 
-
-
-Shchepin, et al.                                               [Page 44]
-

-                               Tkabber 1.0                  January 2014
-
-
    When someone enters/exits conference, the following hooks are called:
 
    chat_user_enter $group $nick
@@ -2473,8 +2494,16 @@
    The hooks are given two parameters: chatid of conference and nick of
    participant.
 
-8.2.  Login Hooks
+   When someone changes his/her nickname in a conference room, the
+   following hook is called:
 
+   room_nickname_changed_hook $chatid $nick $new_nick
+
+   The hook is given three parameters: chatid of conference old nickname
+   and the new nickname of participant.
+
+8.3.  Login Hooks
+
    Two hooks are invoked whenever a session is connected or
    disconnected:
 
@@ -2485,8 +2514,15 @@
    Both hooks are given one parameter: connection token (_Tkabber_
    allows several connections at once).
 
-8.3.  Presence Hooks
 
+
+Shchepin, et al.                                               [Page 45]
+

+                               Tkabber 1.0                  January 2014
+
+
+8.4.  Presence Hooks
+
    When our presence status changes, a hook is run:
 
    change_our_presence_post_hook $status
@@ -2514,13 +2550,6 @@
    (e.g., "fred") or the JID itself (e.g., "fred at example.com") if no
    label exists in the roster; and, the user's new status.
 
-
-
-Shchepin, et al.                                               [Page 45]
-

-                               Tkabber 1.0                  January 2014
-
-
    And for all received presence packets, a hook is run:
 
    client_presence_hook $xlib $from $type $x $args
@@ -2530,8 +2559,28 @@
    extended subtags and parameters of this presence (e.g., "-show xa
    -status online").
 
-8.4.  Roster Hooks
+8.5.  Info/Query Hook
 
+   When an IQ stanza is received, a hook is run:
+
+   client_iq_hook $xlib $from $type $queries $args
+
+   The hook is given four compulsory parameters: connection token, who
+   sent this query/response type of stanza (e.g., "get", "set", "result"
+   or "error"), list of query subelements (usually it contains only one
+   element), list of optional arguments (e.g., "-lang language -to jid
+
+
+
+Shchepin, et al.                                               [Page 46]
+

+                               Tkabber 1.0                  January 2014
+
+
+   -id id -x $list_of_other_attributes").
+
+8.6.  Roster Hooks
+
    When an item is added to the roster window, one of the four hooks is
    run to add stuff to the menu associated with that item:
 
@@ -2564,31 +2613,26 @@
    current popup text is stored, the connection token, and the JID of
    the roster item.
 
+8.7.  Miscellaneous Hooks
 
+   There are three "obvious" hooks:
 
+   postload_hook
 
+   finload_hook
 
+   quit_hook
 
+   The first two, by default, run the "postload" and "finload"
+   procedures, respectively. "postload_hook" is run after all code has
 
 
 
-Shchepin, et al.                                               [Page 46]
+Shchepin, et al.                                               [Page 47]
 

                                Tkabber 1.0                  January 2014
 
 
-8.5.  Miscellaneous Hooks
-
-   There are three "obvious" hooks:
-
-   postload_hook
-
-   finload_hook
-
-   quit_hook
-
-   The first two, by default, run the "postload" and "finload"
-   procedures, respectively. "postload_hook" is run after all code has
    been loaded and before initializing main _Tkabber_ window.  After
    that "finload_hook" is run.  The final hook is called just before
    _Tkabber_ terminates (cf., Section 7.3.7).
@@ -2628,7 +2672,19 @@
 
 
 
-Shchepin, et al.                                               [Page 47]
+
+
+
+
+
+
+
+
+
+
+
+
+Shchepin, et al.                                               [Page 48]
 

                                Tkabber 1.0                  January 2014
 
@@ -2684,7 +2740,7 @@
 
 
 
-Shchepin, et al.                                               [Page 48]
+Shchepin, et al.                                               [Page 49]
 

                                Tkabber 1.0                  January 2014
 
@@ -2740,7 +2796,7 @@
 
 
 
-Shchepin, et al.                                               [Page 49]
+Shchepin, et al.                                               [Page 50]
 

                                Tkabber 1.0                  January 2014
 
@@ -2796,7 +2852,7 @@
 
 
 
-Shchepin, et al.                                               [Page 50]
+Shchepin, et al.                                               [Page 51]
 

                                Tkabber 1.0                  January 2014
 
@@ -2852,7 +2908,7 @@
 
 
 
-Shchepin, et al.                                               [Page 51]
+Shchepin, et al.                                               [Page 52]
 

                                Tkabber 1.0                  January 2014
 
@@ -2908,7 +2964,7 @@
 
 
 
-Shchepin, et al.                                               [Page 52]
+Shchepin, et al.                                               [Page 53]
 

                                Tkabber 1.0                  January 2014
 
@@ -2964,7 +3020,7 @@
 
 
 
-Shchepin, et al.                                               [Page 53]
+Shchepin, et al.                                               [Page 54]
 

                                Tkabber 1.0                  January 2014
 
@@ -3020,7 +3076,7 @@
 
 
 
-Shchepin, et al.                                               [Page 54]
+Shchepin, et al.                                               [Page 55]
 

                                Tkabber 1.0                  January 2014
 
@@ -3076,7 +3132,7 @@
 
 
 
-Shchepin, et al.                                               [Page 55]
+Shchepin, et al.                                               [Page 56]
 

                                Tkabber 1.0                  January 2014
 
@@ -3132,7 +3188,7 @@
 
 
 
-Shchepin, et al.                                               [Page 56]
+Shchepin, et al.                                               [Page 57]
 

                                Tkabber 1.0                  January 2014
 
@@ -3188,7 +3244,7 @@
 
 
 
-Shchepin, et al.                                               [Page 57]
+Shchepin, et al.                                               [Page 58]
 

                                Tkabber 1.0                  January 2014
 
@@ -3244,7 +3300,7 @@
 
 
 
-Shchepin, et al.                                               [Page 58]
+Shchepin, et al.                                               [Page 59]
 

                                Tkabber 1.0                  January 2014
 
@@ -3300,7 +3356,7 @@
 
 
 
-Shchepin, et al.                                               [Page 59]
+Shchepin, et al.                                               [Page 60]
 

                                Tkabber 1.0                  January 2014
 
@@ -3356,7 +3412,7 @@
 
 
 
-Shchepin, et al.                                               [Page 60]
+Shchepin, et al.                                               [Page 61]
 

                                Tkabber 1.0                  January 2014
 
@@ -3412,7 +3468,7 @@
 
 
 
-Shchepin, et al.                                               [Page 61]
+Shchepin, et al.                                               [Page 62]
 

                                Tkabber 1.0                  January 2014
 
@@ -3468,7 +3524,7 @@
 
 
 
-Shchepin, et al.                                               [Page 62]
+Shchepin, et al.                                               [Page 63]
 

                                Tkabber 1.0                  January 2014
 
@@ -3524,7 +3580,7 @@
 
 
 
-Shchepin, et al.                                               [Page 63]
+Shchepin, et al.                                               [Page 64]
 

                                Tkabber 1.0                  January 2014
 
@@ -3580,5 +3636,5 @@
 
 
 
-Shchepin, et al.                                               [Page 64]
+Shchepin, et al.                                               [Page 65]
 


Modified: trunk/tkabber/doc/tkabber.html
===================================================================
--- trunk/tkabber/doc/tkabber.html	2013-12-25 10:46:59 UTC (rev 2027)
+++ trunk/tkabber/doc/tkabber.html	2013-12-26 17:07:18 UTC (rev 2028)
@@ -283,46 +283,50 @@
 <a href="#s.extensibility">8.</a> 
 Extensibility<br />
     <a href="#anchor1">8.1.</a> 
+Message Hooks<br />
+    <a href="#anchor2">8.2.</a> 
 Chat Hooks<br />
-    <a href="#anchor2">8.2.</a> 
+    <a href="#anchor3">8.3.</a> 
 Login Hooks<br />
-    <a href="#anchor3">8.3.</a> 
+    <a href="#anchor4">8.4.</a> 
 Presence Hooks<br />
-    <a href="#anchor4">8.4.</a> 
+    <a href="#anchor5">8.5.</a> 
+Info/Query Hook<br />
+    <a href="#anchor6">8.6.</a> 
 Roster Hooks<br />
-    <a href="#anchor5">8.5.</a> 
+    <a href="#anchor7">8.7.</a> 
 Miscellaneous Hooks<br />
 <a href="#s.user-interface">9.</a> 
 User Interface basics<br />
     <a href="#s.ui-searching">9.1.</a> 
 Searching<br />
-<a href="#anchor6">Appendix A.</a> 
+<a href="#anchor8">Appendix A.</a> 
 Releases History<br />
-    <a href="#anchor7">A.1.</a> 
+    <a href="#anchor9">A.1.</a> 
 Main changes in 1.0<br />
-    <a href="#anchor8">A.2.</a> 
+    <a href="#anchor10">A.2.</a> 
 Main changes in 0.11.1<br />
-    <a href="#anchor9">A.3.</a> 
+    <a href="#anchor11">A.3.</a> 
 Main changes in 0.11.0<br />
-    <a href="#anchor10">A.4.</a> 
+    <a href="#anchor12">A.4.</a> 
 Main changes in 0.10.0<br />
-    <a href="#anchor11">A.5.</a> 
+    <a href="#anchor13">A.5.</a> 
 Main changes in 0.9.9<br />
-    <a href="#anchor12">A.6.</a> 
+    <a href="#anchor14">A.6.</a> 
 Main changes in 0.9.8<br />
-    <a href="#anchor13">A.7.</a> 
+    <a href="#anchor15">A.7.</a> 
 Main changes in 0.9.7beta<br />
-    <a href="#anchor14">A.8.</a> 
+    <a href="#anchor16">A.8.</a> 
 Main changes in 0.9.6beta<br />
-    <a href="#anchor15">A.9.</a> 
+    <a href="#anchor17">A.9.</a> 
 Main changes in 0.9.5beta<br />
 <a href="#XRDB">Appendix B.</a> 
 Tk option database resources<br />
-<a href="#anchor16">Appendix C.</a> 
+<a href="#anchor18">Appendix C.</a> 
 Documentation TODO<br />
-<a href="#anchor17">Appendix D.</a> 
+<a href="#anchor19">Appendix D.</a> 
 Acknowledgements<br />
-<a href="#anchor18">Appendix E.</a> 
+<a href="#anchor20">Appendix E.</a> 
 Copyrights<br />
 <a href="#rfc.authors">§</a> 
 Authors' Addresses<br />
@@ -2580,7 +2584,7 @@
 hook::add draw_message_hook ...::handle_info 10
 hook::add draw_message_hook ...::draw_timestamp 15
 hook::add draw_message_hook    ::logger::log_message 15
-hook::add draw_message_hook      muc::set_message_timestamp 15
+hook::add draw_message_hook ...::set_message_timestamp 15
 hook::add draw_message_hook ...::add_number_of_messages_to_title 18
 hook::add draw_message_hook ...::chat_message_notify19
 hook::add draw_message_hook ...::handle_server_message 20
@@ -2609,6 +2613,30 @@
 <a name="anchor1"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.8.1"></a><h3>8.1. 
+Message Hooks</h3>
+
+<p>
+When <em>Tkabber</em> receives a message stanza it calls two hooks:
+
+</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+rewrite_message_hook \
+    xlib from id type is_subject subject body err thread priority x
+process_message_hook \
+    $xlib $from $id $type $is_subject $subject $body $err $thread \
+    $priority $x
+</pre></div>
+<p>The first hook takes eleven variable names as arguments, so the calling
+procedures can rewrite them. This means that a procedure in this hook should call
+<tt>upvar 2 $varbody body</tt> and use the <tt>body</tt>
+variable to change the actual message body. For example, this allows <em>Tkabber</em> to put
+decrypted message into the <tt>body</tt> variable if it is encrypted.
+</p>
+<p>The second hook does the job of showing message to the user (or doing something else with it if it's
+a special message like part of an in-band file transfer.
+</p>
+<a name="anchor2"></a><br /><hr />
+<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
+<a name="rfc.section.8.2"></a><h3>8.2. 
 Chat Hooks</h3>
 
 <p>When <em>Tkabber</em> decides that it needs to open a (tabbed)
@@ -2701,9 +2729,20 @@
             participant.
           
 </p>
-<a name="anchor2"></a><br /><hr />
+<p>
+            When someone changes his/her nickname in a conference room, the following hook is called:
+          
+</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+room_nickname_changed_hook $chatid $nick $new_nick
+</pre></div>
+<p>
+            The hook is given three parameters: chatid of conference old nickname and the new nickname of
+            participant.
+          
+</p>
+<a name="anchor3"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
-<a name="rfc.section.8.2"></a><h3>8.2. 
+<a name="rfc.section.8.3"></a><h3>8.3. 
 Login Hooks</h3>
 
 <p>Two hooks are invoked whenever a session is connected or
@@ -2716,9 +2755,9 @@
 <p>Both hooks are given one parameter: connection token (<em>Tkabber</em>
 allows several connections at once).
 </p>
-<a name="anchor3"></a><br /><hr />
+<a name="anchor4"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
-<a name="rfc.section.8.3"></a><h3>8.3. 
+<a name="rfc.section.8.4"></a><h3>8.4. 
 Presence Hooks</h3>
 
 <p>When our presence status changes,
@@ -2770,9 +2809,26 @@
             and parameters of this presence (e.g., "-show xa -status online").
           
 </p>
-<a name="anchor4"></a><br /><hr />
+<a name="anchor5"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
-<a name="rfc.section.8.4"></a><h3>8.4. 
+<a name="rfc.section.8.5"></a><h3>8.5. 
+Info/Query Hook</h3>
+
+<p>When an IQ stanza is received,
+a hook is run:
+</p><div style='display: table; width: 0; margin-left: 3em; margin-right: auto'><pre>
+client_iq_hook $xlib $from $type $queries $args
+</pre></div>
+<p>
+          The hook is given four compulsory parameters:
+          connection token, who sent this query/response type of stanza (e.g., "get", "set", "result" or "error"),
+          list of query subelements (usually it contains only one element), list of optional arguments
+          (e.g., "-lang language -to jid -id id -x $list_of_other_attributes").
+        
+</p>
+<a name="anchor6"></a><br /><hr />
+<table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
+<a name="rfc.section.8.6"></a><h3>8.6. 
 Roster Hooks</h3>
 
 <p>
@@ -2817,9 +2873,9 @@
             current popup text is stored, the connection token, and the JID of the roster item.
           
 </p>
-<a name="anchor5"></a><br /><hr />
+<a name="anchor7"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
-<a name="rfc.section.8.5"></a><h3>8.5. 
+<a name="rfc.section.8.7"></a><h3>8.7. 
 Miscellaneous Hooks</h3>
 
 <p>There are three "obvious" hooks:
@@ -2942,12 +2998,12 @@
 </ul><p>
 
 </p>
-<a name="anchor6"></a><br /><hr />
+<a name="anchor8"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A"></a><h3>Appendix A. 
 Releases History</h3>
 
-<a name="anchor7"></a><br /><hr />
+<a name="anchor9"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.1"></a><h3>A.1. 
 Main changes in 1.0</h3>
@@ -2988,7 +3044,7 @@
 </ul><p>
         
 </p>
-<a name="anchor8"></a><br /><hr />
+<a name="anchor10"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.2"></a><h3>A.2. 
 Main changes in 0.11.1</h3>
@@ -3005,7 +3061,7 @@
 </ul><p>
         
 </p>
-<a name="anchor9"></a><br /><hr />
+<a name="anchor11"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.3"></a><h3>A.3. 
 Main changes in 0.11.0</h3>
@@ -3054,7 +3110,7 @@
 </ul><p>
         
 </p>
-<a name="anchor10"></a><br /><hr />
+<a name="anchor12"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.4"></a><h3>A.4. 
 Main changes in 0.10.0</h3>
@@ -3100,7 +3156,7 @@
 </ul><p>
         
 </p>
-<a name="anchor11"></a><br /><hr />
+<a name="anchor13"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.5"></a><h3>A.5. 
 Main changes in 0.9.9</h3>
@@ -3127,7 +3183,7 @@
 </ul><p>
         
 </p>
-<a name="anchor12"></a><br /><hr />
+<a name="anchor14"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.6"></a><h3>A.6. 
 Main changes in 0.9.8</h3>
@@ -3158,7 +3214,7 @@
 </ul><p>
         
 </p>
-<a name="anchor13"></a><br /><hr />
+<a name="anchor15"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.7"></a><h3>A.7. 
 Main changes in 0.9.7beta</h3>
@@ -3181,7 +3237,7 @@
 </ul><p>
         
 </p>
-<a name="anchor14"></a><br /><hr />
+<a name="anchor16"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.8"></a><h3>A.8. 
 Main changes in 0.9.6beta</h3>
@@ -3206,7 +3262,7 @@
 </ul><p>
         
 </p>
-<a name="anchor15"></a><br /><hr />
+<a name="anchor17"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.A.9"></a><h3>A.9. 
 Main changes in 0.9.5beta</h3>
@@ -3508,7 +3564,7 @@
 </dl></blockquote><p>
       
 </p>
-<a name="anchor16"></a><br /><hr />
+<a name="anchor18"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.C"></a><h3>Appendix C. 
 Documentation TODO</h3>
@@ -3546,7 +3602,7 @@
 </li>
 </ul>
 
-<a name="anchor17"></a><br /><hr />
+<a name="anchor19"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.D"></a><h3>Appendix D. 
 Acknowledgements</h3>
@@ -3561,7 +3617,7 @@
 <p>The new sound theme appeared in 0.11.1 release was created by
 Serge Yudin
 </p>
-<a name="anchor18"></a><br /><hr />
+<a name="anchor20"></a><br /><hr />
 <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc"> TOC </a></td></tr></table>
 <a name="rfc.section.E"></a><h3>Appendix E. 
 Copyrights</h3>

Modified: trunk/tkabber/doc/tkabber.xml
===================================================================
--- trunk/tkabber/doc/tkabber.xml	2013-12-25 10:46:59 UTC (rev 2027)
+++ trunk/tkabber/doc/tkabber.xml	2013-12-26 17:07:18 UTC (rev 2028)
@@ -2104,7 +2104,7 @@
 hook::add draw_message_hook ...::handle_info 10
 hook::add draw_message_hook ...::draw_timestamp 15
 hook::add draw_message_hook    ::logger::log_message 15
-hook::add draw_message_hook      muc::set_message_timestamp 15
+hook::add draw_message_hook ...::set_message_timestamp 15
 hook::add draw_message_hook ...::add_number_of_messages_to_title 18
 hook::add draw_message_hook ...::chat_message_notify19
 hook::add draw_message_hook ...::handle_server_message 20
@@ -2131,6 +2131,28 @@
 <t>Now let's look at the different kind of hooks that <spanx>Tkabber</spanx> knows
 about.</t>
 
+<section title='Message Hooks'>
+<figure>
+<preamble>
+When <spanx>Tkabber</spanx> receives a message stanza it calls two hooks:
+</preamble>
+<artwork><![CDATA[
+rewrite_message_hook \
+    xlib from id type is_subject subject body err thread priority x
+process_message_hook \
+    $xlib $from $id $type $is_subject $subject $body $err $thread \
+    $priority $x
+]]></artwork>
+</figure>
+<t>The first hook takes eleven variable names as arguments, so the calling
+procedures can rewrite them. This means that a procedure in this hook should call
+<spanx style='verb'>upvar 2 $varbody body</spanx> and use the <spanx style='verb'>body</spanx>
+variable to change the actual message body. For example, this allows <spanx>Tkabber</spanx> to put
+decrypted message into the <spanx style='verb'>body</spanx> variable if it is encrypted.</t>
+<t>The second hook does the job of showing message to the user (or doing something else with it if it's
+a special message like part of an in-band file transfer.</t>
+</section>
+
 <section title='Chat Hooks'>
 <figure>
 <preamble>When <spanx>Tkabber</spanx> decides that it needs to open a (tabbed)
@@ -2235,6 +2257,18 @@
             participant.
           </postamble>
         </figure>
+        <figure>
+          <preamble>
+            When someone changes his/her nickname in a conference room, the following hook is called:
+          </preamble>
+<artwork><![CDATA[
+room_nickname_changed_hook $chatid $nick $new_nick
+]]></artwork>
+          <postamble>
+            The hook is given three parameters: chatid of conference old nickname and the new nickname of
+            participant.
+          </postamble>
+        </figure>
       </section>
 
 <section title='Login Hooks'>
@@ -2302,6 +2336,22 @@
         </figure>
       </section>
 
+<section title='Info/Query Hook'>
+<figure>
+<preamble>When an IQ stanza is received,
+a hook is run:</preamble>
+<artwork><![CDATA[
+client_iq_hook $xlib $from $type $queries $args
+]]></artwork>
+        <postamble>
+          The hook is given four compulsory parameters:
+          connection token, who sent this query/response type of stanza (e.g., "get", "set", "result" or "error"),
+          list of query subelements (usually it contains only one element), list of optional arguments
+          (e.g., "-lang language -to jid -id id -x $list_of_other_attributes").
+        </postamble>
+      </figure>
+    </section>
+
       <section title='Roster Hooks'>
         <figure>
           <preamble>



More information about the Tkabber-dev mailing list