take into account that a path from a rowref can be NULL. (#72623 and

[~andy/gtk] / docs / refcounting.txt

diff --git a/docs/refcounting.txt b/docs/refcounting.txt
index aa8823e22553a96a242dc0e54410733829c2de9e..0c9de313360a70961fb18b9e4148ce9f045bbdd6 100644 (file)
--- a/docs/refcounting.txt
+++ b/docs/refcounting.txt
@@ -7,14 +7,15 @@ functions that follow these conventions:
   *_new:      Create a new structure with a reference count of 1.
   *_ref:      Increase ref count by one.
   *_unref:    Decrease ref count by one.  If the count drops to zero,
-              run aprropriate finalization code and free the memory.
-              No user visible actions should take place, like
-              destryoing windows, etc.
+              run appropriate finalization code and free the memory.
+             For data structures with a _destroy function, it will be
+             invoked at this point, if the data structure is not
+              already in a destroyed state.
 
 GtkObjects also provide the following functions:
 
   *_destroy:  Render an object `unusable', but as long as there are
-              references to it, it's allocated memory will not be freed.
+              references to it, its allocated memory will not be freed.
   *_sink:     Clear a GtkObjects `floating' state and decrement the
              reference count by 1.
 
@@ -35,6 +36,10 @@ ref_count is updated accordingly.
 You can call gdk_window_destroy more than once on a particular
 GdkWindow, it will only be destroyed when it hasn't been yet.  The
 ref_count is *always* decremented, tho. Be careful.
+
+Remark: When writing NO_WINDOW widgets, care should be taken about
+        proper referencing/unreferencing of the parent's GdkWindow
+        that is used by the widget.
  
 GdkPixmap
 ---------
@@ -235,7 +240,7 @@ Taking care of proper referencing
 ---------------------------------
 
 There are some cases where referencing of widgets from outside the toolkit
-(on the application side is needed).
+(on the application side) is needed.
 Once the application performes an operation on a widget that will cause
 its reference count to drop, if it wants to take further actions on the
 widget, it needs to hold a reference to it.
@@ -243,7 +248,7 @@ widget, it needs to hold a reference to it.
 Example code sequences that require reference wraps:
 
    /* gtk_container_remove() will unparent the child and therefore
-    * cause it's reference count to be decremented by one.
+    * cause its reference count to be decremented by one.
     */
    gtk_widget_ref (widget);
    gtk_container_remove (container, widget);
@@ -301,28 +306,10 @@ void       gtk_menu_item_remove_submenu (GtkMenuItem      *menu_item);
 void       gtk_option_menu_remove_menu  (GtkOptionMenu    *option_menu);
 
 
-Gnits to care about
--------------------
-
-On another note, though somewhat unrelated, the notification nature
-of the signal mechanism might cause events to be emitted that have their
-GdkWindow pointer set to NULL. This is due to the fact that certain
-events need to be emitted after the real GdkWindow of a widget is not
-any longer pertinent. It's up to the application to check for the window
-field of the event structure to be != NULL, if it is going to perform
-any operations through Gdk calls on it.
-Events that a likely to trigger a missing check for the window pointer
-currently are (and correspond to the trailing signals):
-
-GDK_SELECTION_CLEAR     GtkWidget::selection_clear_event
-GDK_FOCUS_CHANGE        GtkWidget::focus_in_event
-                        GtkWidget::focus_out_event
-
-
 
 Initial proposal:
        - Marius Vollmer <mvo@zagadka.ping.de>
 
-Small fixups, "Taking care of proper referencing" and reference
-counting solution for GtkMenus:
+Some modifications/additions, "Taking care of proper referencing" and
+reference counting solution for GtkMenus:
        - Tim Janik <timj@gimp.org>