g_signal_*

[Owen Taylor <otaylor redhat com>]

The issue of the exact prototypes for g_signal_* is not
the biggest outstanding API issue by any means, but it is
probably the most urgent in affecting lots of code.

There are a number of subparts to this issue:

 1) Change g_signal_connect_data() to take flags, 
    not two trailing booleans. So, the prototype would
    become:

    typedef enum
    {
      G_CONNECT_AFTER = 1 << 0,
      G_CONNECT_SWAPPED = 1 << 1
    } GConnectFlags;

    gulong g_signal_connect_data (gpointer	  instance,
				  const gchar	 *detailed_signal,
				  GCallback	  c_handler,
				  gpointer        data,
				  GClosureNotify  destroy_data,
                                  GConnectFlags   flags);

    This is uncontroversial.
 
 1b) Change g_signal_connect_closure_by_id(), g_signal_connect_closure()
     to take GConnectFlags rather than 'gboolean after'. I'm
     not sure if this makes sense or not. Note the SWAPPED
     flag is a C-only thing.

 2) Remove the c from g_signal_connectc(). Rational, the 
    the connect() method for a particular language binding
    will  be specific to that language binding.

    This was agreed upon.

 3) Simplify/modify the prototype for g_signal_connect(). It is currently
 
    gulong g_signal_connect (gpointer	     instance,
			     const gchar    *detailed_signal,
			     GCallback	     c_handler,
			     gpointer        data,
                             gboolean        swapped);

    The two possibilities are:


    gulong g_signal_connect (gpointer	     instance,
			     const gchar    *detailed_signal,
			     GCallback	     c_handler,
			     gpointer        data,
                             GConnectFlags   flags);

    So, like g_signal_connect_data(), but without the
    destroy_data flag.

    Or, 

    gulong g_signal_connect (gpointer	     instance,
			     const gchar    *detailed_signal,
			     GCallback	     c_handler,
			     gpointer        data);

    Exactly like gtk_signal_connect(). Since g_signal_connect()
    is simply a convenience function for g_signal_connect_data(),
    IMO, the right thing to do is to make it simple for the 
    most common case - gtk_signal_connect(). 

    A matter of disagreement.

 3b) Modify the prototype of g_signal_connect_object() to match.

 4) Rename g_signal_connect_data().

    There a sentiment that I don't understand that a version
    of foo() which is more complete version with more arguments
    should not be called foo_full(), and that foo_full() should
    be reserved for a version with a single extra GDestroyNotify
    argument.

    This sentiment has resulted for g_signal_connect_data() in
    a name that means nothing whatsover. g_signal_connect()
    already has a 'data' argument.

    If we have a flags argument for g_signal_connect(), then
    g_signal_connect_data() is exactly a version with a single
    GDestroyNotify argument, so it should definitely be 
    g_signal_connect_full().

    If we don't put the flags argument in g_signal_connect(),
    then it's possible that we need to find a different name
    for g_signal_connect_data() than _full() - we could call it 
    g_signal_connnect_flags() and at least describe _one_
    of the extra arguments.

 5) Rename g_signal_newc() to g_signal_new(). No discussion 
    of this yet, but it seems to make sense by analogy
    to g_signal_connectc().

 6) Change:
    
     g_signal_disconnect_by_func => g_signal_handlers_disconnect_by_func
     g_signal_block_by_func      => g_signal_handlers_block_by_func
     g_signal_unblock_by_func    => g_signal_handlers_disconnect_by_func

   Earlier agreed upon.