tickle

{tickle} is a package for creating UIs in base R.

This is an opinionated abstraction over the base R package {tcltk}.

This package aims to provide:

a simplified UI creation process similar to shiny.
a modern-looking visual default.
more documentation to help create common UI elements without resorting to the online tcl/tk documentation.
a way to still access the low-level tcl/tk structures in order to achieve complex effects and customisation.

What’s in the box

An array of tic_*() functions for nested creation of a UI specification.
render_ui() to render a UI specification into a window onscreen.
reactive_*() to create reactive values used to transfer values between the UI and R
canvas_*() functions to do some simple drawing an manipulation on canvas widgets.

Overview

Create reactive variables (with reactive_*()) in order to pass values between R and the UI. e.g. the value of the slider, or the text in a text entry box.
Define callback functions that are called, say, when a button is pressed.
Create a UI specification by nesting containers and widgets with tic_*() calls. This specification can include
- binding callback functions to particular events like mouse buttons or key presses (bind argument)
- controlling how widgets are packed within their parent container (pack argument)
Render the UI to an actual object on the screen with render_ui()
The object returned by render_ui() can be ignored by beginners. For intermediate/advanced users, this object is a nested list of tclObj objects representing the UI components, and these can be further manipulated with {tcltk} to finesse and configure the UI.

Installation

You can install from GitHub with:

# install.package('remotes')
remotes::install_github('coolbutuseless/tickle')

Hello World

Things to note:

Define a reactive variable for the slider before defining the UI
UI specificaiton created with nested tic_*() calls.
Some commands (e.g. tic_button()) have an explicit command function which is run when they are activated.
After defining the UI specificaiton, it is rendered to screen with render_ui()

library(tickle)

happiness <- reactive_dbl(40)

ui_spec <- tic_window(
  title = "Hello World", 
  tic_row(
    tic_col(
      tic_button("Hello", command = function() {message("Hello")}, style = 'primary'),
      tic_button("World", command = function() {message("World")})
    ),
    tic_col(
      tic_slider(happiness),
      tic_label(textvariable = happiness)
    )
  )
)

win <- render_ui(ui_spec)

Gallery

Examples/Vignettes

Please view the online vignettes for more details on how to use {tickle}

Containers

Containers are ways of grouping multiple widgets.

Containers can be nested within other containers to achieve complex layouts.

Container	Code/Description
	`tic_window(…)` Create a top level window
	`tic_col(A, B, C)` Layout objects in column
	`tic_row(A, B, C)` Layout objects rowwise
	`tic_frame(…)` Invisible container. Useful for advanced users who want to customize layout
	`tic_labelframe(…)` Frame with a a label and usually visible outline
	`tic_notebook(A, B, C)` Tabbed display
	`tic_panedwindow(A, B, C)` Layout multiple elements which can be resized as panes

Widgets

Widget	Code/Description
	`tic_label(…)` Display text. If you need headings rather than body text, Use `style = 'h1'` to `style = 'h5'` for different sized text
	`tic_button(…)` Clickable button. Available `style` options: ‘primary’, ‘seconary’, ‘info’, ‘success’, ‘warning’, ‘danger’, ‘light’, ‘dark’
	`tic_checkbutton(…)` On/off button (default styling)
	`tic_checkbutton(…)` On/off button with `style = 'toggle'`
	`tic_checkbutton(…)` On/off button with `style = 'switch'`
	`tic_radiobutton(…)` Groups of mutually exclusion options
	`tic_menubutton(…)` Button which displays a drop-down menu
	`tic_canvas(…)` General drawing canvas
	`tic_spinbox(…)` Choose options
	`tic_combobox(…)` Choose options
	`tic_textentry(…)` Single line text entry
	`tic_textbox(…)` Multipe line text entry
	`tic_progressbar(…)` Progress bar
	`tic_slider(…)` Slider

Popups

Popups are windows which are initiated separate from the main UI.

Popup	Code/Description
	`popup_color_picker()`
	`popup_messagebox()`
	`popup_open_file()`
	`popup_save_file()`

Canvas

After creating a canvas with tic_canvas(), it can be manipulated with the following commands:

Draw on the canvas
- canvas_line()
- canvas_text()
- canvas_rect()
- canvas_polygon()
- canvas_oval()
- canvas_arc()
canvas_plot() render a plot to the canvas
canvas_clear() clear all objects from the canvas
canvas_image() render an image from a file to the canvas
canvas_save() save the contents of the canvas to an image file.

The actual canvas in tcl/tk renders structured graphics and it is much more like SVG or PDF than just a simple array of pixels.

The canvas implementation in this package treats the canvas as just a raster object i.e. a rectangular collection of pixels. This made it easier to write this package and keep the API/syntax simple, but it doesn’t unleash the full power of the canvas.

The effort to write a more complete abstraction over the canvas is not currently warranted. Please get in contact if such a facility is important to you.

Theme

The theme for this package is an adaptaton of the sun-valley-light theme available from rdbende on github.

The sun-valley-light theme is MIT licensed (see “LICENSE-sun-valley”) and has been adapted into the theme r-sun-valley-light included in this package which has the following extra features:

Styles ‘h1’ through ‘h5’ for different sized heading text to use with tic_label() widgets.
- To use: tic_label(..., style = 'h1')
Standard buttons colours from Bootstrap to use with tic_button() widgets.
- To use: tic_button(..., style = 'primary')
- Available styles: primary, secondary, success, danger, warning, info, light, dark

Possible Future Features

The following items are not yet implemented, or incomplete:

Popup menus when a user right-clicks in the window.
No access yet to the “grid” geometry layout.
treeview, listbox and some other widgets

Package Name

tcl is the scripting language
tk is the graphics toolkit for tcl
tcl/tk is often how the langauge and toolkit are talked about as a single entity
{tcltk} is the R package interfacing to tcl/tk
tcl is often pronounced as “tickle” i.e. tcl/tk = “tickle-tee-kay”

Acknowledgements

R Core for developing and maintaining the language.
CRAN maintainers, for patiently shepherding packages onto CRAN and maintaining the repository

coolbutuseless/tickle

coolbutuseless

Reviews

Repository Details