GI.Gtk.Objects.DrawingArea

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

static 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);
}

int
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);
  return 0;
}

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][gdk4-Cairo-Interaction] page and the cairo documentation.

To receive mouse events on a drawing area, you will need to use event controllers. 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.

If you need more complex control over your widget, you should consider creating your own Widget subclass.

Exported types

newtype DrawingArea

Memory-managed wrapper type.

Constructors

DrawingArea (ManagedPtr DrawingArea)

Instances

Eq DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

Methods

(==) :: DrawingArea -> DrawingArea -> Bool

(/=) :: DrawingArea -> DrawingArea -> Bool

GObject DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

ManagedPtrNewtype DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

Methods

toManagedPtr :: DrawingArea -> ManagedPtr DrawingArea

TypedObject DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

Methods

glibType :: IO GType

HasParentTypes DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

IsGValue (Maybe DrawingArea)

Convert DrawingArea to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.DrawingArea

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe DrawingArea -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe DrawingArea)

type ParentTypes DrawingArea

Defined in GI.Gtk.Objects.DrawingArea

type ParentTypes DrawingArea = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o

Type class for types which can be safely cast to DrawingArea, for instance with toDrawingArea.

Instances

(GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o

Defined in GI.Gtk.Objects.DrawingArea

toDrawingArea :: (MonadIO m, IsDrawingArea o) => o -> m DrawingArea

Cast to DrawingArea, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getContentHeight, getContentWidth, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setCanFocus, setCanTarget, setChildVisible, setContentHeight, setContentWidth, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setDrawFunc, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

getContentHeight

drawingAreaGetContentHeight

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a)

=> a

self: a DrawingArea

-> m Int32

Returns: The height requested for content of the drawing area

Retrieves the value previously set via drawingAreaSetContentHeight.

getContentWidth

drawingAreaGetContentWidth

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a)

=> a

self: a DrawingArea

-> m Int32

Returns: The width requested for content of the drawing area

Retrieves the value previously set via drawingAreaSetContentWidth.

new

drawingAreaNew

Arguments

:: (HasCallStack, MonadIO m)

=> m DrawingArea

Returns: a new DrawingArea

Creates a new drawing area.

setContentHeight

drawingAreaSetContentHeight

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a)

=> a

self: a DrawingArea

-> Int32

height: the height of contents

-> 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

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a)

=> a

self: a DrawingArea

-> Int32

width: the width of contents

-> 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

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a)

=> a

self: a DrawingArea

-> Maybe DrawingAreaDrawFunc

drawFunc: callback that lets you draw the drawing area's contents

-> 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)

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

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 ()

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)

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

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 ()

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 ()

Type for the callback on the (unwrapped) C side.

type DrawingAreaResizeCallback

Arguments

 = Int32

width: the width of the viewport

-> Int32

height: the height of the viewport

-> IO ()

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

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)

Wrap the callback into a GClosure.

mk_DrawingAreaResizeCallback :: C_DrawingAreaResizeCallback -> IO (FunPtr C_DrawingAreaResizeCallback)

Generate a function pointer callable from C code, from a C_DrawingAreaResizeCallback.

noDrawingAreaResizeCallback :: Maybe DrawingAreaResizeCallback

A convenience synonym for Nothing :: Maybe DrawingAreaResizeCallback.

onDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> DrawingAreaResizeCallback -> m SignalHandlerId

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

wrap_DrawingAreaResizeCallback :: DrawingAreaResizeCallback -> C_DrawingAreaResizeCallback

Wrap a DrawingAreaResizeCallback into a C_DrawingAreaResizeCallback.