Elaborate a bit more in the docs on GdkFilterFunc and GdkFilterReturn.

2003-08-09  Noah Levitt  <nlevitt@columbia.edu>

	* gdk/gdkevents.h:
	* docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
	docs on GdkFilterFunc and GdkFilterReturn.

diff --git a/ChangeLog b/ChangeLog
index 214acc56aea97855504997dd3d5bcb18c0915152..f5cfc969ec0dd46aadb95af2d528a91e5154069e 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2003-08-09  Noah Levitt  <nlevitt@columbia.edu>
+
+       * gdk/gdkevents.h:
+       * docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
+       docs on GdkFilterFunc and GdkFilterReturn.
+
 2003-08-09  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcalendar.c:  Add and hook in gtk_calendar_scroll,

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 214acc56aea97855504997dd3d5bcb18c0915152..f5cfc969ec0dd46aadb95af2d528a91e5154069e 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,9 @@
+2003-08-09  Noah Levitt  <nlevitt@columbia.edu>
+
+       * gdk/gdkevents.h:
+       * docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
+       docs on GdkFilterFunc and GdkFilterReturn.
+
 2003-08-09  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcalendar.c:  Add and hook in gtk_calendar_scroll,

diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index 214acc56aea97855504997dd3d5bcb18c0915152..f5cfc969ec0dd46aadb95af2d528a91e5154069e 100644 (file)
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,9 @@
+2003-08-09  Noah Levitt  <nlevitt@columbia.edu>
+
+       * gdk/gdkevents.h:
+       * docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
+       docs on GdkFilterFunc and GdkFilterReturn.
+
 2003-08-09  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcalendar.c:  Add and hook in gtk_calendar_scroll,

diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index 214acc56aea97855504997dd3d5bcb18c0915152..f5cfc969ec0dd46aadb95af2d528a91e5154069e 100644 (file)
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,9 @@
+2003-08-09  Noah Levitt  <nlevitt@columbia.edu>
+
+       * gdk/gdkevents.h:
+       * docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
+       docs on GdkFilterFunc and GdkFilterReturn.
+
 2003-08-09  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcalendar.c:  Add and hook in gtk_calendar_scroll,

diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index 214acc56aea97855504997dd3d5bcb18c0915152..f5cfc969ec0dd46aadb95af2d528a91e5154069e 100644 (file)
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,9 @@
+2003-08-09  Noah Levitt  <nlevitt@columbia.edu>
+
+       * gdk/gdkevents.h:
+       * docs/reference/gdk/tmpl/windows.sgml: Elaborate a bit more in the
+       docs on GdkFilterFunc and GdkFilterReturn.
+
 2003-08-09  Matthias Clasen  <maclas@gmx.de>
 
        * gtk/gtkcalendar.c:  Add and hook in gtk_calendar_scroll,

diff --git a/docs/reference/gdk/tmpl/windows.sgml b/docs/reference/gdk/tmpl/windows.sgml
index 389a116cda4416395817a8e625a91b92df2f93eb..190688bc9ffa3716e2818e062f56af50514d66d2 100644 (file)
--- a/docs/reference/gdk/tmpl/windows.sgml
+++ b/docs/reference/gdk/tmpl/windows.sgml
@@ -746,8 +746,15 @@ Registers a window as a potential drop destination.
 <!-- ##### USER_FUNCTION GdkFilterFunc ##### -->
 <para>
 Specifies the type of function used to filter native events before they are
-converted to GDK events. A filter may translate the native event to a GDK
-event or handle it without translation.
+converted to GDK events. 
+</para>
+
+<para>
+When a filter is called, @event is unpopulated, except for
+<literal>event-&gt;window</literal>. The filter may translate the native
+event to a GDK event and store the result in @event, or handle it without
+translation. If the filter translates the event and processing should
+continue, it should return <literal>GDK_FILTER_TRANSLATE</literal>.
 </para>
 
 @xevent: the native event to filter.
@@ -762,7 +769,8 @@ Specifies the result of applying a #GdkFilterFunc to a native event.
 </para>
 
 @GDK_FILTER_CONTINUE: event not handled, continue processing.
-@GDK_FILTER_TRANSLATE: translated event stored.
+@GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored
+                       in the <literal>event</literal> structure that was passed in.
 @GDK_FILTER_REMOVE: event handled, terminate processing.
 
 <!-- ##### TYPEDEF GdkXEvent ##### -->

diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 818bb27465ab24cd6d3be65f378022d2dec22c1a..c4dbf51c6098dbe85527f08122715069187ae7cd 100644 (file)
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -48,7 +48,9 @@ typedef void GdkXEvent;         /* Can be cast to window system specific
 
 typedef enum {
   GDK_FILTER_CONTINUE,   /* Event not handled, continue processesing */
-  GDK_FILTER_TRANSLATE,          /* Translated event stored */
+  GDK_FILTER_TRANSLATE,          /* Native event translated into a GDK event and
+                             stored in the "event" structure that was
+                             passed in */
   GDK_FILTER_REMOVE      /* Terminate processing, removing event */
 } GdkFilterReturn;