Re: Scaffold API proposal

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

Hi John,

On Thu, 2004-01-15 at 00:54, John (J5) Palmieri wrote:
> > > > ---
> > > > 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?
> 
> I'm not intimate on how GtkSourceView works but I assume it has some
> sort of a layout.  Perhaps we add an API that allows the inserting of
> widgets at a perticular row, column or position (row and column). 
> Almost like how applets are embeded in the doc, these widgets would have
> callbacks into the plugin that spawned them.  The Plugin can then react
> to these events by using Glimmer's API.  Most of the time a plugin would
> want to take over the left column for things like breakpoints but some
> would want to put an icon next to keyword to signify something (such as
> the exact code where an error in the compiler occured).  

Well, I think for this we will need a lot of work.  I haven't tried
embedding a widget (using a child anchor AFAICS), and I don't know how
will GtkSourceView interact with it.

What we can (and will have to) do is provide an API for markers.  Maybe
something general, like the Eclipse marker specification:

http://help.eclipse.org/help21/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/api/org/eclipse/core/resources/IMarker.html

As far as I understand it they define a general interface for a marker
which is basically an attribute container.  What does the attributes
mean is left to the object displaying the resource the marker is
attached to.

> <snip>
> > > > 	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?
> 
> Ok, if we go the aggregate object route for implementing UI merging
> instead of implementing it in the shell you will need a default
> implementation.  You could just have a base class but this does not fit
> in with plugins that were not made exclusivly for Scaffold (i.e. Glade
> 3).  With the interface you could wrap a plugin, register the interface
> and if you didn't feel like implementing your own UI merging code, load
> up the default implementation and hook it up to the interface.  This
> could be made easier if GObject interfaces allow for actual code to be
> placed into them.  Most languages won't allow you to mix an interface
> with actual code but this is C so I don't know if it applies within the
> GObject framework.

AFAIK, this is not possible with GObject.

> <snip>
> > > > 
> > > > 	[ 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.
> Ok.
> 
> > As for exposing GUI elements as values, the questions is what do you
> > store at a given path.
> 
> GLib's type system is dynamic so the short answer is anything you want. 
> In reality we would have an API for the most common paths and the rest
> you would either have to know in advanced or use introspection.  Basicly
> it is the same concept as in Glade where you can search for a widget by
> name without knowing exactly what kind of widget it is.  In our case we
> use a structured path instead of a hash of names.

I'm not really sure it's a good idea to expose GUI elements directly. 
My main concern is the way a plugin displays anything might change with
time.  If you exposed the UI through the value repository, you run the
risk of breaking other plugins whenever you want to e.g. change the
layout of your plugin.

OTOH, exposing say a GtkTreeModel might make sense.  Personally I don't
like this idea very much either.  It's like showing the guts of the
plugin, if you know what I mean.  In any case, you still need to make
sure the semantics of the model are well known.

> 
> <snip>
> > [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?
> 
> Say I want to write a cross refrencer.  I want to highlight a function
> to signal that it can be clicked on to find where it is defined.  Say I
> want to write a language translation plugin.  I want to highlight every
> litteral that has not been translated yet to a perticular language.  The
> list goes on.  

This particular example could be implemented using a marker API like the
one linked above.

> > [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.
> 
> Ok, that sound resonable.  So wee need something more generic.  I look
> forward to seeing what you come up with.

I've been thinking about this, and probably the easiest solution would
be adding a method to the ShellUI interface:

gboolean switch_layout (const gchar *layout_name, gboolean create);

This function returns FALSE if the given layout doesn't exist and create
was FALSE.  In that case, the plugin wanting to switch the layout can
create a new layout by passing create=TRUE and then calling
present_widget() for the dock items it wants to make sure are present in
the given layout.  The shell should keep track of the current layout
name and autosave it whenever the shell quits or a new switch is made.  

This way, for new layouts we can make sure the relevant UI components
are shown but at the same time we respect the user choice if e.g. he
doesn't want the "Local variables" dock item in debug mode.

What do you think?

> > > 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?
> 
> I don't know but it is a legitimate event that somone might want to know
> about.  It is the difference between reacting to an event or causing
> something else to react to an event.  For instance a components might
> not care about the specifics to why a layout was changed, but it might
> want to know when it has changed.  In fact the component that would use
> the signal would most likely not even know anything about Documents so
> it couldn't react to the Selected event.

Ok, agreed.

> I can't wait untill this is mostly fleshed out :-)  Good stuff.

Yeah, me too.

Regards,
Gustavo