Re: Scaffold API proposal

[Gustavo Giráldez <gustavo giraldez gmx net>]

Hi John,

[snip]

> > ---
> > The ValueContainer interface:
> > 
> > One of the main components of the shell is the ValueContainer.  The
> > ValueContainer is an interface which can also be implemented by
> > plugins which want to "take over" certain subpaths of the main
> > hierarchy.
> > 
> > The shell's ValueContainer exposes a tree hierarchy where each of the
> > nodes can hold a single GValue.  Paths in the tree are represented by
> > strings, where each element of the path is separated by a special
> > character or sequence of characters (still undecided, but the slash
> > '/' will be used in the following examples).  The root of the
> > hierarchy is not accesible, and thus the initial slash in a given path
> > can be omitted.  Another way of looking at the model exposed by
> > ValueContainer is as nested hashes.
> 
> Why not do things the way XPath or DBUS does them?

You mean separating path parts with a dot '.'?  Could work too.  It's a
small detail IMO.

[snip]

> > 
> > ---
> > The action UI merging interface UIActionTarget:
> > 
> > This interface will allow a plugin to merge action-type UI elements
> > (menus, toolbars).  This API mirrors the GtkUIManager API.
> 
> What about more complex UI elements such as dragpoints in Glimmer? 
> Doing this could also allow for the debugger to add stop point UI
> instead of Glimmer having to implement it. 

Haven't thought about this, but we certainly need it.  Currently there's
the gutter IDL which glimmer implements, but it's probably not enough. 
Do you have any ideas?

> > 	[ DECISION: should we have each visual component implement this
> > 	interface, or have a single implementation at the shell, and
> > 	somehow namespace the UI elements (popups)?
> 
> A base level of functionality (such as merging menus and toolbars)
> should be automaticly gained by any plugin.  If this is done through the
> shell or we provide a default implementation that can be inherited or
> aggrigated by a plugin is up for debate.

Nod.

> > 	I tend to prefer offering this interface and have each
> > 	interested plugin implement it, since that allows greater
> > 	flexibility.  For example, in the project manager we could
> > 	have different popups depending on the row type and one place
> > 	to add common actions to all types.  The individual types
> > 	would be accessed as an interface in the shell's repository:
> > 	'/Project/targets', '/Project/sources', '/Project/groups',
> > 	while the common place through '/Project/all' (or similar).
> 
> I agree.  So a default implementation would be the best way to go for
> this.  If a plugin fails to implement the feature we can simply make the
> default object a member of the plugin and hook it up to the interface.

I don't follow you here.  What do you mean default implementation?

> > 	If we decide to go the other way, we could eventually ditch
> > 	this interface and have a shell method which would return the
> > 	GtkUIManager. ]
> > 
> > 
> >   /* install an action group */
> >   void add_action_group (GtkActionGroup *group);
> > 
> >   /* remove an action group */
> >   void remove_action_group (GtkActionGroup *group);
> > 
> >   /* merge UI elements to the component's UI; the returned id is used
> >      for unmerging */
> >   guint merge_ui (const gchar *ui);
> > 
> >   /* unmerge a previously merged UI */
> >   void unmerge_ui (guint merge_id);
> > 
> > 
> > The shell will have a <menu> element and a <toolbar> element at a
> > minimum.  Plugins implementing the interface will have a <popup>
> > element.
> > 
> > 	[ UNDECIDED: how to register and use several toolbars ]
> > 
> 
> Perhaps we should look at how the new GtKFileChooser allows merging of
> other GUI elements.  Also why not extend your path paradigm to include
> elements within the plugin?  so /Project Manager/Toolbar0

AFAICS, GtkFileChooser only provides placeholders to add some certain
widgets, namely the preview widget and an extra widget.  I don't think
that's enough for us.

As for exposing GUI elements as values, the questions is what do you
store at a given path.

> > 
> > ---
> > The FileOpen Service:
> > 
> > This service is offered by the shell in principle since it's way too
> > common and will probably be used by almost all plugins.
> > 
> > The concept is as follows: a plugin which can open a certain type of
> > document (selected by the mimetype) registers itself with the
> > service.  When an open request is made, the shell checks to see if it
> > has any registered provider and invokes the handler if so.  Otherwise,
> > it opens the file using Gnome's standard machinery (gnome_url_show()
> > or whatever).
> 
> Ah, yes I asked for this above :-) Guess I could scratch it off my
> wishlist.  One thing would be nice is to use the Nautilus views also.

See my reply to Jeroen regarding this.  This interface should be
implemented by the document manager now.  As for using Nautilus views,
it should be possible.  In fact, the current document manager does
that.  The only problem will be merging toolbars and menus (i.e. mixing
bonobo parts with GtkUIManager), but it should be fixable.

[snip]

> > ---
> > The TextDocument interface:
> > 
> > Implemented by textual documents, allows direct manipulation of the
> > file contents.
> > 
> > Document regions are delimited by the point and the mark (ala emacs).
> > Cut and copy operations affect the region.  Insert occurs at the point
> > always.
> > 
> >   /* movement modifiers: a combination of one value from the following
> >      mask values */
> > 
> >   #define RELATIVE_POS_SHIFT 0
> >   #define STEP_SIZE_SHIFT    2
> > 
> >   /* relative position */
> >   #define FROM_CURRENT 0 << RELATIVE_POS_SHIFT
> >   #define FROM_START   1 << RELATIVE_POS_SHIFT
> >   #define FROM_END     2 << RELATIVE_POS_SHIFT
> > 
> >   /* steps */
> >   #define CHAR   0 << STEP_SIZE_SHIFT
> >   #define WORD   1 << STEP_SIZE_SHIFT
> >   #define LINE   2 << STEP_SIZE_SHIFT
> >   #define COLUMN 3 << STEP_SIZE_SHIFT
> > 
> >   void set_mark (gboolean swap_with_point);
> > 
> >   gboolean move_point (gint modifier, gint offset);
> > 
> >   gchar *get_text (gboolean cut);
> > 
> >   void insert_text (const gchar *text);
> > 
> >   gint get_position (gint modifier);
> > 
> Dynamic highlighting?  I guess that would be a seperate interface.

Can you give an example use?  As I see it, highlighting is a text editor
task.  Which plugin would want to add highlighting?

[snip]

> Very nice document.  This was just a quick reply.  One other thing to
> would like to mention is the Layout Manager which manages how the docks
> are layed out.  Basicly when I am editing a glade file the layout should
> change as opposed to editing a c file.  Also editing a README file
> doesn't need the symbol browser present.  Basicly we should have an API
> for matching layouts to mime-types.

Nice idea.

> Interface:
> 
> void join_layout (char *layout_name, char * mime_type);
> void remove_layout (char *layout_name);
> void register_layout (Layout *layout, char *layout_name);
> void switch_layout_with_mime_type (char *mime-type);
> void switch_layout (char *layout_name);

Hmm... actually layout switching will also happen on certain particular
events (e.g. starting a program for debug) besides document switching. 
I don't know for sure what would the interface look like, but I suspect
we will need to extend the shell docking interface.  I'll look into it.

> Signals:
> 
> Documents::Selected - signals when a document has selected for editing
> Layout::Changed - signals when a layout has changed

Why is this last event necessary?

Regards,
Gustavo