diff options
Diffstat (limited to 'desktop/treeview.h')
-rw-r--r-- | desktop/treeview.h | 157 |
1 files changed, 138 insertions, 19 deletions
diff --git a/desktop/treeview.h b/desktop/treeview.h index d21a8a43b..0bcd7bc01 100644 --- a/desktop/treeview.h +++ b/desktop/treeview.h @@ -35,12 +35,12 @@ struct treeview_node; enum treeview_relationship { TREE_REL_FIRST_CHILD, TREE_REL_NEXT_SIBLING -}; +}; /**< Relationship between nodes */ enum treeview_msg { - TREE_MSG_NODE_DELETE, - TREE_MSG_NODE_EDIT, - TREE_MSG_NODE_LAUNCH + TREE_MSG_NODE_DELETE, /**< Node to be deleted */ + TREE_MSG_NODE_EDIT, /**< Node to be edited */ + TREE_MSG_NODE_LAUNCH /**< Node to be launched */ }; struct treeview_node_msg { enum treeview_msg msg; /**< The message type */ @@ -63,39 +63,108 @@ enum treeview_field_flags { }; struct treeview_field_desc { - lwc_string *field; - enum treeview_field_flags flags; -}; + lwc_string *field; /**< A treeview field name */ + enum treeview_field_flags flags; /**< Flags for field */ +}; /**< Treeview field description */ struct treeview_field_data { - lwc_string *field; - const char *value; - size_t value_len; + lwc_string *field; /**< Field name */ + const char *value; /**< Field value */ + size_t value_len; /**< Field value length (bytes) */ }; struct treeview_callback_table { nserror (*folder)(struct treeview_node_msg msg, void *data); nserror (*entry)(struct treeview_node_msg msg, void *data); -}; +}; /**< Client callbacks for events concerning nodes */ +/** + * Prepare treeview module for treeview usage + * + * \return NSERROR_OK on success, appropriate error otherwise + */ nserror treeview_init(void); + +/** + * Finalise the treeview module (all treeviews must have been destroyed first) + * + * \return NSERROR_OK on success, appropriate error otherwise + */ nserror treeview_fini(void); +/** + * Create a treeview + * + * \param tree Returns created treeview object + * \param callbacks Treeview client node event callbacks + * \param n_fields Number of treeview fields (see description) + * \param fields Array of treeview fields + * \param cw_t Callback table for core_window containing the treeview + * \param cw The core_window in which the treeview is shown + * \return NSERROR_OK on success, appropriate error otherwise + * + * The fields array order is as follows (N = n_fields): + * + * fields[0] Main field for entries (shown when not expanded) + * fields[1]...fields[N-2] Additional fields for entries + * fields[N-1] Field for folder nodes + * + * So fields[0] and fields[N-1] have TREE_FLAG_DEFAULT set. + */ nserror treeview_create(struct treeview **tree, const struct treeview_callback_table *callbacks, int n_fields, struct treeview_field_desc fields[], const struct core_window_callback_table *cw_t, struct core_window *cw); +/** + * Destroy a treeview object + * + * \param tree Treeview object to destroy + * \return NSERROR_OK on success, appropriate error otherwise + * + * Will emit folder and entry deletion msg callbacks for all nodes in treeview. + */ nserror treeview_destroy(struct treeview *tree); +/** + * Create a folder node in given treeview + * + * \param tree Treeview object in which to create folder + * \param folder Returns created folder node + * \param relation Existing node to insert as relation of, or NULL + * \param rel Folder's relationship to relation + * \param field Field data + * \param data Client data for node event callbacks + * \return NSERROR_OK on success, appropriate error otherwise + * + * Field name must match name past in treeview_create fields[N-1]. + * + * If relation is NULL, will insert as child of root node. + */ nserror treeview_create_node_folder(struct treeview *tree, struct treeview_node **folder, struct treeview_node *relation, enum treeview_relationship rel, const struct treeview_field_data *field, void *data); + +/** + * Create an entry node in given treeview + * + * \param tree Treeview object in which to create entry + * \param entry Returns created entry node + * \param relation Existing node to insert as relation of, or NULL + * \param rel Folder's relationship to relation + * \param fields Array of field data + * \param data Client data for node event callbacks + * \return NSERROR_OK on success, appropriate error otherwise + * + * Fields array names must match names past in treeview_create fields[0...N-2]. + * + * If relation is NULL, will insert as child of root node. + */ nserror treeview_create_node_entry(struct treeview *tree, struct treeview_node **entry, struct treeview_node *relation, @@ -103,41 +172,91 @@ nserror treeview_create_node_entry(struct treeview *tree, const struct treeview_field_data fields[], void *data); +/** + * Update an entry node in given treeview + * + * \param tree Treeview object in which to create entry + * \param entry Entry node to update + * \param fields Array of new field data + * \param data Client data for node event callbacks + * \return NSERROR_OK on success, appropriate error otherwise + * + * Fields array names must match names past in treeview_create fields[0...N-2]. + */ nserror treeview_update_node_entry(struct treeview *tree, struct treeview_node *entry, const struct treeview_field_data fields[], void *data); +/** + * Delete a treeview node + * + * \param tree Treeview object to delete node from + * \param n Node to delete + * \return NSERROR_OK on success, appropriate error otherwise + * + * Will emit folder or entry deletion msg callback. + */ nserror treeview_delete_node(struct treeview *tree, struct treeview_node *n); +/** + * Expand a treeview node + * + * \param tree Treeview object to expande node in + * \param node Node to expand + * \return NSERROR_OK on success, appropriate error otherwise + */ nserror treeview_node_expand(struct treeview *tree, struct treeview_node *node); + +/** + * Contract a treeview node + * + * \param tree Treeview object to contract node in + * \param node Node to contract + * \return NSERROR_OK on success, appropriate error otherwise + */ nserror treeview_node_contract(struct treeview *tree, struct treeview_node *node); +/** + * Redraw a treeview object + * + * \param tree Treeview object to render + * \param x X coordinate to render treeview at + * \param x Y coordinate to render treeview at + * \param clip Current clip rectangle + * \param ctx Current redraw context + */ void treeview_redraw(struct treeview *tree, int x, int y, struct rect *clip, const struct redraw_context *ctx); /** * Handles all kinds of mouse action * - * \param tree Treeview - * \param mouse the mouse state at action moment - * \param x X coordinate - * \param y Y coordinate + * \param tree Treeview object + * \param mouse The current mouse state + * \param x X coordinate + * \param y Y coordinate */ void treeview_mouse_action(struct treeview *tree, browser_mouse_state mouse, int x, int y); struct treeview_node * treeview_get_root(struct treeview *tree); +/** + * Determine whether treeview has a selection + * + * \param tree Treeview object to delete node from + * \return true iff treeview has a selection + */ bool treeview_has_selection(struct treeview *tree); /** * Clear any selection in a treeview * - * \param tree treeview to clear selection in - * \param rect redraw rectangle (if redraw required) + * \param tree Treeview object to clear selection in + * \param rect Redraw rectangle (if redraw required) * \return true iff redraw required */ bool treeview_clear_selection(struct treeview *tree, struct rect *rect); @@ -145,8 +264,8 @@ bool treeview_clear_selection(struct treeview *tree, struct rect *rect); /** * Select all in a treeview * - * \param tree treeview to select all in - * \param rect redraw rectangle (if redraw required) + * \param tree Treeview object to select all in + * \param rect Redraw rectangle (if redraw required) * \return true iff redraw required */ bool treeview_select_all(struct treeview *tree, struct rect *rect); |