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 "expose_event" signal to handle redrawing the
  39     contents of the 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 expose_event_callback (GdkWidget *widget, GdkEventExpose *event, gpointer data)
  57 {
  58   gdk_draw_arc (widget->window,
  59                 widget->style->fg_gc[GTK_WIDGET_STATE (widget)],
  60                 TRUE,
  61                 0, 0, widget->allocation.width, widget->allocation.height,
  62                 0, 64 * 360);
  63
  64   return TRUE;
  65 }
  66 [...]
  67   GtkWidget *drawing_area = gtk_drawing_area_new (<!>);
  68   gtk_widget_set_size_request (drawing_area, 100, 100);
  69   g_signal_connect (G_OBJECT (drawing_area), "expose_event",
  70                     G_CALLBACK (expose_event_callback), NULL);
  71 </programlisting>
  72 </example>
  73
  74 <para>
  75 Expose events are normally delivered when a drawing area first comes
  76 onscreen, or when it's covered by another window and then uncovered
  77 (exposed). You can also force an expose event by adding to the "damage
  78 region" of the drawing area's window; gtk_widget_queue_draw_area() and
  79 gdk_window_invalidate_rect() are equally good ways to do this. You'll
  80 then get an expose event for the invalid region.
  81 </para>
  82
  83 <para>
  84 To receive mouse events on a drawing area, you will need to enable
  85 them with gtk_widget_add_events(). To receive keyboard events,
  86 you will need to set the #GTK_CAN_FOCUS flag on the drawing area, and
  87 should probably draw some user-visible indication that the drawing
  88 area is focused. See gtk_paint_focus() for one way to draw focus.
  89 </para>
  90
  91 <!-- ##### SECTION See_Also ##### -->
  92 <para>
  93
  94 </para>
  95
  96 <!-- ##### STRUCT GtkDrawingArea ##### -->
  97 <para>
  98 The #GtkDrawingArea struct contains private data only, and
  99 should be accessed using the functions below.
 100 </para>
 101
 102
 103 <!-- ##### FUNCTION gtk_drawing_area_new ##### -->
 104 <para>
 105 Creates a new drawing area.
 106 </para>
 107
 108 @Returns: a new #GtkDrawingArea
 109
 110
 111 <!-- ##### FUNCTION gtk_drawing_area_size ##### -->
 112 <para>
 113 Sets the size that the drawing area will request
 114 in response to a "size_request" signal. The
 115 drawing area may actually be allocated a size
 116 larger than this depending on how it is packed
 117 within the enclosing containers.
 118 </para>
 119
 120 @darea: a #GtkDrawingArea.
 121 @width: the width to request.
 122 @height: the height to request.
 123
 124