% % NOTE -- ONLY EDIT THE .Rnw FILE!!! The .tex file is % likely to be overwritten. % %\VignetteIndexEntry{HOWTO widgetInvoke} %\VignetteDepends{widgetInvoke} %\VignetteKeywords{} %\VignettePackage{widgetInvoke} \documentclass{article} \usepackage{hyperref} \newcommand{\Rfunction}[1]{{\texttt{#1}}} \newcommand{\Robject}[1]{{\texttt{#1}}} \newcommand{\Rpackage}[1]{{\textit{#1}}} \author{Jeff Gentry} \begin{document} \title{HowTo use the widgetInvoke package} \maketitle \section{Overview} The \Rpackage{widgetInvoke} package, available as part of Bioconductor, is designed to allow for the creation of user interfaces for arbitrary functions. The design involves the use of Gtk for the actual interface and XML for data exchange, both of which were chosen for their cross platform abilities. Package authors and maintainers can create and customize metadata files for the functions of their packages using tools provided by \Rpackage{widgetInvoke} (or on their own), distribute these files with the package and then users of the package can use \Rpackage{widgetInvoke} to provide a GUI interface to this function. With all of this, a simple and standare mechanism can be used to quickly allow for GUI interaction with the functions of any given package. \section{Getting Started} The \Rpackage{widgetInvoke} package requires the use of the \Rpackage{RGtk} package from \url{www.omegahat.org} to interface with the Gtk libraries. While not explicitly required, the \Rpackage{RGtkHTML} and \Rpackage{RGtkDevices} are recommended as it will provide a bit richer environment (although at this time, users will not encounter any functionality loss if they are not installed, just a lower quality interface in a couple of spots). To load the \Rpackage{widgetInvoke} package, use the \Rfunction{library} function: <>= library(widgetInvoke) @ Also note that for the examples in this vignette, we shall be using a copy of the \Rfunction{apropos} function, named \Rfunction{testWIfun}. \section{The \Rfunction{widgetInvoke} function} The \Rfunction{widgetInvoke} function is used by the end user of a package to present the GUI for their desired function. To do this, they first must load not only the \Rpackage{widgetInvoke} package, but make sure that the function they wish to actually use is also loaded. At this point, the user only needs to call \Rfunction{widgetInvoke} with the name of the function they wish to use. <>= if (interactive()) { widgetInvoke("testWIfun") } @ \begin{center} \includegraphics[scale=0.5]{widgetInvoke} \end{center} Please note that this and most other code chunks shall have the 'interactive' test. This is solely for the handling of this vignette by automatic sessions without displays, and users following along do not need to include this test (although it will not hurt to do so). Here we are presented with the interface window of a very simple function, \Rfunction{testWIfun} (which of course is an exact replica of \Rfunction{apropos}). This function has three arguments (\Robject{what}, \Robject{where} and \Robject{mode}) which in this case are spread across two separate notebook panes ('main' and 'more'). The assignment of arguments to a particular notebook pane is done by the creator of the metadata (typically the package author or maintainer) and is explained in the section 'Creating the function metadata'. The function name is presented at the top, with a button which will display the man page for this function (using \Rpackage{RGtkHTML} if available, otherwise a less rich text widget is used). Clicking on this button will provide a window like this: \begin{center} \includegraphics{manPage} \end{center} The \Robject{what} argument has its name surrounded by '*' characters (\Robject{*what*}). This implies that the \Robject{what} function is required to have a value (default values are okay, but this function does not provide one) before evaluation. Other arguments are okay to leave empty if that is your desire. Here we will use \Robject{"testWIfun"} as the \Robject{what} argument, select \Robject{TRUE} for the \Robject{where} argument (instead of using the default value of \Robject{FALSE}), and in the second pane we shall stay with the default value of \Robject{"any"} for the \Robject{mode} argument. When these are filled in, we can hit the \Robject{Evaluate} button: \begin{center} \includegraphics{widgetInvokeVals} \end{center} This leaves us with the output: <>= testWIfun("testWIfun", TRUE, "any") @ As you can see, the function was evaluated in the \Robject{R} session as if the user called \Rfunction{testWIfun} themselves. One note on the entry of values into the text entry fields. Anything entered in there is handled in almost the same manner as entering a value into \Robject{R} - if the value is quoted (e.g. \Robject{"any"}), it is treated as a character string. If the value is not quoted, it is first checked to see if it represents an object in the search path and if it is not then it is assumed to be of numeric type. The one exception to this is a comma separated list of values, which are handled as a vector (where each element is handled by the rules above). For complex values, it is recommended to assign them first to a variable before calling \Rfunction{widgetInvoke} and then using that variable in the entry field. Arguments which have limited possiblities for values use radio buttons or drop down lists, and do not have this problem. \section{Creating the function metadata} The \Rfunction{widgetInvoke} function will not work unless the proper structure has already been put in place to support a given function in a package. This must be done ahead of time, typically by the package author or maintainer. To do this, a metadata file must be created for every function that is intended to work with \Rfunction{widgetInvoke} and stored in the \Robject{inst/wFun} directory of the package sources. This file is in XML format, and that format is discussed in the section 'The widgetInvoke XML'. There is an authoring tool in the \Rpackage{widgetInvoke} package that provides an easy interface to generating these metadata files, the \Rfunction{createWF} function. This will first attempt to figure out as much information as possible about the desired function, either from the function itself or if a metadata file already exists in the current directory it will use that for default values, and then display an interface to allow the operator to modify the settings for the display. To do this, simply call the \Rfunction{createWF} function with the name of the function that you would like to create the metadata for: <>= if (interactive()) { createWF("testWIfun") } @ \begin{center} \includegraphics[scale=0.5]{createWF} \end{center} The window itself is structured in a tabular format. At the top is the name of the function, the current name of the file to save to (using the \Robject{Save} button), a \Robject{Save As} button to change that filename and a button to provide the man page (which works identically to the one in the \Rfunction{widgetInvoke} function). Below the table are five buttons: \Robject{Close}, \Robject{Reset}, \Robject{Check}, \Robject{Preview} and \Robject{Save}. The table in the middle provides a row for every argument with columns marked \Robject{Type}, \Robject{Default}, \Robject{Location}, \Robject{WidgetType} and \Robject{Required}. The \Robject{Close} button will simply close the window without performing any further work. The \Robject{Reset} button will reset the fields in the argument table to the values that existed when this instance of \Rfunction{createWF} was started. The \Robject{Check} button will attempt to check the validity of the current values in the argument table, and alert the user to any problems that might be detected, if there are no problems a dialog will appear detailing that there are no problems. The \Robject{Preview} button will display a sample of the window that a user of the \Rfunction{widgetInvoke} function would see - in this instance the \Robject{Evaluate} button of this subwindow will simply close the window and not actually perform any call to R. Lastly the \Robject{Save} button will save the values in the argument table to the XML metadata file. In the argument table, each row corresponds to an argument, and each column corresponds to part of the metadata required for the use of this function with \Rfunction{widgetInvoke}. The first column, \Robject{Type}, details what type the value for this argument should be, e.g. \Robject{logical}, \Robject{character}, \Robject{numeric}, etc. For arguments that do not have a specific type requirement, the \Robject{ANY} value should be used. When \Rfunction{createWF} attempts to determine an appropriate default, if there is no default value for a particular argument it will automatically assign \Robject{ANY}, so operators of \Rfunction{createWF} should double check that this is actually true. The \Robject{Type} can also be a character vector, which corresponds to a structure such as \Robject{xloc=c("equispaced", "physical")}. In a situation like this, the first value of the vector is assumed to be the default, which is another situation where the operator should double check this value. The \Robject{Default} field will specify the default value for the argument. If one is specified in the formal arguments for the target function, it will appear here, but otherwise there will not. Operators of \Rfunction{createWF} can assign a new default or remove the default altogether. The type of the default value should match the type listed in \Robject{Type}, and this will be verified by the \Robject{Check} button. The \Robject{Location} field specifies which notebook pane this argument will appear on. These are sorted by name, and in a fresh run of \Rfunction{createWF} will all be set to \Robject{main}. To create a new pane, simply create a new name for the \Robject{Location} field of a particular row. There is no limit to the number of arguments that can be in a particular pane. The \Robject{WidgetType} field allows the operator to specify what sort of display widget that \Rfunction{widgetInvoke} uses for this argument. There are currently three options: \Robject{Radio} which uses radio buttons, \Robject{DropDown} which uses a drop down list, and \Robject{TypeIn} which provides a text entry widget. The first two (\Robject{Radio} and \Robject{DropDown}) are limited to arguments with a set of possible values - arguments with the \Robject{Type} set to being \Robject{logical} or a vector of possible values. All other arguments currently must use the \Robject{TypeIn} widget. These rules are enforced when the \Robject{Check} button is used. The \Robject{Required} button, if checked, indicates that this particular argument must be filled in by the \Rfunction{widgetInvoke} user of this function before evaluation can take place (or they can use the default value, if one is provided). In a fresh instance of \Rfunction{createWF} for a function, these are all unchecked. Operators should make sure that any argument that is crucial to the proper flow for this function are marked as being required. Once all of the fields are written to the operator's satisfaction, the \Robject{Preview} button can be used to make sure that the layout is visibly appealing as well. The \Robject{Check} button should be used to make sure that there are no problems with the defined structure, and if all is well the \Robject{Save} button can be used to save this particular metadata to a file named \Robject{function.xml} (where \Robject{function} is the name of the function) and stored in the current working directory of the operator's R session. For distribution, this should be put in the \Robject{inst/wFun} directory of the package. At this point, users can interact with this function with \Rfunction{widgetInvoke}. \section{The \Rpackage{widgetInvoke} XML} The XML format used by the \Rpackage{widgetInvoke} package is simple and straightforward. The \Robject{wFun} tag defines the primary XML block that is specifying the \Robject{wFun} object for a particular function. Every function has its own file, and thus a single \Robject{wFun} block. Within the \Robject{wFun} block are two main children nodes, \Robject{funName} and \Robject{funArgList}. The former simply provides for the name of the function, while the latter contains a series of \Robject{funArg} blocks - one for each argument in this function. The \Robject{funArg} blocks contain the majority of the information stored in the \Robject{wFun}, each one providing six fields: \begin{verbatim} argName: Name of this argument. argDefault: The default value, if any, of this argument. argType: The type of this argument (e.g. logical, numeric, character). "ANY" is used for typeless arguments. argLocation: The name of the notebook pane this argument will be displayed in. argRequired: A logical value specifying whether or not this argument is required or not. \end{verbatim} Each of these are then stored in the \Robject{inst/wFun} directory of the package source, using the name \Robject{function.xml} (where 'function' is the name of the function). When installed, these files are available in the \Robject{wFun} directory of the installed package. An example of the XML is provided for the \Rfunction{testWIfun} function. \begin{verbatim} testWIfun what ANY main TypeIn TRUE where FALSE logical main Radio FALSE mode "any" character more TypeIn FALSE \end{verbatim} \end{document}