[rkward-cvs] SF.net SVN: rkward:[3050] trunk/rkward/rkward
kapatp at users.sourceforge.net
kapatp at users.sourceforge.net
Mon Sep 20 07:36:04 UTC 2010
Revision: 3050
http://rkward.svn.sourceforge.net/rkward/?rev=3050&view=rev
Author: kapatp
Date: 2010-09-20 07:36:03 +0000 (Mon, 20 Sep 2010)
Log Message:
-----------
Rewrite the public functions documentation in Rd format
Modified Paths:
--------------
trunk/rkward/rkward/pages/rkward_public_functions.rkh
Added Paths:
-----------
trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.graph.on.Rd
trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.record.plot.Rd
trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
Modified: trunk/rkward/rkward/pages/rkward_public_functions.rkh
===================================================================
--- trunk/rkward/rkward/pages/rkward_public_functions.rkh 2010-09-18 06:24:58 UTC (rev 3049)
+++ trunk/rkward/rkward/pages/rkward_public_functions.rkh 2010-09-20 07:36:03 UTC (rev 3050)
@@ -3,90 +3,24 @@
<title>Utility functions in RKWard</title>
<summary>
- This help page briefly documents the various utility functions available in RKWard which are accessible to the user.
+ This help page links to the man pages of various utility functions available in RKWard which are accessible to the user.
</summary>
<section title="Graphics related functions" id="public_g_fns">
- Most of the functions described in this section, unless otherwise mentioned, returns NULL invisibly.<br></br><br></br>
-
- <b><code>rk.graph.on (device.type=getOption ("rk.graphics.type"), width=getOption ("rk.graphics.width"), height=getOption ("rk.graphics.height"), quality, ...)</code></b>:<br></br>this function is used to copy the currently displayed plot to the output html file. The output can be seen from Windows->Show output. <code>device.type</code> can be either <i>PNG</i> or <i>SVG</i> or <i>JPG</i> or <i>NULL</i> (in case of NULL <i>PNG</i> is used). Additional parameters are passed on to the relevant device. Typical usages include:
- <pre>
- rk.graph.on ("JPG", 480, 480, 75)
- plot (rnorm (100))
- rk.graph.off ()
- </pre>
- or
- <pre>
- plot (rnorm (100))
- dev.copy (device = "rk.graph.on")
- rk.graph.off ()
- </pre>Returns the value of the device call invisibly.<br></br><br></br>
-
- <b><code>rk.graph.off ()</code></b>:<br></br>
- closes the device that was opened by rk.graph.on. See the examples above. Returns the name and number of the device that was active before rk.graph.on was called.<br></br><br></br>
-
- <b><code>rk.duplicate.device (devId = dev.cur ())</code></b>:<br></br>
- duplicates the specified screen device. The plot on the new device behaves independently of the one it was duplicated from. Returns the value of a <code>dev.copy</code> call.<br></br><br></br>
-
- <b><code>rk.record.plot</code></b>:<br></br>
- This is an environment to store the screen device history. You should not use the functions / variables in this environment directly, instead use the many wrapper functions as discussed below. (Should this be put in internal_graphics.R?)<br></br><br></br>
-
- <b><code>rk.toggle.plot.history (x = TRUE)</code></b>:<br></br>
- x = TRUE enables and x = FALSE disables the plot history. You should not use this function. Instead use the checkbox in Settings->Configure RKWard->Onscreen Graphics->Screen device history. After the needed initialization / clean up, it sets the option variable <i>rk.enable.graphics.history</i> to x.<br></br><br></br>
-
- <b><code>rk.first.plot (devId = dev.cur ())</code></b>:<br></br>
- replay the first plot on the specified device.<br></br><br></br>
-
- <b><code>rk.previous.plot (devId = dev.cur ())</code></b>:<br></br>
- replay the previous plot in the history on the specified device.<br></br><br></br>
-
- <b><code>rk.next.plot (devId = dev.cur ())</code></b>:<br></br>
- replay the next plot in the history on the specified device.<br></br><br></br>
-
- <b><code>rk.last.plot (devId = dev.cur ())</code></b>:<br></br>
- replay the last plot on the specified device.<br></br><br></br>
-
- <b><code>rk.goto.plot (devId = dev.cur (), index=1)</code></b>:<br></br>
- replay a particular plot, identified by <code>index</code> on the specified device.<br></br><br></br>
-
- <b><code>rk.force.append.plot (devId = dev.cur ())</code></b>:<br></br>
- forcefully append the currently displayed plot to the history. This function ignores the type of plot (graphics / lattice) and by-passes the general recording mechanism, as a result the plot call can not be identified.<br></br><br></br>
-
- <b><code>rk.removethis.plot (devId = dev.cur ())</code></b>:<br></br>
- removes the plot displayed on the specified device from history. If there are more than one device showing the same plot then removing from one does not wipe it from the other devices. They can be re-added to the history from the other devices.<br></br><br></br>
-
- <b><code>rk.clear.plot.history ()</code></b>:<br></br>
- clears the screen device history.<br></br><br></br>
-
- <b><code>rk.show.plot.info (devId = dev.cur ())</code></b>:<br></br>
- when available, shows some extra information regarding the displayed plot on the specified device.<br></br><br></br>
-
- <b><code>rk.verify.plot.hist.limits (lmax)</code></b>:<br></br>
- You should not need to use this function. (Put it in internal_graphics.R?)<br></br><br></br>
-
- <b><code>rk.plot.history.summary (which = NULL, type = c ("devices", "history"))</code></b>:<br></br>
- Provides some summaries of the screen device history. <code>type = "devices"</code> provides summary of all or one device(s) depending on whether <code>which = NULL</code> or <code>which</code> is a single number identifying the device. <code>type = "history"</code> provides summary of the entire stored history. Returns a data.frame with some messages.<br></br><br></br>
+ <ul>
+ <li>See <link href="rkward://rhelp/rk.graph.on"/> or <link href="rkward://rhelp/rk.graph.off"/>.</li>
+ <li>See <link href="rkward://rhelp/rk.record.plot"/></li>
+ <li>See <link href="rkward://rhelp/rk.duplicate.device"/></li>
+ </ul>
</section>
<section title="Other functions" id="public_fns">
- <b><code>rk.show.message (message, caption = "Information", wait=TRUE)</code></b>:<br></br>
- shows a message box with <code>message</code> as the content of the box and <code>caption</code> as the box title. <code>wait=FALSE</code> displays the message box asynchronously. Always returns TRUE invisibly. See <link href="rkward://rhelp/system"/>.<br></br><br></br>
+ <ul>
+ <li>See <link href="rkward://rhelp/rk.show.message"/> or <link href="rkward://rhelp/rk.show.question"/>.</li>
+ </ul>
- <b><code>rk.show.question (message, caption = "Question", button.yes = "yes", button.no = "no", button.cancel = "cancel")</code></b>:<br></br>
- shows a message box waiting for an input from the user, either "yes" or "no" or "cancel," with <code>message</code> as the content of the box and <code>caption</code> as the box title. The text on the "yes," "no," and "cancel" buttons can be modified using <code>button.yes</code>, <code>button.no</code>, and <code>button.cancel</code> arguments. Setting any of these arguements to <b>""</b> (empty string) will disable the corresponding button. Returns TRUE for "yes," FALSE for "no," and NULL for "cancel."<br></br><br></br>
-
TODO: add documentation for all functions from public.R
</section>
- <related>
- <ul>
- <li><link href="rkward://rhelp/options"/></li>
- <li><link href="rkward://rhelp/getOption"/></li>
- <li><link href="rkward://rhelp/invisible"/></li>
- <li><link href="rkward://rhelp/dev.cur"/>, <link href="rkward://rhelp/dev.copy"/></li>
- <li><link href="rkward://rhelp/png"/>, <link href="rkward://rhelp/svg"/></li>
- </ul>
- </related>
-
</document>
Added: trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.graph.on.Rd
===================================================================
--- trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.graph.on.Rd (rev 0)
+++ trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.graph.on.Rd 2010-09-20 07:36:03 UTC (rev 3050)
@@ -0,0 +1,62 @@
+\name{rk.graph.on}
+\alias{rk.graph.on}
+\alias{rk.graph.off}
+
+\title{Copy device to HTML output}
+
+\description{
+ Create or copy a device to a html page which is displayed as "output" in RKWard; accessible from Windows->Show Output. \code{rk.graph.off} closes the device that was opened by \code{rk.graph.on}. The default settings for \code{device.type}, \code{width}, \code{height}, and \code{quality} can be modified from Settings -> Configure RKWard -> Output.
+}
+
+\usage{
+rk.graph.on(device.type = getOption("rk.graphics.type"),
+ width = getOption("rk.graphics.width"), height = getOption("rk.graphics.height"),
+ quality, ...)
+
+rk.graph.off()
+}
+\arguments{
+ \item{device.type}{a string, either \code{"PNG"} or \code{"JPG"} or \code{"SVG"} or \code{NULL}. In case of \code{NULL}, the default, \code{"PNG"}, is used.}
+ \item{width,height}{in pixels, the width and height of the copied device; default is 480 for both.}
+ \item{quality, \dots}{other arguments passed to the device function}
+}
+
+\value{
+ \code{rk.graph.on} invisibly returns the value of the corresponding device call, which, generally, is nothing.
+
+ \code{rk.graph.off} returns the number and name of the device that was active before \code{rk.graph.on} was called, whenever possbile. When not possible it returns the number and name of the next active device as done by \code{\link{dev.off}}.
+}
+
+\author{Thomas Friedrichsmeier \email{rkward-devel at lists.sourceforge.net}}
+
+\section{Warning}{
+ \itemize{
+ \item It is advised to use \code{rk.graph.off} and \bold{not} \code{dev.off} to close the device opened by \code{rk.graph.on}.
+
+ \item \code{dev.print(device = rk.graph.on)} is a \bold{wrong} usage for this "device," and will result in errors.
+ }
+}
+
+\seealso{
+ \code{\link{options}}, \code{\link{getOption}}, \code{\link{png}}, \code{\link{svg}}, \code{\link{dev.copy}}, \code{\link{dev.off}}, \code{\link{invisible}}
+}
+
+\examples{
+require (rkward)
+
+## Plot directly to the output (html) file, by-passing screen device:
+rk.graph.on ("JPG", 480, 480, 75)
+plot (rnorm (100))
+rk.graph.off ()
+
+## Copy the displayed plot to the output:
+plot (rnorm (100))
+dev.copy (device = rk.graph.on)
+rk.graph.off ()
+
+## WRONG USAGE: not run:
+#plot (rnorm (100))
+#dev.print (device = rk.graph.on)
+}
+
+\keyword{device}
Added: trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.record.plot.Rd
===================================================================
--- trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.record.plot.Rd (rev 0)
+++ trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.record.plot.Rd 2010-09-20 07:36:03 UTC (rev 3050)
@@ -0,0 +1,121 @@
+\name{rk.record.plot}
+\alias{rk.record.plot}
+\alias{rk.toggle.plot.history}
+\alias{rk.first.plot}
+\alias{rk.previous.plot}
+\alias{rk.next.plot}
+\alias{rk.last.plot}
+\alias{rk.goto.plot}
+\alias{rk.force.append.plot}
+\alias{rk.removethis.plot}
+\alias{rk.clear.plot.history}
+\alias{rk.show.plot.info}
+\alias{rk.verify.plot.hist.limits}
+\alias{rk.plot.history.summary}
+\alias{rk.duplicate.device}
+
+\title{Record screen device history and duplicate a screen device}
+\description{
+ TODO TODO
+}
+
+\usage{
+rk.toggle.plot.history(x = TRUE)
+
+rk.first.plot(devId = dev.cur())
+rk.previous.plot(devId = dev.cur())
+rk.next.plot(devId = dev.cur())
+rk.last.plot(devId = dev.cur())
+rk.goto.plot(devId = dev.cur(), index=1)
+
+rk.force.append.plot(devId = dev.cur())
+rk.removethis.plot(devId = dev.cur())
+
+rk.clear.plot.history()
+
+rk.show.plot.info(devId = dev.cur())
+rk.plot.history.summary(which = NULL, type = c("devices", "history"))
+
+rk.duplicate.device(devId = dev.cur())
+}
+
+\arguments{
+ \item{devId, which}{ an integer, the screen device on which an action is to be performed.}
+ \item{x}{ a logical (not NA), whether to enable the screen device history.}
+ \item{index}{ an integer, which plot to jump to?}
+ \item{type}{ a string, either \code{"devices"} or \code{"history"}, the type of summary to be printed.}
+}
+
+\details{
+ TODO TODO
+
+ \code{rk.record.plot} is an environment to store the screen device history. You should not use the functions / variables in this environment directly, instead use the many wrapper functions as described below.
+
+ \code{rk.toggle.plot.history} enables or disables the screen device history. You should not use this function. Instead use the checkbox in Settings->Configure RKWard->Onscreen Graphics->Screen device history. After the needed initialization / clean up, it sets the option variable \code{"rk.enable.graphics.history"} to \code{x}.
+
+ \code{rk.first.plot}, \code{rk.previous.plot}, \code{rk.next.plot}, \code{rk.last.plot} these functions provide browing actions to respective plots saved in the history on the specified device (\code{devId}).
+
+ \code{rk.goto.plot} this function provides a one step jump action to the plot specified by \code{index} on the specified device (\code{devId}).
+
+ \code{rk.force.append.plot} forcefully append the currently displayed plot to the history. This function ignores the type of plot (graphics / lattice) and by-passes the general recording mechanism, as a result the plot call can not be identified.
+
+ \code{rk.removethis.plot} removes the plot displayed on the specified device from history. If there are more than one device showing the same plot then removing from one device does not wipe it from the other devices. They can be re-added to the history from the other devices.
+
+ \code{rk.clear.plot.history} clears the screen device history.
+
+ \code{rk.show.plot.info} when available, shows some extra information regarding the displayed plot on the specified device.
+
+ \code{rk.plot.history.summary} provides some summaries of the screen device history. \code{type = "devices"} provides summary of all or one device(s) depending on whether \code{which = NULL} or \code{which} is a single number identifying the device. \code{type = "history"} provides summary of the entire stored history.
+
+ \code{rk.duplicate.device} duplicates the specified screen device. The plot on the new device behaves independently of the one it was duplicated from.
+}
+
+\value{
+ Except those mentioned below, the rest return \code{NULL} invisibly.
+
+ \code{rk.plot.history.summary} returns a data.frame with some messages.
+
+ \code{rk.duplicate.device} returns the value of a \code{dev.copy} call.
+}
+\author{Prasenjit Kapat \email{rkward-devel at lists.sourceforge.net}}
+
+\section{Warning}{
+ TODO TODO
+}
+
+\seealso{
+ \code{\link{dev.cur}}, \code{\link{dev.copy}}, \code{\link{setHook}},
+
+ \code{\link{graphics}}, \code{\link{recordPlot}}, \code{\link{replayPlot}}, \code{\link{persp}},
+
+ \code{\link{Lattice}}, \code{\link{print.trellis}}, \code{\link{trellis.last.object}}
+}
+
+\examples{
+## Example for this?
+require (rkward)
+
+.L. <- getOption ("rk.graphics.hist.max.length")
+
+local ({
+ options ("rk.graphics.hist.max.length" = 150)
+ x <- seq(-2*pi,2*pi,length=400)
+ xlim <- range(x); ylim <- c(-1,1)
+ n <- 100;
+ for (i in seq_len (n)) {
+ plot(x, sin(x-(i-1)*4*pi/n), type='l', xlim=xlim, ylim=ylim,
+ bty='n', xlab='', ylab='', xaxt='n', yaxt='n')
+ }
+})
+
+rk.first.plot ()
+for (i in 1:(rk.record.plot$sP.length-1)) rk.next.plot ()
+
+## Not run
+rk.clear.plot.history ()
+options ("rk.graphics.hist.max.length" = .L.)
+
+}
+\keyword{device}
+\keyword{dynamic}
+\keyword{environment}
Added: trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
===================================================================
--- trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd (rev 0)
+++ trunk/rkward/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd 2010-09-20 07:36:03 UTC (rev 3050)
@@ -0,0 +1,53 @@
+\name{rk.show.message}
+\alias{rk.show.message}
+\alias{rk.show.question}
+
+\title{Message box using native KDE GUI}
+
+\description{
+ Multi-purpose pop-up message boxes using native KDE GUI elements; used either to show some information or ask some question.
+}
+
+\usage{
+rk.show.message (message, caption = "Information", wait = TRUE)
+
+rk.show.question (message, caption = "Question",
+ button.yes = "yes", button.no = "no", button.cancel = "cancel")
+}
+
+\arguments{
+ \item{message}{a string for the content of the message box.}
+ \item{caption}{a string for title of the message box.}
+ \item{button.yes}{a string for the text label of the \bold{Yes} button. Can be an empty string (\code{""}), in which case the button is not displayed at all.}
+ \item{button.no}{a string used for the text label of the \bold{No} button, similar to \code{button.yes}.}
+ \item{button.canel}{a string used for the text label of the \bold{Cancel} button, similar to \code{button.yes}.}
+ \item{wait}{a logical (not NA) indicating whether the R interpreter should wait for the user's action, or run it asynchronously.}
+}
+
+\details{
+ For \code{rk.show.question}, the R interpreter always waits for the user's choice.
+}
+
+\value{
+ \code{rk.show.message} always returns \code{TRUE}, invisibly.
+
+ \code{rk.show.question} returns \code{TRUE} for \bold{Yes}, \code{FALSE} for \bold{No}, and \code{NULL} for \bold{Cancel} actions.
+}
+
+\author{Thomas Friedrichsmeier \email{rkward-devel at lists.sourceforge.net}}
+
+\seealso{
+ \code{\link{system}}
+}
+\examples{
+require (rkward)
+
+if (rk.show.question ("Question:\nDo you want to know about RKWard?",
+ button.yes = "Yes, I do!", button.no = "No, I don't care!", button.cancel = "")) {
+ rk.show.message ("Message:\nRKWard is a KDE GUI for R.", "RKWard Info")
+} else {
+ rk.show.message ("You must be joking!", "RKWard Info", wait = FALSE) ## Run asynchronously
+}
+}
+
+\keyword{utilities}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the rkward-tracker
mailing list