*_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.
GdkWindow
---------
-A GdkWindow has to be explicitely destroyed with gdk_window_destroy.
+A GdkWindow has to be explicitly destroyed with gdk_window_destroy.
This will send out a request to destroy this window and all its
children, and will decrement the ref_count of the GdkWindow by one.
-Thus, it releases the inital reference created by gdk_window_new.
+Thus, it releases the initial reference created by gdk_window_new.
All GdkWindows are kept in a hash table to translate from their XId to
the actual structure and the pointer in the hash table is reflected in
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
---------
---------
There are no *_new or *_destroy functions and the *_ref and *_unref
-functions are noops. GdkVisuals are static structures and thus do not
+functions are no-ops. GdkVisuals are static structures and thus do not
need reference counting. The ref counting functions are only there
for extra defensive programming.
/* menu_item->ref_count == 1 and it is flagged as `floating'.
*/
- gtk_menu_append (GTK_MENU (menu), menu_item);
+ gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
/* menu_item->ref_count still == 1, but it is no longer `floating'.
*/
/* The GdkWindow of `window' and all its child GdkWindows are
* destroyed.
*
- * window is unregistered from the loplevel list and its ref_count
- * drops to zero. The destroy code of `window' destroyes `option_menu'.
+ * window is unregistered from the toplevel list and its ref_count
+ * drops to zero. The destroy code of `window' destroys `option_menu'.
*
* The destroy code of `option_menu' causes the `menu' to be detached
* from it and its reference count drops to zero.
*
- * The destroy code of `menu' destroyes `menu_item'.
+ * The destroy code of `menu' destroys `menu_item'.
*
* The destruction of `menu_item' removes it from its parent, the
* menu_item->ref_count drops to zero and `menu_item' is finalized (freed).
---------------------------------
There are some cases where referencing of widgets from outside the toolkit
-(on the application side is needed).
-Once the application performes an operation on a widget that will cause
+(on the application side) is needed.
+Once the application performs 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.
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);
+ g_object_ref (widget);
gtk_container_remove (container, widget);
/* without the reference count, the widget would have been destroyed here.
*/
gtk_container_add (container, widget);
- gtk_widget_unref (widget);
+ g_object_unref (widget);
/* all items in item_list need to be referenced
slist = NULL;
for (list = item_list; list; list = list->next)
{
- gtk_widget_ref (GTK_WIDGET (list->data));
+ g_object_ref (GTK_WIDGET (list->data));
slist = g_slist_prepend (slist, list->data);
}
gtk_list_remove_items (list, item_list);
tmp = slist;
slist = slist->next;
- gtk_widget_unref (GTK_WIDGET (tmp->data));
+ g_object_unref (GTK_WIDGET (tmp->data));
g_slist_free_1 (tmp);
}
+
+ /* Alternatively to the removal above you could just use
+ * gtk_list_remove_items_no_unref() which will add the additional
+ * reference count to the widget.
+ */
+ gtk_list_remove_items_no_unref (list, item_list);
+ gtk_list_prepend_items (other_list, item_list);
Now a (hopefully) complete list of functions that require
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_EXPOSE GtkWidget::expose_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>
projects / ~andy / gtk / blobdiff