InfGtkBrowserModel

InfGtkBrowserModel — Interface for tree models representing infinote directories

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfgtk/inf-gtk-browser-model.h>

#define             INF_GTK_TYPE_BROWSER_MODEL_STATUS
                    InfGtkBrowserModel;
struct              InfGtkBrowserModelIface;
enum                InfGtkBrowserModelStatus;
enum                InfGtkBrowserModelColumn;
void                inf_gtk_browser_model_set_browser   (InfGtkBrowserModel *model,
                                                         GtkTreePath *path,
                                                         GtkTreeIter *iter,
                                                         InfBrowser *old_browser,
                                                         InfBrowser *new_browser);
void                inf_gtk_browser_model_resolve       (InfGtkBrowserModel *model,
                                                         InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);
gboolean            inf_gtk_browser_model_browser_iter_to_tree_iter
                                                        (InfGtkBrowserModel *model,
                                                         InfBrowser *browser,
                                                         const InfBrowserIter *iter,
                                                         GtkTreeIter *tree_iter);

Object Hierarchy

  GInterface
   +----InfGtkBrowserModel
  GEnum
   +----InfGtkBrowserModelStatus

Prerequisites

InfGtkBrowserModel requires GtkTreeModel and GObject.

Known Implementations

InfGtkBrowserModel is implemented by InfGtkBrowserModelFilter, InfGtkBrowserModelSort and InfGtkBrowserStore.

Signals

  "set-browser"                                    : Run Last

Description

InfGtkBrowserModel provides an interface for tree models that are used to show the contents of infinote directories. All implementations of InfGtkBrowserModel also need to implement GtkTreeModel and can then by displayed in a GtkTreeView.

InfGtkBrowserStore is a reference implementation of this interface, allowing to add discoveries and browsers to it which it then manages. Other implementations include InfGtkBrowserModelSort and InfGtkBrowserModelFilter which can be used to sort or filter the list.

Details

INF_GTK_TYPE_BROWSER_MODEL_STATUS

#define INF_GTK_TYPE_BROWSER_MODEL_STATUS          (inf_gtk_browser_model_status_get_type())


InfGtkBrowserModel

typedef struct _InfGtkBrowserModel InfGtkBrowserModel;

InfGtkBrowserModel is an opaque data type. You should only access it via the public API functions.


struct InfGtkBrowserModelIface

struct InfGtkBrowserModelIface {
  /* signals */
  void(*set_browser)(InfGtkBrowserModel* model,
                     GtkTreePath* path,
                     GtkTreeIter* iter,
                     InfBrowser* old_browser,
                     InfBrowser* new_browser);

  /* virtual functions */
  void(*resolve)(InfGtkBrowserModel* model,
                 InfDiscovery* discovery,
                 InfDiscoveryInfo* info);

  gboolean(*browser_iter_to_tree_iter)(InfGtkBrowserModel* model,
                                       InfBrowser* browser,
                                       const InfBrowserIter* iter,
                                       GtkTreeIter* tree_iter);
};

This structure contains virtual functions and signal handlers of the InfGtkBrowserModel interface.

set_browser ()

Default signal handler of the "set-browser" signal.

resolve ()

Virtual function for resolving a discovered infinote service.

browser_iter_to_tree_iter ()

Virtual function for converting a InfBrowserIter to a GtkTreeIter.

enum InfGtkBrowserModelStatus

typedef enum {
  INF_GTK_BROWSER_MODEL_INVALID,
  INF_GTK_BROWSER_MODEL_DISCOVERED,
  INF_GTK_BROWSER_MODEL_RESOLVING,
  INF_GTK_BROWSER_MODEL_DISCONNECTED,
  INF_GTK_BROWSER_MODEL_CONNECTING,
  INF_GTK_BROWSER_MODEL_CONNECTED,
  INF_GTK_BROWSER_MODEL_ERROR
} InfGtkBrowserModelStatus;

The different statuses an item in the InfGtkBrowserModel can have. The status of an item is only defined for toplevel items in the tree.

INF_GTK_BROWSER_MODEL_INVALID

Invalid state. A healthy item should not have this status.

INF_GTK_BROWSER_MODEL_DISCOVERED

The item was discovered with a InfDiscovery, but no attempt has been made at connecting to it.

INF_GTK_BROWSER_MODEL_RESOLVING

The item was discovered with a InfDiscovery and is currently being resolved, see inf_discovery_resolve().

INF_GTK_BROWSER_MODEL_DISCONNECTED

A connection attempt to the remote site was not successful, or the connection was lost. The connection parameters are known, but currently no connection is established.

INF_GTK_BROWSER_MODEL_CONNECTING

A connection attempt to the remote site is currently in progress.

INF_GTK_BROWSER_MODEL_CONNECTED

A connection to the remote site has been established and its directory can be browsed.

INF_GTK_BROWSER_MODEL_ERROR

An error has occured with this item. The column with index INF_GTK_BROWSER_MODEL_COL_ERROR has more information about the error that occurred.

enum InfGtkBrowserModelColumn

typedef enum {
  INF_GTK_BROWSER_MODEL_COL_DISCOVERY_INFO,
  INF_GTK_BROWSER_MODEL_COL_DISCOVERY,
  INF_GTK_BROWSER_MODEL_COL_BROWSER,
  INF_GTK_BROWSER_MODEL_COL_STATUS, /* only toplevel */
  INF_GTK_BROWSER_MODEL_COL_NAME,
  INF_GTK_BROWSER_MODEL_COL_ERROR,
  INF_GTK_BROWSER_MODEL_COL_NODE,

  INF_GTK_BROWSER_MODEL_NUM_COLS
} InfGtkBrowserModelColumn;

The various GtkTreeModel columns that a tree model implementing InfGtkBrowserModel must support.

INF_GTK_BROWSER_MODEL_COL_DISCOVERY_INFO

The InfDiscoveryInfo of a discovered toplevel item, or NULL if the item was not discovered.

INF_GTK_BROWSER_MODEL_COL_DISCOVERY

The InfDiscovery object that the item has been discovered with, if any.

INF_GTK_BROWSER_MODEL_COL_BROWSER

The InfBrowser with which this item is being browsed, or NULL if no browser is available.

INF_GTK_BROWSER_MODEL_COL_STATUS

The status of this item. This column is only valid for toplevel items, i.e. for connections to directories.

INF_GTK_BROWSER_MODEL_COL_NAME

The name of the item as a simple string.

INF_GTK_BROWSER_MODEL_COL_ERROR

If an error has occurred with the item, for example the connection failed, or a node exploration failed, this column contains a GError with more error information.

INF_GTK_BROWSER_MODEL_COL_NODE

The InfBrowserIter pointing to the corresponding node of the InfBrowser.

INF_GTK_BROWSER_MODEL_NUM_COLS

The total number of columns of a InfGtkBrowserModel.

inf_gtk_browser_model_set_browser ()

void                inf_gtk_browser_model_set_browser   (InfGtkBrowserModel *model,
                                                         GtkTreePath *path,
                                                         GtkTreeIter *iter,
                                                         InfBrowser *old_browser,
                                                         InfBrowser *new_browser);

Emits the "set-browser" signal. This is supposed to only be called by implementations of InfGtkBrowserModel whenever they set or unset a browser on a row.

model :

A InfGtkBrowserModel.

path :

A GtkTreePath to a top-level row.

iter :

A GtkTreeIter pointing to the same row.

old_browser :

The browser which was set at this row before.

new_browser :

The new InfBrowser to set for this row.

inf_gtk_browser_model_resolve ()

void                inf_gtk_browser_model_resolve       (InfGtkBrowserModel *model,
                                                         InfDiscovery *discovery,
                                                         InfDiscoveryInfo *info);

Resolves info and adds the resulting connection to the model. If that connection is already contained, the original (newly resolved) entry is removed in favor of the existing entry whose browser might already have explored (parts of) the server's directory.

model :

A InfGtkBrowserModel.

discovery :

A InfDiscovery added to store.

info :

A InfDiscoveryInfo discovered by discovery.

inf_gtk_browser_model_browser_iter_to_tree_iter ()

gboolean            inf_gtk_browser_model_browser_iter_to_tree_iter
                                                        (InfGtkBrowserModel *model,
                                                         InfBrowser *browser,
                                                         const InfBrowserIter *iter,
                                                         GtkTreeIter *tree_iter);

Sets tree_iter to point to the same node iter refers to within the model. If browser is not known to model, i.e. its connection was never added to model, then the function returns FALSE and tree_iter is left untouched.

If iter is NULL, the function sets tree_iter to point to the top level entry representing browser.

model :

A InfGtkBrowserModel.

browser :

A InfBrowser.

iter :

A InfBrowserIter pointing into browser, or NULL.

tree_iter :

A GtkTreeIter that will be set by this function.

Returns :

Whether tree_iter was set.

Signal Details

The "set-browser" signal

void                user_function                      (InfGtkBrowserModel *model,
                                                        GtkTreePath        *path,
                                                        GtkTreeIter        *iter,
                                                        InfBrowser         *old_browser,
                                                        InfBrowser         *new_browser,
                                                        gpointer            user_data)        : Run Last

This signal is emitted every time the InfBrowser for one of the model's top-level entries change. This means either that a completely new item was inserted, that an item providing only a discovery has been resolved (see inf_gtk_browser_model_resolve()), or that a top-level entry has been removed.

During emission of the signal the actual value in the model might either be the old or the new browser.

model :

The InfGtkBrowserModel emitting the signal.

path :

A GtkTreePath pointing to the item with a new browesr.

iter :

A GtkTreeIter pointing to the item with a new browser.

old_browser :

The previous InfBrowser.

new_browser :

The new InfBrowser.

user_data :

user data set when the signal handler was connected.

See Also

InfGtkBrowserStore