Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
The DrawingArea
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:
- 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.)
- The resize signal to take any necessary actions when the widget changes size.
- Call
drawingAreaSetDrawFunc
to handle redrawing the contents of the widget.
The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color.
Simple GtkDrawingArea usage
C code
void draw_function (GtkDrawingArea *area, cairo_t *cr, int width, int height, gpointer data) { GdkRGBA color; GtkStyleContext *context; context = gtk_widget_get_style_context (GTK_WIDGET (area)); cairo_arc (cr, width / 2.0, height / 2.0, MIN (width, height) / 2.0, 0, 2 * G_PI); gtk_style_context_get_color (context, &color); gdk_cairo_set_source_rgba (cr, &color); cairo_fill (cr); } void main (int argc, char **argv) { gtk_init (); GtkWidget *area = gtk_drawing_area_new (); gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area), draw_function, NULL, NULL); }
The draw function is normally called 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 using widgetQueueDraw
.
This will cause the drawing area to call the draw function again.
The available routines for drawing are documented on the [GDK Drawing Primitives][gdk3-Cairo-Interaction] 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 “can-focus” property on the drawing area, and you
should probably draw some user-visible indication that the drawing
area is focused. Use widgetHasFocus
in your expose event
handler to decide whether to draw the focus indicator. See
renderFocus
for one way to draw focus.
If you need more complex control over your widget, you should consider
creating your own Widget
subclass.
Synopsis
- newtype DrawingArea = DrawingArea (ManagedPtr DrawingArea)
- class (GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o
- toDrawingArea :: (MonadIO m, IsDrawingArea o) => o -> m DrawingArea
- drawingAreaGetContentHeight :: (HasCallStack, MonadIO m, IsDrawingArea a) => a -> m Int32
- drawingAreaGetContentWidth :: (HasCallStack, MonadIO m, IsDrawingArea a) => a -> m Int32
- drawingAreaNew :: (HasCallStack, MonadIO m) => m DrawingArea
- drawingAreaSetContentHeight :: (HasCallStack, MonadIO m, IsDrawingArea a) => a -> Int32 -> m ()
- drawingAreaSetContentWidth :: (HasCallStack, MonadIO m, IsDrawingArea a) => a -> Int32 -> m ()
- drawingAreaSetDrawFunc :: (HasCallStack, MonadIO m, IsDrawingArea a) => a -> Maybe DrawingAreaDrawFunc -> m ()
- constructDrawingAreaContentHeight :: (IsDrawingArea o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getDrawingAreaContentHeight :: (MonadIO m, IsDrawingArea o) => o -> m Int32
- setDrawingAreaContentHeight :: (MonadIO m, IsDrawingArea o) => o -> Int32 -> m ()
- constructDrawingAreaContentWidth :: (IsDrawingArea o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getDrawingAreaContentWidth :: (MonadIO m, IsDrawingArea o) => o -> m Int32
- setDrawingAreaContentWidth :: (MonadIO m, IsDrawingArea o) => o -> Int32 -> m ()
- type C_DrawingAreaResizeCallback = Ptr () -> Int32 -> Int32 -> Ptr () -> IO ()
- type DrawingAreaResizeCallback = Int32 -> Int32 -> IO ()
- afterDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> DrawingAreaResizeCallback -> m SignalHandlerId
- genClosure_DrawingAreaResize :: MonadIO m => DrawingAreaResizeCallback -> m (GClosure C_DrawingAreaResizeCallback)
- mk_DrawingAreaResizeCallback :: C_DrawingAreaResizeCallback -> IO (FunPtr C_DrawingAreaResizeCallback)
- noDrawingAreaResizeCallback :: Maybe DrawingAreaResizeCallback
- onDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> DrawingAreaResizeCallback -> m SignalHandlerId
- wrap_DrawingAreaResizeCallback :: DrawingAreaResizeCallback -> C_DrawingAreaResizeCallback
Exported types
newtype DrawingArea Source #
Memory-managed wrapper type.
Instances
Eq DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea (==) :: DrawingArea -> DrawingArea -> Bool # (/=) :: DrawingArea -> DrawingArea -> Bool # | |
IsGValue DrawingArea Source # | Convert |
Defined in GI.Gtk.Objects.DrawingArea toGValue :: DrawingArea -> IO GValue # fromGValue :: GValue -> IO DrawingArea # | |
ManagedPtrNewtype DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea | |
TypedObject DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea | |
GObject DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea | |
HasParentTypes DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea | |
type ParentTypes DrawingArea Source # | |
Defined in GI.Gtk.Objects.DrawingArea |
class (GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o Source #
Type class for types which can be safely cast to DrawingArea
, for instance with toDrawingArea
.
Instances
(GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o Source # | |
Defined in GI.Gtk.Objects.DrawingArea |
toDrawingArea :: (MonadIO m, IsDrawingArea o) => o -> m DrawingArea Source #
Cast to DrawingArea
, for types for which this is known to be safe. For general casts, use castTo
.
Methods
Overloaded methods
getContentHeight
drawingAreaGetContentHeight Source #
:: (HasCallStack, MonadIO m, IsDrawingArea a) | |
=> a |
|
-> m Int32 | Returns: The height requested for content of the drawing area |
Retrieves the value previously set via drawingAreaSetContentHeight
.
getContentWidth
drawingAreaGetContentWidth Source #
:: (HasCallStack, MonadIO m, IsDrawingArea a) | |
=> a |
|
-> m Int32 | Returns: The width requested for content of the drawing area |
Retrieves the value previously set via drawingAreaSetContentWidth
.
new
:: (HasCallStack, MonadIO m) | |
=> m DrawingArea | Returns: a new |
Creates a new drawing area.
setContentHeight
drawingAreaSetContentHeight Source #
:: (HasCallStack, MonadIO m, IsDrawingArea a) | |
=> a |
|
-> Int32 |
|
-> m () |
Sets the desired height of the contents of the drawing area. Note that
because widgets may be allocated larger sizes than they requested, it is
possible that the actual height passed to your draw function is larger
than the height set here. You can use widgetSetValign
to avoid
that.
If the height is set to 0 (the default), the drawing area may disappear.
setContentWidth
drawingAreaSetContentWidth Source #
:: (HasCallStack, MonadIO m, IsDrawingArea a) | |
=> a |
|
-> Int32 |
|
-> m () |
Sets the desired width of the contents of the drawing area. Note that
because widgets may be allocated larger sizes than they requested, it is
possible that the actual width passed to your draw function is larger
than the width set here. You can use widgetSetHalign
to avoid
that.
If the width is set to 0 (the default), the drawing area may disappear.
setDrawFunc
drawingAreaSetDrawFunc Source #
:: (HasCallStack, MonadIO m, IsDrawingArea a) | |
=> a |
|
-> Maybe DrawingAreaDrawFunc |
|
-> m () |
Setting a draw function is the main thing you want to do when using a drawing area. It is called whenever GTK needs to draw the contents of the drawing area to the screen.
The draw function will be called during the drawing stage of GTK. In the drawing stage it is not allowed to change properties of any GTK widgets or call any functions that would cause any properties to be changed. You should restrict yourself exclusively to drawing your contents in the draw function.
If what you are drawing does change, call widgetQueueDraw
on the
drawing area. This will cause a redraw and will call drawFunc
again.
Properties
contentHeight
The content height. See drawingAreaSetContentHeight
for details.
constructDrawingAreaContentHeight :: (IsDrawingArea o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “content-height
” property. This is rarely needed directly, but it is used by new
.
getDrawingAreaContentHeight :: (MonadIO m, IsDrawingArea o) => o -> m Int32 Source #
Get the value of the “content-height
” property.
When overloading is enabled, this is equivalent to
get
drawingArea #contentHeight
setDrawingAreaContentHeight :: (MonadIO m, IsDrawingArea o) => o -> Int32 -> m () Source #
Set the value of the “content-height
” property.
When overloading is enabled, this is equivalent to
set
drawingArea [ #contentHeight:=
value ]
contentWidth
The content width. See drawingAreaSetContentWidth
for details.
constructDrawingAreaContentWidth :: (IsDrawingArea o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “content-width
” property. This is rarely needed directly, but it is used by new
.
getDrawingAreaContentWidth :: (MonadIO m, IsDrawingArea o) => o -> m Int32 Source #
Get the value of the “content-width
” property.
When overloading is enabled, this is equivalent to
get
drawingArea #contentWidth
setDrawingAreaContentWidth :: (MonadIO m, IsDrawingArea o) => o -> Int32 -> m () Source #
Set the value of the “content-width
” property.
When overloading is enabled, this is equivalent to
set
drawingArea [ #contentWidth:=
value ]
Signals
resize
type C_DrawingAreaResizeCallback = Ptr () -> Int32 -> Int32 -> Ptr () -> IO () Source #
Type for the callback on the (unwrapped) C side.
type DrawingAreaResizeCallback Source #
The resize signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, like for instance a backing surface.
afterDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> DrawingAreaResizeCallback -> m SignalHandlerId Source #
Connect a signal handler for the resize signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
drawingArea #resize callback
genClosure_DrawingAreaResize :: MonadIO m => DrawingAreaResizeCallback -> m (GClosure C_DrawingAreaResizeCallback) Source #
Wrap the callback into a GClosure
.
mk_DrawingAreaResizeCallback :: C_DrawingAreaResizeCallback -> IO (FunPtr C_DrawingAreaResizeCallback) Source #
Generate a function pointer callable from C code, from a C_DrawingAreaResizeCallback
.
noDrawingAreaResizeCallback :: Maybe DrawingAreaResizeCallback Source #
A convenience synonym for
.Nothing
:: Maybe
DrawingAreaResizeCallback
onDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> DrawingAreaResizeCallback -> m SignalHandlerId Source #
Connect a signal handler for the resize signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
drawingArea #resize callback