From 040865e7e83b18d757b841355593afdad47bd102 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 29 Oct 2008 18:59:40 +0000 Subject: [PATCH] The GTK+ Drawing Model: new chapter for the documentation Signed-off-by: Federico Mena Quintero svn path=/trunk/; revision=21727 --- docs/reference/ChangeLog | 13 + docs/reference/gtk/Makefile.am | 3 + docs/reference/gtk/drawing-model.xml | 587 ++++++++++++++++++ docs/reference/gtk/glossary.xml | 4 +- docs/reference/gtk/gtk-docs.sgml | 1 + .../images/figure-hierarchical-drawing.png | Bin 0 -> 15502 bytes .../gtk/images/figure-windowed-label.png | Bin 0 -> 3501 bytes docs/reference/gtk/tmpl/gtkwidget.sgml | 9 +- 8 files changed, 614 insertions(+), 3 deletions(-) create mode 100644 docs/reference/gtk/drawing-model.xml create mode 100644 docs/reference/gtk/images/figure-hierarchical-drawing.png create mode 100644 docs/reference/gtk/images/figure-windowed-label.png diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 312324c1d6..ae48ef8f8f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,16 @@ +2008-10-29 Federico Mena Quintero + + * gtk/drawing-model.xml: New chapter for "The GTK+ Drawing Model". + + * gtk/Makefile.am (content_files): Add drawing-model.xml. + (HTML_IMAGES): Add a the images for that new chapter. + + * gtk/tmpl/gtkwidget.sgml: Link to the drawing model docs from the + descriptions of GTK_APP_PAINTABLE and GTK_DOUBLE_BUFFERED. + + * gtk/glossary.xml: Link to the drawing model docs on no-window + widgets. + 2008-10-27 Matthias Clasen * gtk/gtk-sections.txt: diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 16155f4dcd..3669707a85 100644 --- a/docs/reference/gtk/Makefile.am +++ b/docs/reference/gtk/Makefile.am @@ -128,6 +128,7 @@ content_files = \ changes-2.0.sgml \ compiling.sgml \ directfb.sgml \ + drawing-model.xml \ glossary.xml \ migrating-checklist.sgml \ migrating-GtkAction.sgml \ @@ -301,6 +302,8 @@ HTML_IMAGES = \ $(srcdir)/images/combo-box.png \ $(srcdir)/images/combo-box-entry.png \ $(srcdir)/images/entry.png \ + $(srcdir)/images/figure-hierarchical-drawing.png \ + $(srcdir)/images/figure-windowed-label.png \ $(srcdir)/images/file-button.png \ $(srcdir)/images/filechooser.png \ $(srcdir)/images/font-button.png \ diff --git a/docs/reference/gtk/drawing-model.xml b/docs/reference/gtk/drawing-model.xml new file mode 100644 index 0000000000..1da700480c --- /dev/null +++ b/docs/reference/gtk/drawing-model.xml @@ -0,0 +1,587 @@ + + The GTK+ Drawing Model + + + This chapter describes the GTK+ drawing model in detail. If you + are interested in the procedure which GTK+ follows to draw its + widgets and windows, you should read this chapter; this will be + useful to know if you decide to implement your own widgets. This + chapter will also clarify the reasons behind the ways certain + things are done in GTK+; for example, why you cannot change the + background color of all widgets with the same method. + + +
+ Overview of the drawing model + + + Programs that run in a windowing system generally create + rectangular regions in the screen called + windows. Traditional windowing systems + do not automatically save the graphical content of windows, and + instead ask client programs to repaint those windows whenever it + is needed. For example, if a window that is stacked below other + windows gets raised to the top, then a client program has to + repaint the area that was previously obscured. When the + windowing system asks a client program to redraw part of a + window, it sends an exposure event to the + program for that window. + + + + Here, "windows" means "rectangular regions with automatic + clipping", instead of "toplevel application windows". Most + windowing systems support nested windows, where the contents of + child windows get clipped by the boundaries of their parents. + Although GTK+ and GDK in particular may run on a windowing + system with no such notion of nested windows, GDK presents the + illusion of being under such a system. A toplevel window may + contain many subwindows and sub-subwindows, for example, one for + the menu bar, one for the document area, one for each scrollbar, + and one for the status bar. In addition, controls that receive + user input, such as clickable buttons, are likely to have their + own subwindows as well. + + + + Generally, the drawing cycle begins when GTK+ receives an + exposure event from the underlying windowing system: if the + user drags a window over another one, the windowing system will + tell the underlying window that it needs to repaint itself. The + drawing cycle can also be initiated when a widget itself decides + that it needs to update its display. For example, when the user + types a character in a GtkEntry + widget, the entry asks GTK+ to queue a redraw operation for + itself. + + + + The following sections describe how GTK+ decides which widgets + need to be repainted, and how widgets work internally in terms + of the resources they use from the windowing system. + + +
+ Window and no-window widgets + + + A GdkWindow + represents a window from the underlying windowing system on which GTK+ + is running. For example, on X11 it corresponds to a + Window; on Win32, it corresponds to a HANDLE. + The windowing system generates events for these windows. The GDK + interface to the windowing system translates such native events into + GdkEvent + structures and sends them on to the GTK layer. In turn, the GTK layer + finds the widget that corresponds to a particular + GdkWindow and emits the corresponding event + signals on that widget. + + + + When the program needs to redraw a region of a + GdkWindow, GDK generates an event of + type GDK_EVENT_EXPOSE + for that window. The GTK+ widget layer in turn finds the + widget that corresponds to that window, and emits the expose-event signal + for that widget. + + + + In principle, each widget could have a + GdkWindow of its own. With such a + scheme, the drawing cycle would be trivial: when GDK notifies + the GTK layer about an exposure event for a + GdkWindow, the GTK layer would simply + emit the expose-event + signal for that widget. The widget's expose event + handler would subsequently repaint the widget. No further + work would be necessary; the windowing system would generate + exposure events for each window that needs it, and then each + corresponding widget would draw itself in turn. + + + + However, in practice it is convenient to have widgets which do + not have a GdkWindow of their own, but + rather share the one from their parent widget. Such widgets + have the GTK_NO_WINDOW widget flag turned on; this + can be tested easily with the GTK_WIDGET_NO_WINDOW() + macro. As such, these are called no-window + widgets. + + + + No-window widgets are useful for various reasons: + + + + + + Some widgets may want the parent's background to show through, even + when they draw on parts of it. For example, consider a theme that + uses textured backgrounds, such as gradients or repeating + patterns. If each widget had its own window, and in turn its own + gradient background, labels would look bad because there would be a + visible break with respect to their surroundings. shows this undesirable effect. + + +
+ Windowed label vs. no-window label + + +
+ + + + + Reducing the number of windows creates less traffic between GTK+ and + the underlying windowing system, especially when getting events. + + + + + + On the other hand, widgets that would benefit from having a "hard" + clipping region may find it more convenient to create their own + windows. Also, widgets which want to receive events resulting from + user interaction may find it convenient to use windows of their own as + well. Widgets may have more than one window if they want to + define different regions for capturing events. + +
+ +
+ Hierarchical drawing + + + When the GTK layer receives an exposure event from GDK, it + finds the widget that corresponds to the window which received + the event. By definition, this corresponds to a widget that + has the GTK_NO_WINDOW flag turned + off (otherwise, the widget wouldn't own + the window!). First this widget paints its background, and + then, if it is a container widget, it tells each of its + GTK_NO_WINDOW children to paint + themselves. This process is applied recursively for all the + GTK_NO_WINDOW descendants of the original + widget. + + + + Note that this process does not get propagated to widgets + which have windows of their own, that is, to widgets which + have the GTK_NO_WINDOW flag turned off. + If such widgets require redrawing, then the windowing system + will already have sent exposure events to their corresponding + windows. As such, there is no need to + propagate the exposure to them on the + GTK+ side. + + + + shows how a simple toplevel window would + paint itself when it contains only GTK_NO_WINDOW descendants: + + + + + The outermost, thick rectangle is a toplevel GtkWindow, + which is not a GTK_NO_WINDOW widget — + as such, it does receive its exposure event as it comes from GDK. + First the GtkWindow would paint its own + background. Then, it would ask its only child to paint itself, + numbered 2. + + + + + The dotted rectangle represents a GtkVBox, which + has been made the sole child of the + GtkWindow. Boxes are just layout + containers that do not paint anything by themselves, so this + GtkVBox would draw nothing, but rather ask + its children to draw themselves. The children are numbered 3 and + 6. + + + + + The thin rectangle is a GtkFrame, + which has two children: a label for the frame, numbered 4, and + another label inside, numbered 5. First the frame would draw its + own beveled box, then ask the frame label and its internal child to + draw themselves. + + + + + The frame label has no children, so it just draws its text: "Frame Label". + + + + + The internal label has no children, so it just draws its text: "This + is some text inside the frame!". + + + + + The dotted rectangle represents a GtkHBox. Again, + this does not draw anything by itself, but rather asks its children + to draw themselves. The children are numbered 7 and 9. + + + + + The thin rectangle is a GtkButton with + a single child, numbered 8. First the button would draw its + beveled box, and then it would ask its child to draw itself. + + + + + This is a text label which has no children, so it just draws its + own text: "Cancel". + + + + + Similar to number 7, this is a button with a single child, numbered + 10. First the button would draw its beveled box, and then it would + ask its child to draw itself. + + + + + Similar to number 8, this is a text label which has no children, + so it just draws its own text: "OK". + + + + + +
+ Hierarchical drawing order + + +
+ + + To avoid the flickering that would result from each widget drawing + itself in turn, GTK+ uses a double-buffering mechanism. The following + sections describe this mechanism in detail. + +
+ +
+ Notes on drawing no-window widgets + + + Remember that the coordinates in a GdkEventExpose are relative to + the GdkWindow that received the event, + not to the widget whose expose-event + handler is being called. If your widget owns the window, then + these coordinates are probably what you expect. However, if + you have a GTK_NO_WINDOW widget that + shares its parent's window, then the event's coordinates will + be offset by your widget's allocation: remember that the + allocation is always relative to the parent + window of the widget, not to the parent + widget itself. + + + + For example, if you have a no-window widget whose allocation + is { x=5, y=6, + width, height }, + then your drawing origin should be at (5, 6), not at + (0, 0). + +
+ +
+ Drawing over child windows + + + When you draw on a GdkWindow, your + drawing gets clipped by any child windows that it may + intersect. Sometimes you need to draw over your child windows + as well; for example, when drawing a drag-handle to resize + something. In this case, turn on the GDK_INCLUDE_INFERIORS + subwindow mode for the GdkGC which you use for + drawing. + +
+
+ +
+ Double buffering + + + When the GTK layer receives an exposure event from GDK, it first finds + the !GTK_NO_WINDOW widget that + corresponds to the event's window. Then, it emits the expose-event signal for that + widget. As described above, that widget will first draw its background, + and then ask each of its GTK_NO_WINDOW children to + draw themselves. + + + + If each of the drawing calls made by each subwidget's + expose-event handler were sent directly to the + windowing system, flicker could result. This is because areas may get + redrawn repeatedly: the background, then decorative frames, then text + labels, etc. To avoid flicker, GTK+ employs a double + buffering system at the GDK level. Widgets normally don't + know that they are drawing to an off-screen buffer; they just issue their + normal drawing commands, and the buffer gets sent to the windowing system + when all drawing operations are done. + + + + + + Two basic functions in GDK form the core of the double-buffering + mechanism: gdk_window_begin_paint_region() + and gdk_window_end_paint(). + The first function tells a GdkWindow to + create a temporary off-screen buffer for drawing. All + subsequent drawing operations to this window get automatically + redirected to that buffer. The second function actually paints + the buffer onto the on-screen window, and frees the buffer. + + +
+ Automatic double buffering + + + It would be inconvenient for all widgets to call + gdk_window_begin_paint_region() and + gdk_window_end_paint() at the beginning + and end of their expose-event handlers. + + + + To make this easier, most GTK+ widgets have the + GTK_DOUBLE_BUFFERED widget flag turned on by + default. When GTK+ encounters such a widget, it automatically + calls gdk_window_begin_paint_region() + before emitting the expose-event signal for the widget, and + then it calls gdk_window_end_paint() + after the signal has been emitted. This is convenient for + most widgets, as they do not need to worry about creating + their own temporary drawing buffers or about calling those + functions. + + + + However, some widgets may prefer to disable this kind of + automatic double buffering and do things on their own. To do + this, turn off the GTK_DOUBLE_BUFFERED + flag in your widget's constructor. + + + + Disabling automatic double buffering + + +static void +my_widget_init (MyWidget *widget) +{ + ... + + GTK_WIDGET_UNSET_FLAGS (widget, GTK_DOUBLE_BUFFERED); + + ... +} + + + + + When is it convenient to disable double buffering? Generally, + this is the case only if your widget gets drawn in such a way + that the different drawing operations do not overlap each + other. For example, this may be the case for a simple image + viewer: it can just draw the image in a single operation. + This would not be the case with a word + processor, since it will need to draw and over-draw the page's + background, then the background for highlighted text, and then + the text itself. + + + + Even if you turn off the + GTK_DOUBLE_BUFFERED flag on a widget, you + can still call + gdk_window_begin_paint_region() and + gdk_window_end_paint() by hand to use + temporary drawing buffers. + +
+
+ +
+ App-paintable widgets + + + Generally, applications use the pre-defined widgets in GTK+ and + they do not draw extra things on top of them (the exception + being GtkDrawingArea). However, + applications may sometimes find it convenient to draw directly + on certain widgets like toplevel windows or event boxes. When + this is the case, GTK+ needs to be told not to overwrite your + drawing afterwards, when the window gets to drawing its default + contents. + + + + GtkWindow and + GtkEventBox are the only two widgets + which will draw their default contents unless you turn on the + GTK_APP_PAINTABLE widget flag. If you turn on + this flag, then they will not draw their contents and let you do + it instead. + + + + The expose-event handler for GtkWindow is + implemented effectively like this: + + + +static gint +gtk_window_expose (GtkWidget *widget, + GdkEventExpose *event) +{ + if (!GTK_WIDGET_APP_PAINTABLE (widget)) + gtk_paint_flat_box (widget->style, widget->window, GTK_STATE_NORMAL, + GTK_SHADOW_NONE, event->area, widget, "base", 0, 0, -1, -1); + + if (GTK_WIDGET_CLASS (gtk_window_parent_class)->expose_event) + return GTK_WIDGET_CLASS (gtk_window_parent_class)->expose_event (widget, event); + + return FALSE; +} + + + + The expose-event handler for GtkEventBox + is implemented in a similar fashion. + + + + Since the expose-event + signal runs user-connected handlers + before the widget's default handler, what + happens is this: + + + + + + Your own expose-event handler gets run. It paints something + on the window or the event box. + + + + + + The widget's default expose-event handler gets run. If + GTK_APP_PAINTABLE is turned off (this + is the default), your drawing will be + overwritten. If that flag is turned on, the + widget will not draw its default contents and preserve your + drawing instead. + + + + + + The expose-event handler for the parent class gets run. + Since both GtkWindow and + GtkEventBox are descendants of + GtkContainer, their no-window + children will be asked to draw themselves recursively, as + described in . + + + + + + Summary of app-paintable widgets + + + Turn on the GTK_APP_PAINTABLE flag if you + intend to draw your own content directly on a + GtkWindow and + GtkEventBox. You seldom need to draw + on top of other widgets, and + GtkDrawingArea ignores this flag, as it + is intended to be drawn on. + + +
+ +
+ TODO + + + + + APP_PAINTABLE: link the flag's documentation to this document. + + + + + DOUBLE_BUFFERED: link the flag's documentation to this document. + + + +
+ + + diff --git a/docs/reference/gtk/glossary.xml b/docs/reference/gtk/glossary.xml index c402b3d660..1dce9c3dfc 100644 --- a/docs/reference/gtk/glossary.xml +++ b/docs/reference/gtk/glossary.xml @@ -197,7 +197,9 @@ draw its contents, but rather shares its parent's. Such a widget has the %GTK_NO_WINDOW flag set, and - can be tested with the GTK_WIDGET_NO_WINDOW() macro. + can be tested with the GTK_WIDGET_NO_WINDOW() macro. See + for a detailed + description of this flag. diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml index de30afe550..e6aa20819c 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -96,6 +96,7 @@ that is, GUI components such as #GtkButton or #GtkTextView. + diff --git a/docs/reference/gtk/images/figure-hierarchical-drawing.png b/docs/reference/gtk/images/figure-hierarchical-drawing.png new file mode 100644 index 0000000000000000000000000000000000000000..a2acbc53d8d49ff65faa4155aae9ad21ad101d98 GIT binary patch literal 15502 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 v@5y%};ln$F$AH^Cyu7$AN3{91{K$|f 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 ZXI6{?Ug$Xxal$uP(h>>}vc#Ue{U3vkOhEtu literal 0 HcmV?d00001 diff --git a/docs/reference/gtk/images/figure-windowed-label.png b/docs/reference/gtk/images/figure-windowed-label.png new file mode 100644 index 0000000000000000000000000000000000000000..74f398cb884405ccb5732b8ea5f4a221cbc2fb66 GIT binary patch literal 3501 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 literal 0 HcmV?d00001 diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index df417d863c..3a7eb60898 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -939,13 +939,18 @@ Tells about certain properties of the widget. @GTK_APP_PAINTABLE: Set and unset by gtk_widget_set_app_paintable(). Must be set on widgets whose window the application directly draws on, - in order to keep GTK+ from overwriting the drawn stuff. + in order to keep GTK+ from overwriting the drawn stuff. See + for a detailed + description of this flag. @GTK_RECEIVES_DEFAULT: The widget when focused will receive the default action and have %GTK_HAS_DEFAULT set even if there is a different widget set as default. @GTK_DOUBLE_BUFFERED: Set and unset by gtk_widget_set_double_buffered(). - Indicates that exposes done on the widget should be double-buffered. + Indicates that exposes done on the widget should be + double-buffered. See for a + detailed discussion of how double-buffering works in GTK+ and + why you may want to disable it for special cases. @GTK_NO_SHOW_ALL: