Re: GTK+ Application class

[Emmanuele Bassi <ebassi gmail com>]

Hi Yevgen;

On Wed, 2006-10-25 at 12:24 -0500, Yevgen Muntyan wrote:
> Emmanuele Bassi wrote:
> 
> >... 
> >  gchar *       (*new_document)      (GtkApplication       *application);
> >  gboolean      (*save_document)     (GtkApplication       *application,
> >                                      const gchar          *document_name,
> >                                      const gchar          *document_uri,
> >                                      gboolean              save_backup,
> >                                      gboolean              overwrite,
> >                                      GError              **error);
> >  gboolean      (*open_document)     (GtkApplication       *application,
> >                                      const gchar          *document_uri,
> >                                      gboolean              read_only,
> >                                      GError              **error);
> >  gboolean      (*close_document)    (GtkApplication       *application,
> >                                      const gchar          *document_name,
> >                                      GError              **error);
> >  
> >
> What are these going to do and who is going to call them?

Those vfuncs have been changed to be asynchronous, and moved to the
GtkDocumentModel interface.  In any case, vfuncs are supposed to be
implemented by the sub-classes of GtkApplication - which should be an
abstract type.  You can then use the GtkApplication API (which I did not
include in the email for sake of brevity) inside your application's
code.

> [snip]
> 
> >Each GtkApplication should declare which MIME types it supports:
> >
> >  void          (*set_mime_types)    (GtkApplication       *application,
> >                                      const gchar * const   mime_types[],
> >                                      gint                  n_mime_types);
> >  GSList       *(*get_mime_types)    (GtkApplication       *application);
> >  
> >
> What's the purpose of this?

These vfuncs have been moved too to the GtkDocumentModel interface,
inside a more complex GtkDocumentInfo boxed type. The rationale between
setting and getting the document's MIME type is to advertise which
documents can be read/written by the application.  It's a "declaration
of intent", if you want.

Let's assume that you have a GtkWindow with a 'Open...' menu item bound
to a yourapp_file_open_cb callback;  inside the callback you'll create a
FileChooserDialog widget and set the GtkFileFilter on the MIME types -
by getting them from the GtkApplication (or the GtkDocumentModel
provided by the application and bound to the window):

  gchar *types;
  gsize types_len, i;

  types = gtk_application_get_mime_types (application, &types_len);
  for (i = 0; i < len; i++)
    gtk_file_filter_add_mime (filter, types[i]);

If you application supports plugins for input/output operations, which
allow you to read or write new MIME types, you'll have to add the MIME
types to the application and keep them there.

Probably, though, the alternative design (GdkMimeEntry, working like
GdkTargetEntry) with an integer id and a flag (_READ/_WRITE/_BOTH) is
better and more flexible.

> [snip]
> 
> >  void          (*add_window)        (GtkApplication       *application,
> >                                      const gchar          *document_name,
> >                                      GtkWindow            *window);
> >  void          (*remove_window)     (GtkApplication       *application,
> >                                      const gchar          *document_name,
> >                                      GtkWindow            *window);
> >  
> >
> What does it mean to "add window"? And is this one-window-one-document
> setup?

No; "add window" means adding a GtkWindow to the list of windows
belonging to the application; a window is bound to a document (hence the
document id) so that multiple windows can show the same document.

> [snip]
> 
> >I'd like to hear from developers using an "application" abstraction in
> >their code (like Gedit, Evince and Epiphany) what they think about this
> >API and what they think an application API should provide for their
> >needs.  For instance, this API is designed for document-based
> >applications; 
> >
> All in all, it's really not clear what this api is doing. The document
> stuff looks like it's a desktop file taken to the next level, but what for?

Where did you get the "desktop file" part from? :-)

The GtkApplication is a controller object: it controls the lifetime of
documents and windows, and binds them in a <document>::[<window>, *]
relation.  It's a bit of high-level object orientated design for
document-oriented applications - even though you don't really need real
documents to implement a GtkDocumentModel interface, for instance.

Ciao,
 Emmanuele.

-- 
Emmanuele Bassi,  E: ebassi gmail com
W: http://www.emmanuelebassi.net
B: http://log.emmanuelebassi.net