Re: Scaffold API proposal

["John (J5) Palmieri" <johnp martianrock com>]

On Wed, 2004-01-14 at 18:36, Gustavo Giráldez wrote:
> Hi John,
> 
<snip>
> > > 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.

Well XPath uses "/" and DBUS uses ".".  The only reason I mentioned it
is because the specs have already been drawn up so why create our own.  

> [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?

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).  

<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.

<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.

<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.  

> [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.

> > 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.

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