Tool: Conveniently manipulate toolbars, whatever the window

Description

These functions provide an unifying way of dealing with (simple) toolbars in R. Currently, they support only Tcl/Tk toolbars and toolbuttons, but other graphical toolboxes could be supported too in the future.

Usage

ToolAdd(toolbar, side = "top")
  ToolAddItem(toolbar, item, action, image = "", options = "")
  ToolDel(toolbar)
  ToolDelItem(toolbar, item)
  ToolNames()
  ToolItems(toolbar)
  ToolType(toolbar, warn = TRUE)
  ToolInvoke(toolbar, item)
  ToolChangeItem(toolbar, item, action = "", options = "")
  ToolStateItem(toolbar, item, active = TRUE)
  ToolRead(file = "Tools.txt")
  ToolReadPackage(package, subdir = "gui", file = "Tools.txt")

  ## S3 method for class 'guiTool':
print(x, \dots)

Arguments

toolbar

Name of a toolbar

side

Where to place the toolbar in the window ("top", "bottom", "left", or "right")?

item

Name of a toolbar item (a toolbutton)

action

Action the toolbutton triggers (R code)

image

Name of an image to display in the toolbutton

options

Additional options, for instance "disable" to disable the toolbutton at creation.

warn

Do we issue a warning if the type of menu is not recognized?

active

Do we enable or disable the toolbutton?

file

A file containing toolbars specifications to read

package

Name of a package from where to load toolbars specifications

subdir

Subdirectory in the package where the toolbars specifications are stored. By default, it is the "gui" subdirectory.

An object of class 'guiTool'

...

Further arguments (currently not used)

Value

ToolAdd(), ToolAddItem() return the handle to the newly created toolbar or toolbutton invisibly. ToolDel() and ToolDelItem() return invisibly TRUE if the resource is found and deleted, FALSE otherwise. ToolNames() returns the list of all toolbars registered in .guiTools in the 'TempEnv' environment. ToolInvoke() returns invisibly TRUE if the toolbutton was invoked, FALSE otherwise. ToolRead() and ToolReadPackage() return invisibly the list of toolbars that are imported and created.

Details

These functions care about creating, deleting and managing custom toolbars. Informations and handles to the various toolbars created with these functions are stored in the .guiTools variable, located in the 'TempEnv' environment. Use 'Img' resources to load images to display in the toolbuttons.

Examples

Run this code

## These cannot be run by examples() but should be OK when pasted
## into an interactive R session with the tcltk package loaded
## Run these commands one at a time

WinAdd("tt", title = "A Tk window with toolbars", pos ="-40+20")
ImgReadPackage("svWidgets")     # Make sure images are loaded
# Create a toolbar and populate it
ToolAdd("$Tk.tt/Main")
ToolNames()
(ToolItems("$Tk.tt/Main"))   # Still nothing in it
ToolAddItem("$Tk.tt/Main", "List variables",
	action = "print(ls(envir = .GlobalEnv))", image = "$Tk.butCopy")
ToolAddItem("$Tk.tt/Main", "Say yo!", action = "cat('yo!\n')")
ToolAddItem("$Tk.tt/Main", "-")
ToolAddItem("$Tk.tt/Main", "Search",
	action = "print(search())", image = "$Tk.butPaste")
(ToolItems("$Tk.tt/Main"))
# Change state of buttons in the toolbar
ToolStateItem("$Tk.tt/Main", "Search", FALSE)
ToolStateItem("$Tk.tt/Main", "Search", TRUE)
ToolStateItem("$Tk.tt/Main", "Say yo!", FALSE)
ToolStateItem("$Tk.tt/Main", "Say yo!", TRUE)
# Invoke a button
ToolInvoke("$Tk.tt/Main", "Say yo!")
# Remove a button and add another one (always at the end!)
ToolDelItem("$Tk.tt/Main", "Say yo!")
ToolAddItem("$Tk.tt/Main", "Say yo! twice", "cat('yo! yo!\n')")
(ToolItems("$Tk.tt/Main"))
ToolDel("$Tk.tt/Main")
ToolNames()
(ToolItems("$Tk.tt/Main"))
WinDel("tt")