![]() |
![]() |
![]() |
Scw Reference Manual | |
---|---|---|---|---|
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);
"action-attributes" gchararray : Read / Write "align-presences" gboolean : Read / Write "embedded-icon-size" gint : Read / Write "interaction" ScwInteraction : 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
"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
"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
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.
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.
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.
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:
gtk_icon_theme_add_builtin_icon()
). This means
big images are not feasible as they will stay in memory.
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.
#define SCW_TYPE_TIMESTAMP (scw_timestamp_get_type ())
The timestamp type for creating automatically formatted time columns in the model.
#define SCW_TYPE_PRESENCE (scw_presence_get_type ())
The presence type for creating specialized textual model columns.
#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.
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. |
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. |
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" |
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. |
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. |
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. |
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
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
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
interaction
" property"interaction" ScwInteraction : Read / Write
The method of interaction with the view.
Default value: SCW_INTERACTION_SELECT
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
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
selection-column-separator
" property"selection-column-separator" gchararray : Read / Write
The string used to separate columns in selections.
Default value: NULL
selection-row-separator
" property"selection-row-separator" gchararray : Read / Write
The string used to separate rows in selections.
Default value: NULL
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
column-spacing
" style property"column-spacing" gint : Read
Amount of empty space to leave between columns.
Allowed values: >= 0
Default value: 6
even-row-color
" style property"even-row-color" GdkColor : Read
Color to use for even rows, also used as the background color.
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
void user_function (ScwView *scwview, gchar *arg1, gchar *arg2, gpointer user_data) : Run first
The activate signal is emitted when the user clicks on an activatable text in the view (text enclosed in an action tag) with the first mouse button.
scwview : |
the object which received the signal. |
action_id : |
the id attribute of an action tag. |
action_data : |
the text enclosed in an action tag. |
user_data : |
user data set when the signal handler was connected. |
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. |
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. |
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. |