%
% 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:

<<loading>>=
  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.

<<widgetInvoke>>=
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:

<<fillInVals, echo=FALSE>>=
   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:

<<createWF>>=
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}
<?xml version="1.0"?>
 <wFun xmlns:bt="http://www.bioconductor.org/WINVOKE">
        <funName>testWIfun</funName>
        <funArgList>
                <funArg>
                        <argName>what</argName>
                        <argDefault></argDefault>
                        <argType>ANY</argType>
                        <argLocation>main</argLocation>
                        <argWidgetType>TypeIn</argWidgetType>
                        <argRequired>TRUE</argRequired>
                </funArg>
                <funArg>
                        <argName>where</argName>
                        <argDefault>FALSE</argDefault>
                        <argType>logical</argType>
                        <argLocation>main</argLocation>
                        <argWidgetType>Radio</argWidgetType>
                        <argRequired>FALSE</argRequired>
                </funArg>
                <funArg>
                        <argName>mode</argName>
                        <argDefault>"any"</argDefault>
                        <argType>character</argType>
                        <argLocation>more</argLocation>
                        <argWidgetType>TypeIn</argWidgetType>
                        <argRequired>FALSE</argRequired>
                </funArg>
        </funArgList>
</wFun>
\end{verbatim}
\end{document}