forked from AuroraMiddleware/gtk
484 lines
15 KiB
Plaintext
484 lines
15 KiB
Plaintext
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 <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).
|
|
|
|
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 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).
|
|
[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 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:
|
|
---------------
|
|
|
|
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
|
|
is made in gtkwidget.c, but by 3) and 5),
|
|
|
|
GTK_WIDGET_MAPPED => GTK_WIDGET_VISIBLE
|
|
]
|
|
|
|
|
|
|
|
III. How states are changed:
|
|
----------------------------
|
|
|
|
How can the user control the state of a widget:
|
|
-----------------------------------------------
|
|
|
|
(In the following, set flag means set the flag, do appropriate
|
|
actions, and enforce above invariants)
|
|
|
|
gtk_widget_show:
|
|
if !GTK_DESTROYED sets GTK_VISIBLE
|
|
|
|
gtk_widget_hide:
|
|
if !GTK_VISIBLE for widget
|
|
|
|
gtk_widget_destroy:
|
|
sets GTK_DESTROYED
|
|
For a top-level widget
|
|
|
|
gtk_widget_realize:
|
|
if !GTK_DESTROYED sets GTK_REALIZED
|
|
- Calling gtk_widget_realize when the widget is not a descendent
|
|
of a toplevel is an ERROR.
|
|
|
|
gtk_container_add (container, widget) [ and container-specific variants ]
|
|
Sets widget->parent
|
|
|
|
gtk_container_remove (container, widget)
|
|
unsets widget->parent
|
|
|
|
gtk_widget_reparent (widget, new_parent)
|
|
Equivalent to removing widget from old parent and adding it to
|
|
the new parent, except that the widget will not be temporarily
|
|
unrealized if both the old parent and the new parent are realized.
|
|
|
|
|
|
gtk_widget_unrealize
|
|
gtk_widget_map
|
|
gtk_widget_unmap
|
|
|
|
These functions are not meant to be used by applications - they
|
|
are used only by GTK and widgets to enforce invariants on the
|
|
state.
|
|
|
|
When The X window corresponding to a GTK window is destroyed:
|
|
-------------------------------------------------------------
|
|
|
|
gtk_widget_destroy is called (as above).
|
|
|
|
|
|
|
|
IV. Responsibilities of widgets
|
|
--------------------------------
|
|
|
|
Adding to a container
|
|
---------------------
|
|
|
|
When a widget is added to a container, the container:
|
|
|
|
1) calls gtk_widget_set_parent (widget, container)
|
|
2) calls gtk_widget_set_parent_window (widget, window) if
|
|
the widget is being added to something other than container->window
|
|
3) if container is realized, and not widget, realizes widget
|
|
4) if container is mapped, and not widget and widget is GTK_VISIBLE,
|
|
maps widget
|
|
5) Queues a resize if the widget is mapped
|
|
|
|
Note: It would be nice to remove 3) and 4) out of widget specific code
|
|
since they are of the invariant-enforcing nature, but it is
|
|
a bit hard, since they can't be done until after 2)
|
|
|
|
|
|
Removing from a container
|
|
-------------------------
|
|
|
|
When a widget is removed to a container, the container:
|
|
|
|
1) Calls gtk_widget_unparent (widget)
|
|
2) Sets widget->parent to NULL
|
|
3) Queues a resize.
|
|
|
|
Notes:
|
|
|
|
gtk_widget_unparent unrealizes the widget except in the
|
|
special case GTK_IN_REPARENT is set.
|
|
|
|
|
|
At widget creation
|
|
------------------
|
|
|
|
Widgets are created in an unrealized state.
|
|
|
|
1) The widget should allocate and initialize needed data structures
|
|
|
|
|
|
The Realize signal
|
|
------------------
|
|
|
|
When a widget recieves the "realize" signal it should:
|
|
|
|
NO_WINDOW widgets: (probably OK to use default handler)
|
|
|
|
1) set the realized flag
|
|
2) set widget->window
|
|
widget->window = gtk_widget_get_parent_window (widget);
|
|
gdk_window_ref (widget->window);
|
|
3) attach the widget's style
|
|
|
|
widget->style = gtk_style_attach (widget->style, widget->window);
|
|
|
|
widget with window(s)
|
|
|
|
1) set the REALIZED flag
|
|
2) create windows with the parent obtained from
|
|
gtk_widget_get_parent_window (widget);
|
|
3) attach the widget's style
|
|
4) set the background color for the new window based on the style
|
|
|
|
The Map signal
|
|
--------------
|
|
|
|
1) Set the MAPPED flag
|
|
2) If the widget has any windows, gdk_window_show those windows
|
|
3) call gtk_widget_map for all child windows that are
|
|
VISIBLE and !MAPPED.
|
|
3) Do any other functions related to putting the widget onscreen.
|
|
(for instance, showing extra popup windows...)
|
|
|
|
The Unmap signal
|
|
----------------
|
|
|
|
When a widget receives the unmap signal, it must:
|
|
|
|
1) If the widget has a window, gdk_window_hide that window,
|
|
2) If the widget does not have a window, unmap all child widgets
|
|
3) Do any other functions related to taking the widget offscreen
|
|
(for instance, removing popup windows...)
|
|
3) Unset GTK_MAPPED
|
|
|
|
|
|
The Unrealize signal
|
|
--------------------
|
|
|
|
When a widget receives the unrealize signal, it must
|
|
|
|
1) For any windows other than widget->window do:
|
|
|
|
gdk_window_set_user_data (window, NULL);
|
|
gdk_window_destroy (window);
|
|
|
|
2) Call the parent's unrealize handler
|
|
|
|
|
|
The Widget class unrealize handler will take care of unrealizing
|
|
all children if necessary. [should this be made consistent with
|
|
unmap???]
|
|
|
|
|
|
The Destroy Signal
|
|
------------------
|
|
|
|
Commentary:
|
|
|
|
The destroy signal probably shouldn't exist at all. A widget
|
|
should merely be unrealized and removed from its parent
|
|
when the user calls gtk_widget_destroy or a GDK_DESTROY event
|
|
is received. However, a large body of code depends on
|
|
getting a definitive signal when a widget goes away.
|
|
|
|
That could be put in the finalization step, but, especially
|
|
with language bindings, the cleanup step may need to refer
|
|
back to the widget. (To use gtk_widget_get_data, for instance)
|
|
If it does so via a pointer in a closure (natural for
|
|
Scheme, or Perl), then the finalization procedure will never
|
|
be called.
|
|
|
|
Also, if we made that the finalization step, we would have
|
|
to propagate the GDK_DESTROY event in any case, since it is
|
|
at that point at which user-visible actions need to be taken.
|
|
|
|
|
|
When a widget receives the destroy signal, it must:
|
|
|
|
1) If the widget "owns" any widgets other than its child
|
|
widgets, (for instance popup windows) it should
|
|
call gtk_widget_destroy () for them.
|
|
|
|
2) Call the parent class's destroy handler.
|
|
|
|
|
|
The "destroy" signal will only be received once. A widget
|
|
will never receive any other signals after the destroy
|
|
signal (but see the sectionalize on "Finalize" below)
|
|
|
|
The widget must handle calls to all publically accessible
|
|
functions in an innocuous manner even after a "destroy"
|
|
signal. (A widget can assume that it will not be realized
|
|
after a "destroy" signal is received, which may simplify
|
|
handling this requirement)
|
|
|
|
|
|
The Finalize Pseudo-signal
|
|
--------------------------
|
|
|
|
The finalize pseudo-signal is received after all references
|
|
to the widget have been removed. The finalize callback
|
|
cannot make any GTK calls with the widget as a parameter.
|
|
|
|
1) Free any memory allocated by the widget. (But _not_
|
|
the widget structure itself.
|
|
|
|
2) Call the parent class's finalize signal
|
|
|
|
|
|
A note on chaining "destroy" signals and finalize signals:
|
|
---------------------------------------------------------
|
|
|
|
This is done by code like:
|
|
|
|
if (GTK_OBJECT_CLASS (parent_class)->destroy)
|
|
(* GTK_OBJECT_CLASS (parent_class)->destroy) (object);
|
|
|
|
It may not be completely obvious why this works. Note
|
|
that parent_class is a static variable on a per-class
|
|
basis. So say: we have
|
|
|
|
GtkFoo <- GtkBar <- GtkWidget <-GtkObject
|
|
|
|
And that Foo, Widget, and Object all have destructors, but
|
|
not Bar.
|
|
|
|
Then gtk_foo_destroy will call gtk_widget_destroy (because
|
|
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.
|