widget_system.txt

gtk是linux一款强大的夸平台的图形化开发工具

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:

 I) A description of the meaning of the various flags

 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)

 III) Some notes about the ways that a widget changes states

 IV) A list of responsibilities of various widget signals when
    the states change.

Any action necessary to maintain the invariants in II which is not
explicitly mentioned in IV), is the responsibility of the core GTK
code, which is roughly defined as:

  gtkobject.c
  gtkwidget.c
  gtkcontainer.c
  gtkmain.c
  gtksignal.c

Section II is mostly of interest to those maintaining GTK, the
other sections may also be interesting to people writing
new widgets.

Main outline:
	- Owen Taylor <[e-mail]>
	  1998/02/03

Flag descriptions:
	- Tim Janik <[e-mail]>
	  1998/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 without 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 parent's 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).

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).

GTK_VISIBLE:
	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.

GTK_SENSITIVE:
	Set and unset by gtk_widget_set_sensitive.
	The sensitivity of a widget determines whether 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 whether 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 be 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 default 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 attempt at making a distinction
	between widgets that handle user input e.g. key/button presses
	and those that don't. Subsequent parent<->child relation ships
	of non `basic' widgets should be avoided. The checking for
	this is currently not properly 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.

GTK_RESERVED_3:

GTK_RC_STYLE:
	This flag indicates that its style has been looked up through
	the rc mechanism. It does not imply that the widget actually
	had a style defined through the rc mechanism.


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).
	[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)).

GTK_RESIZE_PENDING:
	First, this is only valid for GtkContainers.
	[some of the code should move to gtkcontainer.c therefore]
	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
	resize it.

GTK_RESIZE_NEEDED:
	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 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 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_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:
	This macro examines whether 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
	whether both the widget and all its parents are in sensitive state.


II. Invariants:
---------------

This section describes various constraints on the states of 
the widget:

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 A <= B)


1)  GTK_WIDGET_DESTROYED (widget) => !GTK_WIDGET_REALIZED (widget)
                                  => !GTK_WIDGET_VISIBLE (widget)
[ The latter is not currently in place, but it should be ] 
 
2) GTK_WIDGET_MAPPED (widget) => GTK_WIDGET_REALIZED (widget)

3) if GTK_WIDGET_TOPLEVEL (widget):
   GTK_WIDGET_VISIBLE (widget) <=> GTK_WIDGET_MAPPED (widget)

4) if !GTK_WIDGET_TOPLEVEL (widget):
  widget->parent && GTK_WIDGET_REALIZED (widget->parent) <=>
     GTK_WIDGET_REALIZED (widget)

5) if !GTK_WIDGET_TOPLEVEL (widget):

   GTK_WIDGET_MAPPED (widget) => GTK_WIDGET_VISIBLE (widget)
                              => GTK_WIDGET_REALIZED (widget)

   widget->parent && GTK_WIDGET_MAPPED (widget->parent) && 
     GTK_WIDGET_VISIBLE (widget) => GTK_WIDGET_MAPPED (widget)

Note:, the definition

[  GTK_WIDGET_DRAWABLE = GTK_WIDGET_VISIBLE && GTK_WIDGET_MAPPED