DrawingAreaProtocol

public protocol DrawingAreaProtocol : WidgetProtocol

GtkDrawingArea is a widget that allows drawing with cairo.

An example GtkDrawingArea

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

The [signalGtk.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 [signalGtk.DrawingArea::resize] signal to take any necessary actions when the widget changes size.
Call [methodGtk.DrawingArea.set_draw_func] 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

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 [methodGtk.Widget.queue_draw]. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented on the GDK Drawing Primitives 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 GtkWidget subclass.

The DrawingAreaProtocol protocol exposes the methods and properties of an underlying GtkDrawingArea instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DrawingArea. Alternatively, use DrawingAreaRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub

ptr
Untyped pointer to the underlying GtkDrawingArea instance.
Declaration
Swift

var ptr: UnsafeMutableRawPointer! { get }
Show on GitHub
drawing_area_ptr Default implementation
Typed pointer to the underlying GtkDrawingArea instance.

Default Implementation

Return the stored, untyped pointer as a typed pointer to the GtkDrawingArea instance.
Declaration
Swift

var drawing_area_ptr: UnsafeMutablePointer<GtkDrawingArea>! { get }
Show on GitHub
init(raw:)
Required Initialiser for types conforming to DrawingAreaProtocol
Declaration
Swift

init(raw: UnsafeMutableRawPointer)
Show on GitHub


                    
                    
                    setDrawFunc(_:)

Extension method

Set the drawing function for this drawing area

Declaration

Swift

@inlinable
func setDrawFunc(_ drawFunction: @escaping (DrawingAreaRef, Cairo.ContextRef, Int, Int) -> Void)

Parameters


                                drawFunction

a function or closure that takes a reference to this drawing area, a Cairo context reference, the width, and the height of the area for drawing

Show on GitHub

DrawingArea Class


                    
                    
                    bind(property:to:_:flags:transformFrom:transformTo:)

Extension method

Bind a DrawingAreaPropertyName source property to a given target object.

Declaration

Swift

@discardableResult
@inlinable
func bind<Q, T>(property source_property: DrawingAreaPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

Parameters

`source_property`	the source property to bind
`target`	the target object to bind to
`target_property`	the target property to bind to
`flags`	the flags to pass to the `Binding`
`transform_from`	`ValueTransformer` to use for forward transformation
`transform_to`	`ValueTransformer` to use for backwards transformation

Return Value

binding reference or nil in case of an error

Show on GitHub


                    
                    
                    get(property:)

Extension method

Get the value of a DrawingArea property

Declaration

Swift

@inlinable
func get(property: DrawingAreaPropertyName) -> GLibObject.Value

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub


                    
                    
                    set(property:value:)

Extension method

Set the value of a DrawingArea property. Note that this will only have an effect on properties that are writable and not construct-only!

Declaration

Swift

@inlinable
func set(property: DrawingAreaPropertyName, value v: GLibObject.Value)

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub

DrawingArea signals


                    
                    
                    connect(signal:flags:handler:)

Extension method

Connect a Swift signal handler to the given, typed DrawingAreaSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: DrawingAreaSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`handler`	The Swift signal handler (function or callback) to invoke on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    connect(signal:flags:data:destroyData:signalHandler:)

Extension method

Connect a C signal handler to the given, typed DrawingAreaSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: DrawingAreaSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`signalHandler`	The C function to be called on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    onResize(flags:handler:)

Extension method

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.

Note

This represents the underlying resize signal

Declaration

Swift

@discardableResult
@inlinable
func onResize(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DrawingAreaRef, _ width: Int, _ height: Int) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`width`	the width of the viewport
`height`	the height of the viewport
`handler`	The signal handler to call Run the given callback whenever the `resize` signal is emitted

Show on GitHub

resizeSignal Extension method
Typed resize signal for using the connect(signal:) methods
Declaration
Swift

static var resizeSignal: DrawingAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyContentHeight(flags:handler:)

Extension method

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::content-height signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyContentHeight(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DrawingAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyContentHeight` signal is emitted

Show on GitHub

notifyContentHeightSignal Extension method
Typed notify::content-height signal for using the connect(signal:) methods
Declaration
Swift

static var notifyContentHeightSignal: DrawingAreaSignalName { get }
Show on GitHub


                    
                    
                    onNotifyContentWidth(flags:handler:)

Extension method

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::content-width signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyContentWidth(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DrawingAreaRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyContentWidth` signal is emitted

Show on GitHub

notifyContentWidthSignal Extension method
Typed notify::content-width signal for using the connect(signal:) methods
Declaration
Swift

static var notifyContentWidthSignal: DrawingAreaSignalName { get }
Show on GitHub

DrawingArea Class: DrawingAreaProtocol extension (methods and fields)

getContentHeight() Extension method
Retrieves the content height of the GtkDrawingArea.
Declaration
Swift

@inlinable func getContentHeight() -> Int
Show on GitHub
getContentWidth() Extension method
Retrieves the content width of the GtkDrawingArea.
Declaration
Swift

@inlinable func getContentWidth() -> Int
Show on GitHub
setContent(height:) Extension method
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 [methodGtk.Widget.set_valign] to avoid that.

If the height is set to 0 (the default), the drawing area may disappear.
Declaration
Swift

@inlinable func setContent(height: Int)
Show on GitHub
setContent(width:) Extension method
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 [methodGtk.Widget.set_halign] to avoid that.

If the width is set to 0 (the default), the drawing area may disappear.
Declaration
Swift

@inlinable func setContent(width: Int)
Show on GitHub
set(drawFunc:userData:destroy:) Extension method
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 [methodGtk.Widget.queue_draw] on the drawing area. This will cause a redraw and will call draw_func again.
Declaration
Swift

@inlinable func set(drawFunc: GtkDrawingAreaDrawFunc? = nil, userData: gpointer! = nil, destroy: GDestroyNotify?)
Show on GitHub
contentHeight Extension method
Retrieves the content height of the GtkDrawingArea.
Declaration
Swift

@inlinable var contentHeight: Int { get nonmutating set }
Show on GitHub
contentWidth Extension method
Retrieves the content width of the GtkDrawingArea.
Declaration
Swift

@inlinable var contentWidth: Int { get nonmutating set }
Show on GitHub
widget Extension method
Undocumented
Declaration
Swift

@inlinable var widget: GtkWidget { get }
Show on GitHub

DrawingAreaProtocol

Simple GtkDrawingArea usage

Declaration

Default Implementation

Declaration

Declaration

Declaration

Parameters

DrawingArea Class

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

DrawingArea signals

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

DrawingArea Class: DrawingAreaProtocol extension (methods and fields)

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration