Return value from events

[Dennis Bjorklund <db zigo dhs org>]

I've added this

@Returns: %TRUE if the event was handled, %FALSE if it shall be propagated
to the parent widget.

to all the events in the template gtkwidget.sgml.

I have two concerns

1. English is not my language so maybe it sounds funny or something
that I cant tell.

2. I've changed a template file, maybe there is some way to write this in
the code somewhere. This is the first time I look at the gtk+ docs from
the inside.

I have three concerns:

3. The "event"-event got the same text as above. But maybe one should
write more on this event since it also blocks the real event from being
sent later.

Among my concerns are

4. Maybe one should just write "%TRUE if the event was handled, %FALSE if
it shall be propagated further." And then it fits all events.

NOBODY expects the Spanish Inquisition!

-- 
/Dennis

Index: gtkwidget.sgml
===================================================================
RCS file: /cvs/gnome/gtk+/docs/reference/gtk/tmpl/gtkwidget.sgml,v
retrieving revision 1.35
diff -u -w -r1.35 gtkwidget.sgml
--- gtkwidget.sgml	2001/12/05 00:06:35	1.35
+++ gtkwidget.sgml	2002/01/02 08:18:35
@@ -1456,7 +1456,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::button-release-event ##### -->
 <para>
@@ -1465,7 +1465,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::child-notify ##### -->
 <para>
@@ -1482,7 +1482,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::configure-event ##### -->
 <para>
@@ -1491,7 +1491,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::delete-event ##### -->
 <para>
@@ -1500,7 +1500,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::destroy-event ##### -->
 <para>
@@ -1509,7 +1509,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::direction-changed ##### -->
 <para>
@@ -1607,7 +1607,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::event ##### -->
 <para>
@@ -1616,7 +1616,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::event-after ##### -->
 <para>
@@ -1633,7 +1633,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::focus ##### -->
 <para>
@@ -1642,7 +1642,7 @@
 
 @widget: the object which received the signal.
 @arg1: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::focus-in-event ##### -->
 <para>
@@ -1651,7 +1651,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::focus-out-event ##### -->
 <para>
@@ -1660,7 +1660,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::grab-focus ##### -->
 <para>
@@ -1703,7 +1703,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::key-release-event ##### -->
 <para>
@@ -1712,7 +1712,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::leave-notify-event ##### -->
 <para>
@@ -1721,7 +1721,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::map ##### -->
 <para>
@@ -1737,7 +1737,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::mnemonic-activate ##### -->
 <para>
@@ -1755,7 +1755,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::no-expose-event ##### -->
 <para>
@@ -1764,7 +1764,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::parent-set ##### -->
 <para>
@@ -1788,7 +1788,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::proximity-in-event ##### -->
 <para>
@@ -1797,7 +1797,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::proximity-out-event ##### -->
 <para>
@@ -1806,12 +1806,12 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::realize ##### -->
 <para>
 
-</para>
+</para>%TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 @widget: the object which received the signal.
 
@@ -1822,7 +1822,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::selection-clear-event ##### -->
 <para>
@@ -1831,7 +1831,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::selection-get ##### -->
 <para>
@@ -1850,7 +1850,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::selection-received ##### -->
 <para>
@@ -1868,7 +1868,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::show ##### -->
 <para>
@@ -1931,7 +1931,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::unrealize ##### -->
 <para>
@@ -1947,7 +1947,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### SIGNAL GtkWidget::window-state-event ##### -->
 <para>
@@ -1956,7 +1956,7 @@
 
 @widget: the object which received the signal.
 @event: 
- Returns: 
+ Returns: %TRUE if the event was handled, %FALSE if it shall be propagated to the parent widget.
 
 <!-- ##### ARG GtkWidget:name ##### -->
 <para>