Define Interactive Graphlet Regions

DESCRIPTION:

Define interactive regions within a Graphlet and actions, if any, to be performed when those regions are moused over.

USAGE:

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)

OPTIONAL ARGUMENTS:

x1,y1,x2,y2
numeric vectors specifying points or coordinates of rectangles within the current plot, as follows: (1) If all of 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.

labels
character vector to be associated with the regions. Each label is displayed whenever the mouse is over the associated region. Labels can include "\n", displaying as multiple lines of text. If length(labels) is less than the number of regions, the labels vector is extended with empty strings to the proper length.
actions
character vector to be associated with the regions, defining the action to occur when the mouse is left-clicked within each active region. The format of action specification strings is given below. If length(actions) is less than the number of regions, the actions vector is extended with empty strings (which specify no action) to the proper length.
size
a numeric vector. In cases where only points are specified, this argument determines how large a region around the point should be active. It can be a vector of two numbers, which is then interpreted as separate X and Y values. If size.relative is T, it is interpreted as a fraction of the plot X or Y range, otherwise it is interpreted as specifying absolute values in pixels.
size.relative
determines how the size argument is interpreted.
adj
a numeric vector. In cases where only points are specified, this argument determines where the region is located relative to the point. Like size, this can be a vector of two numbers, to specify separate X and Y values. The default positions the point in the center of the region. If it is given as 0.0, the rectangle is positioned with the point at the lower left.
polygons
if this value is true, then this command defines one or more polygonal regions rather than rectangles. In this case, the polygon vertices are given by the x1,y1 arguments, and x2,y2 are ignored. The polygon vertices are listed in order, and it is assumed that the polygon closes by joining the last point to the first. Missing values (NAs) are allowed and signify breaks between polygons
one.region
if this value is true, then this command defines a single region composed of one or more subregions, which may be rectangles or polygons. This can be used to specify a set of non-contiguous regions that act as a single active region. If this is true, then only the first element in the labels and actions arguments is used.

VALUE:

0, invisibly.

SIDE EFFECTS:

creates regions and defines actions for them within the Graphlet.

DETAILS:

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.

SEE ALSO:

.

EXAMPLES:

# 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))
}