API changes for multi-head compatibity

[Owen Taylor <otaylor redhat com>]

I went through Erwann Chenede's multihead branch last week to check
for possible source and binary incompatible changes that might be
involved that we should fix for 2.0, so that we can make sure we
can add it compatibly in 2.2.

The ones I found were:

 * style->font should be an only-when-realized resource, since GdkFont's
   are display specific resources.

 * gdk_colormap_get_system_size() should be deprecated.

 * We should add a gdk_pixbuf_render_pixmap_and_mask_for_colormap() function,
   since a) we need it in various places like gtkwindow.c 
   b) gdk_pixbuf_render_pixmap_and_mask() is not multi-head safe so we'll 
   need that variant later.

 * Make all the GDK structures where derivation is not involved opaque - 
   in particular, all the structures for gdk-x11 should be opaque and
   macros like GDK_WINDOW_XWINDOW() should be changed to be function calls.

 * Questions about gdk_set/get_use_xshm() that I've brought up in a 
   separate mail.

 * We need to figure out how colormap handling for widgets will interact 
   with screen handling when we have multihead support, and if colormap 
   handling for GTK+-2.0 should be changed to correspond to that.

   The current GTK+-2.0 colormap widget API is:

   void gtk_widget_set_colormap         (GtkWidget   *widget,
                                         GdkColormap *colormap);
   void gtk_widget_push_colormap        (GdkColormap *cmap);
   void gtk_widget_pop_colormap         (void);
   void gtk_widget_set_default_colormap (GdkColormap *colormap);

   The way this works is that:

    - The colormap for a widget is the colormap that has been 
      set on it explicitely, otherwise the default colormap.

    - Any widgets created between a push_colormap/pop_colormap()
      pair will have that colormap explicitely set.

    - gtk_widget_set_colormap() also explicitely sets the colormap
      for a widget().

   The problem here for multihead support is the second step ...
   at gtk_widget_init(), we don't know the proper screen for the
   widget. (The screen for a widget is a property of its toplevel,
   and basically not known until realize time.)

   I think the best way to fix the problem is:

    - Make gtk_widget_push/pop_colormap() affect only toplevel
      widgets. (So, when you push_colormap() all _toplevel_ widgets
      will have the colormap set to that value until 

    - Make the default colormap the colormap from gdk_rgb_get_cmap(), 
      rather than the system default colormap.

    - Make the colormap/visual "inherited" by child widgets if it
      is not explicitely set.

   The reason for changing the default colormap / visual is that there
   are a lot of instances of:

    gtk_widget_push_colormap([ GdkRGB or GdkImlib colormap ])
    [ create non-toplevel widget ]
    gtk_widget_pop_colormap()

   Which will stop working if we make push/pop colormap not affect
   child widgets, but if we change the default visual, then it won't 
   matter that they stop working. (It's pretty broken to set the 
   colormap/visual on child widgets anyways ... gdk_rgb_get_cmap()
   can return a private colormap for pseudo-color displays in 
   some circumstances...)

   Changing the default colormap will have the following negative
   consequences:
 
    - If you have a 8/24 display where the 24-bit part is really slow
      then performance may suffer. (True on some old Sparcs, apparently.)

    - If you try to draw to the root window or a non-GTK+ window with
      the default GTK+ colormap, you'll get a BadMatch.

   But will make things look a lot better if you have a 8/24 display
   where the 24 bit visual is fast and the 8 bit visual is just 
   there to keep old broken clients working.

   We could also try to rely on the fact that GdkRGB can draw to
   any colormap now to keep:

    gtk_widget_push_colormap([ GdkRGB or GdkImlib colormap ])
    [ create non-toplevel widget ]
    gtk_widget_pop_colormap()

   Working, but I suspect people amy be explicitely referencing 
   the GdkRGB colormap in such circumstances.
   
Regards,
                                        Owen