bonobo-ui-component

bonobo-ui-component

Functions

void (*BonoboUIListenerFn) ()
void (*BonoboUIVerbFn) ()
BonoboUIComponent * bonobo_ui_component_construct ()
BonoboUIComponent * bonobo_ui_component_new ()
BonoboUIComponent * bonobo_ui_component_new_default ()
void bonobo_ui_component_set_name ()
const char * bonobo_ui_component_get_name ()
void bonobo_ui_component_set_container ()
void bonobo_ui_component_unset_container ()
Bonobo_UIContainer bonobo_ui_component_get_container ()
void bonobo_ui_component_add_verb ()
void bonobo_ui_component_add_verb_full ()
void bonobo_ui_component_remove_verb ()
void bonobo_ui_component_remove_verb_by_closure ()
void bonobo_ui_component_add_listener ()
void bonobo_ui_component_add_listener_full ()
void bonobo_ui_component_remove_listener ()
void bonobo_ui_component_remove_listener_by_closure ()
void bonobo_ui_component_set ()
void bonobo_ui_component_set_translate ()
void bonobo_ui_component_set_tree ()
void bonobo_ui_component_rm ()
gboolean bonobo_ui_component_path_exists ()
CORBA_char * bonobo_ui_component_get ()
BonoboUINode * bonobo_ui_component_get_tree ()
void bonobo_ui_component_object_set ()
Bonobo_Unknown bonobo_ui_component_object_get ()
void bonobo_ui_component_widget_set ()
void bonobo_ui_component_freeze ()
void bonobo_ui_component_thaw ()
void bonobo_ui_component_set_prop ()
gchar * bonobo_ui_component_get_prop ()
void bonobo_ui_component_set_status ()
#define BONOBO_UI_VERB()
#define BONOBO_UI_VERB_DATA()
#define BONOBO_UI_UNSAFE_VERB()
#define BONOBO_UI_UNSAFE_VERB_DATA()
void bonobo_ui_component_add_verb_list ()
void bonobo_ui_component_add_verb_list_with_data ()

Signals

void exec-verb Run First
void ui-event Run First

Types and Values

Object Hierarchy

    GObject
    ╰── BonoboObject
        ╰── BonoboUIComponent

Description

Functions

BonoboUIListenerFn ()

void
(*BonoboUIListenerFn) (BonoboUIComponent *component,
                       const char *path,
                       Bonobo_UIComponent_EventType type,
                       const char *state,
                       gpointer user_data);

BonoboUIVerbFn ()

void
(*BonoboUIVerbFn) (BonoboUIComponent *component,
                   gpointer user_data,
                   const char *cname);

bonobo_ui_component_construct ()

BonoboUIComponent *
bonobo_ui_component_construct (BonoboUIComponent *component,
                               const char *name);

Construct the UI component with name name

Parameters

ui_component

the UI component itself

 

name

the name of the UI component

 

Returns

a constructed UI component or NULL on error


bonobo_ui_component_new ()

BonoboUIComponent *
bonobo_ui_component_new (const char *name);

Create a new UI component with the specified name

Parameters

name

the name of the UI component

 

Returns

a new UI component


bonobo_ui_component_new_default ()

BonoboUIComponent *
bonobo_ui_component_new_default (void);

Create a UI component with a unique default name constructed from various available system properties.

Returns

a new UI component


bonobo_ui_component_set_name ()

void
bonobo_ui_component_set_name (BonoboUIComponent *component,
                              const char *name);

Set the name of the UI component

Parameters

component

the UI component

 

name

the new name

 

bonobo_ui_component_get_name ()

const char *
bonobo_ui_component_get_name (BonoboUIComponent *component);

Parameters

component

the UI component

 

Returns

the name of the UI component


bonobo_ui_component_set_container ()

void
bonobo_ui_component_set_container (BonoboUIComponent *component,
                                   Bonobo_UIContainer container,
                                   CORBA_Environment *opt_ev);

This associates this component with a remote container object.

Parameters

component

the component

 

container

a remote container object.

 

bonobo_ui_component_unset_container ()

void
bonobo_ui_component_unset_container (BonoboUIComponent *component,
                                     CORBA_Environment *opt_ev);

This dis-associates the component from its associated BonoboUIContainer.

Parameters

component

the component

 

bonobo_ui_component_get_container ()

Bonobo_UIContainer
bonobo_ui_component_get_container (BonoboUIComponent *component);

Parameters

component

the component.

 

Returns

the associated remote container


bonobo_ui_component_add_verb ()

void
bonobo_ui_component_add_verb (BonoboUIComponent *component,
                              const char *cname,
                              BonoboUIVerbFn fn,
                              gpointer user_data);

Add a verb to the UI component, that can be invoked by the container.

Parameters

component

the component to add it to

 

cname

the programmatic name of the verb

 

fn

the callback function for invoking it

 

user_data

the associated user data for the callback

 

bonobo_ui_component_add_verb_full ()

void
bonobo_ui_component_add_verb_full (BonoboUIComponent *component,
                                   const char *cname,
                                   GClosure *closure);

Add a verb to the UI component, that can be invoked by the container.

Parameters

component

the component to add it to

 

cname

the programmatic name of the verb

 

fn

the callback function for invoking it

 

user_data

the associated user data for the callback

 

destroy_fn

a destroy function for the callback data

 

bonobo_ui_component_remove_verb ()

void
bonobo_ui_component_remove_verb (BonoboUIComponent *component,
                                 const char *cname);

Remove a verb by it's unique name

Parameters

component

the component to add it to

 

cname

the programmatic name of the verb

 

bonobo_ui_component_remove_verb_by_closure ()

void
bonobo_ui_component_remove_verb_by_closure
                               (BonoboUIComponent *component,
                                GClosure *closure);

remove any verb handled by fn .

Parameters

component

the component to add it to

 

fn

the function pointer

 

bonobo_ui_component_add_listener ()

void
bonobo_ui_component_add_listener (BonoboUIComponent *component,
                                  const char *id,
                                  BonoboUIListenerFn fn,
                                  gpointer user_data);

Add a listener for stateful events.

Parameters

component

the component to add it to

 

id

the programmatic name of the id

 

fn

the callback function for invoking it

 

user_data

the associated user data for the callback

 

bonobo_ui_component_add_listener_full ()

void
bonobo_ui_component_add_listener_full (BonoboUIComponent *component,
                                       const char *id,
                                       GClosure *closure);

Add a listener for stateful events.

Parameters

component

the component to add it to

 

id

the programmatic name of the id

 

fn

the callback function for invoking it

 

user_data

the associated user data for the callback

 

destroy_fn

a destroy function for the callback data

 

bonobo_ui_component_remove_listener ()

void
bonobo_ui_component_remove_listener (BonoboUIComponent *component,
                                     const char *cname);

Remove any listener by its unique id

Parameters

component

the component to add it to

 

cname

the programmatic name of the id

 

bonobo_ui_component_remove_listener_by_closure ()

void
bonobo_ui_component_remove_listener_by_closure
                               (BonoboUIComponent *component,
                                GClosure *closure);

bonobo_ui_component_set ()

void
bonobo_ui_component_set (BonoboUIComponent *component,
                         const char *path,
                         const char *xml,
                         CORBA_Environment *opt_ev);

Set the xml fragment into the remote BonoboUIContainer's tree attached to component at the specified path

If you see blank menu items ( or just separators ) it's likely that you should be using bonobo_ui_component_set_translate which substantialy deprecates this routine.

Parameters

component

the component

 

path

the path to set

 

xml

the xml to set

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_set_translate ()

void
bonobo_ui_component_set_translate (BonoboUIComponent *component,
                                   const char *path,
                                   const char *xml,
                                   CORBA_Environment *opt_ev);

This routine parses the XML strings, and converts any: _label="Hello World" type strings into the translated, and encoded format expected by the remote BonoboUIContainer.

Parameters

component

the component

 

path

the path to set

 

xml

the non translated xml to set

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_set_tree ()

void
bonobo_ui_component_set_tree (BonoboUIComponent *component,
                              const char *path,
                              BonoboUINode *node,
                              CORBA_Environment *ev);

Set the xml fragment into the remote BonoboUIContainer's tree attached to component at the specified path

Parameters

component

the component

 

path

the path to set

 

node

the BonoboUINode representation of an xml tree to set

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_rm ()

void
bonobo_ui_component_rm (BonoboUIComponent *component,
                        const char *path,
                        CORBA_Environment *ev);

This routine removes a chunk of the XML tree in the BonoboUIContainer associated with component pointed to by path .

Parameters

component

the component

 

path

the path to set

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_path_exists ()

gboolean
bonobo_ui_component_path_exists (BonoboUIComponent *component,
                                 const char *path,
                                 CORBA_Environment *ev);

Parameters

component

the component

 

path

the path to set the property on

 

ev

the (optional) CORBA exception environment

 

Returns

TRUE if the path exists in the container.


bonobo_ui_component_get ()

CORBA_char *
bonobo_ui_component_get (BonoboUIComponent *component,
                         const char *path,
                         gboolean recurse,
                         CORBA_Environment *opt_ev);

This routine fetches a chunk of the XML tree in the BonoboUIContainer associated with component pointed to by path . If recurse then the child nodes of path are returned too, otherwise they are not.

Parameters

component

the component

 

path

the path to get

 

recurse

whether to get child nodes of path

 

opt_ev

the (optional) CORBA exception environment

 

Returns

an XML string (CORBA allocated)


bonobo_ui_component_get_tree ()

BonoboUINode *
bonobo_ui_component_get_tree (BonoboUIComponent *component,
                              const char *path,
                              gboolean recurse,
                              CORBA_Environment *opt_ev);

This routine fetches a chunk of the XML tree in the BonoboUIContainer associated with component pointed to by path . If recurse then the child nodes of path are returned too, otherwise they are not.

Parameters

component

the component

 

path

the path to get

 

recurse

whether to get child nodes of path

 

opt_ev

the (optional) CORBA exception environment

 

Returns

an BonoboUINode XML representation


bonobo_ui_component_object_set ()

void
bonobo_ui_component_object_set (BonoboUIComponent *component,
                                const char *path,
                                Bonobo_Unknown control,
                                CORBA_Environment *opt_ev);

This registers the control CORBA object into the BonoboUIContainer associated with this component at the specified path . This is most often used to associate controls with a certain path.

Parameters

component

the component

 

path

the path to set

 

control

a CORBA object reference

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_object_get ()

Bonobo_Unknown
bonobo_ui_component_object_get (BonoboUIComponent *component,
                                const char *path,
                                CORBA_Environment *opt_ev);

This returns the control CORBA object registered with the BonoboUIContainer associated with this component at the specified path .

Parameters

component

the component

 

path

the path to set

 

ev

the (optional) CORBA exception environment

 

Returns

the associated remote CORBA object.


bonobo_ui_component_widget_set ()

void
bonobo_ui_component_widget_set (BonoboUIComponent *component,
                                const char *path,
                                GtkWidget *widget,
                                CORBA_Environment *opt_ev);

bonobo_ui_component_freeze ()

void
bonobo_ui_component_freeze (BonoboUIComponent *component,
                            CORBA_Environment *opt_ev);

This increments the freeze count on the associated BonoboUIContainer, (if not already frozen) this means that a batch of update operations can be performed without a re-render penalty per update.

NB. if your GUI is frozen / not updating you probably have a freeze / thaw reference leak/

Parameters

component

the component

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_thaw ()

void
bonobo_ui_component_thaw (BonoboUIComponent *component,
                          CORBA_Environment *opt_ev);

This decrements the freeze count on the remote associated BonoboUIContainer, (if frozen). This means that a batch of update operations can be performed without a re-render penalty per update.

NB. if your GUI is frozen / not updating you probably have a freeze / thaw reference leak/

Parameters

component

the component

 

ev

the (optional) CORBA exception environment

 

bonobo_ui_component_set_prop ()

void
bonobo_ui_component_set_prop (BonoboUIComponent *component,
                              const char *path,
                              const char *prop,
                              const char *value,
                              CORBA_Environment *opt_ev);

This helper function sets an XML property ( or attribute ) on the XML node pointed at by path . It does this by a read / modify / write process. If you find yourself doing this a lot, you need to consider batching this process.

Parameters

component

the component

 

path

the path to set the property on

 

prop

the property name

 

value

the property value

 

opt_ev

the (optional) CORBA exception environment

 

bonobo_ui_component_get_prop ()

gchar *
bonobo_ui_component_get_prop (BonoboUIComponent *component,
                              const char *path,
                              const char *prop,
                              CORBA_Environment *opt_ev);

This helper function fetches an XML property ( or attribute ) from the XML node pointed at by path in the BonoboUIContainer associated with component

Parameters

component

the component

 

path

the path to set the property on

 

prop

the property name

 

value

the property value

 

opt_ev

the (optional) CORBA exception environment

 

Returns

the xml property value or NULL - free with g_free.


bonobo_ui_component_set_status ()

void
bonobo_ui_component_set_status (BonoboUIComponent *component,
                                const char *text,
                                CORBA_Environment *opt_ev);

This sets the contents of the status bar to text in the remote BonoboUIContainer associated with component . This is done by setting the contents of the /status/main node.

Parameters

component

the component

 

text

the new status text

 

ev

the (optional) CORBA exception environment

 

BONOBO_UI_VERB()

#define BONOBO_UI_VERB(name,cb)                  { (name), (cb), NULL, NULL   }

BONOBO_UI_VERB_DATA()

#define BONOBO_UI_VERB_DATA(name,cb,data)        { (name), (cb), (data), NULL }

BONOBO_UI_UNSAFE_VERB()

#define BONOBO_UI_UNSAFE_VERB(name,cb)           { (name), ((BonoboUIVerbFn)(cb)), NULL, NULL   }

BONOBO_UI_UNSAFE_VERB_DATA()

#define BONOBO_UI_UNSAFE_VERB_DATA(name,cb,data) { (name), ((BonoboUIVerbFn)(cb)), (data), NULL }

bonobo_ui_component_add_verb_list ()

void
bonobo_ui_component_add_verb_list (BonoboUIComponent *component,
                                   const BonoboUIVerb *list);

Add a list of verbs with no associated user_data, you probably want bonobo_ui_component_add_verb_list_with_data

Parameters

component

the component

 

list

the list of verbs.

 

bonobo_ui_component_add_verb_list_with_data ()

void
bonobo_ui_component_add_verb_list_with_data
                               (BonoboUIComponent *component,
                                const BonoboUIVerb *list,
                                gpointer user_data);

This is a helper function to save registering verbs individualy it allows registration of a great batch of verbs at one time in a list of BonoboUIVerb terminated by BONOBO_UI_VERB_END

Parameters

component

the component

 

list

the list of verbs

 

user_data

the user data passed to the verb callbacks

 

Types and Values

struct BonoboUIComponent

struct BonoboUIComponent;

BonoboUIComponentPrivate

typedef struct _BonoboUIComponentPrivate BonoboUIComponentPrivate;

BonoboUIComponentClass

typedef struct {
	BonoboObjectClass          parent_class;

	POA_Bonobo_UIComponent__epv epv;

	gpointer dummy[6];

	/* Signals */
	void (*exec_verb) (BonoboUIComponent *comp,
			   const char        *cname);

	void (*ui_event)  (BonoboUIComponent *comp,
			   const char        *path,
			   Bonobo_UIComponent_EventType type,
			   const char        *state);
	/* Virtual XML Methods */
	void (*freeze)    (BonoboUIComponent *component,
			   CORBA_Environment *opt_ev);

	void (*thaw)      (BonoboUIComponent *component,
			   CORBA_Environment *opt_ev);

	void (*xml_set)   (BonoboUIComponent *component,
			   const char        *path,
			   const char        *xml,
			   CORBA_Environment *ev);

	CORBA_char *(*xml_get) (BonoboUIComponent *component,
				const char        *path,
				gboolean           recurse,
				CORBA_Environment *ev);

	void (*xml_rm)    (BonoboUIComponent *component,
			   const char        *path,
			   CORBA_Environment *ev);

	void (*set_prop)  (BonoboUIComponent *component,
			   const char        *path,
			   const char        *prop,
			   const char        *value,
			   CORBA_Environment *opt_ev);

	gchar *(*get_prop) (BonoboUIComponent *component,
			    const char        *path,
			    const char        *prop,
			    CORBA_Environment *opt_ev);

	gboolean (*exists) (BonoboUIComponent *component,
			    const char        *path,
			    CORBA_Environment *ev);
} BonoboUIComponentClass;

BonoboUIVerb

typedef struct {
	const char    *cname;
	BonoboUIVerbFn cb;
	gpointer       user_data;
	gpointer       dummy;
} BonoboUIVerb;

BONOBO_UI_VERB_END

#define BONOBO_UI_VERB_END                       { NULL, NULL, NULL, NULL }

Signal Details

The “exec-verb” signal

void
user_function (BonoboUIComponent *bonobouicomponent,
               char              *arg1,
               gpointer           user_data)

Flags: Run First


The “ui-event” signal

void
user_function (BonoboUIComponent *bonobouicomponent,
               char              *arg1,
               int                arg2,
               char              *arg3,
               gpointer           user_data)

Flags: Run First