![]() |
![]() |
![]() |
LibMateComponentUI API Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Signals |
MateComponentUIComponentMateComponentUIComponent — A UI interface that handles UI merging for a component |
struct MateComponentUIComponent; MateComponentUIComponentPrivate; void (*MateComponentUIListenerFn) (MateComponentUIComponent *component
,const char *path
,MateComponent_UIComponent_EventType type
,const char *state
,gpointer user_data
); void (*MateComponentUIVerbFn) (MateComponentUIComponent *component
,gpointer user_data
,const char *cname
); MateComponentUIComponentClass; MateComponentUIComponent * matecomponent_ui_component_construct (MateComponentUIComponent *component
,const char *name
); MateComponentUIComponent * matecomponent_ui_component_new (const char *name
); MateComponentUIComponent * matecomponent_ui_component_new_default (void
); void matecomponent_ui_component_set_name (MateComponentUIComponent *component
,const char *name
); const char * matecomponent_ui_component_get_name (MateComponentUIComponent *component
); void matecomponent_ui_component_set_container (MateComponentUIComponent *component
,MateComponent_UIContainer container
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_unset_container (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
); MateComponent_UIContainer matecomponent_ui_component_get_container (MateComponentUIComponent *component
); void matecomponent_ui_component_add_verb (MateComponentUIComponent *component
,const char *cname
,MateComponentUIVerbFn fn
,gpointer user_data
); void matecomponent_ui_component_add_verb_full (MateComponentUIComponent *component
,const char *cname
,GClosure *closure
); void matecomponent_ui_component_remove_verb (MateComponentUIComponent *component
,const char *cname
); void matecomponent_ui_component_remove_verb_by_closure (MateComponentUIComponent *component
,GClosure *closure
); void matecomponent_ui_component_add_listener (MateComponentUIComponent *component
,const char *id
,MateComponentUIListenerFn fn
,gpointer user_data
); void matecomponent_ui_component_add_listener_full (MateComponentUIComponent *component
,const char *id
,GClosure *closure
); void matecomponent_ui_component_remove_listener (MateComponentUIComponent *component
,const char *cname
); void matecomponent_ui_component_remove_listener_by_closure (MateComponentUIComponent *component
,GClosure *closure
); void matecomponent_ui_component_set (MateComponentUIComponent *component
,const char *path
,const char *xml
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_set_translate (MateComponentUIComponent *component
,const char *path
,const char *xml
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_set_tree (MateComponentUIComponent *component
,const char *path
,MateComponentUINode *node
,CORBA_Environment *ev
); void matecomponent_ui_component_rm (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *ev
); gboolean matecomponent_ui_component_path_exists (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *ev
); CORBA_char * matecomponent_ui_component_get (MateComponentUIComponent *component
,const char *path
,gboolean recurse
,CORBA_Environment *opt_ev
); MateComponentUINode * matecomponent_ui_component_get_tree (MateComponentUIComponent *component
,const char *path
,gboolean recurse
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_object_set (MateComponentUIComponent *component
,const char *path
,MateComponent_Unknown control
,CORBA_Environment *opt_ev
); MateComponent_Unknown matecomponent_ui_component_object_get (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_widget_set (MateComponentUIComponent *component
,const char *path
,GtkWidget *widget
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_freeze (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_thaw (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_set_prop (MateComponentUIComponent *component
,const char *path
,const char *prop
,const char *value
,CORBA_Environment *opt_ev
); gchar * matecomponent_ui_component_get_prop (MateComponentUIComponent *component
,const char *path
,const char *prop
,CORBA_Environment *opt_ev
); void matecomponent_ui_component_set_status (MateComponentUIComponent *component
,const char *text
,CORBA_Environment *opt_ev
); MateComponentUIVerb; #define MATECOMPONENT_UI_VERB (name, cb) #define MATECOMPONENT_UI_VERB_DATA (name, cb, data) #define MATECOMPONENT_UI_UNSAFE_VERB (name, cb) #define MATECOMPONENT_UI_UNSAFE_VERB_DATA (name, cb, data) #define MATECOMPONENT_UI_VERB_END void matecomponent_ui_component_add_verb_list (MateComponentUIComponent *component
,const MateComponentUIVerb *list
); void matecomponent_ui_component_add_verb_list_with_data (MateComponentUIComponent *component
,const MateComponentUIVerb *list
,gpointer user_data
);
The MateComponentUIComponent is the client side portion of the UI merging scheme. It should be implemented by any component that wishes to merge menus / UI. The Component object is neccessary to receive notifications from the associated MateComponentUIContainer. Notifications come in two forms - verbs and events. Verbs have an associated ( non translated ) name that is used to match them with callbacks. Events have an associated ( non translated ) id that does the same thing. Events pass a state string. Events are used for eg. toggle buttons, Verbs are used for eg. Menu items.
Mostly you don't need to bother with creating your own MateComponentUIComponent, if you implement a Control eg. a MateComponentUIComponent is created at Control construction time and can be accessed thus:
Example 4. Using the UI Component associated with a control
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
/* * For the format of the XML see matecomponent/doc/xml-ui.txt * For a standard template to base your UI on see matecomponent/doc/std-ui.xml */ const char my_ui_elements [] = ">placeholder name=\"FileOps\"<" " >menuitem name=\"Foo\" verb=\"FileFoo\" _label=\"Foo!\"" " _tip=\"do some foo thing\"/<" ">/placeholder<"; static void control_activate_cb (MateComponentControl *object, gboolean state, gpointer user_data) { MateComponentUIComponent *ui_component; /* Get UIComponent from control */ ui_component = matecomponent_control_get_ui_component (control); if (state) /* Activate */ matecomponent_ui_component_set_translate ( ui_component, "/menu/File", my_ui_elements, NULL); else /* De-activate */ matecomponent_ui_component_unset_container (ui_component); } static void verb_foo_cb (MateComponentUIComponent *ui_container, gpointer user_data, const char *cname) { MateComponentControl *control = user_data; g_print ("FileFoo !\n"); } static MateComponentUIVerb my_ui_verbs[] = { MATECOMPONENT_UI_VERB ("FileFoo", verb_foo_cb), MATECOMPONENT_UI_VERB_END }; MateComponentObject * create_ui_control (void) { MateComponentControl *control; MateComponentUIComponent *ui_component; GtkWidget *widget; control = matecomponent_control_new ((widget = gtk_widget_new_label ("Hello World"))); /* Automaticaly associate the remote UIContainer for us on activate */ matecomponent_control_set_automerge (control, TRUE); ui_component = matecomponent_control_get_ui_component (control); /* Register the verbs with the UI Component */ matecomponent_ui_component_add_verb_list_with_data ( ui_component, my_ui_verbs, control); gtk_signal_connect (GTK_OBJECT (control), "activate", GTK_SIGNAL_FUNC (control_activate_cb), NULL); gtk_widget_show (widget); return MATECOMPONENT_OBJECT (control); } |
This sets up the UI, associates a 'FileFoo' verb with a callback, and
on control activation merges the UI elements into a standard path
in the file menu.
There are several standard placeholders that it is important for containers to implement, basing your UI on the doc/std-ui.xml is a very good starting point. Also in the above example the _label and _tip are not cmd / widget separated - for more information read doc/ui-xml.txt.
Most applications will should not use the MateComponentUIComponent in this
way, there is a matecomponent_ui_util_set_ui
that does
the translation, help menu build, insertion etc. from an installed
XML file. The above example is complete except for translation, which
is extremely important. Here is a better activate function:
Example 5. A better way to create your UI
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
static void control_activate_cb (MateComponentControl *object, gboolean state, gpointer user_data) { MateComponentUIComponent *ui_component; /* Get UIComponent from control */ ui_component = matecomponent_control_get_ui_component (control); if (state) /* Activate */ /* * Use a helper function to setup your UI from a file: */ matecomponent_ui_util_set_ui ( ui_component, MY_COMPILE_TIME_PREFIX, "MATE_MyApp.ui", "my-app"); else /* De-activate */ matecomponent_ui_component_unset_container (ui_component); } |
In this example "MATE_MyApp.ui" is the correctly namespaced UI
xml filename, ( see doc/NAMESPACE to register your name ), and
"my-app" is the mate application name, from which a path to your
installed help files can be deduced.
typedef struct _MateComponentUIComponentPrivate MateComponentUIComponentPrivate;
void (*MateComponentUIListenerFn) (MateComponentUIComponent *component
,const char *path
,MateComponent_UIComponent_EventType type
,const char *state
,gpointer user_data
);
|
|
|
|
|
|
|
|
|
void (*MateComponentUIVerbFn) (MateComponentUIComponent *component
,gpointer user_data
,const char *cname
);
|
|
|
|
|
typedef struct { MateComponentObjectClass parent_class; POA_MateComponent_UIComponent__epv epv; gpointer dummy[6]; /* Signals */ void (*exec_verb) (MateComponentUIComponent *comp, const char *cname); void (*ui_event) (MateComponentUIComponent *comp, const char *path, MateComponent_UIComponent_EventType type, const char *state); /* Virtual XML Methods */ void (*freeze) (MateComponentUIComponent *component, CORBA_Environment *opt_ev); void (*thaw) (MateComponentUIComponent *component, CORBA_Environment *opt_ev); void (*xml_set) (MateComponentUIComponent *component, const char *path, const char *xml, CORBA_Environment *ev); CORBA_char *(*xml_get) (MateComponentUIComponent *component, const char *path, gboolean recurse, CORBA_Environment *ev); void (*xml_rm) (MateComponentUIComponent *component, const char *path, CORBA_Environment *ev); void (*set_prop) (MateComponentUIComponent *component, const char *path, const char *prop, const char *value, CORBA_Environment *opt_ev); gchar *(*get_prop) (MateComponentUIComponent *component, const char *path, const char *prop, CORBA_Environment *opt_ev); gboolean (*exists) (MateComponentUIComponent *component, const char *path, CORBA_Environment *ev); } MateComponentUIComponentClass;
MateComponentUIComponent * matecomponent_ui_component_construct (MateComponentUIComponent *component
,const char *name
);
Construct the UI component with name name
|
|
|
the name of the UI component |
Returns : |
a constructed UI component or NULL on error |
MateComponentUIComponent * matecomponent_ui_component_new (const char *name
);
Create a new UI component with the specified name
|
the name of the UI component |
Returns : |
a new UI component |
MateComponentUIComponent * matecomponent_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 |
void matecomponent_ui_component_set_name (MateComponentUIComponent *component
,const char *name
);
Set the name
of the UI component
|
the UI component |
|
the new name |
const char * matecomponent_ui_component_get_name (MateComponentUIComponent *component
);
|
the UI component |
Returns : |
the name of the UI component
|
void matecomponent_ui_component_set_container (MateComponentUIComponent *component
,MateComponent_UIContainer container
,CORBA_Environment *opt_ev
);
This associates this component
with a remote container
object.
|
the component |
|
a remote container object. |
|
void matecomponent_ui_component_unset_container (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
);
This dis-associates the component
from its associated
MateComponentUIContainer.
|
the component |
|
MateComponent_UIContainer matecomponent_ui_component_get_container (MateComponentUIComponent *component
);
|
the component. |
Returns : |
the associated remote container |
void matecomponent_ui_component_add_verb (MateComponentUIComponent *component
,const char *cname
,MateComponentUIVerbFn fn
,gpointer user_data
);
Add a verb to the UI component, that can be invoked by the container.
|
the component to add it to |
|
the programmatic name of the verb |
|
the callback function for invoking it |
|
the associated user data for the callback |
void matecomponent_ui_component_add_verb_full (MateComponentUIComponent *component
,const char *cname
,GClosure *closure
);
Add a verb to the UI component, that can be invoked by the container.
|
the component to add it to |
|
the programmatic name of the verb |
|
void matecomponent_ui_component_remove_verb (MateComponentUIComponent *component
,const char *cname
);
Remove a verb by it's unique name
|
the component to add it to |
|
the programmatic name of the verb |
void matecomponent_ui_component_remove_verb_by_closure (MateComponentUIComponent *component
,GClosure *closure
);
remove any verb handled by fn
.
|
the component to add it to |
|
void matecomponent_ui_component_add_listener (MateComponentUIComponent *component
,const char *id
,MateComponentUIListenerFn fn
,gpointer user_data
);
Add a listener for stateful events.
|
the component to add it to |
|
the programmatic name of the id |
|
the callback function for invoking it |
|
the associated user data for the callback |
void matecomponent_ui_component_add_listener_full (MateComponentUIComponent *component
,const char *id
,GClosure *closure
);
Add a listener for stateful events.
|
the component to add it to |
|
the programmatic name of the id |
|
void matecomponent_ui_component_remove_listener (MateComponentUIComponent *component
,const char *cname
);
Remove any listener by its unique id
|
the component to add it to |
|
the programmatic name of the id |
void matecomponent_ui_component_remove_listener_by_closure (MateComponentUIComponent *component
,GClosure *closure
);
|
|
|
void matecomponent_ui_component_set (MateComponentUIComponent *component
,const char *path
,const char *xml
,CORBA_Environment *opt_ev
);
Set the xml
fragment into the remote MateComponentUIContainer'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 matecomponent_ui_component_set_translate which substantialy deprecates this routine.
|
the component |
|
the path to set |
|
the xml to set |
|
the (optional) CORBA exception environment |
void matecomponent_ui_component_set_translate (MateComponentUIComponent *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 MateComponentUIContainer.
|
the component |
|
the path to set |
|
the non translated xml to set |
|
the (optional) CORBA exception environment |
void matecomponent_ui_component_set_tree (MateComponentUIComponent *component
,const char *path
,MateComponentUINode *node
,CORBA_Environment *ev
);
Set the xml
fragment into the remote MateComponentUIContainer's tree
attached to component
at the specified path
|
the component |
|
the path to set |
|
the MateComponentUINode representation of an xml tree to set |
|
the (optional) CORBA exception environment |
void matecomponent_ui_component_rm (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *ev
);
This routine removes a chunk of the XML tree in the
MateComponentUIContainer associated with component
pointed
to by path
.
|
the component |
|
the path to set |
|
the (optional) CORBA exception environment |
gboolean matecomponent_ui_component_path_exists (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *ev
);
|
the component |
|
the path to set the property on |
|
the (optional) CORBA exception environment |
Returns : |
TRUE if the path exists in the container. |
CORBA_char * matecomponent_ui_component_get (MateComponentUIComponent *component
,const char *path
,gboolean recurse
,CORBA_Environment *opt_ev
);
This routine fetches a chunk of the XML tree in the
MateComponentUIContainer associated with component
pointed
to by path
. If recurse
then the child nodes of path
are returned too, otherwise they are not.
|
the component |
|
the path to get |
|
whether to get child nodes of path
|
|
the (optional) CORBA exception environment |
Returns : |
an XML string (CORBA allocated) |
MateComponentUINode * matecomponent_ui_component_get_tree (MateComponentUIComponent *component
,const char *path
,gboolean recurse
,CORBA_Environment *opt_ev
);
This routine fetches a chunk of the XML tree in the
MateComponentUIContainer associated with component
pointed
to by path
. If recurse
then the child nodes of path
are returned too, otherwise they are not.
|
the component |
|
the path to get |
|
whether to get child nodes of path
|
|
the (optional) CORBA exception environment |
Returns : |
an MateComponentUINode XML representation |
void matecomponent_ui_component_object_set (MateComponentUIComponent *component
,const char *path
,MateComponent_Unknown control
,CORBA_Environment *opt_ev
);
This registers the control
CORBA object into the
MateComponentUIContainer associated with this component
at
the specified path
. This is most often used to associate
controls with a certain path.
|
the component |
|
the path to set |
|
a CORBA object reference |
|
the (optional) CORBA exception environment |
MateComponent_Unknown matecomponent_ui_component_object_get (MateComponentUIComponent *component
,const char *path
,CORBA_Environment *opt_ev
);
This returns the control
CORBA object registered with the
MateComponentUIContainer associated with this component
at
the specified path
.
|
the component |
|
the path to set |
|
|
Returns : |
the associated remote CORBA object. |
void matecomponent_ui_component_widget_set (MateComponentUIComponent *component
,const char *path
,GtkWidget *widget
,CORBA_Environment *opt_ev
);
|
|
|
|
|
|
|
void matecomponent_ui_component_freeze (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
);
This increments the freeze count on the associated MateComponentUIContainer, (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/
|
the component |
|
void matecomponent_ui_component_thaw (MateComponentUIComponent *component
,CORBA_Environment *opt_ev
);
This decrements the freeze count on the remote associated MateComponentUIContainer, (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/
|
the component |
|
void matecomponent_ui_component_set_prop (MateComponentUIComponent *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.
|
the component |
|
the path to set the property on |
|
the property name |
|
the property value |
|
the (optional) CORBA exception environment |
gchar * matecomponent_ui_component_get_prop (MateComponentUIComponent *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 MateComponentUIContainer
associated with component
|
the component |
|
the path to set the property on |
|
the property name |
|
the (optional) CORBA exception environment |
Returns : |
the xml property value or NULL - free with g_free. |
void matecomponent_ui_component_set_status (MateComponentUIComponent *component
,const char *text
,CORBA_Environment *opt_ev
);
This sets the contents of the status bar to text
in the
remote MateComponentUIContainer associated with component
.
This is done by setting the contents of the /status/main
node.
|
the component |
|
the new status text |
|
typedef struct { const char *cname; MateComponentUIVerbFn cb; gpointer user_data; gpointer dummy; } MateComponentUIVerb;
#define MATECOMPONENT_UI_VERB(name,cb) { (name), (cb), NULL, NULL }
This declares and fills a MateComponentUIVerb structure suitable for use in constructing a lost of verbs to add with matecomponent_ui_component_add_verb_list_with_data.
|
the verb name |
|
the callback function. |
#define MATECOMPONENT_UI_VERB_DATA(name,cb,data) { (name), (cb), (data), NULL }
This declares and fills a MateComponentUIVerb structure suitable for use in constructing a lost of verbs to add with matecomponent_ui_component_add_verb_list.
|
the verb name |
|
the callback function |
|
some associated user_data |
#define MATECOMPONENT_UI_UNSAFE_VERB(name,cb) { (name), ((MateComponentUIVerbFn)(cb)), NULL, NULL }
As MATECOMPONENT_UI_VERB, but unsafely casts cb
to the correct type
|
the verb name |
|
the callback function. |
#define MATECOMPONENT_UI_UNSAFE_VERB_DATA(name,cb,data) { (name), ((MateComponentUIVerbFn)(cb)), (data), NULL }
As MATECOMPONENT_UI_VERB_DATA, but unsafely casts cb
to the correct type
|
the verb name |
|
the callback function |
|
some associated user_data |
#define MATECOMPONENT_UI_VERB_END { NULL, NULL, NULL, NULL }
The terminator MateComponentUIVerb structure for a list of MateComponentUIVerbs.
void matecomponent_ui_component_add_verb_list (MateComponentUIComponent *component
,const MateComponentUIVerb *list
);
Add a list of verbs with no associated user_data, you probably want matecomponent_ui_component_add_verb_list_with_data
|
the component |
|
the list of verbs. |
void matecomponent_ui_component_add_verb_list_with_data (MateComponentUIComponent *component
,const MateComponentUIVerb *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 MateComponentUIVerb terminated by MATECOMPONENT_UI_VERB_END
|
the component |
|
the list of verbs |
|
the user data passed to the verb callbacks |
"exec-verb"
signalvoid user_function (MateComponentUIComponent *matecomponentuicomponent,
gchar *arg1,
gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |
"ui-event"
signalvoid user_function (MateComponentUIComponent *matecomponentuicomponent,
gchar *arg1,
gint arg2,
gchar *arg3,
gpointer user_data) : Run First
|
the object which received the signal. |
|
|
|
|
|
|
|
user data set when the signal handler was connected. |