bonobo-ui-util

Name

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);
GdkPixbuf*  bonobo_ui_util_xml_get_icon_pixbuf
                                            (BonoboUINode *node,
                                             gboolean prepend_menu);
GtkWidget*  bonobo_ui_util_xml_get_icon_pixmap_widget
                                            (BonoboUINode *node,
                                             gboolean prepend_menu);
void        bonobo_ui_util_xml_set_pixbuf   (BonoboUINode *node,
                                             GdkPixbuf *pixbuf);
void        bonobo_ui_util_xml_set_pix_xpm  (BonoboUINode *node,
                                             const char **xpm);
void        bonobo_ui_util_xml_set_pix_stock
                                            (BonoboUINode *node,
                                             const char *name);
void        bonobo_ui_util_xml_set_pix_fname
                                            (BonoboUINode *node,
                                             const char *name);
void        bonobo_ui_util_build_help_menu  (BonoboUIComponent *listener,
                                             const char *app_prefix,
                                             const char *app_name,
                                             BonoboUINode *parent);
BonoboUINode* bonobo_ui_util_build_accel    (guint accelerator_key,
                                             GdkModifierType accelerator_mods,
                                             const char *verb);
BonoboUINode* bonobo_ui_util_new_menu       (gboolean submenu,
                                             const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *verb);
BonoboUINode* bonobo_ui_util_new_placeholder
                                            (const char *name,
                                             gboolean top,
                                             gboolean bottom);
void        bonobo_ui_util_set_radiogroup   (BonoboUINode *node,
                                             const char *group_name);
void        bonobo_ui_util_set_toggle       (BonoboUINode *node,
                                             const char *id,
                                             const char *init_state);
BonoboUINode* bonobo_ui_util_new_std_toolbar
                                            (const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *verb);
BonoboUINode* bonobo_ui_util_new_toggle_toolbar
                                            (const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *id);
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_icons      (BonoboUINode *node);
void        bonobo_ui_util_fixup_help       (BonoboUIComponent *component,
                                             BonoboUINode *node,
                                             const char *app_prefix,
                                             const char *app_name);
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);
void        bonobo_ui_util_set_pixbuf       (BonoboUIComponent *component,
                                             const char *path,
                                             GdkPixbuf *pixbuf);
gchar*      bonobo_ui_util_accel_name       (guint accelerator_key,
                                             GdkModifierType accelerator_mods);
void        bonobo_ui_util_accel_parse      (char *name,
                                             guint *accelerator_key,
                                             GdkModifierType *accelerator_mods);
char*       bonobo_ui_util_decode_str       (const char *str,
                                             gboolean *err);
char*       bonobo_ui_util_encode_str       (const char *str);

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_pixbuf ()

GdkPixbuf*  bonobo_ui_util_xml_get_icon_pixbuf
                                            (BonoboUINode *node,
                                             gboolean prepend_menu);

This routine returns a GdkPixbuf for a node, if prepend_menu is TRUE then if it is a stock pixbuf 'Menu_' will be prepended to the stock name. Otherwise the pixbuf is extracted either from the node, a filename, or the stock system.

node : the node
prepend_menu : whether the pixbuf is for a menu item
Returns : A handed reference to the extracted pixbuf.


bonobo_ui_util_xml_get_icon_pixmap_widget ()

GtkWidget*  bonobo_ui_util_xml_get_icon_pixmap_widget
                                            (BonoboUINode *node,
                                             gboolean prepend_menu);

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

node : the node
prepend_menu : whether the pixbuf is for a menu item
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_xml_set_pix_xpm ()

void        bonobo_ui_util_xml_set_pix_xpm  (BonoboUINode *node,
                                             const char **xpm);

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

node : the node
xpm : an xpm


bonobo_ui_util_xml_set_pix_stock ()

void        bonobo_ui_util_xml_set_pix_stock
                                            (BonoboUINode *node,
                                             const char *name);

Associate the stock pixmap named name with this node

node : the node
name : the stock name


bonobo_ui_util_xml_set_pix_fname ()

void        bonobo_ui_util_xml_set_pix_fname
                                            (BonoboUINode *node,
                                             const char *name);

Associate a pixmap filename name with a node

node : the node
name : the filename


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 : 
app_name : application name
parent : toplevel node


bonobo_ui_util_build_accel ()

BonoboUINode* bonobo_ui_util_build_accel    (guint accelerator_key,
                                             GdkModifierType accelerator_mods,
                                             const char *verb);

This routine builds an accelerator node from the key and mod mask and associates it with a verb.

accelerator_key : the accelerator key
accelerator_mods : the accelerator mods
verb : the associated verb.
Returns : the built node.


bonobo_ui_util_new_menu ()

BonoboUINode* bonobo_ui_util_new_menu       (gboolean submenu,
                                             const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *verb);

A helper routine to create a menu or submenu with associated information - this routine is strongly deprecated.

submenu : whether it is a menu or submenu
name : the path element name of the menu
label : the label
tip : the description
verb : the associated verb
Returns : the constructed node.


bonobo_ui_util_new_placeholder ()

BonoboUINode* bonobo_ui_util_new_placeholder
                                            (const char *name,
                                             gboolean top,
                                             gboolean bottom);

A helper routine to create a menu or submenu with associated information - this routine is strongly deprecated - it is also broken.

name : path element name of the placeholder
top : whether to delimit at the top
bottom : whether to delimit at the bottom
Returns : the new node


bonobo_ui_util_set_radiogroup ()

void        bonobo_ui_util_set_radiogroup   (BonoboUINode *node,
                                             const char *group_name);

This is a helper function that sets the radiogroup to the requested group - deprecated

node : the node
group_name : the group name.


bonobo_ui_util_set_toggle ()

void        bonobo_ui_util_set_toggle       (BonoboUINode *node,
                                             const char *id,
                                             const char *init_state);

Deprecated, makes a node toggleable.

node : the node
id : the associated id
init_state : 


bonobo_ui_util_new_std_toolbar ()

BonoboUINode* bonobo_ui_util_new_std_toolbar
                                            (const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *verb);

Deprecated - created a new toolbar item.

name : 
label : 
tip : 
verb : 
Returns : 


bonobo_ui_util_new_toggle_toolbar ()

BonoboUINode* bonobo_ui_util_new_toggle_toolbar
                                            (const char *name,
                                             const char *label,
                                             const char *tip,
                                             const char *id);

Deprecated - creates a new toggle toolbar item

name : 
label : 
tip : 
id : 
Returns : 


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_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_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 : 
app_name : the application name


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);

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 datadir.
app_name : the application name - for help merging


bonobo_ui_util_set_pixbuf ()

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

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


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      (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 ()

char*       bonobo_ui_util_decode_str       (const char *str,
                                             gboolean *err);

This provides the inverse mapping for bonobo_ui_util_encode_str

str : the string
err : a pointer to an error flag
Returns : the decoded string or NULL on failure.


bonobo_ui_util_encode_str ()

char*       bonobo_ui_util_encode_str       (const char *str);

This function is needed to encode labels that contain either UTF-8 or other 8 bit charsets. This is due to severe libxml1 breakage. If you want to do manual label setting you need this function.

str : the string
Returns : the mangled (hex) text.