Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkdrawingarea.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkDrawingArea
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A widget for custom user interface elements
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 The #GtkDrawingArea widget is used for creating custom user interface
  11 elements. It's essentially a blank widget; you can draw on
  12 <literal>widget-&gt;window</literal>. After creating a drawing area,
  13 the application may want to connect to:
  14
  15 <itemizedlist>
  16   <listitem>
  17     <para>
  18     Mouse and button press signals to respond to input from
  19     the user. (Use gtk_widget_add_events() to enable events
  20     you wish to receive.)
  21     </para>
  22   </listitem>
  23   <listitem>
  24     <para>
  25     The "realize" signal to take any necessary actions
  26     when the widget is instantiated on a particular display.
  27     (Create GDK resources in response to this signal.)
  28     </para>
  29   </listitem>
  30   <listitem>
  31     <para>
  32     The "configure_event" signal to take any necessary actions
  33     when the widget changes size.
  34     </para>
  35   </listitem>
  36   <listitem>
  37     <para>
  38     The "draw" signal to handle redrawing the contents of the
  39     widget.
  40     </para>
  41   </listitem>
  42 </itemizedlist>
  43 </para>
  44 <para>
  45 The following code portion demonstrates using a drawing
  46 area to display a circle in the normal widget foreground
  47 color.
  48 Note that GDK automatically clears the exposed area
  49 to the background color before sending the expose event, and
  50 that drawing is implicitly clipped to the exposed area.
  51 </para>
  52 <example>
  53 <title>Simple <structname>GtkDrawingArea</structname> usage.</title>
  54 <programlisting>
  55 gboolean
  56 draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
  57 {
  58   guint width, height;
  59   GdkRGBA color;
  60
  61   width = gtk_widget_get_allocated_width (widget);
  62   height = gtk_widget_get_allocated_height (widget);
  63   cairo_arc (cr,
  64              width / 2.0, height / 2.0,
  65              MIN (width, height) / 2.0,
  66              0, 2 * G_PI);
  67
  68   gtk_style_context_get_color (gtk_widget_get_style_context (widget),
  69                                0,
  70                                &amp;color);
  71   gdk_cairo_set_source_rgba (cr, &amp;color);
  72
  73   cairo_fill (cr);
  74
  75   return FALSE;
  76 }
  77
  78  /* ... */
  79
  80   GtkWidget *drawing_area = gtk_drawing_area_new (<!-- -->);
  81   gtk_widget_set_size_request (drawing_area, 100, 100);
  82   g_signal_connect (G_OBJECT (drawing_area), "draw",
  83                     G_CALLBACK (draw_callback), NULL);
  84 </programlisting>
  85 </example>
  86
  87 <para>
  88 Draw signals are normally delivered when a drawing area first comes
  89 onscreen, or when it's covered by another window and then uncovered.
  90 You can also force a redraw by adding to the "damage region" of the
  91 drawing area's window; use gtk_widget_queue_draw_area() to do this.
  92 You'll then get a draw event for the invalid region.
  93 </para>
  94
  95 <para>
  96 The available routines for drawing are documented on the <link
  97 linkend="gdk3-Cairo-Interaction">GDK Drawing Primitives</link> page
  98 and the cairo documentation.
  99 </para>
 100
 101 <para>
 102 To receive mouse events on a drawing area, you will need to enable
 103 them with gtk_widget_add_events(). To receive keyboard events, you
 104 will need to set the #GTK_CAN_FOCUS flag on the drawing area, and
 105 should probably draw some user-visible indication that the drawing
 106 area is focused. Use the GTK_HAS_FOCUS() macro in your expose event
 107 handler to decide whether to draw the focus indicator. See
 108 gtk_paint_focus() for one way to draw focus.
 109 </para>
 110
 111 <!-- ##### SECTION See_Also ##### -->
 112 <para>
 113 Sometimes #GtkImage is a useful alternative to a drawing area.
 114 You can put a #GdkPixmap in the #GtkImage and draw to the #GdkPixmap,
 115 calling gtk_widget_queue_draw() on the #GtkImage when you want to
 116 refresh to the screen.
 117 </para>
 118
 119 <!-- ##### SECTION Stability_Level ##### -->
 120
 121
 122 <!-- ##### SECTION Image ##### -->
 123
 124
 125 <!-- ##### STRUCT GtkDrawingArea ##### -->
 126 <para>
 127 The #GtkDrawingArea struct contains private data only, and
 128 should be accessed using the functions below.
 129 </para>
 130
 131
 132 <!-- ##### FUNCTION gtk_drawing_area_new ##### -->
 133 <para>
 134 Creates a new drawing area.
 135 </para>
 136
 137 @void:
 138 @Returns: a new #GtkDrawingArea
 139
 140