Re: Extensible Shell

[William Jon McCann <william jon mccann gmail com>]

Hey,

Thanks for kicking off the conversation.

On Mon, Feb 1, 2010 at 5:18 AM, Thomas Wood <thos gnome org> wrote:
> Hi,
>
> Jon McCann has been putting together some ideas for a pluggable, single
> window approach to the control center shell. The code is available in
> the extensible-shell branch of control-center. I'd like to start a
> discussion on how the API works and how we expect it to be used.
>
> So firstly, from reading the code, this is what I currently understand:
>
>  * CcPanel - a top level object representing a control center panel
>           - properties: id, display-name, current-page
>           - signals:    active-changed

Display name is used to tell the shell the name that should be shown
in the titlebar of the shell.  It should probably be the same as the
one found in the desktop file.  We still rely on desktop files to
construct the list of available settings for at least two reasons:
  * We want to fallback to launching the standalone settings windows
when a plugin isn't available
  * The menu approach has a number of advantages like making it easy
to disable/hide certain launchers

One idea for the "id" property is that it can be used to tell the
shell to load a certain panel on startup and it can also be used as an
identifier for indexing search keywords.  More on this below.

The current page property is used to store the page that is currently
in focus.  The active changed signal is used to indicate if the panel
is in view or not.  This is important so that panels know when to
start doing stuff and when to stop doing stuff.  For example, the
background panel should load wallpapers only when made active or the
screensaver one should stop running the previews when made inactive.

>  * CcPage  - an object representing a page within a CcPanel
>           - properties: id, display-name
>           - signals:    active-changed

Display name here is normally used by the Panel in a tab page label.

"id" as with Panel can be used to identify the page in order to start
with a certain location open or to index search results.

One thought is that both Panel and Page ids form a path.  You can
think of individual controls in the center as all having a URI of the
following form:

//panel-id/page-id#widget-id
   or for example
//appearance/background#selector

The fragment widget-id probably isn't that useful in most cases though.

So we can do two things:

   * Start with a page open (gnome-control-center //appearance/background)
   * Map search terms to a page ("Add background" -> //appearance/background)

> Both objects derive from GtkAlignment. The current implementation in the
> capplets that have converted is that each CcPage is packed into a
> notebook created by the CcPanel object. Each page and panel also have a
> set_active() function, which is called when the shell or Panel expects
> the widget to be on screen.
>
> libgnome-control-center-extension contains all this API, but also all
> the cruft that was in the capplets/common directory. I don't think this
> should all be publicly available. The theme utilities (for example)
> should be kept private.

That's fine and I agree.  I moved it in there for convenience and to
make the build dependencies work better.  In fact, most of that cruft
is only used in one capplet so it should really move into the capplet
directory in which it is used.

> I'm hoping Jon can describe a bit more about how the shell, panels and
> pages interact. From what I can see at the moment, the shell will parent
> the panel object, but it does not interact with the pages object.
>
> I have a few questions to start off the discussion:
>
>  * Why do CcPanel and CcPage derive from GtkAlignment rather than (e.g.)
> GtkBin.

I don't think it makes too much difference.  An alignment is a bin
with flexible positioning for children.

>  * Why does the shell not create a notebook for the panel and pack pages
> into it? CcPanel would then not need to derive from GtkWidget.

Panels don't need to be implemented as notebooks.  At an earlier stage
I had Panels derive from notebooks but this turned out to not be
desirable.  Some panels will be purely singleton pages and some will
be notebooks with other controls packed above or below them.  See the
current keyboard or sound capplets for example.

But also I think panels should be more or less able to do what they
think is best.

>  * Should "active" be a property on the CcPanel and CcPage objects?

I can I supposed.  I forget exactly why I didn't do it this way.
Maybe because it is slightly awkward to work with property notify
signals in subclasses or maybe because "active" conflicted with the
notebook superclass I had originally.  Dunno.

> It will be important to have a good API to allow third party capplets to
> be well integrated, so we must make sure we define and document this API
> before it is available in a final release.

Yup.  But I think it is fine if we just mark it as unstable until 3.0.
 Another reason to try to get this to replace the current optional
shell for 2.30.  We'd still have the standalone capplets in the menu
by default.

Here's an example of an out of tree use of the API:
http://git.gnome.org/browse/gnome-screensaver/commit/?h=control-center-ext&id=4531453214e56e8b5798d224f02fb63605fc1dd5

Jon