--- a/gnt.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gnt.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,13 +1,3 @@
- * @defgroup gnt GNT (GLib Ncurses Toolkit)- * GNT is an ncurses toolkit for creating text-mode graphical user interfaces- * in a fast and easy way. * GNT - The GLib Ncurses Toolkit
@@ -32,6 +22,12 @@
+ * @section_id: libgnt-gnt + * @short_description: <filename>gnt.h</filename> @@ -40,158 +36,189 @@
* Start running the mainloop for gnt.
* Check whether the terminal is capable of UTF8 display.
- * @return @c FALSE if the terminal is capable of drawing UTF-8, @c TRUE otherwise.+ * Returns: %FALSE if the terminal is capable of drawing UTF-8, %TRUE otherwise. gboolean gnt_ascii_only(void);
+ * @window: The window the present. * Present a window. If the event was triggered because of user interaction,
* the window is moved to the foreground. Otherwise, the Urgent hint is set.
- * @param window The window the present.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_window_present(GntWidget *window);
- * Use #gnt_widget_show instead.+ * Internal function -- do not use. + * Use gnt_widget_show() instead. void gnt_screen_occupy(GntWidget *widget);
- * Use #gnt_widget_hide instead.+ * Internal function -- do not use. + * Use gnt_widget_hide() instead. void gnt_screen_release(GntWidget *widget);
- * Use #gnt_widget_draw instead.+ * Internal function -- do not use. + * Use gnt_widget_draw() instead. void gnt_screen_update(GntWidget *widget);
+ * gnt_screen_resize_widget: + * @widget: The widget to resize. + * @width: The desired width. + * @height: The desired height. - * @param widget The widget to resize.- * @param width The desired width.- * @param height The desired height. void gnt_screen_resize_widget(GntWidget *widget, int width, int height);
+ * gnt_screen_move_widget: + * @widget: The widget to move. + * @x: The desired x-coordinate. + * @y: The desired y-coordinate. - * @param widget The widget to move.- * @param x The desired x-coordinate.- * @param y The desired y-coordinate. void gnt_screen_move_widget(GntWidget *widget, int x, int y);
+ * gnt_screen_rename_widget: + * @widget: The widget to rename. + * @text: The new name for the widget. - * @param widget The widget to rename.- * @param text The new name for the widget. void gnt_screen_rename_widget(GntWidget *widget, const char *text);
+ * gnt_widget_has_focus: * Check whether a widget has focus.
- * @param widget The widget.- * @return @c TRUE if the widget has the current focus, @c FALSE otherwise.+ * Returns: %TRUE if the widget has the current focus, %FALSE otherwise. gboolean gnt_widget_has_focus(GntWidget *widget);
- * Set the URGENT hint for a widget.+ * gnt_widget_set_urgent: + * @widget: The widget to set the URGENT hint for. - * @param widget The widget to set the URGENT hint for.+ * Set the URGENT hint for a widget. void gnt_widget_set_urgent(GntWidget *widget);
- * Register a global action.+ * @label: The user-visible label for the action. + * @callback: The callback function for the action. - * @param label The user-visible label for the action.- * @param callback The callback function for the action.+ * Register a global action. void gnt_register_action(const char *label, void (*callback)(void));
+ * gnt_screen_menu_show: + * @menu: The menu to display. - * @param menu The menu to display.- * @return @c TRUE if the menu is displayed, @c FALSE otherwise (e.g., if another menu is currently displayed).+ * Returns: %TRUE if the menu is displayed, %FALSE otherwise (e.g., if another menu is currently displayed). gboolean gnt_screen_menu_show(gpointer menu);
* Terminate the mainloop of gnt.
* Get the global clipboard.
- * @return The clipboard.+ * Returns: (transfer none): The clipboard. GntClipboard * gnt_get_clipboard(void);
+ * gnt_get_clipboard_string: * Get the string in the clipboard.
- * @return A copy of the string in the clipboard. The caller must @c g_free the string.+ * Returns: A copy of the string in the clipboard. The caller + * must g_free() the string. gchar * gnt_get_clipboard_string(void);
- * Set the contents of the global clipboard.+ * gnt_set_clipboard_string: + * @string: The new content of the new clipboard. - * @param string The new content of the new clipboard.+ * Set the contents of the global clipboard. void gnt_set_clipboard_string(const gchar *string);
+ * @wd: The working directory for the new application. + * @argv: The argument vector. + * @envp: The environment, or %NULL. + * @stin: Location to store the child's stdin, or %NULL. + * @stout: Location to store the child's stdout, or %NULL. + * @sterr: Location to store the child's stderr, or %NULL. + * @callback: The callback to call after the child exits. + * @data: The data to pass to the callback. * Spawn a different application that will consume the console.
- * @param wd The working directory for the new application.- * @param argv The argument vector.- * @param envp The environment, or @c NULL.- * @param stin Location to store the child's stdin, or @c NULL.- * @param stout Location to store the child's stdout, or @c NULL.- * @param sterr Location to store the child's stderr, or @c NULL.- * @param callback The callback to call after the child exits.- * @param data The data to pass to the callback.- * @return @c TRUE if the child was successfully spawned, @c FALSE otherwise.+ * Returns: %TRUE if the child was successfully spawned, %FALSE otherwise. gboolean gnt_giveup_console(const char *wd, char **argv, char **envp,
gint *stin, gint *stout, gint *sterr,
void (*callback)(int status, gpointer data), gpointer data);
* Check whether a child process is in control of the current terminal.
- * @return @c TRUE if a child process (eg., PAGER) is occupying the current- * terminal, @c FALSE otherwise.+ * Returns: %TRUE if a child process (eg., PAGER) is occupying the current + * terminal, %FALSE otherwise. gboolean gnt_is_refugee(void);
--- a/gntbindable.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntbindable.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntbindable.h Bindable API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntbindable + * @short_description: <filename>gntbindable.h</filename> @@ -59,6 +61,7 @@
GntBindable * help_window;
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
void (*gnt_reserved4)(void);
@@ -66,11 +69,6 @@
GType gnt_bindable_get_type(void);
@@ -91,8 +89,8 @@
char *name; /* The name of the action */
- gboolean (*action)(GntBindable *bindable, GList *params);- gboolean (*action_noparam)(GntBindable *bindable);+ GntBindableActionCallback action; + GntBindableActionCallbackNoParam action_noparam; @@ -105,85 +103,94 @@
/*GntBindableAction *gnt_bindable_action_parse(const char *name);*/
- * Free a bindable action.+ * gnt_bindable_action_free: + * @action: The bindable action. - * @param action The bindable action.+ * Free a bindable action. void gnt_bindable_action_free(GntBindableAction *action);
- * Free a GntBindableActionParam.+ * gnt_bindable_action_param_free: + * @param: The GntBindableActionParam to free. - * @param param The GntBindableActionParam to free.+ * Free a GntBindableActionParam. void gnt_bindable_action_param_free(GntBindableActionParam *param);
- * Register a bindable action for a class.+ * gnt_bindable_class_register_action: + * @klass: The class the binding is for. + * @name: The name of the binding. + * @callback: (scope call): The callback for the binding. + * @trigger: The default trigger for the binding, or %NULL, followed by a + * %NULL-terminated list of default parameters. - * @param klass The class the binding is for.- * @param name The name of the binding.- * @param callback The callback for the binding.- * @param trigger The default trigger for the binding, or @c NULL, followed by a NULL-terminated- * list of default parameters.+ * Register a bindable action for a class. void gnt_bindable_class_register_action(GntBindableClass *klass, const char *name, GntBindableActionCallback callback, const char *trigger, ...);
- * Register a key-binding to an existing action.+ * gnt_bindable_register_binding: + * @klass: The class the binding is for. + * @name: The name of the binding. + * @trigger: A new trigger for the binding, followed by a %NULL-terminated list of parameters for the callback. - * @param klass The class the binding is for.- * @param name The name of the binding.- * @param trigger A new trigger for the binding, followed by a @c NULL-terminated list of parameters for the callback.+ * Register a key-binding to an existing action. void gnt_bindable_register_binding(GntBindableClass *klass, const char *name, const char *trigger, ...);
+ * gnt_bindable_perform_action_key: + * @bindable: The bindable object. + * @keys: The key to trigger the action. * Perform an action from a keybinding.
- * @param bindable The bindable object.- * @param keys The key to trigger the action.- * @return @c TRUE if the action was performed successfully, @c FALSE otherwise.+ * Returns: %TRUE if the action was performed successfully, %FALSE otherwise. gboolean gnt_bindable_perform_action_key(GntBindable *bindable, const char *keys);
+ * gnt_bindable_check_key: + * @bindable: The bindable object. + * @keys: The key to check for. * Discover if a key is bound.
- * @param bindable The bindable object.- * @param keys The key to check for.- * @return @c TRUE if the the key has an action associated with it.+ * Returns: %TRUE if the the key has an action associated with it. gboolean gnt_bindable_check_key(GntBindable *bindable, const char *keys);
+ * gnt_bindable_perform_action_named: + * @bindable: The bindable object. + * @name: The action to perform, followed by a %NULL-terminated list of parameters. * Perform an action on a bindable object.
- * @param bindable The bindable object.- * @param name The action to perform, followed by a @c NULL-terminated list of parameters.- * @return @c TRUE if the action was performed successfully, @c FALSE otherwise.+ * Returns: %TRUE if the action was performed successfully, %FALSE otherwise. gboolean gnt_bindable_perform_action_named(GntBindable *bindable, const char *name, ...) G_GNUC_NULL_TERMINATED;
+ * gnt_bindable_bindings_view: + * @bind: The object to list the bindings for. * Returns a GntTree populated with "key" -> "binding" for the widget.
- * @param bind The object to list the bindings for.+ * Returns: (transfer full): The GntTree. GntBindable * gnt_bindable_bindings_view(GntBindable *bind);
+ * gnt_bindable_build_help_window: + * @bindable: The object to list the bindings for. * Builds a window that list the key bindings for a GntBindable object.
* From this window a user can select a listing to rebind a new key for the given action.
- * @param bindable The object to list the bindings for. gboolean gnt_bindable_build_help_window(GntBindable *bindable);
--- a/gntbox.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntbox.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntbox.h Box API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntbox + * @short_description: <filename>gntbox.h</filename> @@ -69,16 +71,18 @@
GList *focus; /* List of widgets to cycle focus (only valid for parent boxes) */
- void (*gnt_reserved1)(void);- void (*gnt_reserved2)(void);- void (*gnt_reserved3)(void);- void (*gnt_reserved4)(void); void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -88,8 +92,11 @@
GType gnt_box_get_type(void);
@@ -97,110 +104,123 @@
#define gnt_hbox_new(homo) gnt_box_new(homo, FALSE)
+ * @homo: If %TRUE, all the widgets in it will have the same width (or height) + * @vert: Whether the widgets in it should be stacked vertically (if %TRUE) + * or horizontally (if %FALSE). - * @param homo If @c TRUE, all the widgets in it will have the same width (or height)- * @param vert Whether the widgets in it should be stacked vertically (if @c TRUE)- * or horizontally (if @c FALSE).- * @return The new GntBox.+ * Returns: The new GntBox. GntWidget * gnt_box_new(gboolean homo, gboolean vert);
- * Add a widget in the box.+ * @widget: The widget to add
- * @param widget The widget to add+ * Add a widget in the box. void gnt_box_add_widget(GntBox *box, GntWidget *widget);
- * Set a title for the box.+ * @title: The title to set
- * @param title The title to set+ * Set a title for the box. void gnt_box_set_title(GntBox *box, const char *title);
- * Set the padding to use between the widgets in the box.+ * @pad: The padding to use
- * @param pad The padding to use+ * Set the padding to use between the widgets in the box. void gnt_box_set_pad(GntBox *box, int pad);
+ * gnt_box_set_toplevel: + * @set: %TRUE if it's a toplevel box, %FALSE otherwise. * Set whether it's a toplevel box (ie, a window) or not. If a box is toplevel,
* then it will show borders, the title (if set) and shadow (if enabled in
- * @param set @c TRUE if it's a toplevel box, @c FALSE otherwise.+ * <filename>.gntrc</filename>) void gnt_box_set_toplevel(GntBox *box, gboolean set);
- * Reposition and refresh the widgets in the box.+ * gnt_box_sync_children:
+ * Reposition and refresh the widgets in the box. void gnt_box_sync_children(GntBox *box);
- * Set the alignment for the widgets in the box.+ * gnt_box_set_alignment: + * @alignment: The alignment to use
- * @param alignment The alignment to use+ * Set the alignment for the widgets in the box. void gnt_box_set_alignment(GntBox *box, GntAlignment alignment);
- * Remove a widget from the box. Calling this does NOT destroy the removed widget.+ * @widget: The widget to remove
- * @param widget The widget to remove+ * Remove a widget from the box. Calling this does NOT destroy the removed widget. void gnt_box_remove(GntBox *box, GntWidget *widget);
- * Remove all widgets from the box. This DOES destroy all widgets in the box.+ * Remove all widgets from the box. This DOES destroy all widgets in the box. void gnt_box_remove_all(GntBox *box);
* Readjust the size of each child widget, reposition the child widgets and
* recalculate the size of the box.
void gnt_box_readjust(GntBox *box);
- * Set whether the widgets in the box should fill the empty spaces.+ * @fill: Whether the child widgets should fill the empty space
- * @param fill Whether the child widgets should fill the empty space+ * Set whether the widgets in the box should fill the empty spaces. void gnt_box_set_fill(GntBox *box, gboolean fill);
- * Move the focus from one widget to the other.+ * @dir: The direction. If it's 1, then the focus is moved forwards, if it's + * -1, the focus is moved backwards.
- * @param dir The direction. If it's 1, then the focus is moved forwards, if it's- * -1, the focus is moved backwards.+ * Move the focus from one widget to the other. void gnt_box_move_focus(GntBox *box, int dir);
- * Give focus to a specific child widget.+ * gnt_box_give_focus_to_child: + * @widget: The child widget to give focus
- * @param widget The child widget to give focus+ * Give focus to a specific child widget. void gnt_box_give_focus_to_child(GntBox *box, GntWidget *widget);
--- a/gntentry.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntentry.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntentry.h Entry API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntentry + * @short_description: <filename>gntentry.h</filename> @@ -43,7 +45,7 @@
#define GNT_ENTRY_SET_FLAGS(obj, flags) (GNT_ENTRY_FLAGS(obj) |= flags)
#define GNT_ENTRY_UNSET_FLAGS(obj, flags) (GNT_ENTRY_FLAGS(obj) &= ~(flags))
-#define ENTRY_CHAR '_' /* The character to use to fill in the blank places */+#define GNT_ENTRY_CHAR '_' /* The character to use to fill in the blank places */ typedef struct _GntEntry GntEntry;
typedef struct _GntEntryPriv GntEntryPriv;
@@ -86,8 +88,8 @@
gboolean word; /* Are the suggestions for only a word, or for the whole thing? */
gboolean always; /* Should the list of suggestions show at all times, or only on tab-press? */
GntWidget *ddown; /* The dropdown with the suggested list */
- GntEntryKillRing *killring; /**< @since 2.3.0 */- GntEntrySearch *search; /**< @since 2.7.0 */+ GntEntryKillRing *killring; /* Since: 2.3.0 */ + GntEntrySearch *search; /* Since: 2.7.0 */ @@ -95,6 +97,8 @@
void (*text_changed)(GntEntry *entry);
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -104,115 +108,130 @@
- * @return GType for GntEntry.+ * Returns: GType for GntEntry. GType gnt_entry_get_type(void);
+ * @text: The text in the new entry box. - * @param text The text in the new entry box.- * @return The newly created entry box.+ * Returns: The newly created entry box. GntWidget * gnt_entry_new(const char *text);
- * Set the maximum length of the text in the entry box.+ * @entry: The entry box. + * @max: The maximum length for text. A value of 0 means infinite length. - * @param entry The entry box.- * @param max The maximum length for text. A value of 0 means infinite length.+ * Set the maximum length of the text in the entry box. void gnt_entry_set_max(GntEntry *entry, int max);
- * Set the text in an entry box.+ * @entry: The entry box. + * @text: The text to set in the box. - * @param entry The entry box.- * @param text The text to set in the box.+ * Set the text in an entry box. void gnt_entry_set_text(GntEntry *entry, const char *text);
- * Set flags an entry box.+ * @entry: The entry box. + * @flag: The flags to set for the entry box. - * @param entry The entry box.- * @param flag The flags to set for the entry box.+ * Set flags an entry box. void gnt_entry_set_flag(GntEntry *entry, GntEntryFlag flag);
+ * @entry: The entry box. * Get the text in an entry box.
- * @param entry The entry box.- * @return The current text in the entry box.+ * Returns: The current text in the entry box. const char *gnt_entry_get_text(GntEntry *entry);
- * Clear the text in the entry box.+ * @entry: The entry box. - * @param entry The entry box.+ * Clear the text in the entry box. void gnt_entry_clear(GntEntry *entry);
- * Set whether the text in the entry box should be masked for display.+ * gnt_entry_set_masked: + * @entry: The entry box. + * @set: %TRUE if the text should be masked, %FALSE otherwise. - * @param entry The entry box.- * @param set @c TRUE if the text should be masked, @c FALSE otherwise.+ * Set whether the text in the entry box should be masked for display. void gnt_entry_set_masked(GntEntry *entry, gboolean set);
+ * gnt_entry_add_to_history: + * @entry: The entry box. + * @text: A new entry for the history list. * Add a text to the history list for the text. The history length for the
* entry box needs to be set first by gnt_entry_set_history_length.
- * @param entry The entry box.- * @param text A new entry for the history list. void gnt_entry_add_to_history(GntEntry *entry, const char *text);
- * Set the length of history for the entry box.+ * gnt_entry_set_history_length: + * @entry: The entry box. + * @num: The maximum length of the history, -1 for unlimited. - * @param entry The entry box.- * @param num The maximum length of the history, -1 for unlimited.+ * Set the length of history for the entry box. void gnt_entry_set_history_length(GntEntry *entry, int num);
+ * gnt_entry_set_word_suggest: + * @entry: The entry box. + * @word: %TRUE if the suggestions are for individual words, %FALSE otherwise. * Set whether the suggestions are for the entire entry box, or for each
* individual word in the entry box.
- * @param entry The entry box.- * @param word @c TRUE if the suggestions are for individual words, @c FALSE otherwise. void gnt_entry_set_word_suggest(GntEntry *entry, gboolean word);
+ * gnt_entry_set_always_suggest: + * @entry: The entry box. + * @always: %TRUE if the suggestion list should always be displayed. * Set whether to always display the suggestions list, or only when the
* tab-completion key is pressed (the TAB key, by default).
- * @param entry The entry box.- * @param always @c TRUE if the suggestion list should always be displayed. void gnt_entry_set_always_suggest(GntEntry *entry, gboolean always);
- * Add an item to the suggestion list.+ * gnt_entry_add_suggest: + * @entry: The entry box. + * @text: An item to add to the suggestion list. - * @param entry The entry box.- * @param text An item to add to the suggestion list.+ * Add an item to the suggestion list. void gnt_entry_add_suggest(GntEntry *entry, const char *text);
- * Remove an entry from the suggestion list.+ * gnt_entry_remove_suggest: + * @entry: The entry box. + * @text: The item to remove from the suggestion list. - * @param entry The entry box.- * @param text The item to remove from the suggestion list.+ * Remove an entry from the suggestion list. void gnt_entry_remove_suggest(GntEntry *entry, const char *text);
--- a/gntfilesel.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntfilesel.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntfilesel.h File selector API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntfilesel + * @short_description: <filename>gntfilesel.h</filename> + * @title: File Selector @@ -75,6 +77,8 @@
void (*file_selected)(GntFileSel *sel, const char *path, const char *filename);
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -98,123 +102,140 @@
- * @return GType for GntFileSel.+ * gnt_file_sel_get_type: + * Returns: GType for GntFileSel. GType gnt_file_sel_get_type(void);
* Create a new file selector.
- * @return The newly created file selector.+ * Returns: The newly created file selector. GntWidget * gnt_file_sel_new(void);
+ * gnt_file_sel_set_current_location: + * @sel: The file selector. + * @path: The current path of the selector. * Set the current location of the file selector.
- * @param sel The file selector.- * @param path The current path of the selector.- * @return @c TRUE if the current location was successfully changed, @c FALSE otherwise.+ * Returns: %TRUE if the current location was successfully changed, %FALSE otherwise. gboolean gnt_file_sel_set_current_location(GntFileSel *sel, const char *path);
- * Set wheter to only allow selecting directories.+ * gnt_file_sel_set_dirs_only: + * @sel: The file selector. + * @dirs: %TRUE if only directories can be selected, %FALSE if files + * can also be selected. - * @param sel The file selector.- * @param dirs @c TRUE if only directories can be selected, @c FALSE if files- * can also be selected.+ * Set wheter to only allow selecting directories. void gnt_file_sel_set_dirs_only(GntFileSel *sel, gboolean dirs);
+ * gnt_file_sel_get_dirs_only: + * @sel: The file selector. * Check whether the file selector allows only selecting directories.
- * @param sel The file selector.- * @return @c TRUE if only directories can be selected.+ * Returns: %TRUE if only directories can be selected. gboolean gnt_file_sel_get_dirs_only(GntFileSel *sel);
- * Set whether a selected file must exist.+ * gnt_file_sel_set_must_exist: + * @sel: The file selector. + * @must: %TRUE if the selected file must exist. - * @param sel The file selector.- * @param must @c TRUE if the selected file must exist.+ * Set whether a selected file must exist. void gnt_file_sel_set_must_exist(GntFileSel *sel, gboolean must);
+ * gnt_file_sel_get_must_exist: + * @sel: The file selector. * Check whether the selector allows selecting non-existent files.
- * @param sel The file selector.- * @return @c TRUE if the selected file must exist, @c FALSE if a non-existent+ * Returns: %TRUE if the selected file must exist, %FALSE if a non-existent gboolean gnt_file_sel_get_must_exist(GntFileSel *sel);
+ * gnt_file_sel_get_selected_file: + * @sel: The file selector. * Get the selected file in the selector.
- * @param sel The file selector.- * @return The path of the selected file. The caller should g_free the returned+ * Returns: The path of the selected file. The caller should g_free the returned char * gnt_file_sel_get_selected_file(GntFileSel *sel);
+ * gnt_file_sel_get_selected_multi_files: + * @sel: The file selector. * Get the list of selected files in the selector.
- * @param sel The file selector.- * @return A list of paths for the selected files. The caller must g_free the- * contents of the list, and g_list_free the list.+ * Returns: (transfer full) (element-type filename): A list of paths for the + * selected files. The caller must g_free() the contents of the list, + * and g_list_free() the list. GList * gnt_file_sel_get_selected_multi_files(GntFileSel *sel);
- * Allow selecting multiple files.+ * gnt_file_sel_set_multi_select: + * @sel: The file selector. + * @set: %TRUE if selecting multiple files should be allowed. - * @param sel The file selector.- * @param set @c TRUE if selecting multiple files should be allowed.+ * Allow selecting multiple files. void gnt_file_sel_set_multi_select(GntFileSel *sel, gboolean set);
- * Set the suggested file to have selected at startup.+ * gnt_file_sel_set_suggested_filename: + * @sel: The file selector. + * @suggest: The suggested filename. - * @param sel The file selector.- * @param suggest The suggested filename.+ * Set the suggested file to have selected at startup. void gnt_file_sel_set_suggested_filename(GntFileSel *sel, const char *suggest);
- * Set custom functions to read the names of files.+ * gnt_file_sel_set_read_fn: + * @sel: The file selector. + * @read_fn: The custom read function. - * @param sel The file selector.- * @param read_fn The custom read function.+ * Set custom functions to read the names of files. void gnt_file_sel_set_read_fn(GntFileSel *sel, gboolean (*read_fn)(const char *path, GList **files, GError **error));
+ * @name: The name of the file. + * @size: The size of the file. - * @param name The name of the file.- * @param size The size of the file.- * @return The newly created GntFile.+ * Returns: The newly created GntFile. GntFile* gnt_file_new(const char *name, unsigned long size);
+ * @name: The name of the directory. * Create a new GntFile for a directory.
- * @param name The name of the directory.- * @return The newly created GntFile.+ * Returns: The newly created GntFile. GntFile* gnt_file_new_dir(const char *name);
--- a/gntkeys.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntkeys.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntkeys.h Keys API * GNT - The GLib Ncurses Toolkit
@@ -26,11 +22,17 @@
+ * @section_id: libgnt-gntkeys + * @short_description: <filename>gntkeys.h</filename>
* terminfo/termcap doesn't provide all the information that I want to use, eg.
* ctrl-up, ctrl-down etc. So I am going to hard-code some of the information
* for some popular $TERMs
@@ -40,7 +42,7 @@
extern char *gnt_key_cleft;
extern char *gnt_key_cright;
-#define SAFE(x) ((x) ? (x) : "")+#define SAFE(x) ((cur_term && (x)) ? (x) : "") #define GNT_KEY_POPUP SAFE(key_f16) /* Apparently */
@@ -60,12 +62,12 @@
#define GNT_KEY_HOME SAFE(key_home)
#define GNT_KEY_END SAFE(key_end)
-#define GNT_KEY_ENTER carriage_return+#define GNT_KEY_ENTER SAFE(carriage_return) #define GNT_KEY_BACKSPACE SAFE(key_backspace)
#define GNT_KEY_DEL SAFE(key_dc)
#define GNT_KEY_INS SAFE(key_ic)
-#define GNT_KEY_BACK_TAB (back_tab ? back_tab : SAFE(key_btab))+#define GNT_KEY_BACK_TAB ((cur_term && back_tab) ? back_tab : SAFE(key_btab)) #define GNT_KEY_CTRL_A "\001"
#define GNT_KEY_CTRL_B "\002"
@@ -104,56 +106,64 @@
#define GNT_KEY_F12 SAFE(key_f12)
void gnt_init_keys(void);
+ * @text: The input text to refine. * Refine input text. This usually looks at what the terminal claims it is,
* and tries to change the text to work around some oft-broken terminfo entries.
- * @param text The input text to refine. void gnt_keys_refine(char *text);
+ * @name: The user-readable representation of an input (eg.: c-t) * Translate a user-readable representation of an input to a machine-readable representation.
- * @param name The user-readable representation of an input (eg.: c-t)- * @return A machine-readable representation of the input.+ * Returns: A machine-readable representation of the input. const char *gnt_key_translate(const char *name);
+ * @key: The machine-readable representation of an input. * Translate a machine-readable representation of an input to a user-readable representation.
- * @param key The machine-readable representation of an input.- * @return A user-readable representation of the input (eg.: c-t).+ * Returns: A user-readable representation of the input (eg.: c-t). const char *gnt_key_lookup(const char *key);
- * Add a key combination to the internal key-tree.+ * gnt_keys_add_combination: - * @param key The key to add+ * Add a key combination to the internal key-tree. void gnt_keys_add_combination(const char *key);
- * Remove a key combination from the internal key-tree.+ * gnt_keys_del_combination: + * @key: The key to remove. - * @param key The key to remove.+ * Remove a key combination from the internal key-tree. void gnt_keys_del_combination(const char *key);
+ * gnt_keys_find_combination: + * @key: The input string. * Find a combination from the given string.
- * @param key The input string.- * @return The number of bytes in the combination that starts at the beginning+ * Returns: The number of bytes in the combination that starts at the beginning int gnt_keys_find_combination(const char *key);
--- a/gntmenuitem.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntmenuitem.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntmenuitem.h Menuitem API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntmenuitem + * @short_description: <filename>gntmenuitem.h</filename> @@ -78,6 +80,7 @@
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -87,97 +90,108 @@
- * @return GType for GntMenuItem.+ * gnt_menuitem_get_type: + * Returns: GType for GntMenuItem. GType gnt_menuitem_get_type(void);
+ * @text: Label for the menuitem. - * @param text Label for the menuitem.- * @return The newly created menuitem.+ * Returns: The newly created menuitem. GntMenuItem * gnt_menuitem_new(const char *text);
- * Set a callback function for a menuitem.+ * gnt_menuitem_set_callback: + * @callback: (scope call): The callback function. + * @data: Data to send to the callback function. - * @param item The menuitem.- * @param callback The callback function.- * @param data Data to send to the callback function.+ * Set a callback function for a menuitem. void gnt_menuitem_set_callback(GntMenuItem *item, GntMenuItemCallback callback, gpointer data);
- * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback.+ * gnt_menuitem_set_submenu: - * @param item The menuitem.- * @param menu The submenu.+ * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback. void gnt_menuitem_set_submenu(GntMenuItem *item, GntMenu *menu);
+ * gnt_menuitem_get_submenu: * Get the submenu for a menuitem.
- * @param item The menuitem.+ * Returns: (transfer none): The submenu, or %NULL. - * @return The submenu, or @c NULL. GntMenu *gnt_menuitem_get_submenu(GntMenuItem *item);
- * Set a trigger key for the item.+ * gnt_menuitem_set_trigger: + * @trigger: The key that will trigger the item when the parent manu is visible - * @param item The menuitem- * @param trigger The key that will trigger the item when the parent manu is visible+ * Set a trigger key for the item. void gnt_menuitem_set_trigger(GntMenuItem *item, char trigger);
+ * gnt_menuitem_get_trigger: * Get the trigger key for a menuitem.
- * @param item The menuitem+ * See gnt_menuitem_set_trigger(). - * @return The trigger key for the menuitem.- * @see gnt_menuitem_set_trigger+ * Returns: The trigger key for the menuitem. char gnt_menuitem_get_trigger(GntMenuItem *item);
+ * @id: The ID for the menuitem. * Set an ID for the menuitem.
- * @param item The menuitem.- * @param id The ID for the menuitem. void gnt_menuitem_set_id(GntMenuItem *item, const char *id);
* Get the ID of the menuitem.
- * @param item The menuitem.+ * Returns: The ID for the menuitem. - * @return The ID for the menuitem. const char * gnt_menuitem_get_id(GntMenuItem *item);
+ * gnt_menuitem_activate: * Activating the menuitem will first trigger the 'activate' signal for the
* menuitem. Then the callback for the menuitem is triggered, if there is one.
- * @param item The menuitem.+ * Returns: Whether the callback for the menuitem was called. - * @return Whether the callback for the menuitem was called. gboolean gnt_menuitem_activate(GntMenuItem *item);
--- a/gntprogressbar.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntprogressbar.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntprogressbar.h Progress Bar API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
#ifndef GNT_PROGRESS_BAR_H
#define GNT_PROGRESS_BAR_H
+ * SECTION:gntprogressbar + * @section_id: libgnt-gntprogressbar + * @short_description: <filename>gntprogressbar.h</filename> @@ -46,84 +48,100 @@
} GntProgressBarOrientation;
typedef struct _GntProgressBar GntProgressBar;
+typedef struct _GntProgressBarClass GntProgressBarClass; -typedef struct _GntProgressBarClass+struct _GntProgressBarClass void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
void (*gnt_reserved4)(void);
- * Get the GType for GntProgressBar- * @return The GType for GntProrgressBar+ * gnt_progress_bar_get_type: + * Get the #GType for GntProgressBar + * Returns: The GType for GntProrgressBar gnt_progress_bar_get_type (void);
+ * gnt_progress_bar_new: * Create a new GntProgressBar
- * @return The new GntProgressBar+ * Returns: The new GntProgressBar gnt_progress_bar_new (void);
- * Set the progress for a progress bar+ * gnt_progress_bar_set_fraction: + * @pbar: The GntProgressBar + * @fraction: The value between 0 and 1 to display - * @param pbar The GntProgressBar- * @param fraction The value between 0 and 1 to display+ * Set the progress for a progress bar gnt_progress_bar_set_fraction (GntProgressBar *pbar, gdouble fraction);
- * Set the orientation for a progress bar+ * gnt_progress_bar_set_orientation: + * @pbar: The GntProgressBar + * @orientation: The orientation to use - * @param pbar The GntProgressBar- * @param orientation The orientation to use+ * Set the orientation for a progress bar gnt_progress_bar_set_orientation (GntProgressBar *pbar, GntProgressBarOrientation orientation);
- * Controls whether the progress value is shown+ * gnt_progress_bar_set_show_progress: + * @pbar: The GntProgressBar + * @show: A boolean indicating if the value is shown - * @param pbar The GntProgressBar- * @param show A boolean indicating if the value is shown+ * Controls whether the progress value is shown gnt_progress_bar_set_show_progress (GntProgressBar *pbar, gboolean show);
+ * gnt_progress_bar_get_fraction: + * @pbar: The GntProgressBar * Get the progress that is displayed
- * @param pbar The GntProgressBar- * @return The progress displayed as a value between 0 and 1+ * Returns: The progress displayed as a value between 0 and 1 gnt_progress_bar_get_fraction (GntProgressBar *pbar);
+ * gnt_progress_bar_get_orientation: + * @pbar: The GntProgressBar * Get the orientation for the progress bar
- * @param pbar The GntProgressBar- * @return The current orientation of the progress bar+ * Returns: The current orientation of the progress bar GntProgressBarOrientation
gnt_progress_bar_get_orientation (GntProgressBar *pbar);
+ * gnt_progress_bar_get_show_progress: + * @pbar: The GntProgressBar * Get a boolean describing if the progress value is shown
- * @param pbar The GntProgressBar- * @return A boolean @c true if the progress value is shown, @c false otherwise.+ * Returns: %TRUE if the progress value is shown, %FALSE otherwise. gnt_progress_bar_get_show_progress (GntProgressBar *pbar);
--- a/gntslider.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntslider.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntslider.h Slider API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntslider + * @short_description: <filename>gntslider.h</filename> @@ -65,6 +67,8 @@
void (*changed)(GntSlider *slider, int);
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -74,9 +78,11 @@
- * @return The GType for GntSlider- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Returns: The GType for GntSlider + * Since: 2.0.0 (gnt), 2.1.0 (pidgin) GType gnt_slider_get_type(void);
@@ -84,103 +90,110 @@
#define gnt_vslider_new(max, min) gnt_slider_new(TRUE, max, min)
+ * @orient: A vertical slider is created if %TRUE, otherwise the slider is horizontal. + * @max: The maximum value for the slider + * @min: The minimum value for the slider - * @param orient A vertical slider is created if @c TRUE, otherwise the slider is horizontal.- * @param max The maximum value for the slider- * @param min The minimum value for the slider+ * Returns: The newly created slider - * @return The newly created slider- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) GntWidget * gnt_slider_new(gboolean orient, int max, int min);
+ * gnt_slider_set_range: + * @max: The maximum value + * @min: The minimum value * Set the range of the slider.
- * @param slider The slider- * @param max The maximum value- * @param min The minimum value- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_slider_set_range(GntSlider *slider, int max, int min);
+ * @step: The amount for each step * Sets the amount of change at each step.
- * @param slider The slider- * @param step The amount for each step- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_slider_set_step(GntSlider *slider, int step);
+ * gnt_slider_set_small_step: + * @step: The amount for a small step (for the slider) * Sets the amount of change a small step.
- * @param slider The slider- * @param step The amount for a small step (for the slider) void gnt_slider_set_small_step(GntSlider *slider, int step);
+ * gnt_slider_set_large_step: + * @step: The amount for a large step (for the slider) * Sets the amount of change a large step.
- * @param slider The slider- * @param step The amount for a large step (for the slider) void gnt_slider_set_large_step(GntSlider *slider, int step);
+ * gnt_slider_advance_step: + * @steps: The number of amounts to change, positive to change + * forward, negative to change backward * Advance the slider forward or backward.
- * @param slider The slider- * @param steps The number of amounts to change, positive to change- * forward, negative to change backward+ * Returns: The value of the slider after the change - * @return The value of the slider after the change- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) int gnt_slider_advance_step(GntSlider *slider, int steps);
+ * gnt_slider_set_value: + * @value: The current value * Set the current value for the slider.
- * @param slider The slider- * @param value The current value- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_slider_set_value(GntSlider *slider, int value);
+ * gnt_slider_get_value: * Get the current value for the slider.
- * @param slider The slider- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) int gnt_slider_get_value(GntSlider *slider);
+ * gnt_slider_reflect_label: + * @label: The label to update * Update a label with the value of the slider whenever the value changes.
- * @param slider The slider- * @param label The label to update- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_slider_reflect_label(GntSlider *slider, GntLabel *label);
#endif /* GNT_SLIDER_H */
--- a/gntstyle.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntstyle.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntstyle.h Style API * GNT - The GLib Ncurses Toolkit
@@ -24,6 +20,15 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
+ * @section_id: libgnt-gntstyle + * @short_description: <filename>gntstyle.h</filename> @@ -38,115 +43,138 @@
- * Read configuration from a file.+ * gnt_style_read_configure_file: + * @filename: The filename to read configuration from. - * @param filename The filename to read configuration from.+ * Read configuration from a file. void gnt_style_read_configure_file(const char *filename);
* Get the user-setting for a style.
- * @param style The style.- * @return The user-setting, or @c NULL.+ * Returns: The user-setting, or %NULL. const char *gnt_style_get(GntStyle style);
+ * gnt_style_get_from_name: + * @group: The name of the group in the keyfile. If %NULL, the prgname + * will be used first, if available. Otherwise, "general" will be used. * Get the value of a preference in ~/.gntrc.
- * @param group The name of the group in the keyfile. If @c NULL, the prgname- * will be used first, if available. Otherwise, "general" will be used.+ * Returns: The value of the setting as a string, or %NULL - * @return The value of the setting as a string, or @c NULL- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) char *gnt_style_get_from_name(const char *group, const char *key);
+ * gnt_style_get_string_list: + * @group: The name of the group in the keyfile. If %NULL, the prgname + * will be used first, if available. Otherwise, "general" will be used. + * @length: Return location for the number of strings returned, or NULL * Get the value of a preference in ~/.gntrc.
- * @param group The name of the group in the keyfile. If @c NULL, the prgname- * will be used first, if available. Otherwise, "general" will be used.- * @param length Return location for the number of strings returned, or NULL+ * Returns: (transfer full): %NULL terminated string array. The array should be + * freed with g_strfreev(). - * @return NULL terminated string array. The array should be freed with g_strfreev(). char **gnt_style_get_string_list(const char *group, const char *key, gsize *length);
+ * @group: The name of the group in the keyfile. If %NULL, the prgname + * will be used first, if available. Otherwise, "general" will be used. * Get the value of a color pair in ~/.gntrc.
- * @param group The name of the group in the keyfile. If @c NULL, the prgname- * will be used first, if available. Otherwise, "general" will be used.+ * Returns: The value of the color as an int, or 0 on error. - * @return The value of the color as an int, or 0 on error. int gnt_style_get_color(char *group, char *key);
- * Parse a boolean preference. For example, if 'value' is "false" (ignoring case)- * or "0", the return value will be @c FALSE, otherwise @c TRUE.+ * gnt_style_parse_bool: + * @value: The value of the boolean setting as a string - * @param value The value of the boolean setting as a string- * @return The boolean value+ * Parse a boolean preference. For example, if 'value' is "false" (ignoring case) + * or "0", the return value will be %FALSE, otherwise %TRUE. - * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Returns: The boolean value + * Since: 2.0.0 (gnt), 2.1.0 (pidgin) gboolean gnt_style_parse_bool(const char *value);
+ * @def: The default value (i.e, the value if the user didn't define * Get the boolean value for a user-setting.
- * @param style The style.- * @param def The default value (i.e, the value if the user didn't define- * @return The value of the setting.+ * Returns: The value of the setting. gboolean gnt_style_get_bool(GntStyle style, gboolean def);
+ * gnt_styles_get_keyremaps: + * Internal function -- do not use. void gnt_styles_get_keyremaps(GType type, GHashTable *hash);
+ * gnt_style_read_actions: + * Internal function -- do not use. void gnt_style_read_actions(GType type, GntBindableClass *klass);
+ * gnt_style_read_menu_accels: + * @name: The name of the window. + * @table: The hastable to store the accel information. * Read menu-accels from ~/.gntrc
- * @param name The name of the window.- * @param table The hastable to store the accel information.- * @return @c TRUE if some accels were read, @c FALSE otherwise.+ * Returns: %TRUE if some accels were read, %FALSE otherwise. gboolean gnt_style_read_menu_accels(const char *name, GHashTable *table);
- * Read workspace information.+ * gnt_style_read_workspaces: + * Reads workspace information. + * Internal function -- do not use. void gnt_style_read_workspaces(GntWM *wm);
* Initialize style settings.
void gnt_init_styles(void);
* Uninitialize style settings.
void gnt_uninit_styles(void);
+#endif /* GNT_STYLE_H */ --- a/gnttextview.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gnttextview.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gnttextview.h Textview API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gnttextview + * @short_description: <filename>gnttextview.h</filename> @@ -79,6 +81,7 @@
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -88,108 +91,127 @@
- * @return GType for GntTextView.+ * gnt_text_view_get_type: + * Returns: GType for GntTextView. GType gnt_text_view_get_type(void);
- * @return The newly created textview.+ * Returns: The newly created textview. GntWidget * gnt_text_view_new(void);
+ * gnt_text_view_scroll: + * @view: The textview to scroll. + * @scroll: scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end. - * @param view The textview to scroll.- * @param scroll scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end. void gnt_text_view_scroll(GntTextView *view, int scroll);
- * Append new text in a textview.+ * gnt_text_view_append_text_with_flags: + * @text: The text to append to the textview. + * @flags: The text-flags to apply to the new text. - * @param view The textview.- * @param text The text to append to the textview.- * @param flags The text-flags to apply to the new text.+ * Append new text in a textview. void gnt_text_view_append_text_with_flags(GntTextView *view, const char *text, GntTextFormatFlags flags);
- * Append text in the textview, with some identifier (tag) for the added text.+ * gnt_text_view_append_text_with_tag: + * @text: The text to append. + * @flags: The text-flags to apply to the new text. + * @tag: The tag for the appended text, so it can be changed later (see gnt_text_view_tag_change()) - * @param view The textview.- * @param text The text to append.- * @param flags The text-flags to apply to the new text.- * @param tag The tag for the appended text, so it can be changed later (@see gnt_text_view_tag_change)+ * Append text in the textview, with some identifier (tag) for the added text. void gnt_text_view_append_text_with_tag(GntTextView *view, const char *text, GntTextFormatFlags flags, const char *tag);
+ * gnt_text_view_next_line: * Move the cursor to the beginning of the next line and resets text-attributes.
* It first completes the current line with the current text-attributes.
- * @param view The textview. void gnt_text_view_next_line(GntTextView *view);
+ * gnt_text_format_flag_to_chtype: + * @flags: The GNT text format. * Convert GNT-text formats to ncurses-text attributes.
- * @param flags The GNT text format.- * @return Nucrses text attribute.+ * Returns: Nucrses text attribute. chtype gnt_text_format_flag_to_chtype(GntTextFormatFlags flags);
- * Clear the contents of the textview.- * @param view The textview.+ * Clear the contents of the textview. void gnt_text_view_clear(GntTextView *view);
+ * gnt_text_view_get_lines_below: * The number of lines below the bottom-most visible line.
- * @param view The textview.- * @return Number of lines below the bottom-most visible line.+ * Returns: Number of lines below the bottom-most visible line. int gnt_text_view_get_lines_below(GntTextView *view);
+ * gnt_text_view_get_lines_above: * The number of lines above the topmost visible line.
- * @param view The textview.- * @return Number of lines above the topmost visible line.+ * Returns: Number of lines above the topmost visible line. int gnt_text_view_get_lines_above(GntTextView *view);
+ * gnt_text_view_tag_change: + * @name: The name of the tag. + * @text: The new text for the text. If 'text' is %NULL, the tag is removed. + * @all: %TRUE if all of the instancess of the tag should be changed, %FALSE if + * only the first instance should be changed. * Change the text of a tag.
- * @param view The textview.- * @param name The name of the tag.- * @param text The new text for the text. If 'text' is @c NULL, the tag is removed.- * @param all @c TRUE if all of the instancess of the tag should be changed, @c FALSE if- * only the first instance should be changed.- * @return The number of instances changed.+ * Returns: The number of instances changed. int gnt_text_view_tag_change(GntTextView *view, const char *name, const char *text, gboolean all);
+ * gnt_text_view_attach_scroll_widget: + * @widget: The trigger widget. * Setup hooks so that pressing up/down/page-up/page-down keys when 'widget' is
* in focus scrolls the textview.
- * @param view The textview.- * @param widget The trigger widget. void gnt_text_view_attach_scroll_widget(GntTextView *view, GntWidget *widget);
+ * gnt_text_view_attach_pager_widget: + * @pager: The widget to trigger the PAGER. * Setup appropriate hooks so that pressing some keys when the 'pager' widget
* is in focus triggers the PAGER to popup with the contents of the textview
@@ -197,18 +219,19 @@
* The default key-combination to trigger the pager is a-v, and the default
* PAGER application is $PAGER. Both can be changed in ~/.gntrc like this:
- * @param view The textview.- * @param pager The widget to trigger the PAGER. void gnt_text_view_attach_pager_widget(GntTextView *view, GntWidget *pager);
+ * gnt_text_view_attach_editor_widget: + * @widget: The widget to trigger the EDITOR. * Setup appropriate hooks so that pressing some keys when 'widget'
* is in focus triggers the EDITOR to popup with the contents of the textview
@@ -216,24 +239,22 @@
* The default key-combination to trigger the pager is a-e, and the default
* EDITOR application is $EDITOR. Both can be changed in ~/.gntrc like this:
- * @param view The textview.- * @param widget The widget to trigger the EDITOR. void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *widget);
+ * gnt_text_view_set_flag: + * @view: The textview widget + * @flag: The flag to set * Set a GntTextViewFlag for the textview widget.
- * @param view The textview widget- * @param flag The flag to set- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_text_view_set_flag(GntTextView *view, GntTextViewFlag flag);
--- a/gnttree.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gnttree.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gnttree.h Tree API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gnttree + * @short_description: <filename>gnttree.h</filename> @@ -40,12 +42,16 @@
#define GNT_IS_TREE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_TREE))
#define GNT_TREE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_TREE, GntTreeClass))
+typedef guint (*GntTreeHashFunc)(gconstpointer); +typedef gboolean (*GntTreeHashEqualityFunc)(gconstpointer, gconstpointer); typedef struct _GntTree GntTree;
typedef struct _GntTreePriv GntTreePriv;
typedef struct _GntTreeClass GntTreeClass;
typedef struct _GntTreeRow GntTreeRow;
typedef struct _GntTreeCol GntTreeCol;
+typedef struct _GntTreeColInfo GntTreeColInfo; GNT_TREE_COLUMN_INVISIBLE = 1 << 0,
@@ -54,6 +60,14 @@
GNT_TREE_COLUMN_RIGHT_ALIGNED = 1 << 3,
+ GntTreeColumnFlag flags; @@ -67,19 +81,13 @@
GList *list; /* List of GntTreeRow s */
GHashTable *hash; /* We need this for quickly referencing the rows */
- guint (*hash_func)(gconstpointer);- gboolean (*hash_eq_func)(gconstpointer, gconstpointer);+ GntTreeHashFunc hash_func; + GntTreeHashEqualityFunc hash_eq_func; GDestroyNotify key_destroy;
GDestroyNotify value_destroy;
int ncol; /* No. of columns */
- GntTreeColumnFlag flags;- } *columns; /* Would a GList be better? */+ GntTreeColInfo *columns; /* Would a GList be better? */ gboolean show_separator; /* Whether to show column separators */
@@ -93,6 +101,7 @@
void (*selection_changed)(GntTreeRow *old, GntTreeRow * current);
void (*toggled)(GntTree *tree, gpointer key);
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -102,542 +111,593 @@
- * @return The GType for GntTree+ * Returns: The GType for GntTree GType gnt_tree_get_type(void);
* Create a tree with one column.
- * @return The newly created tree+ * See gnt_tree_new_with_columns(). - * @see gnt_tree_new_with_columns+ * Returns: The newly created tree GntWidget * gnt_tree_new(void);
+ * gnt_tree_new_with_columns: + * @columns: Number of columns * Create a tree with a specified number of columns.
- * @param columns Number of columns- * @return The newly created tree+ * Returns: The newly created tree GntWidget * gnt_tree_new_with_columns(int columns);
- * The number of rows the tree should display at a time.+ * gnt_tree_set_visible_rows: + * @rows: The number of rows
- * @param rows The number of rows+ * The number of rows the tree should display at a time. void gnt_tree_set_visible_rows(GntTree *tree, int rows);
+ * gnt_tree_get_visible_rows: * Get the number visible rows.
- * @return The number of visible rows+ * Returns: The number of visible rows int gnt_tree_get_visible_rows(GntTree *tree);
- * Scroll the contents of the tree.+ * @count: If positive, the tree will be scrolled down by count rows, + * otherwise, it will be scrolled up by count rows.
- * @param count If positive, the tree will be scrolled down by count rows,- * otherwise, it will be scrolled up by count rows.+ * Scroll the contents of the tree. void gnt_tree_scroll(GntTree *tree, int count);
+ * gnt_tree_add_row_after: + * @key: The key for the row + * @row: The row to insert + * @parent: The key for the parent row + * @bigbro: The key for the row to insert the new row after. * Insert a row in the tree.
- * @param key The key for the row- * @param row The row to insert- * @param parent The key for the parent row- * @param bigbro The key for the row to insert the new row after.+ * See gnt_tree_create_row(), gnt_tree_add_row_last(), gnt_tree_add_choice(). - * @return The inserted row- * @see gnt_tree_create_row- * @see gnt_tree_add_row_last- * @see gnt_tree_add_choice+ * Returns: The inserted row GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
+ * gnt_tree_add_row_last: + * @key: The key for the row + * @row: The row to insert + * @parent: The key for the parent row * Insert a row at the end of the tree.
- * @param key The key for the row- * @param row The row to insert- * @param parent The key for the parent row+ * See gnt_tree_create_row(), gnt_tree_add_row_after(), gnt_tree_add_choice(). - * @return The inserted row- * @see gnt_tree_create_row- * @see gnt_tree_add_row_after- * @see gnt_tree_add_choice+ * Returns: The inserted row GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);
+ * gnt_tree_get_selection_data: * Get the key for the selected row.
- * @return The key for the selected row+ * Returns: (transfer none): The key for the selected row gpointer gnt_tree_get_selection_data(GntTree *tree);
+ * gnt_tree_get_selection_text: * Get the text displayed for the selected row.
+ * See gnt_tree_get_row_text_list(), gnt_tree_get_selection_text_list(). - * @return The text, which needs to be freed by the caller- * @see gnt_tree_get_row_text_list- * @see gnt_tree_get_selection_text_list+ * Returns: The text, which needs to be freed by the caller char * gnt_tree_get_selection_text(GntTree *tree);
+ * gnt_tree_get_row_text_list: + * @key: A key corresponding to the row in question. If key + * is %NULL, the text list for the selected row will * Get a list of text for a row.
- * @param key A key corresponding to the row in question. If key- * is @c NULL, the text list for the selected row will+ * See gnt_tree_get_selection_text_list(), gnt_tree_get_selection_text(). - * @return A list of texts of a row. The list and its data should be- * freed by the caller. The caller should make sure that if- * any column of the tree contains binary data, it's not freed.- * @see gnt_tree_get_selection_text_list- * @see gnt_tree_get_selection_text+ * Returns: (transfer container) (element-type utf8): A list of texts of a row. + * The list and its data should be freed by the caller. The caller + * should make sure that if any column of the tree contains binary + * data, it's not freed. +/* TODO This leaks when used from introspection. The transfer mode for the + return type here should be 'full', but that would free binary data as GList * gnt_tree_get_row_text_list(GntTree *tree, gpointer key);
+ * gnt_tree_row_get_key: + * @row: The GntTreeRow object
- * @param row The GntTreeRow object+ * Returns: (transfer none): The key of the row. - * @return The key of the row.- * @since 2.8.0 (gnt), 2.7.2 (pidgin)+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin) gpointer gnt_tree_row_get_key(GntTree *tree, GntTreeRow *row);
+ * gnt_tree_row_get_next: + * @row: The GntTreeRow object
- * @param row The GntTreeRow object+ * Returns: The next row. - * @return The next row.- * @since 2.8.0 (gnt), 2.7.2 (pidgin)+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin) GntTreeRow * gnt_tree_row_get_next(GntTree *tree, GntTreeRow *row);
+ * gnt_tree_row_get_prev: + * @row: The GntTreeRow object
- * @param row The GntTreeRow object+ * Returns: The previous row. - * @return The previous row.- * @since 2.8.0 (gnt), 2.7.2 (pidgin)+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin) GntTreeRow * gnt_tree_row_get_prev(GntTree *tree, GntTreeRow *row);
+ * gnt_tree_row_get_child: + * @row: The GntTreeRow object
- * @param row The GntTreeRow object+ * Returns: The child row. - * @return The child row.- * @since 2.8.0 (gnt), 2.7.2 (pidgin)+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin) GntTreeRow * gnt_tree_row_get_child(GntTree *tree, GntTreeRow *row);
+ * gnt_tree_row_get_parent: + * @row: The GntTreeRow object
- * @param row The GntTreeRow object+ * Returns: The parent row. - * @return The parent row.- * @since 2.8.0 (gnt), 2.7.2 (pidgin)+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin) GntTreeRow * gnt_tree_row_get_parent(GntTree *tree, GntTreeRow *row);
+ * gnt_tree_get_selection_text_list: * Get a list of text of the current row.
+ * See gnt_tree_get_row_text_list(), gnt_tree_get_selection_text(). - * @return A list of texts of the currently selected row. The list- * and its data should be freed by the caller. The caller- * should make sure that if any column of the tree contains- * binary data, it's not freed.- * @see gnt_tree_get_row_text_list- * @see gnt_tree_get_selection_text+ * Returns: (transfer container) (element-type utf8): A list of texts of the + * currently selected row. The list and its data should be freed by + * the caller. The caller should make sure that if any column of the + * tree contains binary data, it's not freed. +/* TODO This leaks when used from introspection. The transfer mode for the + return type here should be 'full', but that would free binary data as GList * gnt_tree_get_selection_text_list(GntTree *tree);
* Returns the list of rows in the tree.
- * @return The list of the rows. The list should not be modified by the caller.+ * Returns: (transfer none) (element-type Gnt.TreeRow): The list of the rows. + * The list should not be modified by the caller. GList *gnt_tree_get_rows(GntTree *tree);
- * Remove a row from the tree.+ * @key: The key for the row to remove
- * @param key The key for the row to remove+ * Remove a row from the tree. void gnt_tree_remove(GntTree *tree, gpointer key);
- * Remove all the item from the tree.+ * Remove all the item from the tree. void gnt_tree_remove_all(GntTree *tree);
+ * gnt_tree_get_selection_visible_line: * Get the visible line number of the selected row.
- * @return The line number of the currently selected row+ * Returns: The line number of the currently selected row int gnt_tree_get_selection_visible_line(GntTree *tree);
- * Change the text of a column in a row.+ * gnt_tree_change_text: + * @key: The key for the row + * @colno: The index of the column
- * @param key The key for the row- * @param colno The index of the column- * @param text The new text+ * Change the text of a column in a row. void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
+ * @key: The key for the row + * @parent: The parent of the row, or %NULL + * @bigbro: The row to insert after, or %NULL * Add a checkable item in the tree.
- * @param key The key for the row- * @param row The row to add- * @param parent The parent of the row, or @c NULL- * @param bigbro The row to insert after, or @c NULL+ * See gnt_tree_create_row(), gnt_tree_create_row_from_list(), + * gnt_tree_add_row_last(), gnt_tree_add_row_after(). - * @return The row inserted.- * @see gnt_tree_create_row- * @see gnt_tree_create_row_from_list- * @see gnt_tree_add_row_last- * @see gnt_tree_add_row_after+ * Returns: The row inserted. GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
- * Set whether a checkable item is checked or not.+ * @key: The key for the row + * @set: %TRUE if the item should be checked, %FALSE if not
- * @param key The key for the row- * @param set @c TRUE if the item should be checked, @c FALSE if not+ * Set whether a checkable item is checked or not. void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);
+ * @key: The key for the row * Return whether a row is selected or not, where the row is a checkable item.
- * @param key The key for the row- * @return @c TRUE if the row is checked, @c FALSE otherwise.+ * Returns: %TRUE if the row is checked, %FALSE otherwise. gboolean gnt_tree_get_choice(GntTree *tree, void *key);
- * Set flags for the text in a row in the tree.+ * gnt_tree_set_row_flags: + * @key: The key for the row + * @flags: The flags to set
- * @param key The key for the row- * @param flags The flags to set+ * Set flags for the text in a row in the tree. void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
+ * gnt_tree_set_row_color: + * @key: The key for the row * Set color for the text in a row in the tree.
- * @param key The key for the row- * @param color The color void gnt_tree_set_row_color(GntTree *tree, void *key, int color);
+ * gnt_tree_set_selected: + * @key: The key of the row to select
- * @param key The key of the row to select void gnt_tree_set_selected(GntTree *tree , void *key);
+ * @...: A string for each column in the tree * Create a row to insert in the tree.
- * @param ... A string for each column in the tree+ * See gnt_tree_create_row_from_list(), gnt_tree_add_row_after(), + * gnt_tree_add_row_last(), gnt_tree_add_choice(). - * @see gnt_tree_create_row_from_list- * @see gnt_tree_add_row_after- * @see gnt_tree_add_row_last- * @see gnt_tree_add_choice GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);
+ * gnt_tree_create_row_from_list: + * @list: (element-type utf8): The list containing the text for each column * Create a row from a list of text.
- * @param list The list containing the text for each column+ * See gnt_tree_create_row(), gnt_tree_add_row_after(), gnt_tree_add_row_last(), + * gnt_tree_add_choice(). - * @see gnt_tree_create_row- * @see gnt_tree_add_row_after- * @see gnt_tree_add_row_last- * @see gnt_tree_add_choice+ * Returns: (transfer full): The row GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
+ * gnt_tree_set_col_width: + * @col: The index of the column + * @width: The width for the column * Set the width of a column in the tree.
- * @param col The index of the column- * @param width The width for the column- * @see gnt_tree_set_column_width_ratio- * @see gnt_tree_set_column_resizable+ * See gnt_tree_set_column_width_ratio(), gnt_tree_set_column_resizable() void gnt_tree_set_col_width(GntTree *tree, int col, int width);
+ * gnt_tree_set_column_title: + * @index: The index of the column + * @title: The title for the column * Set the title for a column.
- * @param index The index of the column- * @param title The title for the column+ * See gnt_tree_set_column_titles(), gnt_tree_set_show_title(). - * @see gnt_tree_set_column_titles- * @see gnt_tree_set_show_title- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);
+ * gnt_tree_set_column_titles: + * @...: One title for each column in the tree * Set the titles of the columns
- * @param ... One title for each column in the tree- * @see gnt_tree_set_column_title- * @see gnt_tree_set_show_title+ * See gnt_tree_set_column_title(), gnt_tree_set_show_title(). void gnt_tree_set_column_titles(GntTree *tree, ...);
+ * gnt_tree_set_show_title: + * @set: If %TRUE, the column titles are displayed * Set whether to display the title of the columns.
- * @param set If @c TRUE, the column titles are displayed- * @see gnt_tree_set_column_title- * @see gnt_tree_set_column_titles+ * See gnt_tree_set_column_title(), gnt_tree_set_column_titles(). void gnt_tree_set_show_title(GntTree *tree, gboolean set);
+ * gnt_tree_set_compare_func: + * @func: (scope call): The comparison function, which is used to compare * Set the compare function for sorting the data.
- * @param func The comparison function, which is used to compare- * @see gnt_tree_sort_row+ * See gnt_tree_sort_row(). void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);
- * Set whether a row, which has child rows, should be expanded.+ * gnt_tree_set_expanded: + * @key: The key of the row + * @expanded: Whether to expand the child rows
- * @param key The key of the row- * @param expanded Whether to expand the child rows+ * Set whether a row, which has child rows, should be expanded. void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
- * Set whether to show column separators.+ * gnt_tree_set_show_separator: + * @set: If %TRUE, the column separators are displayed
- * @param set If @c TRUE, the column separators are displayed+ * Set whether to show column separators. void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
+ * @row: The row to sort * Sort a row in the tree.
- * @param row The row to sort- * @see gnt_tree_set_compare_func+ * See gnt_tree_set_compare_func(). void gnt_tree_sort_row(GntTree *tree, void *row);
- * Automatically adjust the width of the columns in the tree.+ * gnt_tree_adjust_columns:
+ * Automatically adjust the width of the columns in the tree. void gnt_tree_adjust_columns(GntTree *tree);
- * Set the hash functions to use to hash, compare and free the keys.+ * gnt_tree_set_hash_fns: + * @hash: The hashing function + * @eq: The function to compare keys + * @kd: The function to use to free the keys when a row is removed
- * @param hash The hashing function- * @param eq The function to compare keys- * @param kd The function to use to free the keys when a row is removed+ * Set the hash functions to use to hash, compare and free the keys. void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
+ * gnt_tree_set_column_visible: + * @col: The index of the column + * @vis: If %FALSE, the column will not be displayed * Set whether a column is visible or not.
* This can be useful when, for example, we want to store some data
* which we don't want/need to display.
- * @param col The index of the column- * @param vis If @c FALSE, the column will not be displayed void gnt_tree_set_column_visible(GntTree *tree, int col, gboolean vis);
+ * gnt_tree_set_column_resizable: + * @col: The index of the column + * @res: If %FALSE, the column will not be resized when the * Set whether a column can be resized to keep the same ratio when the
- * @param col The index of the column- * @param res If @c FALSE, the column will not be resized when the+ * See gnt_tree_set_col_width(), gnt_tree_set_column_width_ratio(). - * @see gnt_tree_set_col_width- * @see gnt_tree_set_column_width_ratio- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);
+ * gnt_tree_set_column_is_binary: + * @col: The index of the column + * @bin: %TRUE if the data for the column is binary * Set whether data in a column should be considered as binary data, and
* not as strings. A column containing binary data will be display empty text.
- * @param col The index of the column- * @param bin @c TRUE if the data for the column is binary void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin);
+ * gnt_tree_set_column_is_right_aligned: + * @col: The index of the column + * @right: %TRUE if the text in the column should be right aligned * Set whether text in a column should be right-aligned.
- * @param col The index of the column- * @param right @c TRUE if the text in the column should be right aligned- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_column_is_right_aligned(GntTree *tree, int col, gboolean right);
+ * gnt_tree_set_column_width_ratio: + * @cols: Array of widths. The width must have the same number + * of entries as the number of columns in the tree, or + * end with a negative value for a column-width. * Set column widths to use when calculating column widths after a tree
- * @param cols Array of widths. The width must have the same number- * of entries as the number of columns in the tree, or- * end with a negative value for a column-width.+ * See gnt_tree_set_col_width(), gnt_tree_set_column_resizable(). - * @see gnt_tree_set_col_width- * @see gnt_tree_set_column_resizable- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);
+ * gnt_tree_set_search_column: + * @col: The index of the column * Set the column to use for typeahead searching.
- * @param col The index of the column- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_search_column(GntTree *tree, int col);
+ * gnt_tree_is_searching: * Check whether the user is currently in the middle of a search.
- * @return @c TRUE if the user is searching, @c FALSE otherwise.+ * Returns: %TRUE if the user is searching, %FALSE otherwise. - * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) gboolean gnt_tree_is_searching(GntTree *tree);
+ * gnt_tree_set_search_function: + * @func: The custom search function. The search function is + * sent the tree itself, the key of a row, the search + * string and the content of row in the search column. + * If the function returns %TRUE, the row is dislayed, * Set a custom search function.
- * @param func The custom search function. The search function is- * sent the tree itself, the key of a row, the search- * string and the content of row in the search column.- * If the function returns @c TRUE, the row is dislayed,- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_tree_set_search_function(GntTree *tree,
gboolean (*func)(GntTree *tree, gpointer key, const char *search, const char *current));
+ * gnt_tree_get_parent_key: + * @key: The key for the row. * Get the parent key for a row.
- * @param key The key for the row.+ * Returns: (transfer none): The key of the parent row. - * @return The key of the parent row. gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
--- a/gntutils.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntutils.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntutils.h Some utility functions * GNT - The GLib Ncurses Toolkit
@@ -24,134 +20,150 @@
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
+ * @section_id: libgnt-gntutils + * @short_description: <filename>gntutils.h</filename> + * @title: Utility functions -typedef gpointer (*GDupFunc)(gconstpointer data);+typedef gpointer (*GntDuplicateFunc)(gconstpointer data); - * Compute the width and height required to view the text on the screen.+ * gnt_util_get_text_bound: + * @text: The text to be displayed. + * @width: The width required is set here, if not %NULL. + * @height: The height required is set here, if not %NULL. - * @param text The text to be displayed.- * @param width The width required is set here, if not @c NULL.- * @param height The height required is set here, if not @c NULL.+ * Compute the width and height required to view the text on the screen. void gnt_util_get_text_bound(const char *text, int *width, int *height);
+ * gnt_util_onscreen_width: + * @start: The beginning of the string. + * @end: The end of the string. The width returned is the width + * upto (but not including) end. If end is NULL, then start + * is considered as a %NULL-terminated string. * Get the onscreen width of a string, or a substring.
- * @param start The beginning of the string.- * @param end The end of the string. The width returned is the width- * upto (but not including) end. If end is NULL, then start- * is considered as a @c NULL-terminated string.- * @return The on-screen width of the string.+ * Returns: The on-screen width of the string. int gnt_util_onscreen_width(const char *start, const char *end);
+ * gnt_util_onscreen_width_to_pointer: + * @len: The length to consider. If non-positive, the entire screenlength is used. + * @w: The actual width of the string upto the returned offset, if not %NULL. * Computes and returns the string after a specific number of onscreen characters.
- * @param str The string.- * @param len The length to consider. If non-positive, the entire screenlength is used.- * @param w The actual width of the string upto the returned offset, if not @c NULL.- * @return The string after len offset.+ * Returns: The string after len offset. const char *gnt_util_onscreen_width_to_pointer(const char *str, int len, int *w);
+ * gnt_util_onscreen_fit_string: + * @maxw: The width that the string should fit into. If maxw is <= 0, + * then the available maximum width is used. * Inserts newlines in 'string' where necessary so that its onscreen width is
- * @param string The string.- * @param maxw The width that the string should fit into. If maxw is <= 0,- * then the available maximum width is used.- * @return A newly allocated string that needs to be freed by the caller.+ * Returns: A newly allocated string that needs to be freed by the caller. char * gnt_util_onscreen_fit_string(const char *string, int maxw);
+ * gnt_hash_table_duplicate: + * @src: The source hashtable. + * @hash: (scope call): The hash-function to use. + * @equal: The hash-equal function to use. + * @key_d: The key-destroy function to use. + * @value_d: The value-destroy function to use. + * @key_dup: (scope call): The function to use to duplicate the key. + * @value_dup: (scope call): The function to use to duplicate the value. * Duplicate the contents of a hastable.
- * @param src The source hashtable.- * @param hash The hash-function to use.- * @param equal The hash-equal function to use.- * @param key_d The key-destroy function to use.- * @param value_d The value-destroy function to use.- * @param key_dup The function to use to duplicate the key.- * @param value_dup The function to use to duplicate the value.- * @return The new hashtable.+ * Returns: (transfer full): The new hashtable. -GHashTable * g_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GDupFunc key_dup, GDupFunc value_dup);+GHashTable * gnt_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GntDuplicateFunc key_dup, GntDuplicateFunc value_dup); + * gnt_boolean_handled_accumulator: * To be used with g_signal_new. Look in the key_pressed signal-definition in
- * @param return_accu NA- * @param handler_return NA gboolean gnt_boolean_handled_accumulator(GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy);
+ * gnt_widget_bindings_view: + * @widget: The widget to get bindings for. * Get a helpful display about the bindings of a widget.
- * @param widget The widget to get bindings for.- * @return Returns a GntTree populated with "key" -> "binding" for the widget.+ * Returns: (transfer full): Returns a GntTree populated with "key" -> "binding" GntWidget * gnt_widget_bindings_view(GntWidget *widget);
+ * gnt_util_parse_widgets: + * @string: The XML string. + * @num: The number of widgets to return, followed by 'num' GntWidget ** * Parse widgets from an XML description. For example,
* GntWidget *win, *button;
* gnt_util_parse_widgets("\
- * <vwindow id='0' fill='0' align='2'> \- * <label>This is a test</label> \- * <button id='1'>OK</button> \+ * <vwindow id='0' fill='0' align='2'> \ + * <label>This is a test</label> \ + * <button id='1'>OK</button> \
- * @param string The XML string.- * @param num The number of widgets to return, followed by 'num' GntWidget ** void gnt_util_parse_widgets(const char *string, int num, ...);
+ * gnt_util_parse_xhtml_to_textview: + * @string: The XHTML string * Parse an XHTML string and add it in a GntTextView with
* appropriate text flags.
- * @param string The XHTML string- * @param tv The GntTextView- * @return @c TRUE if the string was added to the textview properly, @c FALSE otherwise.+ * Returns: %TRUE if the string was added to the textview properly, %FALSE otherwise.
gboolean gnt_util_parse_xhtml_to_textview(const char *string, GntTextView *tv);
+ * gnt_util_set_trigger_widget: + * @key: The key to trigger the button + * @button: The button to trigger * Make some keypress activate a button when some key is pressed with 'wid' in focus.
- * @param widget The widget- * @param key The key to trigger the button- * @param button The button to trigger- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_util_set_trigger_widget(GntWidget *widget, const char *key, GntWidget *button);
+#endif /* GNT_UTILS_H */ --- a/gntwidget.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntwidget.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntwidget.h Widget API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntwidget + * @short_description: <filename>gntwidget.h</filename> @@ -104,10 +106,11 @@
- void (*gnt_reserved1)(void);- void (*gnt_reserved2)(void);- void (*gnt_reserved3)(void);- void (*gnt_reserved4)(void);@@ -131,6 +134,7 @@
void (*activate)(GntWidget *widget);
gboolean (*clicked)(GntWidget *widget, GntMouseEvent event, int x, int y);
void (*gnt_reserved1)(void);
void (*gnt_reserved2)(void);
void (*gnt_reserved3)(void);
@@ -140,175 +144,215 @@
- * @return GType for GntWidget.+ * Returns: GType for GntWidget. GType gnt_widget_get_type(void);
+ * @widget: The widget to destroy. - * @param widget The widget to destroy.+ * Emits the "destroy" signal notifying all reference holders that they + * should release @widget. void gnt_widget_destroy(GntWidget *widget);
+ * @widget: The widget to show. * Show a widget. This should only be used for toplevel widgets. For the rest
* of the widgets, use #gnt_widget_draw instead.
- * @param widget The widget to show. void gnt_widget_show(GntWidget *widget);
+ * @widget: The widget to draw. - * @param widget The widget to draw. void gnt_widget_draw(GntWidget *widget);
* Expose part of a widget.
+ * Internal function -- do not use. void gnt_widget_expose(GntWidget *widget, int x, int y, int width, int height);
+ * @widget: The widget to hide. - * @param widget The widget to hide. void gnt_widget_hide(GntWidget *widget);
- * Get the position of a widget.+ * gnt_widget_get_position: + * @x: Location to store the x-coordinate of the widget. + * @y: Location to store the y-coordinate of the widget. - * @param widget The widget.- * @param x Location to store the x-coordinate of the widget.- * @param y Location to store the y-coordinate of the widget.+ * Get the position of a widget. void gnt_widget_get_position(GntWidget *widget, int *x, int *y);
+ * gnt_widget_set_position: + * @widget: The widget to reposition. + * @x: The x-coordinate of the widget. + * @y: The x-coordinate of the widget. * Set the position of a widget.
- * @param widget The widget to reposition.- * @param x The x-coordinate of the widget.- * @param y The x-coordinate of the widget. void gnt_widget_set_position(GntWidget *widget, int x, int y);
+ * gnt_widget_size_request: * Request a widget to calculate its desired size.
- * @param widget The widget. void gnt_widget_size_request(GntWidget *widget);
+ * @width: Location to store the width of the widget. + * @height: Location to store the height of the widget. * Get the size of a widget.
- * @param widget The widget.- * @param width Location to store the width of the widget.- * @param height Location to store the height of the widget. void gnt_widget_get_size(GntWidget *widget, int *width, int *height);
+ * @widget: The widget to resize. + * @width: The width of the widget. + * @height: The height of the widget. * Set the size of a widget.
- * @param widget The widget to resize.- * @param width The width of the widget.- * @param height The height of the widget.- * @return If the widget was resized to the new size.+ * Returns: If the widget was resized to the new size. gboolean gnt_widget_set_size(GntWidget *widget, int width, int height);
+ * gnt_widget_confirm_size: + * @width: The requested width. + * @height: The requested height. * Confirm a requested a size for a widget.
- * @param widget The widget.- * @param width The requested width.- * @param height The requested height.- * @return @c TRUE if the new size was confirmed, @c FALSE otherwise.+ * Returns: %TRUE if the new size was confirmed, %FALSE otherwise. gboolean gnt_widget_confirm_size(GntWidget *widget, int width, int height);
+ * gnt_widget_key_pressed: + * @keys: The keypress on the widget. * Trigger the key-press callbacks for a widget.
- * @param widget The widget.- * @param keys The keypress on the widget.- * @return @c TRUE if the key-press was handled, @c FALSE otherwise.+ * Returns: %TRUE if the key-press was handled, %FALSE otherwise. gboolean gnt_widget_key_pressed(GntWidget *widget, const char *keys);
+ * @event: The mouseevent. + * @x: The x-coordinate of the mouse. + * @y: The y-coordinate of the mouse. * Trigger the 'click' callback of a widget.
- * @param widget The widget.- * @param event The mouseevent.- * @param x The x-coordinate of the mouse.- * @param y The y-coordinate of the mouse.- * @return @c TRUE if the event was handled, @c FALSE otherwise.+ * Returns: %TRUE if the event was handled, %FALSE otherwise. gboolean gnt_widget_clicked(GntWidget *widget, GntMouseEvent event, int x, int y);
- * Give or remove focus to a widget.- * @param widget The widget.- * @param set @c TRUE of focus should be given to the widget, @c FALSE if+ * gnt_widget_set_focus: + * @set: %TRUE of focus should be given to the widget, %FALSE if * focus should be removed.
- * @return @c TRUE if the focus has been changed, @c FALSE otherwise.+ * Give or remove focus to a widget. + * Returns: %TRUE if the focus has been changed, %FALSE otherwise. gboolean gnt_widget_set_focus(GntWidget *widget, gboolean set);
+ * @widget: The widget to activate. * Activate a widget. This only applies to widgets that can be activated (eg. GntButton)
- * @param widget The widget to activate. void gnt_widget_activate(GntWidget *widget);
+ * @name: A new name for the widget. * Set the name of a widget.
- * @param widget The widget.- * @param name A new name for the widget. void gnt_widget_set_name(GntWidget *widget, const char *name);
* Get the name of a widget.
- * @param widget The widget.- * @return The name of the widget.+ * Returns: The name of the widget. const char *gnt_widget_get_name(GntWidget *widget);
- * Use #gnt_widget_draw instead.+ * gnt_widget_queue_update: + * Internal function -- do not use. + * Use gnt_widget_draw() instead. void gnt_widget_queue_update(GntWidget *widget);
- * Set whether a widget can take focus or not.+ * gnt_widget_set_take_focus: + * @set: %TRUE if the widget can take focus. - * @param widget The widget.- * @param set @c TRUE if the widget can take focus.+ * Set whether a widget can take focus or not. void gnt_widget_set_take_focus(GntWidget *widget, gboolean set);
- * Set the visibility of a widget.+ * gnt_widget_set_visible: + * @set: Whether the widget is visible or not. - * @param widget The widget.- * @param set Whether the widget is visible or not.+ * Set the visibility of a widget. void gnt_widget_set_visible(GntWidget *widget, gboolean set);
+ * gnt_widget_has_shadow: * Check whether the widget has shadows.
- * @param widget The widget.- * @return @c TRUE if the widget has shadows. This checks both the user-setting+ * Returns: %TRUE if the widget has shadows. This checks both the user-setting * and whether the widget can have shadows at all.
gboolean gnt_widget_has_shadow(GntWidget *widget);
--- a/gntwm.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntwm.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntwm.h Window-manager API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntwm + * @short_description: <filename>gntwm.h</filename> + * @title: Window-manager API @@ -49,7 +51,9 @@
GNT_KP_MODE_WAIT_ON_CHILD
+typedef struct _GntNode GntNode; @@ -57,7 +61,7 @@
typedef struct _GntWM GntWM;
@@ -68,6 +72,8 @@
* An application can register actions which will show up in a 'start-menu' like popup
typedef struct _GntAction
@@ -76,48 +82,52 @@
+typedef struct _GntListWindow { + * @acts: List of actions + * @menu: Currently active menu. There can be at most one menu at a time on the + * screen. If there is a menu being displayed, then all the keystrokes + * will be sent to the menu until it is closed, either when the user + * activates a menuitem, or presses Escape to cancel the menu. + * @event_stack: Will be set to %TRUE when a user-event, ie. a mouse-click or a + * key-press is being processed. This variable will be used to + * determine whether to give focus to a new window. GList *tagged; /* tagged windows */
- *windows, /* Window-list window */- *actions; /* Action-list window */+ GntListWindow *windows; /* Window-list window */ + GntListWindow *actions; /* Action-list window */ GHashTable *nodes; /* GntWidget -> GntNode */
GHashTable *name_places; /* window name -> ws*/
GHashTable *title_places; /* window title -> ws */
- GList *acts; /* List of actions */- * There can be at most one menu at a time on the screen.- * If there is a menu being displayed, then all the keystrokes will be sent to- * the menu until it is closed, either when the user activates a menuitem, or- * presses Escape to cancel the menu.- GntMenu *menu; /* Currently active menu */- * 'event_stack' will be set to TRUE when a user-event, ie. a mouse-click- * or a key-press is being processed. This variable will be used to determine- * whether to give focus to a new window.@@ -184,151 +194,191 @@
- * @return GType for GntWM.+ * Returns: GType for GntWM. GType gnt_wm_get_type(void);
+ * gnt_wm_add_workspace: + * @wm: The window-manager. + * @ws: The workspace to add. - * @param wm The window-manager.- * @param ws The workspace to add. void gnt_wm_add_workspace(GntWM *wm, GntWS *ws);
+ * gnt_wm_switch_workspace: + * @wm: The window-manager. + * @n: Index of the workspace to switch to. - * @param wm The window-manager.- * @param n Index of the workspace to switch to.- * @return @c TRUE if the switch was successful.+ * Returns: %TRUE if the switch was successful. gboolean gnt_wm_switch_workspace(GntWM *wm, gint n);
+ * gnt_wm_switch_workspace_prev: + * @wm: The window-manager. * Switch to the previous workspace from the current one.
- * @param wm The window-manager. gboolean gnt_wm_switch_workspace_prev(GntWM *wm);
+ * gnt_wm_switch_workspace_next: + * @wm: The window-manager. * Switch to the next workspace from the current one.
- * @param wm The window-manager. gboolean gnt_wm_switch_workspace_next(GntWM *wm);
+ * gnt_wm_widget_move_workspace: + * @wm: The window manager. + * @neww: The new workspace. + * @widget: The widget to move. * Move a window to a specific workspace.
- * @param wm The window manager.- * @param neww The new workspace.- * @param widget The widget to move. void gnt_wm_widget_move_workspace(GntWM *wm, GntWS *neww, GntWidget *widget);
+ * gnt_wm_set_workspaces: + * @wm: The window manager. + * @workspaces: (element-type Gnt.WS): The list of workspaces. * Set the list of workspaces .
- * @param wm The window manager.- * @param workspaces The list of workspaces. void gnt_wm_set_workspaces(GntWM *wm, GList *workspaces);
+ * gnt_wm_widget_find_workspace: + * @wm: The window-manager. + * @widget: The widget to find. * Find the workspace that contains a specific widget.
- * @param wm The window-manager.- * @param widget The widget to find.- * @return The workspace that has the widget.+ * Returns: (transfer none): The workspace that has the widget. GntWS *gnt_wm_widget_find_workspace(GntWM *wm, GntWidget *widget);
- * Process a new window.+ * @wm: The window-manager. + * @widget: The new window. - * @param wm The window-manager.- * @param widget The new window.+ * Process a new window. void gnt_wm_new_window(GntWM *wm, GntWidget *widget);
+ * gnt_wm_window_decorate: + * @wm: The window-manager. + * @widget: The widget to decorate. - * @param wm The window-manager.- * @param widget The widget to decorate. void gnt_wm_window_decorate(GntWM *wm, GntWidget *widget);
+ * @wm: The window-manager. + * @widget: The window to close. - * @param wm The window-manager.- * @param widget The window to close. void gnt_wm_window_close(GntWM *wm, GntWidget *widget);
+ * gnt_wm_process_input: + * @wm: The window-manager. + * @string: The input string to process. - * @param wm The window-manager.- * @param string The input string to process.- * @return @c TRUE of the string was processed, @c FALSE otherwise.+ * Returns: %TRUE of the string was processed, %FALSE otherwise. gboolean gnt_wm_process_input(GntWM *wm, const char *string);
+ * gnt_wm_process_click: + * @wm: The window manager. + * @event: The mouse event. + * @x: The x-coordinate of the mouse. + * @y: The y-coordinate of the mouse. + * @widget: The widget under the mouse. - * @param wm The window manager.- * @param event The mouse event.- * @param x The x-coordinate of the mouse.- * @param y The y-coordinate of the mouse.- * @param widget The widget under the mouse.- * @return @c TRUE if the event was handled, @c FALSE otherwise.+ * Returns: %TRUE if the event was handled, %FALSE otherwise. gboolean gnt_wm_process_click(GntWM *wm, GntMouseEvent event, int x, int y, GntWidget *widget);
+ * gnt_wm_resize_window: + * @wm: The window manager. + * @widget: The window to resize. + * @width: The desired width of the window. + * @height: The desired height of the window. - * @param wm The window manager.- * @param widget The window to resize.- * @param width The desired width of the window.- * @param height The desired height of the window. void gnt_wm_resize_window(GntWM *wm, GntWidget *widget, int width, int height);
+ * @wm: The window manager. + * @widget: The window to move. + * @x: The desired x-coordinate of the window. + * @y: The desired y-coordinate of the window. - * @param wm The window manager.- * @param widget The window to move.- * @param x The desired x-coordinate of the window.- * @param y The desired y-coordinate of the window. void gnt_wm_move_window(GntWM *wm, GntWidget *widget, int x, int y);
+ * gnt_wm_update_window: + * @wm: The window-manager. + * @widget: The window to update. - * @param wm The window-manager.- * @param widget The window to update. void gnt_wm_update_window(GntWM *wm, GntWidget *widget);
+ * @wm: The window-manager. + * @widget: The window to raise. - * @param wm The window-manager.- * @param widget The window to raise. void gnt_wm_raise_window(GntWM *wm, GntWidget *widget);
+ * gnt_wm_set_event_stack: + * Internal function -- do not use. void gnt_wm_set_event_stack(GntWM *wm, gboolean set);
+ * Internal function -- do not use. void gnt_wm_copy_win(GntWidget *widget, GntNode *node);
- * @return The idle time of the user.+ * gnt_wm_get_idle_time: + * Returns: The idle time of the user. time_t gnt_wm_get_idle_time(void);
--- a/gntws.h Thu Feb 06 19:44:10 2014 +0530
+++ b/gntws.h Mon Feb 10 02:46:00 2014 +0530
@@ -1,7 +1,3 @@
- * @file gntws.h Workspace API * GNT - The GLib Ncurses Toolkit
@@ -26,6 +22,12 @@
+ * @section_id: libgnt-gntws + * @short_description: <filename>gntws.h</filename> + * @title: Workspace API @@ -70,110 +72,123 @@
- * @return The GType for GntWS.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Returns: The GType for GntWS. + * Since: 2.0.0 (gnt), 2.1.0 (pidgin) GType gnt_ws_get_type(void);
+ * @name: The desired name of the workspace, or %NULL. * Create a new workspace with the specified name.
- * @param name The desired name of the workspace, or @c NULL.+ * Returns: The newly created workspace. - * @return The newly created workspace.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) GntWS *gnt_ws_new(const char *name);
+ * @ws: The workspace to rename. + * @name: The new name of the workspace. * Set the name of a workspace.
- * @param ws The workspace to rename.- * @param name The new name of the workspace.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_set_name(GntWS *ws, const gchar *name);
+ * @widget: The widget to add. * Add a widget to a workspace.
- * @param ws The workspace.- * @param widget The widget to add.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_add_widget(GntWS *ws, GntWidget *widget);
+ * gnt_ws_remove_widget: + * @widget: The widget to remove from the workspace. * Remove a widget from a workspace.
- * @param ws The workspace- * @param widget The widget to remove from the workspace.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_remove_widget(GntWS *ws, GntWidget *widget);
+ * @widget: The widget to hide. + * @nodes: A hashtable containing information about the widgets. * Hide a widget in a workspace.
- * @param widget The widget to hide.- * @param nodes A hashtable containing information about the widgets.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_widget_hide(GntWidget *widget, GHashTable *nodes);
+ * @widget: The widget to show. + * @nodes: A hashtable containing information about the widgets. * Show a widget in a workspace.
- * @param widget The widget to show.- * @param nodes A hashtable containing information about the widgets.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_widget_show(GntWidget *widget, GHashTable *nodes);
+ * @reposition: Whether the workspace should reposition the taskbar. * Draw the taskbar in a workspace.
- * @param ws The workspace.- * @param reposition Whether the workspace should reposition the taskbar.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_draw_taskbar(GntWS *ws, gboolean reposition);
+ * @ws: The workspace to hide. + * @table: A hashtable containing information about the widgets. - * @param ws The workspace to hide.- * @param table A hashtable containing information about the widgets.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_hide(GntWS *ws, GHashTable *table);
+ * @ws: The workspace to hide. + * @table: A hashtable containing information about the widgets. - * @param ws The workspace to hide.- * @param table A hashtable containing information about the widgets.- * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) void gnt_ws_show(GntWS *ws, GHashTable *table);
* Get the name of a workspace.
- * @param ws The workspace.- * @return The name of the workspace (can be @c NULL).+ * Returns: The name of the workspace (can be %NULL). - * @since 2.0.0 (gnt), 2.1.0 (pidgin)+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin) const char * gnt_ws_get_name(GntWS *ws);
