ScwView

ScwView — A view widget with messaging-orientated features

Synopsis




            ScwView;
#define     SCW_TYPE_TIMESTAMP
#define     SCW_TYPE_PRESENCE
#define     SCW_TYPE_ROW_COLOR
enum        ScwInteraction;
void        scw_view_scroll_to_end          (ScwView *view);
void        scw_view_scroll_to_row          (ScwView *view,
                                             const gchar *path);
void        scw_view_set_column_foldable    (ScwView *view,
                                             gint column,
                                             gboolean foldable);
gboolean    scw_view_get_column_foldable    (ScwView *view,
                                             gint column);
void        scw_view_set_column_visible     (ScwView *view,
                                             gint column,
                                             gboolean visible);
gboolean    scw_view_get_column_visible     (ScwView *view,
                                             gint column);
void        scw_view_select_rows            (ScwView *view,
                                             const gchar *begin,
                                             const gchar *end);

Object Hierarchy


  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----ScwView

Implemented Interfaces

ScwView implements AtkImplementorIface.

Properties


  "action-attributes"    gchararray            : Read / Write
  "align-presences"      gboolean              : Read / Write
  "embedded-icon-size"   gint                  : Read / Write
  "interaction"          ScwInteraction        : Read / Write
  "invert-panning"       gboolean              : Read / Write
  "model"                GtkTreeModel          : Read / Write
  "presence-alignment"   PangoAlignment        : Read / Write
  "scroll-on-append"     gboolean              : Read / Write
  "selection-column-separator" gchararray            : Read / Write
  "selection-row-separator" gchararray            : Read / Write
  "timestamp-format"     gchararray            : Read / Write

Style Properties


  "alternate-row-colors" gboolean              : Read / Write
  "column-spacing"       gint                  : Read
  "even-row-color"       GdkColor              : Read
  "odd-row-color"        GdkColor              : Read
  "odd-row-tint"         gfloat                : Read
  "row-padding"          gint                  : Read

Signals


"activate"  void        user_function      (ScwView *scwview,
                                            gchar   *arg1,
                                            gchar   *arg2,
                                            gpointer user_data)      : Run first
"buffer-request"
            void        user_function      (ScwView      *scwview,
                                            GtkTreeModel *arg1,
                                            gboolean      arg2,
                                            gpointer      user_data)      : Run first
"context-request"
            void        user_function      (ScwView *scwview,
                                            gchar   *arg1,
                                            gchar   *arg2,
                                            gint     arg3,
                                            gint     arg4,
                                            gpointer user_data)      : Run first
"set-scroll-adjustments"
            void        user_function      (ScwView       *scwview,
                                            GtkAdjustment *arg1,
                                            GtkAdjustment *arg2,
                                            gpointer       user_data)      : Run last

Description

ScwView offers viewing of data kept in GtkTreeModels. Its features are designed specially with messaging applications in mind, but it could be useful for other type of uses too.

Using ScwView

ScwView is a view widget somewhat similar to the GtkTreeView. It has significant differences to the GtkTreeViews rendering consept however, the most prominent being the complete lack of CellRenderers.

Instead of CellRenderers, ScwView determines the way data is rendered by its type. In addition to the existing types (integers, strings, GdkPixbufs), ScwView introduces some custom types that behave differently from the types they derive from (eg. the timestamp type that is an integer, but will be rendered as a time representation).

This makes a ScwView with the default behaviour trivial to set up:

  GtkTreeModel *model;
  ScwView *view;

  [...]

  model = GTK_TREE_MODEL (gtk_list_store_new (4,
                                              SCW_TYPE_TIMESTAMP,
                                              GDK_TYPE_PIXBUF,
                                              SCW_TYPE_PRESENCE,
                                              G_TYPE_STRING));

  widget = GTK_WIDGET (g_object_new (SCW_TYPE_VIEW,
                                    "model", model,
                                    NULL));

After this you have a view that will show whatever you insert in the model ready to be added to a container.

To append data to the model in the example, you would do:

  GtkTreeIter iter;
  GtkTreeModel *model;

  [...]

  gtk_list_store_append (GTK_LIST_STORE (model), &iter);
  gtk_list_store_set (GTK_LIST_STORE (model), &iter,
                      0, time(NULL),
                      1, gdk_pixbuf_new_from_file_at_size ("scw.png",
                                                           24, 24,
                                                           NULL),
                      2, presence_name,
                      3, "This <action id='append'>row</action> was <b>appended</b> ",
                      -1);

Notice that the timestamp type is an integer, and will be converted to a time format automatically. The third column (numbered 2) is a presence column which allows the column to have alignment with regard to other columns and for text within the column, and the last one is a basic string column, which means the text in it will be wrapped.


Actions (activatable text)

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 the span pango tag with user-defineable attributes when parsed, to make the activatable text visually different. 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).

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).

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.


Embedded icons

In addition to rendering columns of the GdkPixbuf type, ScwView supports embedding icons in the middle of the text with a icon tag. It does this through the icon theme to allow things like themeable emoticons. This has some implications however, including:

  • Shown icons need to be installed as a part of the icon theme (you can do this on runtime with gtk_icon_theme_add_builtin_icon()). This means big images are not feasible as they will stay in memory.
  • Icons have one global size, the icon tag does not support size definitions.

These attributes of the icon tag make it very geared towards emoticon and that sort of usage, not a general purpose image system.

The icon tag syntax goes as follows:

  Nice <icon id='gtk-home'> of a home.

The id is the name of the icon. As the example shows, you can use the icon tag on any icon name existing in the current icon theme, including the stock Gtk+ icons.

Details

ScwView

typedef struct _ScwView ScwView;

There is no public members in the ScwView struct


SCW_TYPE_TIMESTAMP

#define SCW_TYPE_TIMESTAMP            (scw_timestamp_get_type ())

The timestamp type for creating automatically formatted time columns in the model.


SCW_TYPE_PRESENCE

#define SCW_TYPE_PRESENCE             (scw_presence_get_type ())

The presence type for creating specialized textual model columns.


SCW_TYPE_ROW_COLOR

#define SCW_TYPE_ROW_COLOR            (scw_row_color_get_type ())

The row color type for creating model columns that can override the row color in the view.


enum ScwInteraction

typedef enum
{
  SCW_INTERACTION_SELECT,
  SCW_INTERACTION_SMART_PAN,
  SCW_INTERACTION_PAN
} ScwInteraction;

Interaction mode of the view.

SCW_INTERACTION_SELECT This is the "normal" mode, text is selectable by dragging the mouse.
SCW_INTERACTION_SMART_PAN This is a mode where the view tries to guess whether the user wants to select text or pan the view when the interaction begins.
SCW_INTERACTION_PAN This is a mode where dragging the mouse on the view scrolls it rather than selects text.

scw_view_scroll_to_end ()

void        scw_view_scroll_to_end          (ScwView *view);

Scrolls the view so that the last row is visible at the bottom of the view.

view : The ScwView.

scw_view_scroll_to_row ()

void        scw_view_scroll_to_row          (ScwView *view,
                                             const gchar *path);

Scrolls the view so that the row denoted by path is visible at the top or as close to top of the view as possible.

view : The ScwView.
path : A string noting the row that should be scrolled to, starting from "0"

scw_view_set_column_foldable ()

void        scw_view_set_column_foldable    (ScwView *view,
                                             gint column,
                                             gboolean foldable);

Sets the column indicated to either be foldable or not foldable. Columns are not foldable by default. If a column is foldable, it will be rendered below the previous column. This includes already folded columns (so if all columns are folded, they will be rendered as a vertical list, row by row)

view : The ScwView.
column : Number of the column to set the attribute for.
foldable : Whether the column is foldable or not.

scw_view_get_column_foldable ()

gboolean    scw_view_get_column_foldable    (ScwView *view,
                                             gint column);

Gets the foldable attribute of the column indicated

view : The ScwView.
column : Number of the column to get the attribute for.
Returns : Boolean value indicating whether the column is foldable or not.

scw_view_set_column_visible ()

void        scw_view_set_column_visible     (ScwView *view,
                                             gint column,
                                             gboolean visible);

Sets the column indicated to be visible or not visible. Invisible rows are hidden completely and do not affect the rendering in any way.

view : The ScwView.
column : Number of the column to set the attribute for.
visible : Whether the column is visible or not.

scw_view_get_column_visible ()

gboolean    scw_view_get_column_visible     (ScwView *view,
                                             gint column);

Gets the visibility of the column indicated.

view : The ScwView.
column : Number of the column to get the attribute for.
Returns : Boolean value indicating whether the column is visible or not.

scw_view_select_rows ()

void        scw_view_select_rows            (ScwView *view,
                                             const gchar *begin,
                                             const gchar *end);

Selects a range of rows, cancelling any previous selections done. The last row given is included in the selection.

view : The ScwView
begin : A string noting the row that should be selected, starting from "0"
end : A string noting the row that the selection should end to. Can be NULL, if only one row is to be selected

Property Details

The "action-attributes" property

  "action-attributes"    gchararray            : Read / Write

The string used as the attribute section for the pango span tag that replaces action tags.

Default value: NULL


The "align-presences" property

  "align-presences"      gboolean              : Read / Write

Aligns presence names (the type ScwPresence) added to the view to take up the same space.

Default value: FALSE


The "embedded-icon-size" property

  "embedded-icon-size"   gint                  : Read / Write

The size of icons that are embedded in the text with the <icon> tag.

Allowed values: >= 0

Default value: 12


The "interaction" property

  "interaction"          ScwInteraction        : Read / Write

The method of interaction with the view.

Default value: SCW_INTERACTION_SELECT


The "invert-panning" property

  "invert-panning"       gboolean              : Read / Write

Invert the direction of the panning.

Default value: FALSE


The "model" property

  "model"                GtkTreeModel          : Read / Write

The model from which the view gets it data


The "presence-alignment" property

  "presence-alignment"   PangoAlignment        : Read / Write

Decide which PangoAlignment type will be used for presence names (the type ScwPresence).

Default value: PANGO_ALIGN_RIGHT


The "scroll-on-append" property

  "scroll-on-append"     gboolean              : Read / Write

Scrolls the view to the end of the buffer when new row is added to the model.

Default value: TRUE


The "selection-column-separator" property

  "selection-column-separator" gchararray            : Read / Write

The string used to separate columns in selections.

Default value: NULL


The "selection-row-separator" property

  "selection-row-separator" gchararray            : Read / Write

The string used to separate rows in selections.

Default value: NULL


The "timestamp-format" property

  "timestamp-format"     gchararray            : Read / Write

The strftime-compatible format string to be used with the timestamp columns.

Default value: NULL

Style Property Details

The "alternate-row-colors" style property

  "alternate-row-colors" gboolean              : Read / Write

Controls whether the row colors should alternate between even and odd rows.

Default value: TRUE


The "column-spacing" style property

  "column-spacing"       gint                  : Read

Amount of empty space to leave between columns.

Allowed values: >= 0

Default value: 6


The "even-row-color" style property

  "even-row-color"       GdkColor              : Read

Color to use for even rows, also used as the background color.


The "odd-row-color" style property

  "odd-row-color"        GdkColor              : Read

Color to use for odd rows.


The "odd-row-tint" style property

  "odd-row-tint"         gfloat                : Read

Amount of shading applied to odd rows if the odd-row-color is not set.

Allowed values: [0,1]

Default value: 0.9


The "row-padding" style property

  "row-padding"          gint                  : Read

Amount of empty space to leave around row contents.

Allowed values: >= 0

Default value: 2

Signal Details

The "activate" signal

void        user_function                  (ScwView *scwview,
                                            gchar   *arg1,
                                            gchar   *arg2,
                                            gpointer user_data)      : Run first

scwview : the object which received the signal.
arg1 :
arg2 :
user_data : user data set when the signal handler was connected.

The "buffer-request" signal

void        user_function                  (ScwView      *scwview,
                                            GtkTreeModel *arg1,
                                            gboolean      arg2,
                                            gpointer      user_data)      : Run first

The buffer request signal is emitted when the user scrolls the scrollbar to the proximity of the extremities of the bar. This is basically intended for "infinite scrolling", so that when the user scrolls near to the end of the visible buffer, the application can fill the buffer some more. In practise, this doesn't work well as GtkScrollbar and GtkAdjustment operate on a finite range and simply making it longer does not pass as infinite scrolling. But it was a start.

scwview : the object which received the signal.
model : the model of the view.
fill_start : wheter we should fill the start or the end of the model
user_data : user data set when the signal handler was connected.

The "context-request" signal

void        user_function                  (ScwView *scwview,
                                            gchar   *arg1,
                                            gchar   *arg2,
                                            gint     arg3,
                                            gint     arg4,
                                            gpointer user_data)      : Run first

The context request signal is emitted when the user clicks on the view with the third mouse button. If the location of the click contains an activatable text, the action_id and action_data parameters will contain the id and text of the action tag, otherwise they will be NULL (indicating a global context request).

scwview : the object which received the signal.
action_id : the id attribute of an action tag or NULL.
action_data : the text enclosed in an action tag.
x : the x coordinate for the click, relative to the widgets origin
y : the y coordinate for the click, relative to the widgets origin
user_data : user data set when the signal handler was connected.

The "set-scroll-adjustments" signal

void        user_function                  (ScwView       *scwview,
                                            GtkAdjustment *arg1,
                                            GtkAdjustment *arg2,
                                            gpointer       user_data)      : Run last

scwview : the object which received the signal.
arg1 :
arg2 :
user_data : user data set when the signal handler was connected.

See Also

The Tree and List Widget Overview from the Gtk+ Reference Manual