From 74d9459cfb4bedb4b75f46d311f51fc8955e1bf9 Mon Sep 17 00:00:00 2001 From: mathieui Date: Thu, 26 Jul 2012 18:32:25 +0200 Subject: Add an overview of the poezio internals to the documentation --- doc/en/dev/index.txt | 7 ++++ doc/en/dev/overview.txt | 106 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 doc/en/dev/index.txt create mode 100644 doc/en/dev/overview.txt (limited to 'doc/en/dev') diff --git a/doc/en/dev/index.txt b/doc/en/dev/index.txt new file mode 100644 index 00000000..263151fb --- /dev/null +++ b/doc/en/dev/index.txt @@ -0,0 +1,7 @@ +Development +=========== + +This section of the documentation is here to provide a quickstart for someone +willing to start hacking poezio. + +* link:overview.html[Overview] diff --git a/doc/en/dev/overview.txt b/doc/en/dev/overview.txt new file mode 100644 index 00000000..ad8f63bf --- /dev/null +++ b/doc/en/dev/overview.txt @@ -0,0 +1,106 @@ +Overview +======== + +NOTE: This is not an introduction to XMPP, but to poezio + + +Global overview +--------------- + +Poezio is an application that has three main layers, mostly separated in three +different python modules: _core_, _tabs_, and _windows_. An UML diagram of +Poezio would be inneficient, cluttered, or incomplete, so there is none, if +that bugs you. + +image::../../images/layers.png["The application layers", title="Layers"] + +_Core_ is mostly a “global” object containing the state of the application at +any time, it contains the global commands, the xmpp event handlers, the list +of open tabs, etc. Most objects in poezio have a self.core attribute +referencing the _Core_ (it’s a singleton, so there is never more than one +instance). _Core_ also contains the main loop of the application, which then +dispatchs the I/O events (keypress) to the appropriate methods. + + +But the main loop is not the most important thing in poezio; because it is an +IM client, it is essentially event-driven. The event part is handled by +SleekXMPP, which is the library we chose after moving away from xmpppy. + + +_Tabs_ are the second layer of poezio, but the first dealing with the UI: each +_Tab_ is a layout of several _windows_, it contains tab-specific commands, +tab-specific keybinds, and it has methods in order for core to +interact with it, and some methods are only proxies for the methods of a +_window_ + +Example scenario: If someone presses the key PageUp, then Core will call the +appropriate method on the current _Tab_, which will in turn, if it implements the +method (inherited empty from the Tab class), call a scrolling method from the +appropriate _window_. + +All tabs types inherit from the class _Tab_, and the _Tabs_ featuring +chat functionnality will inherit fro _ChatTab_ (which inherits from _Tab_). + +Examples of _Tabs_: MUCTab, XMLTab, RosterTab, MUCListTab, etc… + +Event handlers +-------------- + +The events handlers are registered right at the start of poezio, and then +when a matching stanza is received, the handler is called in a separate thread +from the main loop. The handlers are in _Core_, and then they call the +appropriate methods in the corresponding _tabs_. + +Example scenario: if a message is received from a MUC, then the _Core_ handler +will identify the _Tab_, and call the relevant handler from this _Tab_, this tab +will in turn, add the message to the buffer, which will then add it to the +relevant _windows_. + +NOTE: All the _windows_ that deal with received or generated text are linked +to a _text_buffer_, in order to rebuild all the display lines from an the +sources if necessary. This also enables us to have several _windows_ +presenting the same text, even if they are not of the same size and layout. + + +Commands and completion +----------------------- + +Commands are quite straightforward: those are methods that take a string as a +parameter, and they do stuff. + +From an user point of view, the methods are entered like that: + +================================== + + /command arg1 arg2 + +or + + /command "arg1 with spaces" arg2 + +================================== + +However, when creating a command, you wil deal with _one_ str, no matter what. +There are utilities to deal with it (common.shell_split), but it is not always +necessary. Commands are registered in the _commands_ dictionnary of a tab +structured as key (command name) -> tuple(command function, help string, completion). + + +Completions are a bit tricky, but it’s easy once you get used to it: + +They take an _Input_ (a _windows_ class) as a parameter, named the_input +everywhere in the sources. To effectively have a completion, you have to call +_the_input.auto_completion()_ at the end of the function. + +*the_input.auto_completion(completion_list, after='', quote=True)*: +Set the input to iterate over _completion_list_ when the user hits tab, insert +_after_ after the completed item, and surround the item with double quotes or +not. + +There is no method to find the current argument in the input (although the +feature is planned), so you have to assume the current argument is the last, +and guess it by splitting the string an checking for end-space. + +You can look for examples in the sources, all the possible cases are +covered (single-argument, complex arguments with spaces, several arguments, +etc…) -- cgit v1.2.3