GwyNullStore: Gwyddion Widgets Library Reference Manual

## GwyNullStore GwyNullStore — GtkTreeModel wrapper around nothing |

## Functions

GwyNullStore * | gwy_null_store_new ()
guint | gwy_null_store_get_n_rows ()
void | gwy_null_store_set_n_rows ()
gpointer | gwy_null_store_get_model ()
void | gwy_null_store_set_model ()
void | gwy_null_store_row_changed ()
void | gwy_null_store_rows_changed ()
gboolean | gwy_null_store_iter_is_valid ()

## Types and Values

struct | GwyNullStore
struct | GwyNullStoreClass

## Object Hierarchy

        GObject
        ╰── GwyNullStore

## Implemented Interfaces

GwyNullStore implements GtkTreeModel.

## Includes

    #include <libgwyui/gwyui.h>

## Description

GwyNullStore is a very simple GtkTreeModel which pretents to have a single column of type `G_TYPE_UINT`. Values in the column are equal to row numbers (counted from 0). In reality the column is purely virtual and the store always takes up only a small constant amount of memory.

The purpose of GwyNullStore is to provide a low-overhead GtkTreeModel interface for array-like (and other indexed) data structures.

A new null store can be created with `gwy_null_store_new()`, then number of virtual rows can be controlled with `gwy_null_store_set_n_rows()`. For convenience, methods to emit "row-changed" signal on a row or a range of rows by their indices are provided: `gwy_null_store_row_changed()` and `gwy_null_store_rows_changed()`.

Since null stores often serve as wrappers around other data structures, convenience methods to attach and obtain such a data are provided: `gwy_null_store_set_model()`, `gwy_null_store_get_model()`.

A simple example to create a multiplication table with null storage:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    GtkWidget *treeview;
    GtkTreeViewColumn *column;
    GtkCellRenderer *renderer;
    GwyNullStore *store;
    gint i;

    store = gwy_null_store_new(10);
    treeview = gtk_tree_view_new_with_model(GTK_TREE_MODEL(store));
    gtk_tree_view_set_headers_visible(GTK_TREE_VIEW(treeview), FALSE);

    column = gtk_tree_view_column_new();
    for (i = 1; i <= 10; i++) {
        renderer = gtk_cell_renderer_text_new();
        g_object_set(renderer, "xalign", 1.0, "width-chars", 4, NULL);
        gtk_tree_view_column_pack_start(column, renderer, TRUE);
        gtk_tree_view_column_set_cell_data_func(column, renderer,
                                                multiply, GINT_TO_POINTER(i),
                                                NULL);
    }
    gtk_tree_view_append_column(GTK_TREE_VIEW(treeview), column);

The cell data function multiply() just multiplies the column number with the number of (virtual) null store row:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    static void
    multiply(GtkTreeViewColumn *column,
             GtkCellRenderer *renderer,
             GtkTreeModel *model,
             GtkTreeIter *iter,
             gpointer data)
    {
        gchar buf[20];
        gint i;

        gtk_tree_model_get(model, iter, 0, &i, -1);
        g_snprintf(buf, sizeof(buf), "%d", (i + 1)*GPOINTER_TO_INT(data));
        g_object_set(renderer, "text", buf, NULL);
    }

To extend the multiplication table to 20 rows, one only needs

    1
    gwy_null_store_set_n_rows(store, 20);

## Functions

### gwy_null_store_new()

    GwyNullStore *
    gwy_null_store_new (guint n);

Creates a new GtkTreeModel wrapper around nothing.

#### Parameters

n | The initial number of rows. |

#### Returns

The newly created null store.

### gwy_null_store_get_n_rows()

    guint
    gwy_null_store_get_n_rows (GwyNullStore *store);

Gets the number of imaginary rows in a null store.

This is a convenience function, the same information can be obtained with `gtk_tree_model_iter_n_children()`.

#### Parameters

store | A null store. |

#### Returns

The number of rows.

### gwy_null_store_set_n_rows()

    void
    gwy_null_store_set_n_rows (GwyNullStore *store,
                               guint n);

Sets the number of imaginary rows in a null store.

If the new number of rows is larger than the current one, rows will be sequentially and virtually appended to the end of the store until the requested number of rows is reached.

Similarly, if the new number of rows is smaller then the current one, rows will be sequentially and virtually deleted from the end of the store until the requested number of rows is reached.

Note for radical changes it is usually more useful to disconnect the model from its view(s), change the number of rows, and then reconnect.

#### Parameters

store | A null store. |
n | The new number of rows. |

### gwy_null_store_get_model()

    gpointer
    gwy_null_store_get_model (GwyNullStore *store);

Gets the model pointer of a null store.

#### Parameters

store | A null store. |

#### Returns

The pointer set with `gwy_null_store_set_model()`.

### gwy_null_store_set_model()

    void
    gwy_null_store_set_model (GwyNullStore *store,
                              gpointer model,
                              GDestroyNotify destroy);

Sets the model pointer of a null store.

While the virtual integers in GwyNullStore can be used directly, a null store typically serves as an adaptor for array-like structures and its rows are used as indices to these structures. This helper method provides means to attach such a structure to a null store in the common case.

The store itself does not interpret nor access the attached data by any means. No signals are emitted in response to the model pointer change either, particularly because it is expected to be set only once upon creation (null stores are cheap).

You are free to keep the model pointer at `NULL` if these functions do not suit your needs.

#### Parameters

store | A null store. |
model | Model pointer. |
destroy | Function to call on `model` when it is replaced or the store is destroyed. |

### gwy_null_store_row_changed()

    void
    gwy_null_store_row_changed (GwyNullStore *store,
                                guint i);

Emits "GtkTreeModel::row-changed" signal on a null store.

This is a convenience method, with a bit more work the same effect can be achieved with `gtk_tree_model_row_changed()`.

#### Parameters

store | A null store. |
i | A row to emit "row-changed" on. |

### gwy_null_store_rows_changed()

    void
    gwy_null_store_rows_changed (GwyNullStore *store,
                                 guint ifrom,
                                 guint ito);

Emits "GtkTreeModel::row-changed" signal on a block of rows in a null store.

This is a convenience method, with a bit more work the same effect can be achieved with `gtk_tree_model_row_changed()`.

It is possible to pass `ifrom` larger than `ito` . The signal is then emitted for the same rows, but in the opposite order.

#### Parameters

store | A null store. |
ifrom | The first row to emit "row-changed" on. |
ito | The last row to emit "row-changed" on (inclusive). |

### gwy_null_store_iter_is_valid()

    gboolean
    gwy_null_store_iter_is_valid (GwyNullStore *store,
                                  GtkTreeIter *iter);

Checks if the given iter is a valid iter for this null store.

#### Parameters

store | A null store. |
iter | A GtkTreeIter. |

#### Returns

`TRUE` if the iter is valid, `FALSE` if the iter is invalid.

## Types and Values

### struct GwyNullStore

    struct GwyNullStore;

### struct GwyNullStoreClass

    struct GwyNullStoreClass {
        GObjectClass parent_class;
    };

## See Also

GwyInventoryStore -- GtkTreeModel wrapper around GwyInventory