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 The #GtkDrawingArea widget is used for creating custom
  10 user interface elements. After creating a drawing
  11 area, the application may want to connect to:
  12 <itemizedlist>
  13   <listitem>
  14     <para>
  15     Mouse and button press signals to respond to input from
  16     the user.
  17     </para>
  18   </listitem>
  19   <listitem>
  20     <para>
  21     The "realize" signal to take any necessary actions
  22     when the widget
  23     </para>
  24   </listitem>
  25   <listitem>
  26     <para>
  27     The "size_allocate" signal to take any necessary actions
  28     when the widget changes size.
  29     </para>
  30   </listitem>
  31   <listitem>
  32     <para>
  33     The "expose_event" signal to handle redrawing the
  34     contents of the widget.
  35     </para>
  36   </listitem>
  37 </itemizedlist>
  38 As a convenience, the #GtkDrawingArea widget synthesizes
  39 a "configure_event" when the widget is realized
  40 and any time the size of a widget changes when it
  41 is realized. It often suffices to connect to this
  42 signal instead of "realize" and "size_allocate".
  43 </para>
  44 <para>
  45 The following code portion demonstrates using a drawing
  46 area to implement a widget that draws a circle.
  47 As this example demonstrates, an expose handler should
  48 draw only the pixels within the requested area and
  49 should draw or clear all these pixels.
  50 </para>
  51 <example>
  52 <title>Simple <structname>GtkDrawingArea</structname> usage.</title>
  53 <programlisting>
  54 gboolean
  55 expose_event (GdkWidget *widget, GdkEventExpose *event, gpointer data)
  56 {
  57   gdk_window_clear_area (widget->window,
  58                          event->area.x, event->area.y,
  59                          event->area.width, event->area.height);
  60   gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state],
  61                              &amp;event->area);
  62   gdk_draw_arc (widget->window,
  63                 widget->style->fg_gc[widget->state],
  64                 TRUE,
  65                 0, 0, widget->allocation.width, widget->allocation.height,
  66                 0, 64 * 360);
  67   gdk_gc_set_clip_rectangle (widget->style->fg_gc[widget->state],
  68                              NULL);
  69
  70   return TRUE;
  71 }
  72 [...]
  73   GtkWidget *drawing_area = gtk_drawing_area_new (<!>);
  74   gtk_signal_connect (GTK_OBJECT (drawing_area),
  75 </programlisting>
  76 </example>
  77
  78 <!-- ##### SECTION See_Also ##### -->
  79 <para>
  80
  81 </para>
  82
  83 <!-- ##### STRUCT GtkDrawingArea ##### -->
  84 <para>
  85 The #GtkDrawingArea struct contains private data only, and
  86 should be accessed using the functions below.
  87 </para>
  88
  89
  90 <!-- ##### FUNCTION gtk_drawing_area_new ##### -->
  91 <para>
  92 Creates a new drawing area.
  93 </para>
  94
  95 @Returns: a new #GtkDrawingArea
  96
  97
  98 <!-- ##### FUNCTION gtk_drawing_area_size ##### -->
  99 <para>
 100 Sets the size that the drawing area will request
 101 in response to a "size_request" signal. The
 102 drawing area may actually be allocated a size
 103 larger than this depending on how it is packed
 104 within the enclosing containers.
 105 </para>
 106
 107 @darea: a #GtkDrawingArea.
 108 @width: the width to request.
 109 @height: the height to request.
 110
 111