gi-gtk4-4.0.12: Gtk 4.x bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.DrawingArea

Contents

- Exported types
- Methods
  - getContentHeight
  - getContentWidth
  - new
  - setContentHeight
  - setContentWidth
  - setDrawFunc
- Properties
  - contentHeight
  - contentWidth
- Signals
  - resize

Description

Allows drawing with cairo.

<picture> <source srcset="drawingarea-dark.png" media="(prefers-color-scheme: dark)"> <img alt="An example GtkDrawingArea" src="drawingarea.png"> </picture>

It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to:

- The Widget::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 DrawingArea::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;

      cairo_arc (cr,
                 width / 2.0, height / 2.0,
                 MIN (width, height) / 2.0,
                 0, 2 * G_PI);

      gtk_widget_get_color (GTK_WIDGET (area),
                            &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 in the Cairo documentation; GDK offers additional API to integrate with Cairo, like `cairoSetSourceRgba` or `cairoSetSourcePixbuf`.

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 `GtkWidget` 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 DrawingAreaResizeCallback = Int32 -> Int32 -> IO ()
- afterDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> ((?self :: a) => DrawingAreaResizeCallback) -> m SignalHandlerId
- onDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> ((?self :: a) => DrawingAreaResizeCallback) -> m SignalHandlerId

# Exported types

newtype DrawingArea Source #

Memory-managed wrapper type.

Constructors

DrawingArea (ManagedPtr DrawingArea) |

#### Instances

Instances details

Eq DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea Methods (==) :: DrawingArea -> DrawingArea -> Bool Source # (/=) :: DrawingArea -> DrawingArea -> Bool Source #
GObject DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea
ManagedPtrNewtype DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea Methods toManagedPtr :: DrawingArea -> ManagedPtr DrawingArea Source #
TypedObject DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea Methods glibType :: IO GType Source #
HasParentTypes DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea
IsGValue (Maybe DrawingArea) Source # | Convert `DrawingArea` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.DrawingArea Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe DrawingArea -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe DrawingArea) Source #
type ParentTypes DrawingArea Source # |
Instance details Defined in GI.Gtk.Objects.DrawingArea type ParentTypes DrawingArea = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

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

Instances details

(GObject o, IsDescendantOf DrawingArea o) => IsDrawingArea o Source # |
Instance details 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

### Click to display all available methods, including inherited ones

Expand

#### Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, 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, updateNextAccessibleSibling, updatePlatformState, updateProperty, updateRelation, updateState, watchClosure.

#### Getters

getAccessibleId, getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getContentHeight, getContentWidth, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getLimitEvents, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, 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

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

## getContentHeight

drawingAreaGetContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a) |
=> a | `self`: a `GtkDrawingArea`
-> m Int32 | Returns: The height requested for content of the drawing area

Retrieves the content height of the `GtkDrawingArea`.

## getContentWidth

drawingAreaGetContentWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a) |
=> a | `self`: a `GtkDrawingArea`
-> m Int32 | Returns: The width requested for content of the drawing area

Retrieves the content width of the `GtkDrawingArea`.

## new

drawingAreaNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m DrawingArea | Returns: a new `GtkDrawingArea`

Creates a new drawing area.

## setContentHeight

drawingAreaSetContentHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a) |
=> a | `self`: a `GtkDrawingArea`
-> 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 Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a) |
=> a | `self`: a `GtkDrawingArea`
-> 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 Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrawingArea a) |
=> a | `self`: a `GtkDrawingArea`
-> 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.

The draw function 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.

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.

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 DrawingAreaResizeCallback Source #

Arguments

= Int32 | `width`: the width of the viewport
-> Int32 | `height`: the height of the viewport
-> IO () |

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 -> ((?self :: 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

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDrawingAreaResize :: (IsDrawingArea a, MonadIO m) => a -> ((?self :: 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