forked from AuroraMiddleware/gtk
140 lines
4.2 KiB
Plaintext
140 lines
4.2 KiB
Plaintext
<!-- ##### 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 "expose_event" 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
|
|
expose_event_callback (GtkWidget *widget, GdkEventExpose *event, gpointer data)
|
|
{
|
|
gdk_draw_arc (widget->window,
|
|
widget->style->fg_gc[GTK_WIDGET_STATE (widget)],
|
|
TRUE,
|
|
0, 0, widget->allocation.width, widget->allocation.height,
|
|
0, 64 * 360);
|
|
|
|
return TRUE;
|
|
}
|
|
[...]
|
|
GtkWidget *drawing_area = gtk_drawing_area_new (<!-- -->);
|
|
gtk_widget_set_size_request (drawing_area, 100, 100);
|
|
g_signal_connect (G_OBJECT (drawing_area), "expose_event",
|
|
G_CALLBACK (expose_event_callback), NULL);
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Expose events are normally delivered when a drawing area first comes
|
|
onscreen, or when it's covered by another window and then uncovered
|
|
(exposed). 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 an expose event for the invalid region.
|
|
</para>
|
|
|
|
<para>
|
|
The available routines for drawing are documented on the <link
|
|
linkend="gdk-Drawing-Primitives">GDK Drawing Primitives</link> page.
|
|
See also gdk_pixbuf_render_to_drawable() for drawing a #GdkPixbuf.
|
|
</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 ##### -->
|
|
|
|
|
|
<!-- ##### 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>
|
|
|
|
@Returns: a new #GtkDrawingArea
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_drawing_area_size ##### -->
|
|
<para>
|
|
(Use gtk_widget_set_size_request() instead.)
|
|
Sets the size that the drawing area will request
|
|
in response to a "size_request" signal. The
|
|
drawing area may actually be allocated a size
|
|
larger than this depending on how it is packed
|
|
within the enclosing containers.
|
|
</para>
|
|
|
|
@darea: a #GtkDrawingArea.
|
|
@width: the width to request.
|
|
@height: the height to request.
|
|
|
|
|