ChatUI (osso-chat-ui) README file
---------------------------------

- Implements OSSO Chat UI Specification 3.1 at the moment 

SVN structure
-------------
trunk/ui/chat
  test/
    * Contains various testing programs. Warning: some of them are not
      functioning anymore due to chat and framework modifications
  data/
    * Desktop, channel handler files, service files and default GCong values
      in form of GConf schema file.
  src/
    * The source files
  po/
    * Language files. None are provided by this package
  debian/
    * Packaging files

Test environment
----------------

- Maemo 4.0 environment

Test environment setup
----------------------

Build and install evolution-data-server

Build and install osso-addressbook

Build and install libscw

Build and install libtelepathy

Build and install libtelepathy-glib

Build and install telepathy-mission-control

Build and install osso-mission-control

Build and install libosso-rtcom-accounts

Build and install libosso-rtcom

Build and install telepathy-gabble

Build and install chat-ui
  * ChatUI can be launched from TN menu or from command line
    with run-standalone.sh /usr/bin/chat-ui

Configure parameters
--------------------
        --enable-debug           compile with DEBUG
        --enable-stdout          compile with DEBUG to stdout
        --enable-stderr          compile with DEBUG to stderr
        --enable-dmalloc         compile with DMALLOC
        --enable-profiling       compile with profiling
        --enable-coverage        compile with coverage info
        --enable-maemo-launcher        compile with maemo-launcher
        --enable-video-invitation  compile with video call invitation support
        --enable-file-dumper     compile with a file dumper, reads file contents into chat

dmalloc is an old configure parameter, no quarantee that it works. It is
recommended to compile the ui in sbox/x86 environment and test the memory
leaks and errors with valgrind instead.

profiling is also broken at this point.

video-invitation is not supported.

file-dumper is also legacy stuff, was made for debugging purposes, but it's
not being used anywhere. There is some code related to this in chat-view.c
which in my opinion could be removed... if you enable this option, chat will
parse messages like /read and /exec. /read will read a file and dump it into
chat. /exec will try to execute a script or any binary. Unfortunately, not
all scripts and binaries can be run, there are some issues of trying to fork
processes into the ui. /exec's stdout and stderr outputs are sent to remote
party.

enable-stdout and enable-stderr work without enable-debug. enable-debug alone
will cause all debug to be printed into syslog on the device. This is handy
only when debugging the program while using maemo launcher.

Compilation options
-------------------

when using dpkg-buildpackage -D -rfakeroot, you can set DEB_BUILD_OPTIONS
variable to contain few keywords to add some special options to compilation:

nolauncher: disable maemo launcher in the package
debug:      compile with --enable-debug
coverage:   compile with --enable-coverage
thumb:      apply -mthumb to CFLAGS

parallel:   some sort of parallel compilation :) Dmitry's addition, not sure
            what this truly does :D

Module breakdown
----------------

chat-box.c (ChatBox):
  * The text box of the active chat window. Uses ScwView from libscw
  * Handles ring buffer, log searching, log hiliting, log styles, text colors,
    uri handler context sensitive menu and parsing of messages
  * Also, the text message parsing is in this object. Current implementation
    uses POSIX regexec. In a rather stupid manner. This has room for
    optimatization. Regexec allows parsing through a message in a more
    intelligent matter, so at least the message splitting should be removed
    from the code as a first thing. That alone should speed up the parsing
    somewhat (hopefully).
  * Replacing the POSIX regexec with PERL like regexp has also been discussed.
    This is rumored to be more efficient implementation, so it is worth a shot.
  * This parsing is also sort of duplicated inside ScwView. ScwView's parsing
    is equally terrible. That one loops through the same message again,
    starting from the beginning if a known tag is found. This is done until
    the whole message has been gone through.

chat-idle-window.c (ChatIdleWindow):
  * The starter view of chat ui. Uses RtcomIdleView to display the initial
    contacts. Requires a OssoABookContactModel as a construct time parameter,
    which is provided from ChatManager. Selection in this view is transmitted
    to ChatMenu, if this window is a topmost element.
  * Also handles contact searching toolbar.
  * Controlled by ChatUi and ChatMenu

chat-manager.c (ChatManager):
  * Basically a singleton object (not truly, but there's only one instance)
  * Handles communication with MissionControl (libmissioncontrol)
  * Has internal tables for online accounts and their capabilities. These
    are signalled to interested parties.

chat-member.c (ChatMember):
  * The member object describing a single member in a chat
  * Has functions for looking up avatars and contact objects. Other wise it's
    mainly setting and getting.
  * Rationale behind using a GObject is, that GObject emits signals for
    properties. So, anything interested in member's different statuses
    can connect to notify signals. No need to push a new struct everywhere
    in the ui when it's changed.
  * ChatMember is rendered to display by ParticipantPane, created, destroyed
    and mainly also manipulated by ChatView, which contains the actual
    references to the objects in internal hash.
  * ChatMember is accessed, and a little bit also manipulated by ChatMenu.

chat-menu.c (ChatMenu):
  * The application menu. Shared object.
  * Due to the nature of this being a singleton as well, application wise,
    the parent window needs to be set as the topmost window changes. Sounds
    worse than it really is. Selection changes are currently transmitted
    by setter functions, but these should be converted to signals emitted
    by ChatWindow and ChatIdleWindow
  * Also contains most of the dialog handling code. Save for dialogs that are
    window specific. By this, the menu uses the dialog objects. Each dialog
    is it's own object.
  * Most of the menu states are bound to current window and window type.
    The contact sub menu is bound to current selection, window type and
    window properties.
  * Every time the parent or selection changes, state or actual objects,
    the menu states are recalculated.

chat-toolbar.c (ChatToolbar):
  * The application toolbar. There's one toolbar per window.
  * It might be rather simple to make the toolbar a shared object, only
    transmitting a state of the toolbar when topmost window changes. On
    the other hand, the memory consumed by the toolbar is probably quite
    minimal, so this is hardly required.
  * Nothing special in this object, has the side bar toggle button, entry
    field, invite button, send button and a smiley menu button. This menu
    button could be a GtkMenuToolButton, but then it would draw an arrow
    beside this object, which probably isn't what ui designers want.

chat-ui.c (ChatUi):
  * Main object so to speak. Has state machine to handle incoming channels,
    D-BUS calls and starting various chats from various methods inside the
    ui.
  * Controls all windows, setting menu parent as topmost window changes.
  * Also contains the ChannelHandler Telepathy interface.

chat-view.c (ChatView):
  * Telepathy "backend". Contains most of the Telepathy code.
  * Still has the GtkHPaned, side pane, text box and toolbar references. Also
    handles message alerting.
  * All ui components should be moved from this object to ChatWindow. Then,
    A different name should be invented for this object.
  * In order to move the ui components, this object needs to introduce new
    signals, like "members added", "members removed", "message received" and
    "message sent" to mention a few. This would basically mean that this
    would be a wrapper around telepathy, offering the ui a simple backend
    rather than mixing ui handling with the actual chat code. Might actually
    make the telepathy part reusable by other components as well...

chat-window.c (ChatWindow):
  * The chat active window. In addition to basic window code (container) this
    object also has code to control the search in chat toolbar, window
    specific dialog handling and log saving.
  * Also, currently contains couple of pieces of telepathy code; comparing
    2 handles, to decide if this window is a window that already has an
    incoming channel and inviting a contact to a chat. These could be rather
    easily be pushed into ChatView object for consistency.

chat.c (main):
  * The main function and POSIX signal handler.

common.c (common_):
  * Common utilities used throughout the code
  * Couple of mission control account filter functions
  * Account lookup functions
  * Telepathy and common error handler functions
  * Display functions for errors, showing a note, information banner
    or just logging based on an error

list-rooms-dialog.c (ListRoomsDialog):
  * Room listing dialog. Uses mainly raw D-BUS rather than telepathy bindings.
    This is, because when the dialog was coded, the bindings couldn't be used
    to do this well enough. The signal signatures were broken and what not.
    All this is done manually in this object. Propably the bindings should be
    used for this now.
  * There's an issue with the dialog and it's filter and sorting. The actual
    model containing the data of rooms is layered twice before it's shown.
    First, by determining what's visible and then sorted model. Due to
    current ui design this is a necessary evil. Unfortunately, it is terribly
    slow. See https://projects.maemo.org/bugzilla/show_bug.cgi?id=74483

manual-chat-dialog.c (ManualChatDialog):
  * Dialog for joining a chat by typed address. Used for both private chats
    and chat groups

participant-pane.c (ParticipantPane):
  * The side pane containing all members. Members are in a tree model, with
    a utf8 collated names, for sorting.
  * The member objects are not reffed. They're just pointers. Possibly it
    might be worthwhile to see if the members should be reffed and unreffed
    when set/removed.
  * Listens to Settings and ChatMember object notify signals to decide states.
  * Uses a custom cell renderer for rendering member data. This renderer is
    implemented in libosso-rtcom, called RtcomCellRenderer
  * Reason why it is in external lib is the need for automated scripts having
    the header file for this object. Helps the scripts identify the correct
    object and row selected.

password-dialog.c (PasswordDialog):
  * The dialog for asking password when joining a password protected chat

room-settings-dialog.c (RoomSettingsDialog):
  * Group chat settings. Meaning, some manipulation over the group properties.
  * Also contains telepathy code, as expected.
  * Each setting is dimmed / enabled based on property flags.

settings-dialog.c (SettingsDialog):
  * The chat application settings dialog. Manipulates Settings object, which
    uses g_object_notify to notify about it's changes.

settings.c (Settings):
  * A GConf wrapper for chat settings. Uses g_object_notify to inform about
    setting changes.
  * If a key is not found from GConf, a default value is used instead of
    returning an error.

smiley-menu.c (SmileyMenu):
  * The smiley image menu.
  * Was made into a separate GObject to make this a singleton instance.
    Unfortunately, singleton popup window (which this is) didn't handle well
    the situation where the parent was destroyed. Even if the parent was
    first unset before destroyed. So, it's just a cloned GObject, one per
    each window.

Known issues
------------

ScwView
  * Sizing is a bit broken. If the ScwView has at least 2 columns and size is
    set so that the last column doesn't fit the screen, the view tries to
    resize itself endlessly, causing an endless loop. This is solved in chat
    ui by blocking the pane position into a setting where this cannot happen.
    If font size changes to bigger than the current max setting (24) then
    this issue might arise again.
  * Selections are not quite complete. Double and triple clicking around the
    view might cause some text (1 or 2 chars) to be selected, but yet nothing
    is set into primary selection. Haven't really found a reason for this.
  * Clicking on the text area cancels all selections done anywhere. This
    shouldn't be happening, there's checks for this, but yet it's happening.
  * Probable reason is in button release
  * Tag parsing parses each message in a funny way; the message is looped
    through from the beginning until no more unhandled tags are found. This
    should be modified so that the message is looped only once. It's quite
    feasable modification, just needs recoding of the already messy action
    parsing.
  * Limited support of selections. Limited support of text formats (just it's
    own and pango markup)
  * Limited layout formatting, column based, which doesn't work all that
    well in all application. Basically, time stamp is a huge waste of space
    on the device. Fortunately it can be hidden in chat.
  * Lots of weird things with sizing and scrolled window handling. Basically,
    fakes itself to be a huge window and calculates positions by those too.
    But, I would say this is pretty standard stuff, probably easier than
    trying to calculate real and symbolic coordinates all the time. Now just
    only real coordinates are needed to be calculated.
  * Cannot replace text with an icon. Meaning, when selection is manipulated,
    no smiley or icon is returned into the selection.

Avatars
  * Basically, they're a hack. There wasn't native support for account based
    avatars in abook when chat was coded. This could be changed now. Alwhough,
    even if the abook avatar API is much better now, it's still a bit tricky.

Abook presences and contact objects
  * Everything in abook is based on a single contact. Chat is more concentrated
    into certain account / address of a person than the actual person. Either
    simple wrappers into abook elements for using contacts on account basis
    is needed or chat needs to concentrate more on the person instead of
    address. This is kind of a moot point though, current approach, chat
    listening to connection manager directly works very well.
  * EBook contacts are a bit troublesome to handle correctly. Currently, chat
    just skips contact objects that are *completely* marked to be deleted.
    A single account field marked to be deleted isn't checked. This is a bug
    and could be done better in chat, or by a new utility function in abook.
  * With the addition of manual contacts, the above is also valid for manual
    contacts. This caused some hacks, chat basically prefers normal contact
    objects over manual contact objects. It's a bit tricky but well, it's done.
    ... manual contacts mean the recent group exclusive contacts.

Telepathy code
  * It's still seen throughout the ui code. Managed to move most of it to
    single object, but there's still bunch of it that hasn't been moved.
  * It looks messy. Both due to the datatypes that telepathy utilizes and
    because of the need to resolve members in between, amongst other things.
  * In a rare occasion where user has 1 chat to a known contact, 1 chat to
    unknown contact and a chat room open, disconnecting and reconnecting
    (from presence plugin) causes chat to leak at least one channel and one
    connection object. Noticed that all these three are required, otherwise
    this isn't happening. Go figure. Might be that manually reconnecting the
    group chat after reconnect failure is required to reproduce this.

Chat code structure
  * ChatMenu is still called from ChatWindow, ChatView and ChatIdleWindow.
    For the sake of simplicity and consistency these calls should be replaced
    by for instance signals. This is a minor issue, but makes the ui look a
    bit more messy than it really is.
  * ChatMenu does all dimming and what not manually. Would be much much nicer
    if GtkActionGroup could be used. Unfortunately, it would appear that a
    GtkUiManager would then be required as well. This really isn't what
    we want though.
  * ChatManager needs rethinking. It works, does it's task, but for some
    reason it doesn't feel "right" :P Probably because the need to search out
    requests... or basically because the need to have them in the first place
  * ChatUi, mainly the window handling code is hard to understand. There has
    to be a simpler way to do this.
  * ChatManager, ChatUi and Settings could all be singletons on constructor
    level. This way, these objects wouldn't need to be passed around in the
    code, but a specific, interested object could create it's own instance
    of the object it wants.

Link parsing
  * In addition to ScwView's expotentially slowing link parsing, ChatBox's
    parsing is in need of slight improvements: First, message splitting and
    rejoining after parsing is excessive work. This needs to go. It's mainly
    done due to smileys, that need to be separate words in order for the
    smiley to be replaced by an icon.
  * All URIs are hard coded. Should retrieve the URI schemes and check for
    the existence of links based on this. Unfortunately, this wouldn't allow
    www. and foobar@email.com addresses. And, would possibly show also the
    "hidden" link types.
  * All smileys are hard coded. Should be by smiley themes.

Room listing
  * As explained in module breakdown

Chat and Room settings and general stuff
  * Only a fraction of possible, interesting settings in mucs are supported.
  * Member capabilities aren't used
  * No banning, just kicking
  * No cancelling of invites
  * No setting of moderators and other interested member based settings
  * No info about declined room invites
  * No file transfer
  * Cannot view member info, just contact info
  * Cannot send private message to a member in muc unless he's found in
    abook.
  * Cannot control smiley themes
  * Cannot control how links are parsed
  * Doesn't remember side pane setting. Position, visibility. This could be
    in chat settings; Show side pane in private chat / show side pane in muc.
    The button could still be there, but user could have the possibility of
    configuring default behaviour. Currently, it's a huge waste of space.
  * Presence message is still rendered even if a guy is blocked
  * Our own alias and presence isn't send into MUCs. Possibly connection
    manager's work?
    See: https://projects.maemo.org/bugzilla/show_bug.cgi?id=78358
  * No automatic logging of conversation
  * Cannot set own presence message for all presence statuses, just for "away"
  * EBookView loads whole abook list for idle view and for "new contact".
    The queries for this are terrible to form anyhow.

The UI shouldn't have any huge bugs at this point. Currently have 9 of them
open overall, one of them is a oom killer working weirdly in sbox. Others
are very minor, and even one of these is mostly solved, just needs some
additional work. This bug just needs a small fix, where a manual contact
is removed when blocking or adding a contact to abook. See link:
bug https://projects.maemo.org/bugzilla/show_bug.cgi?id=70663

And a little humor link in the end :) Have fun, some more information can be
obtained from Naba Kumar (at nokia dot com), who can contact me if there's need
for it

Good bye and thanks for all the Fish,
Mika Niinistö

http://virtuoosi.pkky.fi/materiaalit/iok/puutarhakoneoppi/tyokalut/tyokalut_kaytto_kuvat/iso_ja_pieni_tunkki.jpg
