diff options
| -rw-r--r-- | docs/reference/gtk/tmpl/.gitignore | 1 | ||||
| -rw-r--r-- | docs/reference/gtk/tmpl/gtkdrawingarea.sgml | 140 | ||||
| -rw-r--r-- | gtk/gtkdrawingarea.c | 116 | ||||
| -rw-r--r-- | gtk/gtkdrawingarea.h | 4 |
4 files changed, 114 insertions, 147 deletions
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index c3acd48305..f87e12ff6a 100644 --- a/docs/reference/gtk/tmpl/.gitignore +++ b/docs/reference/gtk/tmpl/.gitignore @@ -17,6 +17,7 @@ gtkcombobox.sgml gtkcomboboxentry.sgml gtkcontainer.sgml gtkdialog.sgml +gtkdrawingarea.sgml gtkeditable.sgml gtkentry.sgml gtkentrybuffer.sgml diff --git a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml b/docs/reference/gtk/tmpl/gtkdrawingarea.sgml deleted file mode 100644 index 0986d02d1b..0000000000 --- a/docs/reference/gtk/tmpl/gtkdrawingarea.sgml +++ /dev/null @@ -1,140 +0,0 @@ -<!-- ##### SECTION Title ##### --> -GtkDrawingArea - -<!-- ##### SECTION Short_Description ##### --> -A widget for custom user interface elements - -<!-- ##### SECTION Long_Description ##### --> -<para> - -The #GtkDrawingArea widget is used for creating custom user interface -elements. It's essentially a blank widget; you can draw on -<literal>widget->window</literal>. After creating a drawing area, -the application may want to connect to: - -<itemizedlist> - <listitem> - <para> - Mouse and button press signals to respond to input from - the user. (Use gtk_widget_add_events() to enable events - you wish to receive.) - </para> - </listitem> - <listitem> - <para> - The "realize" signal to take any necessary actions - when the widget is instantiated on a particular display. - (Create GDK resources in response to this signal.) - </para> - </listitem> - <listitem> - <para> - The "configure_event" signal to take any necessary actions - when the widget changes size. - </para> - </listitem> - <listitem> - <para> - The "draw" signal to handle redrawing the contents of the - widget. - </para> - </listitem> -</itemizedlist> -</para> -<para> -The following code portion demonstrates using a drawing -area to display a circle in the normal widget foreground -color. -Note that GDK automatically clears the exposed area -to the background color before sending the expose event, and -that drawing is implicitly clipped to the exposed area. -</para> -<example> -<title>Simple <structname>GtkDrawingArea</structname> usage.</title> -<programlisting> -gboolean -draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) -{ - guint width, height; - GdkRGBA color; - - width = gtk_widget_get_allocated_width (widget); - height = gtk_widget_get_allocated_height (widget); - cairo_arc (cr, - width / 2.0, height / 2.0, - MIN (width, height) / 2.0, - 0, 2 * G_PI); - - gtk_style_context_get_color (gtk_widget_get_style_context (widget), - 0, - &color); - gdk_cairo_set_source_rgba (cr, &color); - - cairo_fill (cr); - - return FALSE; -} - - /* ... */ - - GtkWidget *drawing_area = gtk_drawing_area_new (<!-- -->); - gtk_widget_set_size_request (drawing_area, 100, 100); - g_signal_connect (G_OBJECT (drawing_area), "draw", - G_CALLBACK (draw_callback), NULL); -</programlisting> -</example> - -<para> -Draw signals are normally delivered when a drawing area first comes -onscreen, or when it's covered by another window and then uncovered. -You can also force a redraw by adding to the "damage region" of the -drawing area's window; use gtk_widget_queue_draw_area() to do this. -You'll then get a draw event for the invalid region. -</para> - -<para> -The available routines for drawing are documented on the <link -linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> page -and the cairo documentation. -</para> - -<para> -To receive mouse events on a drawing area, you will need to enable -them with gtk_widget_add_events(). To receive keyboard events, you -will need to set the #GTK_CAN_FOCUS flag on the drawing area, and -should probably draw some user-visible indication that the drawing -area is focused. Use the GTK_HAS_FOCUS() macro in your expose event -handler to decide whether to draw the focus indicator. See -gtk_paint_focus() for one way to draw focus. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -Sometimes #GtkImage is a useful alternative to a drawing area. -You can put a #GdkPixmap in the #GtkImage and draw to the #GdkPixmap, -calling gtk_widget_queue_draw() on the #GtkImage when you want to -refresh to the screen. -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT GtkDrawingArea ##### --> -<para> -The #GtkDrawingArea struct contains private data only, and -should be accessed using the functions below. -</para> - - -<!-- ##### FUNCTION gtk_drawing_area_new ##### --> -<para> -Creates a new drawing area. -</para> - -@void: -@Returns: a new #GtkDrawingArea - - diff --git a/gtk/gtkdrawingarea.c b/gtk/gtkdrawingarea.c index 544d23cdf0..6f8272b154 100644 --- a/gtk/gtkdrawingarea.c +++ b/gtk/gtkdrawingarea.c @@ -21,7 +21,7 @@ * Modified by the GTK+ Team and others 1997-2000. See the AUTHORS * file for a list of people on the GTK+ Team. See the ChangeLog * files for a list of changes. These files are distributed with - * GTK+ at ftp://ftp.gtk.org/pub/gtk/. + * GTK+ at ftp://ftp.gtk.org/pub/gtk/. */ #include "config.h" @@ -29,9 +29,109 @@ #include "gtkintl.h" +/** + * SECTION:gtkdrawingarea + * @Short_description: A widget for custom user interface elements + * @Title: GtkDrawingArea + * @See_also: #GtkImage + * + * The #GtkDrawingArea widget is used for creating custom user interface + * elements. It's essentially a blank widget; you can draw on it. After + * creating a drawing area, the application may want to connect to: + * + * <itemizedlist> + * <listitem> + * <para> + * Mouse and button press signals to respond to input from + * the user. (Use gtk_widget_add_events() to enable events + * you wish to receive.) + * </para> + * </listitem> + * <listitem> + * <para> + * The #GtkWidget::realize signal to take any necessary actions + * when the widget is instantiated on a particular display. + * (Create GDK resources in response to this signal.) + * </para> + * </listitem> + * <listitem> + * <para> + * The #GtkWidget::configure-event signal to take any necessary + * actions when the widget changes size. + * </para> + * </listitem> + * <listitem> + * <para> + * The #GtkWidget::draw signal to handle redrawing the + * contents of the widget. + * </para> + * </listitem> + * </itemizedlist> + * + * The following code portion demonstrates using a drawing + * area to display a circle in the normal widget foreground + * color. + * + * Note that GDK automatically clears the exposed area to the + * background color before sending the expose event, and that + * drawing is implicitly clipped to the exposed area. + * + * <example> + * <title>Simple GtkDrawingArea usage</title> + * <programlisting> + * gboolean + * draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data) + * { + * guint width, height; + * GdkRGBA color; + * + * width = gtk_widget_get_allocated_width (widget); + * height = gtk_widget_get_allocated_height (widget); + * cairo_arc (cr, + * width / 2.0, height / 2.0, + * MIN (width, height) / 2.0, + * 0, 2 * G_PI); + * + * gtk_style_context_get_color (gtk_widget_get_style_context (widget), + * 0, + * &color); + * gdk_cairo_set_source_rgba (cr, &color); + * + * cairo_fill (cr); + * + * return FALSE; + * } + * [...] + * GtkWidget *drawing_area = gtk_drawing_area_new (<!-- -->); + * gtk_widget_set_size_request (drawing_area, 100, 100); + * g_signal_connect (G_OBJECT (drawing_area), "draw", + * G_CALLBACK (draw_callback), NULL); + * </programlisting> + * </example> + * + * Draw signals are normally delivered when a drawing area first comes + * onscreen, or when it's covered by another window and then uncovered. + * You can also force an expose event by adding to the "damage region" + * of the drawing area's window; gtk_widget_queue_draw_area() and + * gdk_window_invalidate_rect() are equally good ways to do this. + * You'll then get a draw signal for the invalid region. + * + * The available routines for drawing are documented on the <link + * linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> page + * and the cairo documentation. + * + * To receive mouse events on a drawing area, you will need to enable + * them with gtk_widget_add_events(). To receive keyboard events, you + * will need to set the #GTK_CAN_FOCUS flag on the drawing area, and + * should probably draw some user-visible indication that the drawing + * area is focused. Use the GTK_HAS_FOCUS() macro in your expose event + * handler to decide whether to draw the focus indicator. See + * gtk_paint_focus() for one way to draw focus. + */ + static void gtk_drawing_area_realize (GtkWidget *widget); static void gtk_drawing_area_size_allocate (GtkWidget *widget, - GtkAllocation *allocation); + GtkAllocation *allocation); static void gtk_drawing_area_send_configure (GtkDrawingArea *darea); G_DEFINE_TYPE (GtkDrawingArea, gtk_drawing_area, GTK_TYPE_WIDGET) @@ -50,7 +150,13 @@ gtk_drawing_area_init (GtkDrawingArea *darea) { } - +/** + * gtk_drawing_area_new: + * + * Creates a new drawing area. + * + * Returns: a new #GtkDrawingArea + */ GtkWidget* gtk_drawing_area_new (void) { @@ -101,7 +207,7 @@ gtk_drawing_area_realize (GtkWidget *widget) static void gtk_drawing_area_size_allocate (GtkWidget *widget, - GtkAllocation *allocation) + GtkAllocation *allocation) { g_return_if_fail (GTK_IS_DRAWING_AREA (widget)); g_return_if_fail (allocation != NULL); @@ -135,7 +241,7 @@ gtk_drawing_area_send_configure (GtkDrawingArea *darea) event->configure.y = allocation.y; event->configure.width = allocation.width; event->configure.height = allocation.height; - + gtk_widget_event (widget, event); gdk_event_free (event); } diff --git a/gtk/gtkdrawingarea.h b/gtk/gtkdrawingarea.h index c40bc934a1..20365831b2 100644 --- a/gtk/gtkdrawingarea.h +++ b/gtk/gtkdrawingarea.h @@ -68,8 +68,8 @@ struct _GtkDrawingAreaClass }; -GType gtk_drawing_area_get_type (void) G_GNUC_CONST; -GtkWidget* gtk_drawing_area_new (void); +GType gtk_drawing_area_get_type (void) G_GNUC_CONST; +GtkWidget* gtk_drawing_area_new (void); G_END_DECLS |