## Glade Utils

Glade Utils — Welcome to the zoo.

## Synopsis

    enum                GladeUtilFileDialogType;
    enum                GladeUIMessageType;
    GType               glade_util_get_type_from_name       (const gchar *name,
                                                             gboolean have_func);
    GParamSpec *        glade_utils_get_pspec_from_funcname (const gchar *funcname);
    gboolean            glade_util_ui_message               (GtkWidget *parent,
                                                             GladeUIMessageType type,
                                                             GtkWidget *widget,
                                                             const gchar *format,
                                                             ...);
    void                glade_util_flash_message            (GtkWidget *statusbar,
                                                             guint context_id,
                                                             gchar *format,
                                                             ...);
    gint                glade_util_compare_stock_labels     (gconstpointer a,
                                                             gconstpointer b);
    void                glade_util_hide_window              (GtkWindow *window);
    gchar *             glade_util_gtk_combo_func           (gpointer data);
    gpointer            glade_util_gtk_combo_find           (GtkCombo *combo);
    GtkWidget *         glade_util_file_dialog_new          (const gchar *title,
                                                             GladeProject *project,
                                                             GtkWindow *parent,
                                                             GladeUtilFileDialogType action);
    void                glade_util_replace                  (gchar *str,
                                                             gchar a,
                                                             gchar b);
    gchar *             glade_util_read_prop_name           (const gchar *str);
    gchar *             glade_util_duplicate_underscores    (const gchar *name);
    void                glade_util_add_selection            (GtkWidget *widget);
    void                glade_util_remove_selection         (GtkWidget *widget);
    gboolean            glade_util_has_selection            (GtkWidget *widget);
    void                glade_util_clear_selection          (void);
    GList *             glade_util_get_selection            (void);
    GList *             glade_util_container_get_all_children
                                                            (GtkContainer *container);
    gint                glade_util_count_placeholders       (GladeWidget *parent);
    GtkTreeIter *       glade_util_find_iter_by_widget      (GtkTreeModel *model,
                                                             GladeWidget *findme,
                                                             gint column);
    gboolean            glade_util_basenames_match          (const gchar *path1,
                                                             const gchar *path2);
    GList *             glade_util_purify_list              (GList *list);
    GList *             glade_util_added_in_list            (GList *old_list,
                                                             GList *new_list);
    GList *             glade_util_removed_from_list        (GList *old_list,
                                                             GList *new_list);
    gchar *             glade_util_canonical_path           (const gchar *path);
    gboolean            glade_util_copy_file                (const gchar *src_path,
                                                             const gchar *dest_path);
    gboolean            glade_util_class_implements_interface
                                                            (GType class_type,
                                                             GType iface_type);
    GModule *           glade_util_load_library             (const gchar *library_name);
    gboolean            glade_util_file_is_writeable        (const gchar *path);
    gboolean            glade_util_have_devhelp             (void);
    GtkWidget *         glade_util_get_devhelp_icon         (GtkIconSize size);
    void                glade_util_search_devhelp           (const gchar *book,
                                                             const gchar *page,
                                                             const gchar *search);
    GtkWidget *         glade_util_get_placeholder_from_pointer
                                                            (GtkContainer *container);
    gboolean            glade_util_object_is_loading        (GObject *object);
    gboolean            glade_util_url_show                 (const gchar *url);
    time_t              glade_util_get_file_mtime           (const gchar *filename,
                                                             GError **error);
    void                glade_util_draw_selection_nodes     (GdkWindow *expose_win);

## Description

This is where all of that really usefull miscalanious stuff lands up.

## Details

### enum GladeUtilFileDialogType

    typedef enum {
            GLADE_FILE_DIALOG_ACTION_OPEN,
            GLADE_FILE_DIALOG_ACTION_SAVE
    } GladeUtilFileDialogType;

### enum GladeUIMessageType

    typedef enum {
    	GLADE_UI_INFO,
    	GLADE_UI_WARN,
    	GLADE_UI_ERROR,
    	GLADE_UI_ARE_YOU_SURE,
    	GLADE_UI_YES_OR_NO
    } GladeUIMessageType;

### glade_util_get_type_from_name ()

    GType               glade_util_get_type_from_name       (const gchar *name,
                                                             gboolean have_func);

Returns the type using the "get type" function name based on `name`. If the `have_func` flag is true,`name` is used directly, otherwise the get-type function is contrived from `name` then used.

`name` : | the name of the GType - like 'GtkWidget' or a "get-type" function.
`have_func` : | function-name flag -- true if the name is a "get-type" function.
Returns : | the new GType

### glade_utils_get_pspec_from_funcname ()

    GParamSpec *        glade_utils_get_pspec_from_funcname (const gchar *funcname);

`funcname` : | the symbol name of a function to generate a GParamSpec
Returns : | A GParamSpec created by the delagate function specified by `funcname`

### glade_util_ui_message ()

    gboolean            glade_util_ui_message               (GtkWidget *parent,
                                                             GladeUIMessageType type,
                                                             GtkWidget *widget,
                                                             const gchar *format,
                                                             ...);

Creates a new warning dialog window as a child of `parent` containing the text of `format`, runs it, then destroys it on close. Depending on `type`, a cancel button may apear or the icon may change.

`parent` : | a GtkWindow cast as a GtkWidget
`type` : | a GladeUIMessageType
`widget` : | a GtkWidget to append to the dialog vbox
`format` : | a printf style format string
`...` : | args for the format.
Returns : | True if the `type` was GLADE_UI_ARE_YOU_SURE and the user selected "OK", True if the `type` was GLADE_UI_YES_OR_NO and the user selected "YES"; False otherwise.

### glade_util_flash_message ()

    void                glade_util_flash_message            (GtkWidget *statusbar,
                                                             guint context_id,
                                                             gchar *format,
                                                             ...);

### glade_util_compare_stock_labels ()

    gint                glade_util_compare_stock_labels     (gconstpointer a,
                                                             gconstpointer b);

This is a GCompareFunc that compares the labels of two stock items, ignoring any '_' characters. It isn't particularly efficient.

`a` : | a gconstpointer to a GtkStockItem
`b` : | a gconstpointer to a GtkStockItem
Returns : | negative value if `a` < `b`; zero if `a` = `b`; positive value if `a` > `b`

### glade_util_hide_window ()

    void                glade_util_hide_window              (GtkWindow *window);

If you use this function to handle the delete_event of a window, when it will be shown again it will appear in the position where it was before beeing hidden.

`window` : | a GtkWindow

### glade_util_gtk_combo_func ()

    gchar *             glade_util_gtk_combo_func           (gpointer data);

TODO: write me

### glade_util_gtk_combo_find ()

    gpointer            glade_util_gtk_combo_find           (GtkCombo *combo);

TODO: write me

### glade_util_file_dialog_new ()

    GtkWidget *         glade_util_file_dialog_new          (const gchar *title,
                                                             GladeProject *project,
                                                             GtkWindow *parent,
                                                             GladeUtilFileDialogType action);

`title` : | dialog title
`project` : | a GladeProject used when saving
`parent` : | a parent GtkWindow for the dialog
`action` : | a GladeUtilFileDialogType to say if the dialog will open or save
Returns : | a "glade file" file chooser dialog. The caller is responsible for showing the dialog

### glade_util_replace ()

    void                glade_util_replace                  (gchar *str,
                                                             gchar a,
                                                             gchar b);

Replaces each occurance of the character `a` in `str` to `b`.

`str` : | a string
`a` : | a gchar
`b` : | a gchar

### glade_util_read_prop_name ()

    gchar *             glade_util_read_prop_name           (const gchar *str);

Return a usable version of a property identifier as found in a freshly parserd GladeInterface

`str` : | a string

### glade_util_duplicate_underscores ()

    gchar *             glade_util_duplicate_underscores    (const gchar *name);

Duplicates `name`, but the copy has two underscores in place of any single underscore in the original.

`name` : | a string
Returns : | a newly allocated string

### glade_util_add_selection ()

    void                glade_util_add_selection            (GtkWidget *widget);

Add visual selection to this GtkWidget

`widget` : | a GtkWidget

### glade_util_remove_selection ()

    void                glade_util_remove_selection         (GtkWidget *widget);

Remove visual selection from this GtkWidget

`widget` : | a GtkWidget

### glade_util_has_selection ()

    gboolean            glade_util_has_selection            (GtkWidget *widget);

`widget` : | a GtkWidget
Returns : | `TRUE` if `widget` has visual selection, `FALSE` otherwise

### glade_util_clear_selection ()

    void                glade_util_clear_selection          (void);

Clear all visual selections

### glade_util_get_selection ()

    GList *             glade_util_get_selection            (void);

### glade_util_container_get_all_children ()

    GList *             glade_util_container_get_all_children
                                                            (GtkContainer *container);

Use this to itterate over all children in a GtkContainer, as it used `_forall()` instead of `_foreach()` (and the GTK+ version of this function is simply not exposed).

Note that `glade_widget_class_get_children()` is the high-level abstraction and will usually end up calling this function.

`container` : | a GtkContainer
Returns : | a GList giving the contents of `container`

### glade_util_count_placeholders ()

    gint                glade_util_count_placeholders       (GladeWidget *parent);

`parent` : | a GladeWidget
Returns : | the amount of GladePlaceholders parented by `parent`

### glade_util_find_iter_by_widget ()

    GtkTreeIter *       glade_util_find_iter_by_widget      (GtkTreeModel *model,
                                                             GladeWidget *findme,
                                                             gint column);

Looks through `model` for the GtkTreeIter corresponding to `findme` under `column`.

`model` : | a GtkTreeModel
`findme` : | a GladeWidget
`column` : | a gint
Returns : | a newly allocated GtkTreeIter from `model` corresponding to `findme` which should be freed with `gtk_tree_iter_free()`

### glade_util_basenames_match ()

    gboolean            glade_util_basenames_match          (const gchar *path1,
                                                             const gchar *path2);

### glade_util_purify_list ()

    GList *             glade_util_purify_list              (GList *list);

`list` : | A GList
Returns : | A newly allocated version of `list` with no duplicate data entries

### glade_util_added_in_list ()

    GList *             glade_util_added_in_list            (GList *old_list,
                                                             GList *new_list);

`old_list` : | the old GList
`new_list` : | the new GList
Returns : | A newly allocated GList of elements that are in `new` but not in `old`

### glade_util_removed_from_list ()

    GList *             glade_util_removed_from_list        (GList *old_list,
                                                             GList *new_list);

`old_list` : | the old GList
`new_list` : | the new GList
Returns : | A newly allocated GList of elements that are in `old` no longer in `new`

### glade_util_canonical_path ()

    gchar *             glade_util_canonical_path           (const gchar *path);

`path` : | any path that may contain ".." or "." components
Returns : | an absolute path to the specified file or directory that contains no ".." or "." components (this does not call readlink like `realpath()` does). Note: on some systems; I think its possible that we dont have permission to execute in the directory in which the glade file resides; I decided finally to do it this way anyway since libc's `realpath()` does exactly the same.

### glade_util_copy_file ()

    gboolean            glade_util_copy_file                (const gchar *src_path,
                                                             const gchar *dest_path);

Copies a file from `src` to `dest`, queries the user if it involves overwriting the target and displays an error message upon failure.

`src_path` : | the path to the source file
`dest_path` : | the path to the destination file to create or overwrite.
Returns : | True if the copy was successfull.

### glade_util_class_implements_interface ()

    gboolean            glade_util_class_implements_interface
                                                            (GType class_type,
                                                             GType iface_type);

`class_type` : | A GType
`iface_type` : | A GType
Returns : | whether `class_type` implements the `iface_type` interface

### glade_util_load_library ()

    GModule *           glade_util_load_library             (const gchar *library_name);

Loads the named library from the Glade modules directory, or failing that from the standard platform specific directories.

The `library_name` should not include any platform specifix prefix or suffix, those are automatically added, if needed, by `g_module_build_path()`

`library_name` : | name of the library
Returns : | a GModule on success, or `NULL` on failure.

### glade_util_file_is_writeable ()

    gboolean            glade_util_file_is_writeable        (const gchar *path);

Checks whether the file at `path` is writeable

`path` : | the path to the file
Returns : | TRUE if file is writeable

### glade_util_have_devhelp ()

    gboolean            glade_util_have_devhelp             (void);

Returns : | whether the devhelp module is loaded

### glade_util_get_devhelp_icon ()

    GtkWidget *         glade_util_get_devhelp_icon         (GtkIconSize size);

Creates an image displaying the devhelp icon.

`size` : | the preferred icon size
Returns : | a GtkImage

### glade_util_search_devhelp ()

    void                glade_util_search_devhelp           (const gchar *book,
                                                             const gchar *page,
                                                             const gchar *search);

### glade_util_get_placeholder_from_pointer ()

    GtkWidget *         glade_util_get_placeholder_from_pointer
                                                            (GtkContainer *container);

### glade_util_object_is_loading ()

    gboolean            glade_util_object_is_loading        (GObject *object);

`object` : | A GObject
Returns : | Whether the object's project is being loaded or not.

### glade_util_url_show ()

    gboolean            glade_util_url_show                 (const gchar *url);

Portable function for showing an URL `url` in a web browser.

`url` : | An URL to display
Returns : | TRUE if a web browser was successfully launched, or FALSE

### glade_util_get_file_mtime ()

    time_t              glade_util_get_file_mtime           (const gchar *filename,
                                                             GError **error);

Gets the UTC modification time of file `filename`.

`filename` : | A filename
`error` : | return location for errors
Returns : | The mtime of the file, or `0` if the file attributes could not be read.

### glade_util_draw_selection_nodes ()

    void                glade_util_draw_selection_nodes     (GdkWindow *expose_win);

Redraws any selection nodes that intersect `expose_win`. Steps through all selected widgets, finds their coordinates, and calls `glade_util_draw_nodes()` if appropriate.

`expose_win` : | a GdkWindow