Main outline:
- Owen Taylor <owt1@cornell.edu>
- 98/02/03
+ 1998/02/03
Flag descriptions:
- Tim Janik <timj@gimp.org>
- 98/02/04
+ 1998/02/04
I. Flags
--------
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.
+ prevention of multiple destruction invocations.
GTK_FLOATING:
This flag reflects the fact that the holder of the
GtkWidget, public flags:
GTK_TOPLEVEL:
- Widgets witghout a real parent, as there are GtkWindows and
+ 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 parents GdkWindow.
+ on the parent's GdkWindow.
GTK_REALIZED:
Set by gtk_widget_realize, unset by gtk_widget_unrealize.
Set by gtk_widget_hide.
Implies that a widget is not onscreen, therefore !GTK_MAPPED.
+GTK_CHILD_VISIBLE
+ Set by gtk_widget_set_child_visible, and if FALSE indicates that
+ the widget should not be mapped even if the parent is mapped
+ and visible. Containers like GtkNotebook use this flag.
+ A private flag, not a public flag, so if you need to check
+ this flag, you should call gtk_widget_get_child_visible().
+ (Should be very rarely necessary.)
+
GTK_SENSITIVE:
Set and unset by gtk_widget_set_sensitive.
- The sensitivity of a widget determines wether it will receive
+ 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.
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.
+ 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 bve unset once another widget
+ 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 defalt widget.
+ counterparts, but for the default widget.
GTK_HAS_GRAB:
Set by gtk_grab_add, unset by gtk_grab_remove.
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.
-
+ 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
+ which 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
+ be. it only requires a few checks for GTK_WIDGET_REALIZED 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
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
+ Remark: this flag is also used internally by gtkwindow.c during
the evaluation of resizing worthy widgets.
GTK_LEAVE_PENDING:
to have this flag set to prevent natural unrealization on the
process of getting unparented.
+GTK_NEED_REQUEST:
+ This flag is set if the widget doesn't have an up to date
+ requisition. If this flag is set, we must actually emit ::size-request
+ when gtk_widget_size_request() is called. Otherwise, we can
+ simply widget->requisition. We keep track of this all the time
+ however, widgets with this flag set are only added to the resize
+ queue if they are viewable.
+
+GTK_NEED_ALLOCATION:
+ This flag is set if the widget doesn't have an up to date
+ allocation. If this flag is set, we must actually emit ::size-allocate
+ when gtk_widget_size_allocate() is called, even if the new allocation
+ is the same as the current allocation.
+
Related Macros:
GTK_WIDGET_DRAWABLE:
- This macro examines wether a widget is flagged as GTK_WIDGET_VISIBLE
+ 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
- wether both the widget and all its parents are in sensitive state.
+ whether both the widget and all its parents are in sensitive state.
II. Invariants:
5) if !GTK_WIDGET_TOPLEVEL (widget):
GTK_WIDGET_MAPPED (widget) => GTK_WIDGET_VISIBLE (widget)
+ => GTK_WIDGET_CHILD_VISIBLE (widget)
=> GTK_WIDGET_REALIZED (widget)
widget->parent && GTK_WIDGET_MAPPED (widget->parent) &&
- GTK_WIDGET_VISIBLE (widget) => GTK_WIDGET_MAPPED (widget)
+ GTK_WIDGET_VISIBLE (widget) && GTK_WIDGET_CHILD_VISIBLE
+ <=> 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),
+ is made in gtkwidget.h, but by 3) and 5),
GTK_WIDGET_MAPPED => GTK_WIDGET_VISIBLE
]
-
+6) GTK_REDRAW_PENDING => GTK_WIDGET_REALIZED
+ GTK_RESIZE_PENDING => "
+ GTK_LEAVE_PENDING => "
+ GTK_RESIZE_NEEDED => "
III. How states are changed:
----------------------------
gtk_widget_realize:
if !GTK_DESTROYED sets GTK_REALIZED
-- Calling gtk_widget_realize when the widget is not a descendent
+- Calling gtk_widget_realize when the widget is not a descendant
of a toplevel is an ERROR.
gtk_container_add (container, widget) [ and container-specific variants ]
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
+ 1) 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)
-
+ 2) calls gtk_widget_set_parent (widget, container)
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.
+ 2) Queues a resize.
Notes:
The Realize signal
------------------
-When a widget recieves the "realize" signal it should:
+When a widget receives 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);
+ g_object_ref (widget->window);
3) attach the widget's style
widget->style = gtk_style_attach (widget->style, widget->window);
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) call gtk_widget_map for all child widgets that are
+ VISIBLE, CHILD_VISIBLE and !MAPPED. (A widget will only
+ be !CHILD_VISIBLE if the container set it that way, so
+ most containers will not have to check this.)
3) Do any other functions related to putting the widget onscreen.
(for instance, showing extra popup windows...)
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
+ 4) Unset GTK_MAPPED
The Unrealize signal
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)
+signal (but see the section on "Finalize" below)
The widget must handle calls to all publically accessible
functions in an innocuous manner even after a "destroy"
projects / ~andy / gtk / blobdiff