Re: input only event boxes

[Owen Taylor <otaylor redhat com>]

The main API issue that came to mind is that input-only event boxes
are different from normal event boxes along two different axes:

 A) They aren't visible
 B) They trap events to the child before they get to the child.

While for a non-selectable label or image, B) isn't relevant, it might
be relevant in some other uses - say, trying to put a tooltip on
a container with multiple buttons in it.

So, I wonder if we should offer separate properties:

 "input-only"
 "above-child"

We can implement all four combinations pretty easily with one 
non-obvious trap for input-only, !above-child: since the input
window isn't a parent window of the child, if the child window
doesn't have an event in it's event mask, it won't be received.

The other API issue is that the term input-only is a negative, so
when you start writing "not input-only" in the docs, it looks rather
weird.

Would "visible-window" (default TRUE) be a better name than
"input-only"? 

"An event box with a visible window" "An event box without a visible
window" reads a lot better than "An input-only event box" 
"A not input-only event box".

Some detailed comments, not all completely relevant if we add something
like "above_child".

+typedef struct 
+{
+  gboolean input_only;

I think it's confusing that you use this flag in a couple of places
and GTK_WIDGET_NO_WINDOW() everywhere else. (I assume the usage
of GTK_WIDGET_NO_WINDOW() is to avoid having to get the priv structure.)

You might just want to use NO_WINDOW() everywhere.

+ } GdkEventBoxPrivate;

Better to be consistent with the rest of GTK+ and use a separate
typedef. 

+  g_object_class_install_property (gobject_class,
+                                   PROP_INPUT_ONLY,
+                                   g_param_spec_boolean ("input-only",
+                                                        _("Input
Only"),
+                                                        _("Whether the
event box uses an input only window or not"),

Here and everwhere else, "input-only window" should get a hyphen because
it's a compound adjective. Also, I think if you have one sentence to
gloss a property, you should really try to say something that is
as distinct from the property name as possible.

 Whether the event box is only used to trap events and has no visible
 window.

+/**
+ * gtk_event_box_get_input_only:
+ * @event_box: a #GtkEventBox
+ *
+ * Return whether the event box is using input only windows

"an input-only window" - there is only one of them.

+ * or not.
+ *
+ * Return value: TRUE if the event box uses an input only
+ *   window, and FALSE if it uses a normal window.

TRUE and FALSE should be marked up as %TRUE and %FALSE.
For boolean return values, most of GTK+ leaves the
meaning of %FALSE to the imagination.

"See gtk_event_box_set_input_only()" is useful if you leave
the complete docs to the setter.
+/**
+ * gtk_event_box_set_input_only:
+ * @event_box: a #GtkEventBox
+ * @input_only: boolean value
+ *
+ * Set whether the event box uses a normal (GDK_INPUT_OUTPUT)
+ * child window, or an invisible (GDK_INPUT_ONLY) window.

%GDK_INPUT_OUTPUT, %GDK_INPUT_ONLY (for one thing, giving the
markup will get you the appropriate cross-reference link)

+ * The default is to use normal windows.
+ *
+ * Input only event boxes are useful when you want the contents
+ * of the event box to follow the theme of the parent widget
+ * better. They don't overdraw the background of the parent
+ * window.

This needs to be expanded. An input-only event box has
various differences from normal event boxes tha that
relevant and need to be documented. Something on the
order of:

 In an input-only event box, the window that that the
 event box creates is a %GDK_INPUT_ONLY window, which 
 means that it is invisible and only serves to receive
 events. The input-only window is raised above any
 windows that widgets contained in the event box might create, so 
 if the user clicks the mouse over that portion of the screen, 
 the event goes directly to the event-box rather than to the child.
 (So a button or selectable label in an input-only event
 box won't work.)

 A not input-only event box creates a visible (%GDK_INPUT_OUTPUT)
 window that acts as the parent window for all the widgets  
 contained in the event box. Because this window is behind
 the windows of contained widgets, events go first to the
 child widget and then to the parent widget.

 You should generally make your event box input-only if
 you just want to trap events. Creating a visible window
 may cause artifacts that are visible to the user, especially
 if the user is using a theme with gradients or pixmaps.

 The main reason to create a non input-only event box is if
 you want to set the background to a different color or
 draw on it.


+static void
+gtk_event_box_unrealize (GtkWidget *widget)
+{
+  GtkEventBox *event_box;
+  GtkEventBoxPrivate *priv;
+  
+  g_return_if_fail (widget != NULL);
+  g_return_if_fail (GTK_IS_EVENT_BOX (widget));

No return_if_fail()'s in method implementations (and also,
we don't use separate widget != NULL these days, is
IS_EVENT_BOX() catches that.

+static void
+gtk_event_box_map (GtkWidget *widget)
+{
+  GtkEventBoxPrivate *priv;
+
+  (* GTK_WIDGET_CLASS (parent_class)->map) (widget);
+
+  if (GTK_WIDGET_NO_WINDOW (widget))
+    {
+      priv = GTK_EVENT_BOX_GET_PRIVATE (widget);
+      gdk_window_show (priv->event_window);
+    }

The ordering here needs a comment - the fact that
you map second isn't just random, it's intentional
that the window ends up above windows of child
widgets.

Regards,
					Owen