Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Public Member Functions | Protected Member Functions
Xfc::Gtk::ListStore Class Reference

A GtkListStore C++ wrapper class. More...

#include <xfc/gtk/liststore.hh>

Inheritance diagram for Xfc::Gtk::ListStore:
Xfc::G::Object Xfc::Gtk::TreeModel Xfc::Gtk::TreeSortable Xfc::Gtk::TreeDragSource Xfc::Gtk::TreeDragDest Xfc::G::TypeInstance Xfc::G::TypeInterface Xfc::G::TypeInterface Xfc::G::TypeInterface Xfc::G::TypeInterface Xfc::Trackable Xfc::G::TypeInstance Xfc::G::TypeInstance Xfc::G::TypeInstance Xfc::G::TypeInstance Xfc::Trackable Xfc::Trackable Xfc::Trackable Xfc::Trackable

List of all members.

Public Member Functions

Protected Member Functions

Constructors


Detailed Description

A GtkListStore C++ wrapper class.

The ListStore object is a list model for use with a TreeView widget. It implements the TreeModel interface, and consequentialy, can use all of the methods available there. It also implements the TreeSortable interface so it can be sorted by the view. Finally, it also implements the tree drag and drop interfaces.

Example: Creating a simple list store.

 #include <xfc/main.hh>
 #include <xfc/gtk/window.hh>
 #include <xfc/gtk/liststore.hh>
 #include <xfc/gtk/treeview.hh>
 #include <xfc/gtk/cellrenderer.hh>

 using namespace Xfc;

 class ListStoreWindow : public Gtk::Window
 {
        Pointer<Gtk::ListStore> list_store;
        Gtk::TreeView *tree_view;
 public:
        ListStoreWindow();
 };

 enum
 {
        COLUMN_STRING,
        COLUMN_INT,
        COLUMN_BOOLEAN,
        N_COLUMNS
 };

 ListStoreWindow::ListStoreWindow()
 {
        list_store = new Gtk::ListStore(N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN);

        Gtk::TreeIter iter;
        for (int i = 0; i < 10; i++)
        {
                // Add a new row to the model
                iter = list_store->append();
                list_store->set_value(iter, COLUMN_STRING, "Some Data");
                list_store->set_value(iter, COLUMN_INT, i);
                list_store->set_value(iter, COLUMN_BOOLEAN, false);
        }

        // Modify a particular row
        Pointer<Gtk::TreePath> path = new Gtk::TreePath("4");
        list_store->get_iter(iter, *path);
        list_store->set_value(iter, COLUMN_BOOLEAN, true);

        // Create a TreeView
        tree_view = new Gtk::TreeView(*list_store);

        // Create first column, associating the "text" attribute of the cell_renderer
        // with the first column of the list_store. Add column to TreeView.
        Gtk::CellRendererText *renderer = new Gtk::CellRendererText;
        renderer->property_foreground().set("red");
        Gtk::TreeViewColumn *column = new Gtk::TreeViewColumn("Text", renderer, "text", COLUMN_STRING, 0);
        tree_view->append_column(*column);

        // Create second column, associating the "text" attribute of the cell_renderer
        // with the second column of the list_store. Add column to TreeView.
        renderer = new Gtk::CellRendererText;
        renderer->property_foreground().set("blue");
        column = new Gtk::TreeViewColumn("Number", renderer, "text", COLUMN_INT, 0);
        tree_view->append_column(*column);

        // Create third column, associating the "active" attribute of the toggle cell_renderer
        // with the second column of the list_store. Add column to TreeView. To update checkbox
        // when toggled you must connect to the "toggled_signal".
        Gtk::CellRendererToggle *toggle_renderer = new Gtk::CellRendererToggle;
        column = new Gtk::TreeViewColumn("Boolean", toggle_renderer, "active", COLUMN_BOOLEAN, 0);
        tree_view->append_column(*column);

        add(*tree_view);
        show_all();
 }

 int main (int argc, char *argv[])
 {
        using namespace Main;

        init(&argc, &argv);

        ListStoreWindow window;
        window.signal_destroy().connect(slot(&Xfc::Main::quit));

        run();
        return 0;
 }

Note: dynamically allocated objects must either be unreferenced or assigned to a smart pointer. Stack objects are automatically unreferenced when they go out of scope.

See also: the TreeView Widget HOWTO and example.


Constructor & Destructor Documentation

Xfc::Gtk::ListStore::ListStore ( ) [protected]

Constructs a new list store with a reference count of 1 that the caller owns.

After calling this constructor you must call set_column_types() to set the column types for the list store.

Xfc::Gtk::ListStore::ListStore ( GtkListStore *  list_store,
bool  owns_reference = true 
) [explicit, protected]

Construct a new ListStore from an existing GtkListStore.

Parameters:
list_storeA pointer to a GtkListStore.
owns_referenceSet false if the initial reference count is floating, set true if it's not.

The list_store can be a newly created GtkListStore or an existing GtkListStore (see G::Object::Object).

Xfc::Gtk::ListStore::ListStore ( int  n_columns,
  ... 
)

Construct a list store of n_columns columns of each of the types passed in the variable argument list.

Parameters:
n_columnsThe number of columns in the list store.
...All the GType types for the columns, from first to last.

As an example, ListStore(3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_PIXBUF) will create a new list store with three columns, of type int, string and GdkPixbuf respectively. ListStore is created with a reference count of 1 that the caller owns.

Xfc::Gtk::ListStore::ListStore ( int  n_columns,
const GType *  types 
)

Construct a list store of n_columns columns of each of the types passed in the array of GType.

Parameters:
n_columnsThe number of columns in the list store.
typesAn array of GType containing the column types, from first to last.

ListStore is created with a reference count of 1 that the caller owns.


Member Function Documentation

Appends a new row to a ListStore.

Returns:
An unset TreeIter set to the appended row.

The row will be empty after this method is called. To fill in values, you need to call set_value(), set_object() or set_pointer().

Inserts a new row at position.

Parameters:
positionThe position to insert the new row.
Returns:
An unset TreeIter set to the inserted row.

If position is larger than the number of rows on the list, then the new row will be appended to the list.The row will be empty after this method is called. To fill in values, you need to call set_value(), set_object() or set_pointer().

Inserts a new row after sibling.

Parameters:
siblingA valid TreeIter.
Returns:
An unset TreeIter set to the inserted row.

The row will be empty after this method is called. To fill in values, you need to call set_value(), set_object() or set_pointer().

Inserts a new row before sibling.

Parameters:
siblingA valid TreeIter.
Returns:
An unset TreeIter set to the inserted row.

The row will be empty after this method is called. To fill in values, you need to call set_value(), set_object() or set_pointer().

TreeIter Xfc::Gtk::ListStore::insert_with_values ( int  position,
const TreeRowValues values 
)

Creates a new row at position and fills the row with the values in values.

Parameters:
positionThe position to insert the new row.
valuesA TreeRowValues object that holds the column values to set for the new row.
Returns:
A TreeIter set to the new row.

If position is larger than the number of rows on the list, then the new row will be appended to the list. Calling insert_with_values() has the same effect as calling:

< TreeIter iter = list_store->insert(position);
< list_store->set_value(iter, column, value);
<

with the difference that the former will only emit a "row_inserted" signal, while the latter will emit "row_inserted", "row_changed" and, if the list store is sorted, "rows_reordered". Since emitting the "rows_reordered" signal repeatedly can affect the performance of the program, insert_with_values() should generally be preferred when inserting rows in a sorted list store. To use insert_with_values() do something like this:

< enum { TEXT_COLUMN, COLOR_COLUMN, PIXBUF_COLUMN, N_COLUMNS };
< Gtk::ListStore *model; // allocated somewhere else    
< ...
< TreeRowValues values;
< values.add(TEXT_COLUMN, "text");
< values.add(COLOR_COLUMN, "color");
< values.add_object(GDK_TYPE_PIXBUF, PIXBUF_COLUMN, pixbuf);
< model->insert_with_values(row_number, values);
<
bool Xfc::Gtk::ListStore::iter_is_valid ( const TreeIter iter) const

Checks if the given iter is a valid iter for the list store.

Parameters:
iterA TreeIter.
Returns:
true if the iter is valid, false if it's not.

WARNING: This function is slow. Only use it for debugging and/or testing purposes.

void Xfc::Gtk::ListStore::move_after ( const TreeIter iter,
const TreeIter position 
)

Moves iter in the list store to the position after position.

Parameters:
iterA TreeIter.
positionA TreeIter, or null.

Note: This function only works with unsorted stores. If position is null, iter will be moved to the start of the list.

void Xfc::Gtk::ListStore::move_before ( const TreeIter iter,
const TreeIter position 
)

Moves iter in the list store to the position before position.

Parameters:
iterA TreeIter.
positionA TreeIter, or null.

Note: This function only works with unsorted stores. If position is null, iter will be moved to the end of the list.

Prepends a new row to a ListStore.

Returns:
An unset TreeIter set to the prepended row.

The row will be empty after this method is called. To fill in values, you need to call set_value(), set_object() or set_pointer().

Removes the given row from the list store.

Parameters:
iterA valid TreeIter.
Returns:
true if iter is valid, false if it's not.

After being removed, iter is set to be the next valid row, or invalidated if it pointed to the last row in list_store.

void Xfc::Gtk::ListStore::reorder ( int *  new_order)

Reorders the list store to follow the order indicated by new_order.

Parameters:
new_orderAn integer array indicating the new order for the list.

Note: This method only works with unsorted stores.

void Xfc::Gtk::ListStore::set_column_types ( int  n_columns,
const GType *  types 
) [protected]

Sets the column types for the list store.

Parameters:
n_columnsThe number of columns in the list store.
typesAn array of GType containing the column types, from first to last.

This method is meant primarily for objects that derive from ListStore, and and should only be used when constructing a new list store. It will not function after a row has been added, or a method on the Gtk::TreeModel interface is called.

template<typename DataType >
void Xfc::Gtk::ListStore::set_enum ( const TreeIter iter,
int  column,
const DataType &  data 
)

Sets the enum data in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
dataThe enum value to set.

This method is used to set enumeration values. The DataType is the type of the enumeration being set. There is a good example of setting values in the xfc-demo program <demos/xfc-demo/liststore.cc>.

template<typename DataType >
void Xfc::Gtk::ListStore::set_object ( const TreeIter iter,
int  column,
const DataType &  data 
)

Sets the object pointer data in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
dataA pointer to an object derived from G::Object, passed by reference.

There is a good example of setting values in the xfc-demo program <demos/xfc-demo/liststore.cc>.

template<typename DataType >
void Xfc::Gtk::ListStore::set_pointer ( const TreeIter iter,
int  column,
const DataType &  data 
)

Sets the pointer data in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
dataThe pointer to set in the cell.

The data argument can be a pointer to any object. The pointer is managed internally as a generic (void*) pointer. Unlike set_object() which passes the G::Object pointer internally as a GObject pointer, set_pointer() passes the pointer as is, without interpretation. There is a good example of setting values in the xfc-demo program <demos/xfc-demo/liststore.cc>.

void Xfc::Gtk::ListStore::set_value ( const TreeIter iter,
int  column,
const G::Value value 
)

Sets the data in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
valueThe new value for the cell.

The type of value must be convertible to the type of the column.

void Xfc::Gtk::ListStore::set_value ( const TreeIter iter,
int  column,
const char *  str 
)

Sets a string value in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
strThe new string for the cell.
void Xfc::Gtk::ListStore::set_value ( const TreeIter iter,
int  column,
const std::string &  str 
)

Sets a string value in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
strThe new string for the cell.
template<typename DataType >
void Xfc::Gtk::ListStore::set_value ( const TreeIter iter,
int  column,
const DataType &  data 
)

Sets the data in the cell specified by iter and column.

Parameters:
iterA valid TreeIter for the row being modified.
columnThe column number to modify.
dataThe data to set for the cell.

This method is used to set values corresponding to the standard data types used by G::Value, such as bool, int, double, String and unsigned int. There is a good example of setting values in the xfc-demo program <demos/xfc-demo/liststore.cc>.

void Xfc::Gtk::ListStore::swap ( const TreeIter a,
const TreeIter b 
)

Swaps a and b in the list store.

Parameters:
aA TreeIter.
bAnother TreeIter.

Note: This method only works with unsorted stores.


The documentation for this class was generated from the following file:
Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC