Patch: API documentation improvements
- From: Hongli Lai <h lai chello nl>
- To: gtk-devel-list gnome org
- Subject: Patch: API documentation improvements
- Date: Thu, 03 Nov 2005 17:17:53 +0100
This patch documents GtkWidget's destroy-event, expose-event and
configure-event's signals, and fixes the name for the grab-focus-event
documentation.
Index: gtk/gtkwidget.c
===================================================================
--- gtk/gtkwidget.c (revision 5)
+++ gtk/gtkwidget.c (working copy)
@@ -798,7 +798,7 @@
/**
* GtkWidget::destroy-event:
* @widget: the object which received the signal.
- * @event: the event which triggered this signal
+ * @event: the event which triggered this signal.
*
* The ::destroy-event signal is emitted when a #GdkWindow is destroyed.
* You rarely get this signal, because most widgets disconnect themselves
@@ -817,6 +817,17 @@
_gtk_marshal_BOOLEAN__BOXED,
G_TYPE_BOOLEAN, 1,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+/**
+ * GtkWidget::expose-event:
+ * @widget: the object which received the signal.
+ * @event: the event which triggered this signal.
+ *
+ * The ::expose-event signal is emitted when all or a part of the widget
+ * needs to be redrawn.
+ *
+ * Returns: %TRUE to stop other handlers from being invoked for the event.
+ * %FALSE to propagate the event further.
+ */
widget_signals[EXPOSE_EVENT] =
g_signal_new ("expose_event",
G_TYPE_FROM_CLASS (gobject_class),
@@ -862,6 +873,16 @@
_gtk_marshal_BOOLEAN__BOXED,
G_TYPE_BOOLEAN, 1,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
+ /**
+ * GtkWidget::configure-event:
+ * @widget: the object which received the signal.
+ * @event: the event which triggered this signal.
+ *
+ * The ::configure-event signal is emitted when the widget is moved or resized.
+ *
+ * Returns: %TRUE to stop other handlers from being invoked for the event.
+ * %FALSE to propagate the event further.
+ */
widget_signals[CONFIGURE_EVENT] =
g_signal_new ("configure_event",
G_TYPE_FROM_CLASS (gobject_class),
@@ -1328,7 +1349,7 @@
G_TYPE_BOOLEAN, 1,
GDK_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
/**
- * GtkWidget::grab-broken:
+ * GtkWidget::grab-broken-event:
* @widget: the object which received the signal
* @event: the #GdkEventGrabBroken event
*
Index: docs/reference/gtk/xml/gtkwidget.xml
===================================================================
--- docs/reference/gtk/xml/gtkwidget.xml (revision 3)
+++ docs/reference/gtk/xml/gtkwidget.xml (working copy)
@@ -4648,18 +4648,20 @@
<link linkend="GdkEventConfigure">GdkEventConfigure</link> *event,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
+The ::configure-event signal is emitted when the widget is moved or resized.</para>
+<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter> :</term>
-<listitem><simpara>the object which received the signal.
+<listitem><simpara> the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter> :</term>
-<listitem><simpara>
+<listitem><simpara> the event which triggered this signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
-<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> to stop other handlers from being invoked for the event. <literal>FALSE</literal> to propagate the event further.
-
+<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> to stop other handlers from being invoked for the event.
+ <literal>FALSE</literal> to propagate the event further.
</simpara></listitem></varlistentry>
</variablelist></refsect2><refsect2><title><anchor id="GtkWidget-delete-event"/>The "delete-event" signal</title>
<programlisting><link linkend="gboolean">gboolean</link> user_function (<link linkend="GtkWidget">GtkWidget</link> *widget,
@@ -4701,7 +4703,7 @@
<listitem><simpara> the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter> :</term>
-<listitem><simpara> the event which triggered this signal
+<listitem><simpara> the event which triggered this signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
@@ -5127,18 +5129,21 @@
<link linkend="GdkEventExpose">GdkEventExpose</link> *event,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
+The ::expose-event signal is emitted when all or a part of the widget
+needs to be redrawn.</para>
+<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter> :</term>
-<listitem><simpara>the object which received the signal.
+<listitem><simpara> the object which received the signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter> :</term>
-<listitem><simpara>
+<listitem><simpara> the event which triggered this signal.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
-<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> to stop other handlers from being invoked for the event. <literal>FALSE</literal> to propagate the event further.
-
+<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> to stop other handlers from being invoked for the event.
+ <literal>FALSE</literal> to propagate the event further.
</simpara></listitem></varlistentry>
</variablelist></refsect2><refsect2><title><anchor id="GtkWidget-focus"/>The "focus" signal</title>
<programlisting><link linkend="gboolean">gboolean</link> user_function (<link linkend="GtkWidget">GtkWidget</link> *widget,
@@ -5199,20 +5204,30 @@
<link linkend="GdkEvent">GdkEvent</link> *event,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
+Emitted when a pointer or keyboard grab on a window belonging
+to <parameter>widget</parameter> gets broken.
+</para>
+<para>
+On X11, this happens when the grab window becomes unviewable
+(i.e. it or one of its ancestors is unmapped), or if the same
+application grabs the pointer or keyboard again.</para>
+<para>
</para><variablelist role="params">
<varlistentry><term><parameter>widget</parameter> :</term>
-<listitem><simpara>the object which received the signal.
+<listitem><simpara> the object which received the signal
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event</parameter> :</term>
-<listitem><simpara>
+<listitem><simpara> the <link linkend="GdkEventGrabBroken"><type>GdkEventGrabBroken</type></link> event
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter> :</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
-<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
+<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <literal>TRUE</literal> to stop other handlers from being invoked for the event.
+ <literal>FALSE</literal> to propagate the event further.
</simpara></listitem></varlistentry>
-</variablelist></refsect2><refsect2><title><anchor id="GtkWidget-grab-focus"/>The "grab-focus" signal</title>
+</variablelist><para>Since 2.8
+</para></refsect2><refsect2><title><anchor id="GtkWidget-grab-focus"/>The "grab-focus" signal</title>
<programlisting><link linkend="void">void</link> user_function (<link linkend="GtkWidget">GtkWidget</link> *widget,
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
