## InfGtkBrowserModel

InfGtkBrowserModel — Interface for tree models representing infinote directories

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | inf_gtk_browser_model_set_browser ()
void | inf_gtk_browser_model_resolve ()
gboolean | inf_gtk_browser_model_browser_iter_to_tree_iter ()

## Signals

void | set-browser | Run Last

## Types and Values

#define | INF_GTK_TYPE_BROWSER_MODEL_STATUS
| InfGtkBrowserModel
struct | InfGtkBrowserModelInterface
enum | InfGtkBrowserModelStatus
enum | InfGtkBrowserModelColumn

## Object Hierarchy

        GEnum
        ╰── InfGtkBrowserModelStatus
        GInterface
        ╰── InfGtkBrowserModel

## Prerequisites

InfGtkBrowserModel requires GtkTreeModel and GObject.

## Known Implementations

InfGtkBrowserModel is implemented by InfGtkBrowserModelFilter, InfGtkBrowserModelSort and InfGtkBrowserStore.

## Includes

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

## 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.

## Functions

### 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.

#### Parameters

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.

#### Parameters

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` .

#### Parameters

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. | [out]

#### Returns

Whether `tree_iter` was set.

## Types and Values

### 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 InfGtkBrowserModelInterface

    struct InfGtkBrowserModelInterface {
      /* 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.

#### Members

`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

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

#### Members

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

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

#### Members

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. |

## Signal Details

### The `“set-browser”` signal

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

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.

#### Parameters

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. |

Flags: Run Last

## See Also

InfGtkBrowserStore