bonobo-ui-util

## bonobo-ui-util bonobo-ui-util — A collection of utility functions to help with UI related issues |

## Synopsis

    char*               bonobo_ui_util_pixbuf_to_xml        (GdkPixbuf *pixbuf);
    GdkPixbuf*          bonobo_ui_util_xml_to_pixbuf        (const char *xml);
    GtkWidget*          bonobo_ui_util_xml_get_icon_widget  (BonoboUINode *node,
                                                             GtkIconSize icon_size);
    void                bonobo_ui_util_xml_set_pixbuf       (BonoboUINode *node,
                                                             GdkPixbuf *pixbuf);
    void                bonobo_ui_util_build_help_menu      (BonoboUIComponent *listener,
                                                             const char *app_prefix,
                                                             const char *app_name,
                                                             BonoboUINode *parent);
    char*               bonobo_ui_util_get_ui_fname         (const char *component_prefix,
                                                             const char *file_name);
    void                bonobo_ui_util_translate_ui         (BonoboUINode *node);
    void                bonobo_ui_util_fixup_help           (BonoboUIComponent *component,
                                                             BonoboUINode *node,
                                                             const char *app_prefix,
                                                             const char *app_name);
    void                bonobo_ui_util_fixup_icons          (BonoboUINode *node);
    BonoboUINode*       bonobo_ui_util_new_ui               (BonoboUIComponent *component,
                                                             const char *fname,
                                                             const char *app_prefix,
                                                             const char *app_name);
    void                bonobo_ui_util_set_ui               (BonoboUIComponent *component,
                                                             const char *app_prefix,
                                                             const char *file_name,
                                                             const char *app_name,
                                                             CORBA_Environment *opt_ev);
    void                bonobo_ui_util_set_pixbuf           (BonoboUIComponent *component,
                                                             const char *path,
                                                             GdkPixbuf *pixbuf,
                                                             CORBA_Environment *opt_ev);
    gchar*              bonobo_ui_util_accel_name           (guint accelerator_key,
                                                             GdkModifierType accelerator_mods);
    void                bonobo_ui_util_accel_parse          (const char *name,
                                                             guint *accelerator_key,
                                                             GdkModifierType *accelerator_mods);
    #define             bonobo_ui_util_decode_str           (s,e)
    #define             bonobo_ui_util_encode_str           (s)

## Description

The UI utilities do man things, mostly concerned with smoothing the flow of XML data from containee to container. There are also several generaly useful functions used internaly for manipulating pixmaps. Also, code for stringifying accelerators, fixing up help and working around libxml bugs. Also a large chunk of code is included for dynamic UI tree building that is now strongly deprecated by the various tools to do this from dynamic files.

## Details

### bonobo_ui_util_pixbuf_to_xml ()

    char*               bonobo_ui_util_pixbuf_to_xml        (GdkPixbuf *pixbuf);

Convert a `pixbuf` to a string representation suitable for passing as a "pixname" attribute with a pixtype attribute = "pixbuf".

`pixbuf` : | a GdkPixbuf
Returns : | the stringified pixbuf.

### bonobo_ui_util_xml_to_pixbuf ()

    GdkPixbuf*          bonobo_ui_util_xml_to_pixbuf        (const char *xml);

This converts a stringified pixbuf in `xml` into a GdkPixbuf

`xml` : | a string
Returns : | a handed reference to the created GdkPixbuf.

### bonobo_ui_util_xml_get_icon_widget ()

    GtkWidget*          bonobo_ui_util_xml_get_icon_widget  (BonoboUINode *node,
                                                             GtkIconSize icon_size);

This function extracts a pixbuf from the node and returns a GtkWidget containing a display of the pixbuf.

Unused internally.

`node` : | the node
`icon_size` : | the desired size of the icon
Returns : | the widget.

### bonobo_ui_util_xml_set_pixbuf ()

    void                bonobo_ui_util_xml_set_pixbuf       (BonoboUINode *node,
                                                             GdkPixbuf *pixbuf);

Associate `pixbuf` with this `node` by stringifying it and setting the requisite attributes.

`node` : | the node
`pixbuf` : | the pixbuf

### bonobo_ui_util_build_help_menu ()

    void                bonobo_ui_util_build_help_menu      (BonoboUIComponent *listener,
                                                             const char *app_prefix,
                                                             const char *app_name,
                                                             BonoboUINode *parent);

This routine inserts all the help menu items appropriate for this application as children of the `parent` node.

`listener` : | associated component
`app_prefix` : | application prefix
`app_name` : | application name
`parent` : | toplevel node

### bonobo_ui_util_get_ui_fname ()

    char*               bonobo_ui_util_get_ui_fname         (const char *component_prefix,
                                                             const char *file_name);

Builds a path to the xml file that stores the GUI.

`component_prefix` : |
`file_name` : | the file name of the xml file.
Returns : | the path to the file that describes the UI or NULL if it is not found.

### bonobo_ui_util_translate_ui ()

    void                bonobo_ui_util_translate_ui         (BonoboUINode *node);

Quest through a tree looking for translatable properties ( those prefixed with an '_' ). Translates the value of the property and removes the leading '_'.

`node` : | the node to start at.

### bonobo_ui_util_fixup_help ()

    void                bonobo_ui_util_fixup_help           (BonoboUIComponent *component,
                                                             BonoboUINode *node,
                                                             const char *app_prefix,
                                                             const char *app_name);

This searches for 'BuiltMenuItems' placeholders, and then fills them with the application's menu items.

`component` : | the UI component
`node` : | the node to search under
`app_prefix` : | the application prefix
`app_name` : | the application name

### bonobo_ui_util_fixup_icons ()

    void                bonobo_ui_util_fixup_icons          (BonoboUINode *node);

This function is used to ensure filename pixbuf attributes are converted to in-line pixbufs on the server side, so that we don't sent a ( possibly invalid ) filename across the wire.

`node` : | the node

### bonobo_ui_util_new_ui ()

    BonoboUINode*       bonobo_ui_util_new_ui               (BonoboUIComponent *component,
                                                             const char *fname,
                                                             const char *app_prefix,
                                                             const char *app_name);

Loads an xml tree from a file, cleans the doc cruft from its nodes; and translates the nodes.

`component` : | The component help callback should be on
`fname` : |
`app_prefix` : |
`app_name` : | Application name ( for finding help )
Returns : | The translated tree ready to be merged.

### bonobo_ui_util_set_ui ()

    void                bonobo_ui_util_set_ui               (BonoboUIComponent *component,
                                                             const char *app_prefix,
                                                             const char *file_name,
                                                             const char *app_name,
                                                             CORBA_Environment *opt_ev);

This function loads the UI from the associated file, translates it, fixes up all the menus, ensures pixbuf filenames are resolved to xml and then merges the XML to the remote container - this is the best and most simple entry point for the new UI code.

`component` : | the component
`app_prefix` : |
`file_name` : | the filename of the file to merge relative to the prefix.
`app_name` : | the application name - for help merging
`opt_ev` : |

### bonobo_ui_util_set_pixbuf ()

    void                bonobo_ui_util_set_pixbuf           (BonoboUIComponent *component,
                                                             const char *path,
                                                             GdkPixbuf *pixbuf,
                                                             CORBA_Environment *opt_ev);

This helper function sets a pixbuf at a certain path into an xml tree.

`component` : | the component
`path` : | the path into the xml tree
`pixbuf` : | the pixbuf
`opt_ev` : |

### bonobo_ui_util_accel_name ()

    gchar*              bonobo_ui_util_accel_name           (guint accelerator_key,
                                                             GdkModifierType accelerator_mods);

This stringifies an `accelerator_key` and some `accelerator_mods` it is the converse of bonobo_ui_util_accel_parse

`accelerator_key` : | the key
`accelerator_mods` : | the modifiers
Returns : | the stringified representation

### bonobo_ui_util_accel_parse ()

    void                bonobo_ui_util_accel_parse          (const char *name,
                                                             guint *accelerator_key,
                                                             GdkModifierType *accelerator_mods);

This parses the accelerator string and returns the key and mods associated with it - using a similar format to Gtk+ but one which doesn't involve inefficient XML entities and avoids other misc. problems.

`name` : |
`accelerator_key` : | output of the key
`accelerator_mods` : | output of the mods

### bonobo_ui_util_decode_str()

    #define         bonobo_ui_util_decode_str(s,e) g_strdup (s)

`s` : |
`e` : |
Returns : |

### bonobo_ui_util_encode_str()

    #define         bonobo_ui_util_encode_str(s)   g_strdup (s)

`s` : |
Returns : |