qulogic/libgnt

applied changes from a16a8d9f1b43ee9a6ead24670b2bac2f5cbbf1d3

2007-11-07, Sadrul Habib Chowdhury
09bc2c4bc952
Parents 4065eeac7953
Children aee1c2e8013c
applied changes from a16a8d9f1b43ee9a6ead24670b2bac2f5cbbf1d3
through add41d6b60a51b3213dd113259548c06c030c0e2
And others.
19 files changed, 505 insertions(+), 359 deletions(-)
  • +67 -40
    gnt.h
  • +4 -4
    gntbindable.h
  • +1 -0
    gntfilesel.c
  • +57 -47
    gntfilesel.h
  • +34 -16
    gntkeys.h
  • +14 -13
    gntlabel.h
  • +5 -6
    gntline.h
  • +1 -1
    gntmain.c
  • +9 -9
    gntmenu.h
  • +14 -13
    gntmenuitem.h
  • +13 -12
    gntmenuitemcheck.h
  • +23 -15
    gntstyle.h
  • +80 -52
    gnttextview.h
  • +1 -1
    gntutils.h
  • +1 -1
    gntwidget.c
  • +82 -73
    gntwidget.h
  • +11 -9
    gntwindow.h
  • +1 -1
    gntwm.c
  • +87 -46
    gntwm.h
    • --- a/gnt.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gnt.h Wed Nov 07 14:07:52 2007 +0000
    @@ -46,19 +46,19 @@
    #endif
    /**
    - *
    + * Initialize GNT.
    */
    void gnt_init(void);
    /**
    - *
    + * Start running the mainloop for gnt.
    */
    void gnt_main(void);
    /**
    - *
    + * Check whether the terminal is capable of UTF8 display.
    *
    - * @return
    + * @return @c FALSE if the terminal is capable of drawing UTF-8, @c TRUE otherwise.
    */
    gboolean gnt_ascii_only(void);
    @@ -71,106 +71,133 @@
    * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_window_present(GntWidget *window);
    +
    /**
    - *
    - * @param widget
    + * @internal
    + * Use #gnt_widget_show instead.
    */
    void gnt_screen_occupy(GntWidget *widget);
    /**
    - *
    - * @param widget
    + * @internal
    + * Use #gnt_widget_hide instead.
    */
    void gnt_screen_release(GntWidget *widget);
    /**
    - *
    - * @param widget
    + * @internal
    + * Use #gnt_widget_draw instead.
    */
    void gnt_screen_update(GntWidget *widget);
    /**
    - *
    - * @param widget
    - * @param width
    - * @param height
    + * Resize a widget.
    + *
    + * @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);
    /**
    - *
    - * @param widget
    - * @param x
    - * @param y
    + * Move a widget.
    + *
    + * @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);
    /**
    - *
    - * @param widget
    - * @param text
    + * Rename a 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);
    /**
    - *
    - * @param widget
    + * Check whether a widget has focus.
    *
    - * @return
    + * @param widget The widget.
    + *
    + * @return @c TRUE if the widget has the current focus, @c FALSE otherwise.
    */
    gboolean gnt_widget_has_focus(GntWidget *widget);
    /**
    - *
    - * @param widget
    + * Set the URGENT hint for a widget.
    + *
    + * @param widget The widget to set the URGENT hint for.
    */
    void gnt_widget_set_urgent(GntWidget *widget);
    /**
    - *
    - * @param label
    - * @param callback
    + * Register a global action.
    + *
    + * @param label The user-visible label for the action.
    + * @param callback The callback function for the action.
    */
    void gnt_register_action(const char *label, void (*callback)());
    /**
    - *
    - * @param menu
    + * Show a menu.
    *
    - * @return
    + * @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).
    */
    gboolean gnt_screen_menu_show(gpointer menu);
    /**
    - *
    + * Terminate the mainloop of gnt.
    */
    void gnt_quit(void);
    /**
    - *
    + * Get the global clipboard.
    *
    - * @return
    + * @return The clipboard.
    */
    GntClipboard * gnt_get_clipboard(void);
    /**
    - *
    + * Get the string in the clipboard.
    *
    - * @return
    + * @return A copy of the string in the clipboard. The caller must @c g_free the string.
    */
    gchar * gnt_get_clipboard_string(void);
    /**
    - *
    - * @param string
    + * Set the contents of the global clipboard.
    + *
    + * @param string The new content of the new clipboard.
    */
    -void gnt_set_clipboard_string(gchar *string);
    +void gnt_set_clipboard_string(const gchar *string);
    /**
    * 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.
    */
    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.
    + */
    gboolean gnt_is_refugee(void);
    +
    --- a/gntbindable.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntbindable.h Wed Nov 07 14:07:52 2007 +0000
    @@ -160,8 +160,8 @@
    /**
    * Returns a GntTree populated with "key" -> "binding" for the widget.
    - *
    - * @param widget The object to list the bindings for.
    + *
    + * @param bind The object to list the bindings for.
    *
    * @return The GntTree.
    */
    @@ -170,9 +170,9 @@
    /**
    * 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.
    - *
    + *
    * @return @c TRUE
    */
    --- a/gntfilesel.c Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntfilesel.c Wed Nov 07 14:07:52 2007 +0000
    @@ -719,6 +719,7 @@
    void gnt_file_sel_set_suggested_filename(GntFileSel *sel, const char *suggest)
    {
    + g_free(sel->suggest);
    sel->suggest = g_strdup(suggest);
    }
    --- a/gntfilesel.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntfilesel.h Wed Nov 07 14:07:52 2007 +0000
    @@ -98,113 +98,123 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntFileSel.
    */
    GType gnt_file_sel_get_gtype(void);
    /**
    - *
    + * Create a new file selector.
    *
    - * @return
    + * @return The newly created file selector.
    */
    GntWidget * gnt_file_sel_new(void);
    /**
    - *
    - * @param sel
    - * @param path
    + * Set the current location of the file selector.
    *
    - * @return
    + * @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.
    */
    gboolean gnt_file_sel_set_current_location(GntFileSel *sel, const char *path);
    /**
    - *
    - * @param sel
    - * @param dirs
    + * Set wheter to only allow selecting directories.
    + *
    + * @param sel The file selector.
    + * @param dirs @c TRUE if only directories can be selected, @c FALSE if files
    + * can also be selected.
    */
    void gnt_file_sel_set_dirs_only(GntFileSel *sel, gboolean dirs);
    /**
    - *
    - * @param sel
    + * Check whether the file selector allows only selecting directories.
    *
    - * @return
    + * @param sel The file selector.
    + *
    + * @return @c TRUE if only directories can be selected.
    */
    gboolean gnt_file_sel_get_dirs_only(GntFileSel *sel);
    /**
    - *
    - * @param sel
    - * @param must
    + * Set whether a selected file must exist.
    + *
    + * @param sel The file selector.
    + * @param must @c TRUE if the selected file must exist.
    */
    void gnt_file_sel_set_must_exist(GntFileSel *sel, gboolean must);
    /**
    - *
    - * @param sel
    + * Check whether the selector allows selecting non-existent files.
    *
    - * @return
    + * @param sel The file selector.
    + *
    + * @return @c TRUE if the selected file must exist, @c FALSE if a non-existent
    + * file can be selected.
    */
    gboolean gnt_file_sel_get_must_exist(GntFileSel *sel);
    /**
    - *
    - * @param sel
    + * Get the selected file in the selector.
    *
    - * @return
    + * @param sel The file selector.
    + *
    + * @return The path of the selected file. The caller should g_free the returned
    + * string.
    */
    char * gnt_file_sel_get_selected_file(GntFileSel *sel);
    - /* The returned value should be free'd */
    -
    /**
    - *
    - * @param sel
    + * Get the list of selected files in the selector.
    *
    - * @return
    + * @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.
    */
    GList * gnt_file_sel_get_selected_multi_files(GntFileSel *sel);
    /**
    - *
    - * @param sel
    - * @param set
    + * Allow selecting multiple files.
    + *
    + * @param sel The file selector.
    + * @param set @c TRUE if selecting multiple files should be allowed.
    */
    void gnt_file_sel_set_multi_select(GntFileSel *sel, gboolean set);
    /**
    - *
    - * @param sel
    - * @param suggest
    + * Set the suggested file to have selected at startup.
    + *
    + * @param sel The file selector.
    + * @param suggest The suggested filename.
    */
    void gnt_file_sel_set_suggested_filename(GntFileSel *sel, const char *suggest);
    /**
    - *
    - * @param sel
    - * @param path
    - * @param files
    - * @param error)
    + * Set custom functions to read the names of files.
    + *
    + * @param sel The file selector.
    + * @param read_fn The custom read function.
    */
    void gnt_file_sel_set_read_fn(GntFileSel *sel, gboolean (*read_fn)(const char *path, GList **files, GError **error));
    /**
    - *
    - * @param name
    - * @param size
    + * Create a new GntFile.
    *
    - * @return
    + * @param name The name of the file.
    + * @param size The size of the file.
    + *
    + * @return The newly created GntFile.
    */
    GntFile* gnt_file_new(const char *name, unsigned long size);
    /**
    - *
    - * @param name
    + * Create a new GntFile for a directory.
    *
    - * @return
    + * @param name The name of the directory.
    + *
    + * @return The newly created GntFile.
    */
    GntFile* gnt_file_new_dir(const char *name);
    --- a/gntkeys.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntkeys.h Wed Nov 07 14:07:52 2007 +0000
    @@ -104,41 +104,59 @@
    #define GNT_KEY_F12 SAFE(key_f12)
    /**
    - * This will do stuff with the terminal settings and stuff.
    - */
    -/**
    - *
    + * Initialize the keys.
    */
    void gnt_init_keys(void);
    /**
    - *
    - * @param text
    + * 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);
    +/**
    + * 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.
    + */
    const char *gnt_key_translate(const char *name);
    +
    +/**
    + * 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).
    + */
    const char *gnt_key_lookup(const char *key);
    /**
    - *
    - * @param path
    + * Add a key combination to the internal key-tree.
    + *
    + * @param key The key to add
    */
    -void gnt_keys_add_combination(const char *path);
    +void gnt_keys_add_combination(const char *key);
    /**
    - *
    - * @param path
    + * Remove a key combination from the internal key-tree.
    + *
    + * @param key The key to remove.
    */
    -void gnt_keys_del_combination(const char *path);
    +void gnt_keys_del_combination(const char *key);
    /**
    - *
    - * @param path
    + * Find a combination from the given string.
    + *
    + * @param key The input string.
    *
    - * @return
    + * @return The number of bytes in the combination that starts at the beginning
    + * of key (can be 0).
    */
    -int gnt_keys_find_combination(const char *path);
    +int gnt_keys_find_combination(const char *key);
    /* A lot of commonly used variable names are defined in <term.h>.
    * #undef them to make life easier for everyone. */
    --- a/gntlabel.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntlabel.h Wed Nov 07 14:07:52 2007 +0000
    @@ -67,33 +67,34 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntLabel.
    */
    GType gnt_label_get_gtype(void);
    /**
    - *
    - * @param text
    + * Create a new GntLabel.
    *
    - * @return
    + * @param text The text of the label.
    + *
    + * @return The newly created label.
    */
    GntWidget * gnt_label_new(const char *text);
    /**
    - *
    - * @param text
    - * @param flags
    + * Create a new label with specified text attributes.
    *
    - * @return
    + * @param text The text.
    + * @param flags Text attributes for the text.
    + *
    + * @return The newly created label.
    */
    GntWidget * gnt_label_new_with_format(const char *text, GntTextFormatFlags flags);
    /**
    - *
    - * @param label
    - * @param text
    + * Change the text of a label.
    + *
    + * @param label The label.
    + * @param text The new text to set in the label.
    */
    void gnt_label_set_text(GntLabel *label, const char *text);
    --- a/gntline.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntline.h Wed Nov 07 14:07:52 2007 +0000
    @@ -67,9 +67,7 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntLine.
    */
    GType gnt_line_get_gtype(void);
    @@ -77,10 +75,11 @@
    #define gnt_vline_new() gnt_line_new(TRUE)
    /**
    - *
    - * @param vertical
    + * Create new line
    *
    - * @return
    + * @param vertical @c TRUE if the line should be vertical, @c FALSE for a horizontal line.
    + *
    + * @return The newly created line.
    */
    GntWidget * gnt_line_new(gboolean vertical);
    --- a/gntmain.c Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntmain.c Wed Nov 07 14:07:52 2007 +0000
    @@ -646,7 +646,7 @@
    return TRUE;
    }
    -void gnt_set_clipboard_string(gchar *string)
    +void gnt_set_clipboard_string(const gchar *string)
    {
    gnt_clipboard_set_string(clipboard, string);
    }
    --- a/gntmenu.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntmenu.h Wed Nov 07 14:07:52 2007 +0000
    @@ -86,24 +86,24 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return The GType for GntMenu.
    */
    GType gnt_menu_get_gtype(void);
    /**
    - *
    - * @param type
    + * Create a new menu.
    *
    - * @return
    + * @param type The type of the menu, whether it's a toplevel menu or a popup menu.
    + *
    + * @return The newly created menu.
    */
    GntWidget * gnt_menu_new(GntMenuType type);
    /**
    - *
    - * @param menu
    - * @param item
    + * Add an item to the menu.
    + *
    + * @param menu The menu.
    + * @param item The item to add to the menu.
    */
    void gnt_menu_add_item(GntMenu *menu, GntMenuItem *item);
    --- a/gntmenuitem.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntmenuitem.h Wed Nov 07 14:07:52 2007 +0000
    @@ -86,32 +86,33 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntMenuItem.
    */
    GType gnt_menuitem_get_gtype(void);
    /**
    - *
    - * @param text
    + * Create a new menuitem.
    *
    - * @return
    + * @param text Label for the menuitem.
    + *
    + * @return The newly created menuitem.
    */
    GntMenuItem * gnt_menuitem_new(const char *text);
    /**
    - *
    - * @param item
    - * @param callback
    - * @param data
    + * Set a callback function for a menuitem.
    + *
    + * @param item The menuitem.
    + * @param callback The callback function.
    + * @param data Data to send to the callback function.
    */
    void gnt_menuitem_set_callback(GntMenuItem *item, GntMenuItemCallback callback, gpointer data);
    /**
    - *
    - * @param item
    - * @param menu
    + * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback.
    + *
    + * @param item The menuitem.
    + * @param menu The submenu.
    */
    void gnt_menuitem_set_submenu(GntMenuItem *item, GntMenu *menu);
    --- a/gntmenuitemcheck.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntmenuitemcheck.h Wed Nov 07 14:07:52 2007 +0000
    @@ -66,32 +66,33 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntMenuItemCheck.
    */
    GType gnt_menuitem_check_get_gtype(void);
    /**
    - *
    - * @param text
    + * Create a new menuitem.
    *
    - * @return
    + * @param text The text for the menuitem.
    + *
    + * @return The newly created menuitem.
    */
    GntMenuItem * gnt_menuitem_check_new(const char *text);
    /**
    - *
    - * @param item
    + * Check whether the menuitem is checked or not.
    *
    - * @return
    + * @param item The menuitem.
    + *
    + * @return @c TRUE if the item is checked, @c FALSE otherwise.
    */
    gboolean gnt_menuitem_check_get_checked(GntMenuItemCheck *item);
    /**
    - *
    - * @param item
    - * @param set
    + * Set whether the menuitem is checked or not.
    + *
    + * @param item The menuitem.
    + * @param set @c TRUE if the item should be checked, @c FALSE otherwise.
    */
    void gnt_menuitem_check_set_checked(GntMenuItemCheck *item, gboolean set);
    --- a/gntstyle.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntstyle.h Wed Nov 07 14:07:52 2007 +0000
    @@ -38,11 +38,17 @@
    } GntStyle;
    /**
    - *
    - * @param filename
    + * Read configuration from a file.
    + *
    + * @param filename The filename to read configuration from.
    */
    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.
    + */
    const char *gnt_style_get(GntStyle style);
    /**
    @@ -70,38 +76,40 @@
    gboolean gnt_style_parse_bool(const char *value);
    /**
    - *
    - * @param style
    - * @param def
    + * Get the boolean value for a user-setting.
    *
    - * @return
    + * @param style The style.
    + * @param def The default value (i.e, the value if the user didn't define
    + * any value)
    + *
    + * @return The value of the setting.
    */
    gboolean gnt_style_get_bool(GntStyle style, gboolean def);
    -/* This should be called only once for the each type */
    /**
    - *
    - * @param type
    - * @param hash
    + * @internal
    */
    void gnt_styles_get_keyremaps(GType type, GHashTable *hash);
    /**
    - *
    - * @param type
    - * @param klass
    + * @internal
    */
    void gnt_style_read_actions(GType type, GntBindableClass *klass);
    +/**
    + * @internal
    + * Read workspace information.
    + */
    void gnt_style_read_workspaces(GntWM *wm);
    /**
    - *
    + * Initialize style settings.
    */
    void gnt_init_styles(void);
    /**
    - *
    + * Uninitialize style settings.
    */
    void gnt_uninit_styles(void);
    +
    --- a/gnttextview.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gnttextview.h Wed Nov 07 14:07:52 2007 +0000
    @@ -88,116 +88,144 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntTextView.
    */
    GType gnt_text_view_get_gtype(void);
    -/* XXX: For now, don't set a textview to have any border.
    - * If you want borders real bad, put it in a box. */
    /**
    - *
    + * Create a new textview.
    *
    - * @return
    + * @return The newly created textview.
    */
    GntWidget * gnt_text_view_new(void);
    -/* scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end */
    /**
    - *
    - * @param view
    - * @param scroll
    + * Scroll the textview.
    + * @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);
    /**
    - *
    - * @param view
    - * @param text
    - * @param flags
    + * Append new text in a textview.
    + *
    + * @param view The textview.
    + * @param text The text to append to the textview.
    + * @param flags The text-flags to apply to the new text.
    */
    void gnt_text_view_append_text_with_flags(GntTextView *view, const char *text, GntTextFormatFlags flags);
    /**
    - *
    - * @param view
    - * @param text
    - * @param flags
    - * @param tag
    + * Append text in the textview, with some identifier (tag) for the added text.
    + *
    + * @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)
    */
    void gnt_text_view_append_text_with_tag(GntTextView *view, const char *text, GntTextFormatFlags flags, const char *tag);
    -/* 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
    + * 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);
    /**
    - *
    - * @param flags
    + * Convert GNT-text formats to ncurses-text attributes.
    *
    - * @return
    + * @param flags The GNT text format.
    + *
    + * @return Nucrses text attribute.
    */
    chtype gnt_text_format_flag_to_chtype(GntTextFormatFlags flags);
    /**
    - *
    - * @param view
    + * Clear the contents of the textview.
    + *
    + * @param view The textview.
    */
    void gnt_text_view_clear(GntTextView *view);
    /**
    - *
    - * @param view
    + * The number of lines below the bottom-most visible line.
    *
    - * @return
    + * @param view The textview.
    + *
    + * @return Number of lines below the bottom-most visible line.
    */
    int gnt_text_view_get_lines_below(GntTextView *view);
    /**
    - *
    - * @param view
    + * The number of lines above the topmost visible line.
    *
    - * @return
    + * @param view The textview.
    + *
    + * @return Number of lines above the topmost visible line.
    */
    int gnt_text_view_get_lines_above(GntTextView *view);
    -/* If text is NULL, then the tag is removed. */
    /**
    - *
    - * @param view
    - * @param name
    - * @param text
    - * @param all
    + * Change the text of a tag.
    *
    - * @return
    + * @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.
    */
    int gnt_text_view_tag_change(GntTextView *view, const char *name, const char *text, gboolean all);
    /**
    - *
    - * @param view
    - * @param 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);
    /**
    - *
    - * @param view
    - * @param widget
    + * 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
    + * in it.
    + *
    + * 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:
    + *
    + * @code
    + * [pager]
    + * key = a-v
    + * path = /path/to/pager
    + * @endcode
    + *
    + * @param view The textview.
    + * @param pager The widget to trigger the PAGER.
    */
    void gnt_text_view_attach_pager_widget(GntTextView *view, GntWidget *pager);
    /**
    - *
    - * @param view
    - * @param widget
    + * Setup appropriate hooks so that pressing some keys when 'widget'
    + * is in focus triggers the EDITOR to popup with the contents of the textview
    + * in it.
    + *
    + * 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:
    + *
    + * @code
    + * [editor]
    + * key = a-e
    + * path = /path/to/editor
    + * @endcode
    + *
    + * @param view The textview.
    + * @param widget The widget to trigger the EDITOR.
    */
    -void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *pager);
    +void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *widget);
    /**
    * Set a GntTextViewFlag for the textview widget.
    --- a/gntutils.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntutils.h Wed Nov 07 14:07:52 2007 +0000
    @@ -153,5 +153,5 @@
    *
    * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    -void gnt_util_set_trigger_widget(GntWidget *wid, const char *text, GntWidget *button);
    +void gnt_util_set_trigger_widget(GntWidget *widget, const char *key, GntWidget *button);
    --- a/gntwidget.c Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntwidget.c Wed Nov 07 14:07:52 2007 +0000
    @@ -617,7 +617,7 @@
    return;
    while (widget->parent)
    widget = widget->parent;
    -
    +
    if (!g_object_get_data(G_OBJECT(widget), "gnt:queue_update"))
    {
    int id = g_timeout_add(0, update_queue_callback, widget);
    --- a/gntwidget.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntwidget.h Wed Nov 07 14:07:52 2007 +0000
    @@ -140,167 +140,176 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntWidget.
    */
    GType gnt_widget_get_gtype(void);
    /**
    - *
    - * @param widget
    + * Destroy a widget.
    + * @param widget The widget to destroy.
    */
    void gnt_widget_destroy(GntWidget *widget);
    /**
    - *
    - * @param widget
    + * 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);
    /**
    - *
    - * @param widget
    + * Draw a widget.
    + * @param widget The widget to draw.
    */
    void gnt_widget_draw(GntWidget *widget);
    /**
    - *
    - * @param widget
    - * @param x
    - * @param y
    - * @param width
    - * @param height
    + * @internal
    + * Expose part of a widget.
    */
    void gnt_widget_expose(GntWidget *widget, int x, int y, int width, int height);
    /**
    - *
    - * @param widget
    + * Hide a widget.
    + * @param widget The widget to hide.
    */
    void gnt_widget_hide(GntWidget *widget);
    /**
    - *
    - * @param widget
    - * @param x
    - * @param y
    + * Get the position of a 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.
    */
    void gnt_widget_get_position(GntWidget *widget, int *x, int *y);
    /**
    - *
    - * @param widget
    - * @param x
    - * @param y
    + * 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);
    /**
    - *
    - * @param widget
    + * Request a widget to calculate its desired size.
    + * @param widget The widget.
    */
    void gnt_widget_size_request(GntWidget *widget);
    /**
    - *
    - * @param widget
    - * @param width
    - * @param height
    + * 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);
    /**
    - *
    - * @param widget
    - * @param width
    - * @param height
    + * Set the size of a widget.
    *
    - * @return
    + * @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.
    */
    gboolean gnt_widget_set_size(GntWidget *widget, int width, int height);
    /**
    - *
    - * @param widget
    - * @param width
    - * @param height
    + * Confirm a requested a size for a widget.
    *
    - * @return
    + * @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.
    */
    gboolean gnt_widget_confirm_size(GntWidget *widget, int width, int height);
    /**
    - *
    - * @param widget
    - * @param keys
    + * Trigger the key-press callbacks for a widget.
    *
    - * @return
    + * @param widget The widget.
    + * @param keys The keypress on the widget.
    + *
    + * @return @c TRUE if the key-press was handled, @c FALSE otherwise.
    */
    gboolean gnt_widget_key_pressed(GntWidget *widget, const char *keys);
    /**
    - *
    - * @param widget
    - * @param event
    - * @param x
    - * @param y
    + * Trigger the 'click' callback of a widget.
    *
    - * @return
    + * @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.
    */
    gboolean gnt_widget_clicked(GntWidget *widget, GntMouseEvent event, int x, int y);
    /**
    - *
    - * @param widget
    - * @param set
    + * 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
    + * focus should be removed.
    *
    - * @return
    + * @return @c TRUE if the focus has been changed, @c FALSE otherwise.
    */
    gboolean gnt_widget_set_focus(GntWidget *widget, gboolean set);
    /**
    - *
    - * @param widget
    + * 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);
    /**
    - *
    - * @param widget
    - * @param name
    + * 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.
    + */
    const char *gnt_widget_get_name(GntWidget *widget);
    -/* Widget-subclasses should call this from the draw-callback.
    - * Applications should just call gnt_widget_draw instead of this. */
    /**
    - *
    - * @param widget
    + * @internal
    + * Use #gnt_widget_draw instead.
    */
    void gnt_widget_queue_update(GntWidget *widget);
    /**
    - *
    - * @param widget
    - * @param set
    + * Set whether a widget can take focus or not.
    + *
    + * @param widget The widget.
    + * @param set @c TRUE if the widget can take focus.
    */
    void gnt_widget_set_take_focus(GntWidget *widget, gboolean set);
    /**
    - *
    - * @param widget
    - * @param set
    + * Set the visibility of a widget.
    + *
    + * @param widget The widget.
    + * @param set Whether the widget is visible or not.
    */
    void gnt_widget_set_visible(GntWidget *widget, gboolean set);
    /**
    - *
    - * @param widget
    + * Check whether the widget has shadows.
    *
    - * @return
    + * @param widget The widget.
    + *
    + * @return @c 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/gntwindow.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntwindow.h Wed Nov 07 14:07:52 2007 +0000
    @@ -77,25 +77,27 @@
    #define gnt_hwindow_new(homo) gnt_window_box_new(homo, FALSE)
    /**
    - *
    + * Create a new window.
    *
    - * @return
    + * @return The newly created window.
    */
    GntWidget * gnt_window_new(void);
    /**
    - *
    - * @param homo
    - * @param vert
    + * Create a new window.
    *
    - * @return
    + * @param homo @c TRUE if the widgets inside the window should have the same dimensions.
    + * @param vert @c TRUE if the widgets inside the window should be stacked vertically.
    + *
    + * @return The newly created window.
    */
    GntWidget * gnt_window_box_new(gboolean homo, gboolean vert);
    /**
    - *
    - * @param window
    - * @param menu
    + * Set the menu for a window.
    + *
    + * @param window The window.
    + * @param menu The menu for the window.
    */
    void gnt_window_set_menu(GntWindow *window, GntMenu *menu);
    --- a/gntwm.c Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntwm.c Wed Nov 07 14:07:52 2007 +0000
    @@ -1675,7 +1675,7 @@
    {
    while (widget->parent)
    widget = widget->parent;
    -
    +
    if (GNT_WIDGET_IS_FLAG_SET(widget, GNT_WIDGET_INVISIBLE) ||
    g_hash_table_lookup(wm->nodes, widget)) {
    update_screen(wm);
    --- a/gntwm.h Wed Nov 07 13:49:26 2007 +0000
    +++ b/gntwm.h Wed Nov 07 14:07:52 2007 +0000
    @@ -113,7 +113,7 @@
    * whether to give focus to a new window.
    */
    gboolean event_stack;
    -
    +
    GntKeyPressMode mode;
    GHashTable *positions;
    @@ -184,108 +184,149 @@
    G_BEGIN_DECLS
    /**
    - *
    - *
    - * @return
    + * @return GType for GntWM.
    */
    GType gnt_wm_get_gtype(void);
    +/**
    + * Add a workspace.
    + * @param wm The window-manager.
    + * @param ws The workspace to add.
    + */
    void gnt_wm_add_workspace(GntWM *wm, GntWS *ws);
    +/**
    + * Switch to a workspace.
    + * @param wm The window-manager.
    + * @param n Index of the workspace to switch to.
    + *
    + * @return @c TRUE if the switch was successful.
    + */
    gboolean gnt_wm_switch_workspace(GntWM *wm, gint n);
    +
    +/**
    + * Switch to the previous workspace from the current one.
    + * @param wm The window-manager.
    + */
    gboolean gnt_wm_switch_workspace_prev(GntWM *wm);
    +
    +/**
    + * Switch to the next workspace from the current one.
    + * @param wm The window-manager.
    + */
    gboolean gnt_wm_switch_workspace_next(GntWM *wm);
    +
    +/**
    + * 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);
    +
    +/**
    + * 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);
    +
    +/**
    + * 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.
    + */
    GntWS *gnt_wm_widget_find_workspace(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param widget
    + * Process a new window.
    + *
    + * @param wm The window-manager.
    + * @param widget The new window.
    */
    void gnt_wm_new_window(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param widget
    + * Decorate a window.
    + * @param wm The window-manager.
    + * @param widget The widget to decorate.
    */
    void gnt_wm_window_decorate(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param widget
    + * Close a window.
    + * @param wm The window-manager.
    + * @param widget The window to close.
    */
    void gnt_wm_window_close(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param string
    + * Process input.
    *
    - * @return
    + * @param wm The window-manager.
    + * @param string The input string to process.
    + *
    + * @return @c TRUE of the string was processed, @c FALSE otherwise.
    */
    gboolean gnt_wm_process_input(GntWM *wm, const char *string);
    /**
    - *
    - * @param wm
    - * @param event
    - * @param x
    - * @param y
    - * @param widget
    + * Process a click event.
    + * @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
    + * @return @c TRUE if the event was handled, @c FALSE otherwise.
    */
    gboolean gnt_wm_process_click(GntWM *wm, GntMouseEvent event, int x, int y, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param widget
    - * @param width
    - * @param height
    + * Resize a 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);
    /**
    - *
    - * @param wm
    - * @param widget
    - * @param x
    - * @param y
    + * Move a 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);
    /**
    - *
    - * @param wm
    - * @param widget
    + * Update a window.
    + * @param wm The window-manager.
    + * @param widget The window to update.
    */
    void gnt_wm_update_window(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param widget
    + * Raise a window.
    + * @param wm The window-manager.
    + * @param widget The window to raise.
    */
    void gnt_wm_raise_window(GntWM *wm, GntWidget *widget);
    /**
    - *
    - * @param wm
    - * @param set
    + * @internal
    */
    void gnt_wm_set_event_stack(GntWM *wm, gboolean set);
    +/**
    + * @internal
    + */
    void gnt_wm_copy_win(GntWidget *widget, GntNode *node);
    /**
    - *
    - *
    - * @return
    + * @return The idle time of the user.
    */
    time_t gnt_wm_get_idle_time(void);