brush: Set or query the brush attributes

Description

The brush object in cranvas is essentially an environment, and we can manipulate objects in this environment.

Usage

brush(data, attr)
brush(data, attr) <- value

Arguments

data

the mutaframe created by qdata, with an attribute Brush

attr

the name of the brush attribute (a character scalar), e.g. style (the color, linewidth and linetype of the brush), color (the color of the objects selected by the brush), size (the size of the selected objects, e.g. line width or size of points); if attr is missing, the whole brush object (as a reference object; see setRefClass) will be returned

value

the value of the brush attribute

Value

The function brush returns the brush object or the attribute of the brush; note the brush object can be further manipulated with other methods -- see examples below.

Details

The list of attributes in the brush (they can be accessed by the $ method):

style

a list containing color, linewidth and linetype defining the style of the brush (rectangle) -- not to be confused with the color of the brushed elements

color, size

the color and size of the brushed elements

mode

the brush mode: can be 'none' (default), 'and', 'or', 'xor', 'not' or 'complement'; see mode_selection for details

identify

logical: TRUE (turn on the identify mode) or FALSE (the brush mode)

label.gen

a function to be used to generate the labels (based on the identified data) to show in the identify mode; the default function just prints the identified data as a character string

label.color

the color for the label in the identify mode

history.size

the size of brush history, i.e. how many brushing operations to be recorded; default to be 30

history.list

the list of indices of the brushed elements; we can go back and forth in the brush history according to this list

history.index

the current index of the brush history

persistent

persistent (TRUE) or transient (FALSE) brushing; in the persistent brushing mode, the attributes of the brushed elements will be changed permanently

persistent.color

a color vector to store the colors of persistently brushed elements

persistent.list

the persistent brushing history (a list of indices of the brushed elements)

select.only

is the mouse used to brush graphical elements ((FALSE)) or select elements only (TRUE); the subtle difference here is whether the brush should stay on the plot or not when the mouse is released

zoom

when select.only == TRUE, zoom with selection or not

draw.brush

whether to draw the brush (when the mouse is released and select.only is TRUE, then draw.brush will be FALSE so the brush will go away)

cursor

the cursor type (an integer; see set_cursor)

Examples

Run this code

library(cranvas)
qiris <- qdata(head(iris))  # create a mutaframe
brush(qiris)  # the brush object (a reference object)
brush(qiris, "color")
brush(qiris, "color") <- "green"  # set brush color to green

## attach events on the brush
b <- brush(qiris)

# idx is the index of the event; it can be used to stop the listening
idx <- b$colorChanged$connect(function() {
    message("the color of brushed elements was changed to ", b$color)
})
b$color <- "brown"
b$color <- "gold"

b$colorChanged$disconnect(idx)  # disconnect the event

b$style$color <- "red"  # change the color of the brush itself to red
b$style$linewidth <- 3  # the border width to 3

b$mode <- "or"  # brush mode to OR

b$history.size <- 50  # increase history size to 50

b$cursor <- 3L  # cursor type to WaitCursor

b$identify <- TRUE  # turn on identify mode
b$identify <- FALSE  # turn off; i.e. in brushing mode now

b$persistent <- TRUE  # turn on persistent brushing

## redefine label generating function: show row names in the identify mode
b$label.gen <- function(x) {
    paste(rownames(x), collapse = ", ")
}