The main interface for components is GNOME::Embeddable. Objects implementing it should be created with a GNOME::EmbeddableFactory, which is a factory for Embeddable objects. Such a factory should be declared with the standard .gnorba files we studied in chapter 5.
module GNOME { typedef sequence<string> stringlist; interface GenericFactory { exception CannotActivate { }; boolean supports(in string obj_goad_id); Object create_object(in string goad_id, in stringlist params) raises(CannotActivate); }; interface EmbeddableFactory : GNOME::GenericFactory { Embeddable create_path (in string path); }; }; |
The create_path function is used to handle linking support.
The create_object function is used to create the object itself, as we already discussed it in chapter 5.
Here is the GNOME::embeddable interface:
module GNOME { interface Embeddable : GNOME::Unknown { void set_client_site (in ClientSite client_site); ClientSite get_client_site (); void set_host_name (in string name, in string appname); void set_uri (in string uri); exception UserCancelledSave {}; enum CloseMode { SAVE_IF_DIRTY, NO_SAVE, PROMPT_SAVE }; void close (in CloseMode mode) raises (UserCancelledSave); struct GnomeVerb { string name; string label; string hint; }; typedef sequence<GnomeVerb> verb_list; verb_list get_verb_list (); void advise (in AdviseSink advise); void unadvise (); long get_misc_status (in long type); exception MultiViewNotSupported {}; View new_view (in ViewFrame frame) raises (MultiViewNotSupported); }; }; |
This interface is a big, but fortunately easily understandable.
The set_client_site function is used by the container to tell the component who it is talking to. This function is generally called once the container has created the corresponding ClientSite (yes... it's useful) to allow the embeddable created with its factory to communicate with the container (to handle the size negotiation for example).
The set_host_name function is rather simple: it is used to set the window's name - displayed in the window handle by the window manager - of the window used for editing if the object does not support in-place activation. This name should also be used for the application's window if in-place editing is used.
The close function is the embeddable destructor: it will be called by the container when the composed document is closed.
The advise and unadvise functions will be discussed later. No real implementation is needed now: the GNOME::AdviseSink interface is not yet defined.
new_view is THE main function of this interface. It is used by the container to request new views of the component. The component is not obliged to be able to give away more than one view of the same object (which is why the MultiViewNotSupported signal exists) but is recommended to. This function is the GNOME::View factory. One should note that new views are given their GNOME::ClientSite upon creation with the "frame" parameter.
get_misc_status is used for miscellaneous things. Don't really known what things...
get_verb_list allows the container to ask an Embeddable what special verbs it supports. A verb is a simple non-parametrized action which the Embeddable can execute through GNOME::View::do_verb. The classic example of a verb is "next_page" for a Postscript Viewer.
Here is this famous GNOME::View interface.
module GNOME { interface View : GNOME::Unknown { void size_allocate (in short width, in short height); void size_query (out short desired_width, out short desired_height); typedef unsigned long windowid; void set_window (in windowid id); void activate (in boolean activated); void reactivate_and_undo (); void do_verb (in string verb_name); void set_zoom_factor (in double zoom); }; }; |
size_query and size_allocate are used to handle the size negotiation mechanism of the container: when the container needs to be resized, it asks all of its children for their preferred size. Then, the container allocates corresponding areas for these children, given its size, and notifies them with size_allocate.
size_allocate is also used by the container when the child view requests a resize with GNOME::ViewFrame::resize_request.
set_window is used by the container to give the containee a window to draw its view on. The container calls this function and gives the View an X window. This is achieved through the use of the GtkSocket/GtkPlug mechanism - already studied in chapter 5. see appendix D for sample code.-.
activate is used to tell the view to activate itself. When called, the view will either create a separate edit window or will try in-place activation, depending on the type of component. Please, note that the Embeddable must tell the container about its type - in-place or non-in-place - with a call to GNOME::ClientSite::show.
reactivate_and_undo is called by the container when the user did an 'undo' just after having de-activated a component.
do_verb is mainly used to ask the component to execute simple non-parametrized actions like "next_page" for a Postscript Viewer.
Finally, the set_zoom_factor function's use is obvious: it sets the View zoom factor.