ScwView overview
==================

ScwView is a view widget that has special considerations for chat usage.

It uses a conceptual model similar to that of treeviews, with some
differences. Both use a model-view architecture, but unlike treeview, the
ScwView has no external renderers. Instead, it renders the data according to
the type of the data. A G_TYPE_INT is rendered differently from G_TYPE_STRING
for example.

Since most interesting data is strings in communication, it sounds a little
stupid to render it all the same way, right? True, and that is why there are
defined types that are derivated from G_TYPEs to further spezialize the
rendering.

<TODO>
You can also attach a "filter" function to a type to alter
the rendered object (string, number, image) before it is actually rendered
</TODO>

Currently you can only use certain supported derivates of G_TYPE_INT and
G_TYPE_STRING, which will be autodetected by the widget from the model provided.


Usage
======

The basic usage pattern is simple. All you need to do is create a view and a
model to go with it. Both of the usual treemodel types should work, though
GtkListStore is more accurate with it's data model. For GtkTreeStore, the view
will only use toplevel nodes. Using a TreeStore is not really supported at the
moment, but probably will at some point.

The model should have supported types as the column types. A typical setup would
be (G_TYPE_INT, G_TYPE_STRING, G_TYPE_STRING) to have a timestamp, presence name
and a message column. Now, you don't want to show your users the time as
milliseconds from midnight, do you? So you'd use the provided type
SCW_TYPE_TIMESTAMP that converts the integer you get from say 'time(NULL)' call
to a "hh:mm" format. And set the "show-seconds" property of the view to
get the seconds there as well, if wanted. Likewise, the presence name
usually is preferred to have some formatting in it, so you'd use the type
SCW_TYPE_PRESENCE for it to have user-defined formatting and perhaps set
the "align-presences" property to align the presence names column to a unified
width to enhance readability of the messages.

Currently supported column types:
==========================
SCW_TYPE_TIMESTAMP  an integer value formatted as time
SCW_TYPE_PRESENCE   a string with user-defined formatting and subject to the
                    align-presences property
SCW_TYPE_ROW_COLOR  an gdk_parse_color()-compatible value for individual row
                    coloring.
G_TYPE_STRING       a string, column will be wrapped

Actions
========

Initially designed for supporting urls, the ScwView introduces a markup tag
similar to that of pango markup (which is also supported of course) for marking
a portion of text activatable. The <action> tag will be replaced by
<TODO>user-defineable</TODO> pango tag or tags upon parsing, to make the
activatable text detectable by the user. The tag MUST be of the form:

  Activatable <action id='myid'>text</action> example.

Any deviation from the format in the tags (execpt using " instead of ') will
result in undefined behaviour and outcome of the text (not only warnings).
(I dislike C string handling so if someone wishes to make the parsing more
robust, please do and provide a patch. It will be appreciated :)

When the user left-clicks (mouse button 1) on the activatable text, the
ScwView emits the signal "activate" which has the id and the text enclosed
inside the tags as callback parameters ("myid" and "text" in the above
example). The callback signature is:

  void user_function    (ScwView  *view,
                         gchar    *action_id,
                         gchar    *action_data,
                         gpointer *user_data);

When the user right-clicks (mouse button 3) on anywhere in the ScwView,
the "context-request" signal is emitted. It has also the id and data as
above when clicked on activatable text, but when clicked anywhere else
they are NULL to signify that this is a global context request. In addition
to the id and data, "context-request" also has the x and y coordinates
of the mouse cursor (to allow context menu placement for example). The
coordinates are relative to the widgets origin. Callback signature is:

  void user_function    (ScwView  *view,
                         gchar    *action_id,
                         gchar    *action_data,
                         gint     event_x,
                         gint     event_y,
                         gpointer *user_data);



API
====

[ Better API docs are in API.txt ]

Most of the API for ScwView concentrates on GObject properties and signals.

Here's how to create a view and examples of all the available properties:

  view = GTK_WIDGET (g_object_new (SCW_TYPE_VIEW,
                                    "model", model,
                                    "align-presences", TRUE,
                                    "presence-alignment", PANGO_ALIGN_LEFT,
                                    "scroll-on-append", TRUE,
                                    "timestamp-format", "%H:%M",
                                    "action-attributes", "underline='double' weight='bold'",
                                    "selection-row-separator", "\n",
                                    "selection-column-separator", "\t",
                                    NULL));

Example of a typical model:

  model = GTK_TREE_MODEL (gtk_list_store_new (3,
                                              SCW_TYPE_TIMESTAMP,
                                              SCW_TYPE_PRESENCE,
                                              G_TYPE_STRING));

fill with stuff like this

      gtk_list_store_append (GTK_LIST_STORE (model), &iter);
      gtk_list_store_set (GTK_LIST_STORE (model), &iter,
                          0, time(NULL) + i,
                          1, g_strdup_printf ("[<b>mynick%i</b>]", i),
                          2, "Some <span foreground='blue'>message</span> line",
                          -1);

Selection with ScwView
=======================

Currently only selection by rubberbanding with the mouse is supported.

ScwView operates in two modes of selection. If the selection box is within the
boundaries of the same row, the selection will follow logical text ordering
across the columns.
<FIXME>
Currently, there is an exception to this with folded
columns, a column that is not in the range of selection box will be left out
</FIXME>

If the selection box spans more than one row, the selection is converted to a
per-row mode, where all rows that the selection box touches are selected
completely.

By default, the selected string will have columns separated by " " and rows
by a newline.
