pub trait DeviceDriver: Sized {
    const USE_RASTER: bool = true;
    const USE_CAPTURE: bool = true;
    const USE_LOCATOR: bool = true;
    const USE_PLOT_HISTORY: bool = false;
    const CLIPPING_STRATEGY: ClippingStrategy = ClippingStrategy::DeviceAndEngine;
    const ACCEPT_UTF8_TEXT: bool = true;
Show 24 methods // Provided methods fn activate(&mut self, dd: DevDesc) { ... } fn circle( &mut self, center: (f64, f64), r: f64, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn clip(&mut self, from: (f64, f64), to: (f64, f64), dd: DevDesc) { ... } fn close(&mut self, dd: DevDesc) { ... } fn deactivate(&mut self, dd: DevDesc) { ... } fn line( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc ) { ... } fn char_metric( &mut self, c: char, gc: R_GE_gcontext, dd: DevDesc ) -> TextMetric { ... } fn mode(&mut self, mode: i32, dd: DevDesc) { ... } fn new_page(&mut self, gc: R_GE_gcontext, dd: DevDesc) { ... } fn polygon<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn polyline<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn rect( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc ) { ... } fn path<T: IntoIterator<Item = impl IntoIterator<Item = (f64, f64)>>>( &mut self, coords: T, winding: bool, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn raster<T: AsRef<[u32]>>( &mut self, raster: Raster<T>, pos: (f64, f64), size: (f64, f64), angle: f64, interpolate: bool, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn capture(&mut self, dd: DevDesc) -> Robj { ... } fn size(&mut self, dd: DevDesc) -> (f64, f64, f64, f64) { ... } fn text_width(&mut self, text: &str, gc: R_GE_gcontext, dd: DevDesc) -> f64 { ... } fn text( &mut self, pos: (f64, f64), text: &str, angle: f64, hadj: f64, gc: R_GE_gcontext, dd: DevDesc ) { ... } fn on_exit(&mut self, dd: DevDesc) { ... } fn new_frame_confirm(&mut self, dd: DevDesc) -> bool { ... } fn holdflush(&mut self, dd: DevDesc, level: i32) -> i32 { ... } fn locator(&mut self, x: *mut f64, y: *mut f64, dd: DevDesc) -> bool { ... } fn eventHelper(&mut self, dd: DevDesc, code: i32) { ... } fn create_device<T: DeviceDriver>( self, device_descriptor: DeviceDescriptor, device_name: &'static str ) -> Device { ... }
}
Expand description

A graphic device implementation.

§Safety

To implement these callback functions, extreme care is needed to avoid any panic!() because it immediately crashes the R session. Usually, extendr handles a panic gracefully, but there’s no such protect on the callback functions.

Provided Associated Constants§

source

const USE_RASTER: bool = true

Whether the device accepts the drawing operation of a raster. By default, the default implementation, which just ignores the raster, is used so this can be left true. If there’s a necessity to explicitly refuse the operation, this can be set false.

source

const USE_CAPTURE: bool = true

Whether the device accepts a capturing operation. By default, the default implementation, which just returns an empty capture, is used so this can be left true. If there’s a necessity to explicitly refuse the operation, this can be set false.

source

const USE_LOCATOR: bool = true

Whether the device has a locator capability, i.e., reading the position of the graphics cursor when the mouse button is pressed. It works with X11, windows and quartz devices.

source

const USE_PLOT_HISTORY: bool = false

Whether the device maintains a plot history. This corresponds to displayListOn in the underlying DevDesc.

source

const CLIPPING_STRATEGY: ClippingStrategy = ClippingStrategy::DeviceAndEngine

To what extent the device takes the responsibility of clipping. See ClippingStrategy for the details.

source

const ACCEPT_UTF8_TEXT: bool = true

Set this to false if the implemented strWidth() and text() only accept ASCII text.

Provided Methods§

source

fn activate(&mut self, dd: DevDesc)

A callback function to setup the device when the device is activated.

source

fn circle(&mut self, center: (f64, f64), r: f64, gc: R_GE_gcontext, dd: DevDesc)

A callback function to draw a circle.

The header file1 states:

  • The border of the circle should be drawn in the given col (i.e. gc.col).
  • The circle should be filled with the given fill (i.e. gc.fill) colour.
  • If col is NA_INTEGER then no border should be drawn.
  • If fill is NA_INTEGER then the circle should not be filled.
source

fn clip(&mut self, from: (f64, f64), to: (f64, f64), dd: DevDesc)

A callback function to clip.

source

fn close(&mut self, dd: DevDesc)

A callback function to free device-specific resources when the device is killed. Note that, self MUST NOT be dropped within this function because the wrapper that extendr internally generates will do it.

source

fn deactivate(&mut self, dd: DevDesc)

A callback function to clean up when the device is deactivated.

source

fn line( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a line.

source

fn char_metric(&mut self, c: char, gc: R_GE_gcontext, dd: DevDesc) -> TextMetric

A callback function that returns the TextMetric (ascent, descent, and width) of the given character in device unit.

The default implementation returns (0, 0, 0), following the convention described in the header file:

If the device cannot provide metric information then it MUST return 0.0 for ascent, descent, and width.

source

fn mode(&mut self, mode: i32, dd: DevDesc)

A callback function called whenever the graphics engine starts drawing (mode=1) or stops drawing (mode=0).

source

fn new_page(&mut self, gc: R_GE_gcontext, dd: DevDesc)

A callback function called whenever a new plot requires a new page.

source

fn polygon<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a polygon.

source

fn polyline<T: IntoIterator<Item = (f64, f64)>>( &mut self, coords: T, gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a polyline.

source

fn rect( &mut self, from: (f64, f64), to: (f64, f64), gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a rect.

source

fn path<T: IntoIterator<Item = impl IntoIterator<Item = (f64, f64)>>>( &mut self, coords: T, winding: bool, gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw paths.

nper contains number of points in each polygon. winding represents the filling rule; true means “nonzero”, false means “evenodd” (c.f. https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-rule).

source

fn raster<T: AsRef<[u32]>>( &mut self, raster: Raster<T>, pos: (f64, f64), size: (f64, f64), angle: f64, interpolate: bool, gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a Raster.

pos gives the bottom-left corner. angle is the rotation in degrees, with positive rotation anticlockwise from the positive x-axis. interpolate is whether to apply the linear interpolation on the raster image.

source

fn capture(&mut self, dd: DevDesc) -> Robj

A callback function that captures and returns the current canvas.

This is only meaningful for raster devices.

source

fn size(&mut self, dd: DevDesc) -> (f64, f64, f64, f64)

A callback function that returns the current device size in the format of (left, right, bottom, top) in points.

  • If the size of the graphic device won’t change after creation, the function can simply return the left, right, bottom, and top of the DevDesc (the default implementation).
  • If the size can change, probably the actual size should be tracked in the device-specific struct, i.e. self, and the function should refer to the field (e.g., cbm_Size() in the cairo device).

Note that, while this function is what is supposed to be called “whenever the device is resized,” it’s not automatically done by the graphic engine. The header file states:

This is not usually called directly by the graphics engine because the detection of device resizes (e.g., a window resize) are usually detected by device-specific code.

source

fn text_width(&mut self, text: &str, gc: R_GE_gcontext, dd: DevDesc) -> f64

A callback function that returns the width of the given string in the device units.

The default implementation use char_metric() on each character in the text and sums the widths. This should be sufficient for most of the cases, but the developer can choose to implement this. The header file1 suggests the possible reasons:

  • for performance
  • to decide what to do when font metric information is not available
source

fn text( &mut self, pos: (f64, f64), text: &str, angle: f64, hadj: f64, gc: R_GE_gcontext, dd: DevDesc )

A callback function to draw a text.

angle is the rotation in degrees, with positive rotation anticlockwise from the positive x-axis.

source

fn on_exit(&mut self, dd: DevDesc)

A callback function called when the user aborts some operation. It seems this is rarely implemented.

source

fn new_frame_confirm(&mut self, dd: DevDesc) -> bool

A callback function to confirm a new frame. It seems this is rarely implementad.

source

fn holdflush(&mut self, dd: DevDesc, level: i32) -> i32

A callback function to manage the “suspension level” of the device. R function dev.hold() is used to increase the level, and dev.flush() to decrease it. When the level reaches zero, output is supposed to be flushed to the device. This is only meaningful for screen devices.

source

fn locator(&mut self, x: *mut f64, y: *mut f64, dd: DevDesc) -> bool

A callback function that returns the coords of the event

source

fn eventHelper(&mut self, dd: DevDesc, code: i32)

A callback function for X11_eventHelper.

source

fn create_device<T: DeviceDriver>( self, device_descriptor: DeviceDescriptor, device_name: &'static str ) -> Device

Create a Device.

Object Safety§

This trait is not object safe.

Implementors§