SourceList

A widget that can display a list of items organized in categories.

The source list widget consists of a collection of items, some of which are also expandable (and thus can contain more items). All the items displayed in the source list are children of the widget's root item. The API is meant to be used as follows:

1. Create the items you want to display in the source list, setting the appropriate values for their properties. The desired hierarchy is achieved by creating expandable items and adding items to them. These will be displayed as descendants in the widget's tree structure. The expandable items that are not nested inside any other item are considered to be at root level, and should be added to the widget's root item.

Expandable items located at the root level are treated as categories, and only support text.

Example
The final tree will have the following structure:

Libraries
  Music
Stores
  My Store
     Music
     Podcasts
Devices
  Player 1
  Player 2

var library_category = new Granite.Widgets.SourceList.ExpandableItem ("Libraries");
var store_category = new Granite.Widgets.SourceList.ExpandableItem ("Stores");
var device_category = new Granite.Widgets.SourceList.ExpandableItem ("Devices");

var music_item = new Granite.Widgets.SourceList.Item ("Music");

// "Libraries" will be the parent category of "Music"
library_category.add (music_item);

// We plan to add sub-items to the store, so let's use an expandable item
var my_store_item = new Granite.Widgets.SourceList.ExpandableItem ("My Store");
store_category.add (my_store_item);

var my_store_podcast_item = new Granite.Widgets.SourceList.Item ("Podcasts");
var my_store_music_item = new Granite.Widgets.SourceList.Item ("Music");

my_store_item.add (my_store_music_item);
my_store_item.add (my_store_podcast_item);

var player1_item = new Granite.Widgets.SourceList.Item ("Player 1");
var player2_item = new Granite.Widgets.SourceList.Item ("Player 2");

device_category.add (player1_item);
device_category.add (player2_item);

2. Create a source list widget.

var source_list = new Granite.Widgets.SourceList ();

3. Add root-level items to the Granite.Widgets.SourceList.root item. This item only serves as a container, and all its properties are ignored by the widget.

// This will add the main categories (including their children) to the source list. After
// having being added to be widget, any other item added to any of these items
// (or any other child item in a deeper level) will be automatically added too.
// There's no need to deal with the source list widget directly.

var root = source_list.root;

root.add (library_category);
root.add (store_category);
root.add (device_category);

The steps mentioned above are enough for initializing the source list. Future changes to the items' properties are automatically reflected by the widget.

Final steps would involve connecting handlers to the source list events, being Granite.Widgets.SourceList.item_selected the most important, as it indicates that the selection was modified.

Pack the source list into the GUI using the Gtk.Paned widget. This is usually done as follows:

var pane = new Gtk.Paned (Gtk.Orientation.HORIZONTAL);
pane.pack1 (source_list, false, false);
pane.pack2 (content_area, true, false);

Since:

0.2

See also:

Gtk.Paned