callisto-debian/gtk3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation. -timj

Browse Source 
documentation.
-timj
This commit is contained in:
Tim Janik
1998-02-04 03:18:53 +00:00
parent 8d2bb0f43e
commit 4b86717650
4 changed files with 453 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

304
docs/refcounting.txt Normal file
View File

@ -0,0 +1,304 @@
The Reference Counting Scheme of GDK an GTK+
============================================
Each data structure that provides reference counting offers a bunch of
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.
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.
*_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.
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.
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
the reference count. When a DestroyNotify event is received for a
particular GdkWindow, it is removed from the hash table and the
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.
GdkPixmap
---------
There is no gdk_pixmap_destroy function. The Pixmap is destroyed when
the last reference to it vanishes.
GdkPixmaps are kept in the same hash table as GdkWindows but the
pointer in the hash table is *not* reflected in the ref_count.
This works only when Pixmaps never get XEvents. I'm not sure if this
is the case.
GdkBitmap
---------
A GdkBitmap is only another name for a special use of GdkPixmap.
GdkVisual
---------
There are no *_new or *_destroy functions and the *_ref and *_unref
functions are noops. GdkVisuals are static structures and thus do not
need reference counting. The ref counting functions are only there
for extra defensive programming.
GdkColormap
-----------
Nothing special. There is no gdk_colormap_destroy function.
GdkFont / GdkFontSet
--------------------
GdkFont and GdkFontSet are equivalent as far as ref counting is
concerned. Use gdk_font_ref and gdk_font_unref for both.
There is no gdk_font_free or gdk_fontset_free function.
GtkAcceleratorTable
-------------------
There is no gtk_accelerator_table_destroy function.
GtkTooltips
-----------
There is no gtk_tooltips_destroy function.
GtkStyle
--------
There is no gtk_style_destroy function.
GtkObject
---------
GtkObjects follow the usual ref_counting strategy, but with a twist.
They are created with a ref_count of 1. GtkObjects are able to
run finalization code when the ref_count drops to zero but you cannot
register arbitrary signal handlers to run at finalization time.
There is also the old gtk_object_destroy function and the "destroy"
signal but they are somewhat independent from finalization. Just as
stated at the top of this text, gtk_object_destroy merely renders an
object unusable. When the object is a container widget for example,
it unrealizes that widget, removes all children and disconnects all
signal handlers. The finalization code is different, it would for
example free associated memory for text strings and release the
attached style.
This is the biggest change. Every widget must be revised to have a
proper "destroy" function, etc. Such a destroy function will only
be called once and is expected to leave the widget in a minimal but
consistent state. Widgets that have been "destroyed" but not yet
finalized are flagged with GTK_DESTROY. The "finalization" function
is new and should perform last-minute cleanup actions, in contrast
to the destroy function it will not be emitted as signal though.
It can assume that the "destroy" function has been called as the
last function on this widget.
Essentially, the old "destroy" function has been split into a
"finalize" plus a "destroy" function.
It is not possible to create GtkObjects with a ref_count of 0
because the first ref/unref pair will destroy it unintentionally.
To be mostly backward compatible with existing practice, a GtkObject
leads a more complicated life than the other reference counted structures.
When a GtkObject is created, it starts out in a special state called
"floating" (this is the twist). This means that it is alive and has a
reference to it, but the `owner' of this reference is not known.
There are certain `potential owners' that will adopt a floating
GtkObject. For GtkWidgets the most common adopters are the parent
widget.
When you want to adopt a possibly floating GtkObject, you call
gtk_object_sink on it. This clears the floating state of the
GtkObject and decrements the ref_count by one, if it has been floating
previously. Once the floating state has been cleared, it will never
be set again.
All widgets that are part of the display are linked into a
parent/child tree. The link from the parent to a child is reflected
in the ref_count of the child, but the link from the child to the
parent is not reflected in the ref_count of the parent.
Like a GtkObject, a GtkWidget is created with a ref_count of 1 and
initially flagged as `floating'. As soon as it is added as a child to
a parent, the `floating' flag is cleared and never will be set again.
Not even when it is later unparented. The act of clearing the
`floating' flag also decrements the ref_count of the widget by one.
When the widget is unparented, its underlying GdkWindow is destroyed
(when it has one), it loses its reference from the parent and
naturally the ref_count is decremented.
It is considered a bug if a widget still has a GdkWindow when it is
being freed.
Toplevel widgets, which don't have a `natural' parent, are adopted by
special registering functions. Because the of the reference count that
is set by the registering functions, toplevel widgets will have to be
explicitly destroyed, with the exception of GtkMenus. GtkMenus are a
special case of toplevel widgets in that they will be `attached' to and
`detached' from other widgets. The act of attaching a GtkMenu to a
widget will be reflected in its reference count. The act of detaching
a GtkMenu will revert that. Therefore GtkMenus naturally get destroyed
and finalized once they are detached from their reference holder.
So, the typical career of a GtkWindow a GtMenu attached to a
GtkOptionMenu looks like this:
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
/* window is created with ref_count == 1. It is not flagged as
* `floating' because it has already been registered as a toplevel
* widget.
*/
option_menu = gtk_option_menu_new ();
/* option_menu->ref_count == 1 and it is flagged as `floating'.
*/
gtk_container_add (window, option_menu);
/* option_menu->ref_count still == 1, but it is no longer `floating'.
*/
menu = gtk_menu_new ();
/* menu->ref_count == 1 and it is flagged as `floating'.
*/
menu_item = gtk_menu_item_new_with_label ("Choose Me");
/* menu_item->ref_count == 1 and it is flagged as `floating'.
*/
gtk_menu_append (GTK_MENU (menu), menu_item);
/* menu_item->ref_count still == 1, but it is no longer `floating'.
*/
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
/* menu->ref_count still == 1, but it is no longer `floating'.
*/
gtk_widget_show (menu_item);
gtk_widget_show (option_menu);
gtk_widget_show (window);
/* The widgets get their GdkWindows, nothing significant happens to
* the ref_counts.
*/
Then, when the user wants to get rid of the window:
gtk_widget_destroy (window);
/* 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'.
*
* 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 destruction of `menu_item' removes it from its parent, the
* menu_item->ref_count drops to zero and `menu_item' is finalized (freed).
*
* Now `menu', `option_menu' and `window' will be destroyed and finalized,
* in this order, since the reference count of each is zero.
*/
Taking care of proper referencing
---------------------------------
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
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.
*/
gtk_widget_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);
/* all items in item_list need to be referenced
* before gtk_list_remove_items() is invoked.
* this is somewhat tricky as gtk_list_append_items/gtk_list_prepend_items/
* gtk_list_insert_items will take over the lists nodes.
* we therefore have an extra GSList `*slist' for later unreferencing.
*/
slist = NULL;
for (list = item_list; list; list = list->next)
{
gtk_widget_ref (GTK_WIDGET (list->data));
slist = g_slist_prepend (slist, list->data);
}
gtk_list_remove_items (list, item_list);
gtk_list_append_items (other_list, item_list);
/* gtk_list_prepend_items (other_list, item_list); */
/* gtk_list_insert_items (other_list, item_list, 3); */
while (slist)
{
GSList *tmp;
tmp = slist;
slist = slist->next;
gtk_widget_unref (GTK_WIDGET (tmp->data));
g_slist_free_1 (tmp);
}
Now a (hopefully) complete list of functions that require
wrappers similar to the examples above:
void gtk_container_remove (GtkContainer *container,
GtkWidget *widget);
void gtk_list_remove_items (GtkList *list,
GList *items);
void gtk_tree_remove_items (GtkTree *tree,
GList *items);
void gtk_tree_item_remove_subtree (GtkTreeItem *tree_item);
void gtk_menu_item_remove_submenu (GtkMenuItem *menu_item);
void gtk_option_menu_remove_menu (GtkOptionMenu *option_menu);
Initial proposal:
- Marius Vollmer <mvo@zagadka.ping.de>
Small fixups, "Taking care of proper referencing" and reference
counting solution for GtkMenus:
- Tim Janik <timj@gimp.org>

180
docs/widget_system.txt
View File

@ -1,3 +1,6 @@
Notes about the inner workings of the widget system of GTK+
===========================================================
This file contains some notes as to how the widget system does
and should work. It consists of three parts:
@ -5,7 +8,7 @@ and should work. It consists of three parts:
II) A list of invariants about the states of the widgets.
(Throughout this document, we refer to the states of the
widgets by referring to the flags for gtkwidget)
widgets by referring to the flags for GtkWidget)
III) Some notes about the ways that a widget changes states
@ -26,73 +29,176 @@ Section II is mostly of interest to those maintaining GTK, the
other sections may also be interesting to people writing
new widgets.
Owen Taylor <owt1@cornell.edu>
98/02/03
Main outline:
- Owen Taylor <owt1@cornell.edu>
98/02/03
Flag descriptions:
- Tim Janik <timj@gimp.org>
98/02/04
I. Flags
--------
GtkObject:
GTK_DESTROYED:
This flagged is set for a GtkObject right before its
destruction code is executed. Its main use is the
prevention of multiple destruction invokations.
GTK_FLOATING:
This flag reflects the fact that the holder of the
initial reference count is unknown. Refer to refcounting.txt
for further details.
GTK_RESERVED_1:
GTK_RESERVED_2:
Reserved flags.
GtkWidget, public flags:
GTK_TOPLEVEL:
Widgets witghout a real parent, as there are GtkWindows and
GtkMenus have this flag set throughout their lifetime.
Toplevel widgets always contain their own GdkWindow.
GTK_NO_WINDOW:
This flag is indicative for a widget that does not provide
its own GdkWindow. Visible action (e.g. drawing) is performed
on the parents GdkWindow.
GTK_REALIZED:
set by gtk_widget_realize, unset by gtk_widget_unrealize
relies on ((widget->parent && widget->parent->window)
|| GTK_WIDGET_TOPLEVEL (widget);
means: widget has an associated GdkWindow (XWindow)
Set by gtk_widget_realize, unset by gtk_widget_unrealize.
Relies on ((widget->parent && widget->parent->window)
|| GTK_WIDGET_TOPLEVEL (widget));
Means: widget has an associated GdkWindow (XWindow).
GTK_MAPPED:
set by gtk_widget_map, unset by gtk_widget_unmap
may only be set if GTK_WIDGET_REALIZED(widget)
means: gdk_window_show() has been called on the widgets window(s).
Set by gtk_widget_map, unset by gtk_widget_unmap.
May only be set if GTK_WIDGET_REALIZED (widget).
Means: gdk_window_show() has been called on the widgets window(s).
GTK_VISIBLE:
set by gtk_widget_show
implies that a widget will be GTK_MAPPED as soon as it's
parent is GTK_MAPPED.
Set by gtk_widget_show.
Implies that a widget will be flagged GTK_MAPPED as soon as its
parent is mapped.
!GTK_VISIBLE:
set by gtk_widget_hide
implies that a widget is not onscreen, therefore !GTK_MAPPED
Set by gtk_widget_hide.
Implies that a widget is not onscreen, therefore !GTK_MAPPED.
GTK_SENSITIVE:
Set and unset by gtk_widget_set_sensitive.
The sensitivity of a widget determines wether it will receive
certain events (e.g. button or key presses). One premise for
the widgets sensitivity is to have GTK_SENSITIVE set.
GTK_PARENT_SENSITIVE:
Set and unset by gtk_widget_set_sensitive operations on the
parents of the widget.
This is the second premise for the widgets sensitivity. Once
it has GTK_SENSITIVE and GTK_PARENT_SENSITIVE set, its state is
effectively sensitive. This is expressed (and can be examined) by
the GTK_WIDGET_IS_SENSITIVE macro.
GTK_CAN_FOCUS:
There are no directly corresponding functions for setting/unsetting
this flag, but it can be affected by the GtkWidget::has_focus argument
via gtk_widget_set_arg.
This flag determines wether a widget is able to handle focus grabs.
GTK_HAS_FOCUS:
This flag will be set by gtk_widget_grab_focus for widgets that also
have GTK_CAN_FOCUS set. The flag will bve unset once another widget
grabs the focus.
GTK_CAN_DEFAULT:
GTK_HAS_DEFAULT:
These two flags are mostly equal in functionality to their *_FOCUS
counterparts, but for the defalt widget.
GTK_HAS_GRAB:
Set by gtk_grab_add, unset by gtk_grab_remove.
Means: widget is in the grab_widgets stack, and will be the preferred
one for receiving events other than ones of cosmetic value.
GTK_BASIC:
The GTK_BASIC flag is an attempted at making a distinction between
widgets that will proper handle user input e.g. key/button presses.
Supsequent parent<->child relation ships of non `basic' widgets
should be avoided. The checking for this is currently not proper
enforced in the code. For example GtkButton is a non `basic' widget,
that will therefore disallow to act as a container for another
GtkButton. Now the gnit is, one can add a GtkHBox (which is a
`basic' widget) to the first button, and put the second into
the box.
GtkWidget, private flags:
GTK_USER_STYLE:
A widget is flagged to have a user style, once gtk_widget_set_style
has been invoked for it. The use of this flag is to tell widgets
wich share a global user style from the ones which got a certain
style assign from outside the toolkit.
GTK_REDRAW_PENDING:
relies on GTK_WIDGET_MAPPED(widget)
[this is not really enforced throughout the code, but should
Relies on GTK_WIDGET_MAPPED (widget).
[FIXME: this is not really enforced throughout the code, but should
be. it only requires a few checks for GTK_WIDGET_MAPPED and
minor changes to gtk_widget_unmap, we can then remove the check
in gtk_widget_real_destroy]
means: there is an idle handler waiting for the widget, that
will cause a full redraw (gtk_widget_draw(widget, NULL))
Means: there is an idle handler waiting for the widget, that
will cause a full redraw (gtk_widget_draw (widget, NULL)).
GTK_RESIZE_PENDING:
first, this is only valid for GtkContainers.
First, this is only valid for GtkContainers.
[some of the code should move to gtkcontainer.c therefore]
relies on GTK_WIDGET_REALIZED(widget)
Relies on GTK_WIDGET_REALIZED(widget)
[this is not really enforced throughout the code, but should
be. it only requires a few checks for GTK_WIDGET_RELIZED and
minor changes to gtk_widget_unrealize, we can then remove the check
in gtk_widget_real_destroy]
means: there is an idle handler waiting for the container to
Means: there is an idle handler waiting for the container to
resize it.
GTK_RESIZE_NEEDED:
relies on GTK_WIDGET_REALIZED(widget)
[puhhh, this isn't rely enforced either..., bla bla ...remove check
in gtk_widget_real_destroy]
means: a widget has been added to the resize_widgets list of
Relies on GTK_WIDGET_REALIZED(widget)
[this is not really enforced throughout the code, but should
be. once this is done special checking in gtk_widget_real_destroy
can be avoided]
Means: a widget has been added to the resize_widgets list of
its _toplevel_ container (keep this in mind for GtkViewport).
remark: this flag is also used internaly by gtkwindow.c.
Remark: this flag is also used internaly by gtkwindow.c during
the evaluation of resizing worthy widgets.
GTK_LEAVE_PENDING:
a widget is flagged as such if there is a leave_notify event
pending for it. it receives this event regardless of a grab or
its current sensitivity.
A widget is flagged as such if there is a leave_notify event
pending for it. It will receive this event regardless of a grab
through another widget or its current sensitivity.
[this should be made relying on GTK_REALIZED]
GTK_HAS_GRAB:
set by gtk_grab_add, unset by gtk_grab_remove
means: widget is in the grab_widgets stack.
GTK_HAS_SHAPE_MASK:
Set by gtk_widget_shape_combine_mask if a widget got a shape mask
assigned (making use of the X11 shaped window extension).
GTK_IN_REPARENT:
During the act of reparentation widgets which are already
realized and will be added to an already realized parent need
to have this flag set to prevent natural unrealization on the
process of getting unparented.
Related Macros:
GTK_WIDGET_DRAWABLE:
a widget is flagged as GTK_WIDGET_VISIBLE and GTK_WIDGET_MAPPED
means: it _makes sense_ to draw in a widgets window.
This macro examines wether a widget is flagged as GTK_WIDGET_VISIBLE
and GTK_WIDGET_MAPPED.
Means: it _makes sense_ to draw in a widgets window.
GTK_WIDGET_IS_SENSITIVE:
This macro tells the real sensitivity state of a widget. It returns
wether both the widget and all its parents are in sensitive state.
II. Invariants:
@ -105,7 +211,7 @@ In the following
A => B means if A is true, than B is true
A <=> B means A is true, if and only if B is true
(equivalent to A => B and B <= A)
(equivalent to A => B and A <= B)
1) GTK_WIDGET_DESTROYED (widget) => !GTK_WIDGET_REALIZED (widget)
@ -375,5 +481,3 @@ it was not overridden in the Bar class structure) and
gtk_widget_destroy will call gtk_object_destroy because
the parent_class variable referenced by gtk_foo_destroy is the
static variable in gtkwidget.c: GtkObjectClass.