doc/words/howto/im.html

   1 <?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   2   <head>
   3 <title>Twisted Documentation: Overview of Twisted IM</title>
   4 <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
   5   </head>
   6
   7   <body bgcolor="white">
   8     <h1 class="title">Overview of Twisted IM</h1>
   9     <div class="toc"><ol><li><a href="#auto0">Code flow</a></li><ul><li><a href="#auto1">AccountManager</a></li><li><a href="#auto2">ChatUI</a></li><li><a href="#auto3">Conversation and GroupConversation</a></li><li><a href="#auto4">Accounts</a></li></ul></ol></div>
  10     <div class="content">
  11 <span/>
  12
  13                 <p>Twisted IM (Instance Messenger) is a multi-protocol chat
  14                 framework, based on the Twisted framework we've all come to know
  15                 and love. It's fairly simple and extensible in two directions -
  16                 it's pretty easy to add new protocols, and it's also quite easy
  17                 to add new front-ends.</p>
  18
  19                 <h2>Code flow<a name="auto0"/></h2>
  20
  21                 <h3>AccountManager<a name="auto1"/></h3>
  22                 <p>The control flow starts at the relevant subclass of <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.words.im.baseaccount.AccountManager.html" title="twisted.words.im.baseaccount.AccountManager">baseaccount.AccountManager</a></code>.
  23                 The AccountManager is responsible for, well, managing accounts
  24                 - remembering what accounts are available, their
  25                 settings, adding and removal of accounts, and making accounts
  26                 log on at startup.</p>
  27
  28                 <p>This would be a good place to start your interface, load a
  29                 list of accounts from disk and tell them to login. Most of the
  30                 method names in <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.words.im.baseaccount.AccountManager.html" title="twisted.words.im.baseaccount.AccountManager">AccountManager</a></code>
  31                 are pretty self-explanatory, and your subclass can override
  32                 whatever it wants, but you <em>need</em> to override <code class="python">__init__</code>. Something like
  33                 this:</p>
  34
  35                 <pre class="python"><p class="py-linenumber">1
  36 2
  37 3
  38 4
  39 5
  40 6
  41 </p>...
  42     <span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>):
  43         <span class="py-src-variable">self</span>.<span class="py-src-variable">chatui</span> = ... <span class="py-src-comment"># Your subclass of basechat.ChatUI</span>
  44         <span class="py-src-variable">self</span>.<span class="py-src-variable">accounts</span> = ... <span class="py-src-comment"># Load account list</span>
  45         <span class="py-src-keyword">for</span> <span class="py-src-variable">a</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">accounts</span>:
  46             <span class="py-src-variable">a</span>.<span class="py-src-variable">logOn</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">chatui</span>)
  47 </pre>
  48
  49                 <h3>ChatUI<a name="auto2"/></h3>
  50                 <p>Account objects talk to the user via a subclass of <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.words.im.basechat.ChatUI.html" title="twisted.words.im.basechat.ChatUI">basechat.ChatUI</a></code>.
  51                 This class keeps track of all the various conversations that
  52                 are currently active, so that when an account receives and
  53                 incoming message, it can put that message in its correct
  54                 context.</p>
  55
  56                 <p>How much of this class you need to override depends on what
  57                 you need to do. You will need to override
  58                 <code>getConversation</code> (a one-on-one conversation, like
  59                 an IRC DCC chat) and <code>getGroupConversation</code> (a
  60                 multiple user conversation, like an IRC channel). You might
  61                 want to override <code>getGroup</code> and
  62                 <code>getPerson</code>.</p>
  63
  64                 <p>The main problem with the default versions of the above
  65                 routines is that they take a parameter, <code>Class</code>,
  66                 which defaults to an abstract implementation of that class -
  67                 for example, <code>getConversation</code> has a
  68                 <code>Class</code> parameter that defaults to <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.words.im.basechat.Conversation.html" title="twisted.words.im.basechat.Conversation">basechat.Conversation</a></code> which
  69                 raises a lot of <code>NotImplementedError</code>s. In your
  70                 subclass, override the method with a new method whose Class
  71                 parameter defaults to your own implementation of
  72                 <code>Conversation</code>, that simply calls the parent
  73                 class' implementation.</p>
  74
  75                 <h3>Conversation and GroupConversation<a name="auto3"/></h3>
  76                 <p>These classes are where your interface meets the chat
  77                 protocol. Chat protocols get a message, find the appropriate
  78                 <code>Conversation</code> or <code>GroupConversation</code>
  79                 object, and call its methods when various interesting things
  80                 happen.</p>
  81
  82                 <p>Override whatever methods you want to get the information
  83                 you want to display. You must override the <code>hide</code>
  84                 and <code>show</code> methods, however - they are called
  85                 frequently and the default implementation raises
  86                 <code>NotImplementedError</code>.</p>
  87
  88                 <h3>Accounts<a name="auto4"/></h3>
  89                 <p>An account is an instance of a subclass of <code class="API"><a href="http://twistedmatrix.com/documents/12.1.0/api/twisted.words.im.basesupport.AbstractAccount.html" title="twisted.words.im.basesupport.AbstractAccount">basesupport.AbstractAccount</a></code>.
  90                 For more details and sample code, see the various
  91                 <code>*support</code> files in <code>twisted.words.im</code>.</p>
  92
  93         </div>
  94
  95     <p><a href="index.html">Index</a></p>
  96     <span class="version">Version: 12.1.0</span>
  97   </body>
  98 </html>