java.identify(x1, y1, x2, y2, labels=character(0), actions=character(0), size=0.01, size.relative=T, adj=0.5, polygons=F, one.region=F)
x1,y1,x2,y2
are specified, they define a set of arbitrary rectangular regions. These
regions can be inside or outside the plot region. (2) If only
x1,y1
are specified, they are interpreted
as points with ranges of a particular
size
surrounding them. (3) If
x1,x2
are specified,
regions are created extending along the X-axis, extending the full height
of the plot. (4) If
y1,y2
are specified, regions
are created extending along the Y-axis, extending the full width of the plot.
(5) If only
x1
is specified, regions are
created around these points on the X-axis, extending the full height of the
plot. (6) If only y1 is given, regions are created
around these points on the Y-axis, extending the full width of
the plot.
The argument x1 may also be a structure containing components x and y or a two-column matrix, in which case the two vectors are used for the x1 and y1 arguments, and any supplied y1 argument is ignored.
Each element of the
java.identify
"actions" vector specifies an action
to occur when the mouse is left-clicked within the associated active
region. This action can be rather complicated, particularly when the
action is to pop up a menu of choices, where each choice is another
action. To accommodate representing such actions within a single
string, as well as provide opportunities for future enhancements, the
action string is specified using XML format. This format can be
somewhat difficult for people to write without error, so we have
supplied a set of S-PLUS functions for creating these strings. If an action
string is not in one of the formats below, clicking on the active
region will do nothing.
Action: Jump to Another Web Page
Example Action String:
<link href="http://spotfire.tibco.com" target="_top"/>
The "href" property gives a URL specifying a web page. The "target" property specifies the HTML frame where the Web page should be displayed. If the "target" property is not given, it defaults to "_top", which replaces the current web page being shown in the web browser. Another useful value for the target property is "_blank", which displays the URL in a new Web browser window. Note that some Web browsers may ignore the "target" property.
S-PLUS function:
java.action.link(url, target="_top")
Given a URL as a character string, this function returns an action string in the format above. The function is vectorized, so passing a vector of URLs returns a vector of action strings.
Action: Jump to Another Page of the Graphlet
Example Action String:
<page tag="p3"/>
The "tag" property specifies the page tag of the page to select. If none of the pages in the Graphlet have that tag, it does nothing.
S-PLUS function:
java.action.page(tag)
Given a page tag, this function returns an action string in the format above. This is vectorized, so passing in a vector of page tags will return a vector of action strings.
Action: Popup a menu of actions
Example Action String:
<menu title="some actions"> <menuitem label="go to page 1"> <page tag="p1"/> </menuitem> <menuitem label="go to URL"> <link href="http://www.spotfire.tibco.com" target="_top"/> </menuitem> <menu title="submenu items"> <menuitem label="go to page 2"> <page tag="p2"/> </menuitem> <menuitem label="go to page 3"> <page tag="p3"/> </menuitem> </menu> </menu>
S-PLUS function:
java.action.menu(items=character(0), title="") java.action.menuitem(action, label="item")
java.action.menu
takes a vector of
menuitem actions, and returns a
single long string defining a single menu action command. The title
for the menu is specified with the "title" argument. If it is "",
then the menu has no title. Note: some platforms do not support
titles on popup menus, in which case this argument is ignored.
If one of the menu items is another menu, as in the above XML, this creates a submenu that appears when the mouse is over the menu item. The nested menu title is used as the item name. Submenus can be nested to any level.
java.action.menuitem
is a vectorized function
taking a vector of action strings, and returning a vector of menuitem objects.
Each menu item appears in the menu with the specified label.
Action: Define a selection tag
Example Action String:
<select tag="t17"/>
The "tag" property defines a selection tag for this active region. If this region is buttoned, all regions with this selection tag (including this region) will be selected. A user can select any number of selectable regions, see the corresponding regions selected in other graphs in the same Graphlet, and send the selection list back to a server for further processing.
S-PLUS function:
java.action.select(tag)
Given a selection tag, this function returns an action string in the format above. This is vectorized, so passing in a vector of selection tags will return a vector of action strings.
A simple click on a selectable region selects it and deselects any other regions that might have been selected. A shift-click on a region adds it to the list of selected regions. A control-click on a region toggles the selection, selecting or deselecting the region depending on whether it was already selected.
Goups of selectable regions can selected by sweeping out a rectangle, and then clicking the "Select" button (in a Graphlet), or the "Select Rectangle" menu item. If a user sweeps a rectangular area of the graph and then clicks the Select button, all selectable regions intersecting the swept rectangle will become selected. Holding the shift key down while sweeping the rectangle causes the swept regions to be added to the selected list when the Select button is clicked. Holding the control key down while sweeping the rectangle causes the selection of the swept regions to be toggled when the Select button is clicked.
JavaScript within an HTML page can access the selected tags in a Graphlet
using HTML such as the following:
<applet name="Graphlet1" code="spjgraph.class" archive="spjgraph.jar" width="480" height="360"> <param name="spjgraph.filename" value="StateSelect.spj"> <param name="spjgraph.select.button" value="on"> </applet> <button onclick="alert(document.Graphlet1.getSelectedTags())"> List Selected Tags </button>
In this HTML code, the applet element needs a name property so that the JavaScript can refer to the Graphlet, and the parameter "spjgraph.select.button" must be specified to enable the Select button in the Graphlet. The selected tags are returned as a single string, with tags separated by commas.
# regions identifying each point in a scatterplot java.graph(file="mygraph.spj", format="SPJ") plot(fuel.frame[["Weight"]],fuel.frame[["Fuel"]]) java.identify(fuel.frame[["Weight"]], fuel.frame[["Fuel"]], labels=dimnames(fuel.frame)[[1]], actions=rep(java.action.link("http://www.spotfire.tibco.com"), length(fuel.frame[["Weight"]]))) dev.off() # an example with polygonal regions library("maps") java.graph(file="usegraph.spj", format="SPJ") map() # fill=T outputs complete polygon around each state map.outlines <- map(plot=F,fill=T) map.names <- map(plot=F,namesonly=T) map.html <- paste(map.names,".html",sep="") java.identify(map.outlines, labels=map.names, actions=java.action.link(map.html), polygons=T) dev.off() # an example with two polygonal regions treated as one library("maps") java.graph(file="vermontexas.spj", format="SPJ") map() title("select vermont and texas as one region") java.identify(map(plot=F,fill=T, regions=c("vermont","texas")), labels="Vermont and Texas", actions=java.action.link("vermontexas.html"), polygons=T, one.region=T) dev.off() # an example with selectable regions library(maps) java.graph(file="stateletter.spj", format="SPJ") map() title(paste("click on a state to select", "all states starting with that letter", sep="\n")) java.identify(map(plot=F,fill=T), polygons=T, labels=map(plot=F,namesonly=T), actions=java.action.select( substring(map(plot=F,namesonly=T),1,1))) dev.off() # an example with multiple pages, and a submenu java.graph() # code must be one block, to display multiple pages { plot(0:5, type = "n") java.set.page.title("initial page") java.set.page.tag("p1") text(2:4, 1:3, paste("press here to go to page", 1:3)) java.identify(2:4 - 1, 1:3 - 0.5, 2:4 + 1, 1:3 + 0.5, labels = paste("press here to go to\npage", 1:3), actions = java.action.page(paste("p", 1:3, sep = ""))) text(2, 4, "press here to bring up a menu") java.identify(1, 3.5, 3, 4.5, labels = "bring up a menu", actions = java.action.menu(title="foo", items=c( java.action.menuitem(java.action.page("p1"), "goto p1"), java.action.menuitem(java.action.page("p2"), "goto p2"), java.action.menuitem(java.action.page("p3"), "goto p3"), java.action.menu(title="sub menu", c( java.action.menuitem(java.action.page("p1"), "goto p1"), java.action.menuitem(java.action.page("p2"), "goto p2"), java.action.menuitem(java.action.page("p3"), "goto p3") )) ))) title("this is page 1") plot(1:10) java.set.page.title("") java.set.page.tag("p2") title("this is page 2, with an empty tab") java.identify(x1 = 1:10, labels = rep("jump to page 1",10), actions = rep(java.action.page("p1"), 10)) plot(10:1) java.set.page.title("AReallyLongTabName") java.set.page.tag("p3") title("this is page 3") java.identify(y1 = 1:10, labels = rep("jump to page 1",10), actions = rep(java.action.page("p1"), 10)) }