[education/rkward] rkward/rbackend/rpackages/rkward: documented rk.select.file() and the newly added wrapper rk.choose.dir()
m.eik michalke
null at kde.org
Sat Sep 9 10:51:33 BST 2023
Git commit fa8ca5b81014e6353ba6507194efae97b1921220 by m.eik michalke.
Committed on 09/09/2023 at 11:50.
Pushed by meikm into branch 'master'.
documented rk.select.file() and the newly added wrapper rk.choose.dir()
M +1 -1 rkward/rbackend/rpackages/rkward/DESCRIPTION
M +2 -1 rkward/rbackend/rpackages/rkward/NAMESPACE
M +34 -14 rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
A +12 -0 rkward/rbackend/rpackages/rkward/man/rk.get.completions.Rd
M +36 -7 rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
https://invent.kde.org/education/rkward/-/commit/fa8ca5b81014e6353ba6507194efae97b1921220
diff --git a/rkward/rbackend/rpackages/rkward/DESCRIPTION b/rkward/rbackend/rpackages/rkward/DESCRIPTION
index fccccdaa6..af9477eca 100755
--- a/rkward/rbackend/rpackages/rkward/DESCRIPTION
+++ b/rkward/rbackend/rpackages/rkward/DESCRIPTION
@@ -19,7 +19,7 @@ Authors at R: c(person(given="Thomas", family="Friedrichsmeier",
email="rkward-devel at kde.org", role=c("cre","aut")))
Version: 0.7.6
Date: 2022-10-17
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.2
Collate:
'base_overrides.R'
'internal.R'
diff --git a/rkward/rbackend/rpackages/rkward/NAMESPACE b/rkward/rbackend/rpackages/rkward/NAMESPACE
index 120820136..3bcc1a433 100644
--- a/rkward/rbackend/rpackages/rkward/NAMESPACE
+++ b/rkward/rbackend/rpackages/rkward/NAMESPACE
@@ -50,6 +50,7 @@ export(rk.assign.preview.data)
export(rk.call.plugin)
export(rk.capture.output)
export(rk.check.for.pandoc)
+export(rk.choose.dir)
export(rk.clear.plot.history)
export(rk.demo)
export(rk.describe.alternative)
@@ -102,8 +103,8 @@ export(rk.results)
export(rk.save.workplace)
export(rk.screen.device)
export(rk.select.CRAN.mirror)
-export(rk.select.list)
export(rk.select.file)
+export(rk.select.list)
export(rk.sessionInfo)
export(rk.set.label)
export(rk.set.output.html.file)
diff --git a/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R b/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
index 8df0491cf..cf6cc3331 100755
--- a/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
+++ b/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
@@ -3,20 +3,26 @@
# SPDX-FileContributor: The RKWard Team <rkward-devel at kde.org>
# SPDX-License-Identifier: GPL-2.0-or-later
#' Message boxes and selection list using native KDE GUI
-#'
-#' Multi-purpose pop-up message boxes and selection list using native KDE GUI
-#' elements. The message boxes can be used either to show some information or
+#'
+#' Multi-purpose pop-up message boxes, selection list and file selectors using native
+#' KDE GUI elements. The message boxes can be used either to show some information or
#' ask some question. The selection list can be used to get a vector of
-#' selected items.
-#'
+#' selected items. The file selector opens a file system browser to chose one or
+#' multiple files, a directory, or a path for a new file.
+#'
#' For \code{rk.show.question}, the R interpreter always waits for the user's
#' choice.
-#'
-#' \code{rk.select.list} replaces \code{utils::select.list} for the running
-#' session acting as a drop-in replacement for \code{tk_select.list}. Use
-#' \code{.rk.backups$select.list} for the original \code{utils::select.list}
+#'
+#' \code{rk.select.list} replaces \code{\link[utils:select.list]{utils::select.list}}
+#' for the running session acting as a drop-in replacement for \code{tk_select.list}.
+#' Use \code{.rk.backups$select.list} for the original \code{utils::select.list}
#' function (see Examples).
-#'
+#'
+#' \code{rk.select.file} combines the functionality of \code{\link[base:file.choose]{file.choose}}
+#' and \code{utils::choose.dir}. The latter is only available in R for Windows, but
+#' \code{rk.select.file} can be used on all systems where RKWard is available. \code{rk.choose.dir}
+#' simply is a wrapper for \code{rk.select.file(mode="dir")}.
+#'
#' @aliases rk.show.message rk.show.question rk.select.list
#' @param message a string for the content of the message box.
#' @param msg like \code{message}, only the argument was renamed to mimic the formals of
@@ -61,8 +67,11 @@
#' it returns \code{NA} for \bold{Cancel} actions.
#'
#' \code{rk.select.list} returns the value of \code{\link{select.list}}.
+#'
+#' \code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target.
#' @author Thomas Friedrichsmeier \email{rkward-devel@@kde.org}
-#' @seealso \code{\link{system}}, \code{\link{select.list}}
+#' @seealso \code{\link{system}}, \code{\link{select.list}},
+#' \code{\link[base:file.choose]{file.choose}}
#' @keywords utilities
#' @rdname rk.show.messages
#' @examples
@@ -187,11 +196,22 @@
}
# file dialog
-# NOTE: initial specifies initial directory to start at (or file to select).
-# If this starts with a "#", the last file selected in a dialog with the same initial parameter
-# will be used, instead. E.g. initial="#images".
+#' @param initial character string, specifies initial directory to start at (or file to select).
+#' If this starts with a \code{"#"}, the last file selected in a dialog with the same initial parameter
+#' will be used, instead. E.g. \code{initial="#images"}.
+#' @param filter regular expression to filter for valid file or directory names.
+#' @param mode one of \code{"file"} (select one file), \code{"files"} (select one or more files),
+#' \code{"dir"} (select a directory), or \code{"newfile"} (set path for a new file).
#' @export
#' @rdname rk.show.messages
"rk.select.file" <- function(caption = NULL, initial = NULL, filter = '*', mode=c("file", "files", "dir", "newfile")) {
+ mode <- match.arg(mode)
.rk.do.plain.call ("choosefile", list(caption, initial, filter, mode[1]))
}
+
+# wrapper for dirs only
+#' @export
+#' @rdname rk.show.messages
+"rk.choose.dir" <- function(caption = NULL, initial = NULL, filter = '*'){
+ rk.select.file(caption = caption, initial = initial, filter = filter, mode="dir")
+}
diff --git a/rkward/rbackend/rpackages/rkward/man/rk.get.completions.Rd b/rkward/rbackend/rpackages/rkward/man/rk.get.completions.Rd
new file mode 100644
index 000000000..3266af2bd
--- /dev/null
+++ b/rkward/rbackend/rpackages/rkward/man/rk.get.completions.Rd
@@ -0,0 +1,12 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/rk.completion-functions.R
+\name{.rk.completions}
+\alias{.rk.completions}
+\title{Helper functions for querying completions}
+\usage{
+.rk.completions(fragment, type)
+}
+\description{
+These are currently not exported, as they are not intended to be use in user code
+The API may or may not be stable.
+}
diff --git a/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd b/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
index e44b4902b..9fede1198 100644
--- a/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
+++ b/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
@@ -5,6 +5,8 @@
\alias{rk.show.question}
\alias{rk.select.list}
\alias{rk.askYesNo}
+\alias{rk.select.file}
+\alias{rk.choose.dir}
\title{Message boxes and selection list using native KDE GUI}
\usage{
rk.show.message(message, caption = gettext("Information"), wait = TRUE)
@@ -28,6 +30,15 @@ rk.askYesNo(
)
rk.select.list(list, preselect = NULL, multiple = FALSE, title = NULL)
+
+rk.select.file(
+ caption = NULL,
+ initial = NULL,
+ filter = "*",
+ mode = c("file", "files", "dir", "newfile")
+)
+
+rk.choose.dir(caption = NULL, initial = NULL, filter = "*")
}
\arguments{
\item{message}{a string for the content of the message box.}
@@ -74,6 +85,15 @@ selection is allowed.}
\item{title}{a string, for the window title of the displayed list}
+\item{initial}{character string, specifies initial directory to start at (or file to select).
+If this starts with a \code{"#"}, the last file selected in a dialog with the same initial parameter
+will be used, instead. E.g. \code{initial="#images"}.}
+
+\item{filter}{regular expression to filter for valid file or directory names.}
+
+\item{mode}{one of \code{"file"} (select one file), \code{"files"} (select one or more files),
+\code{"dir"} (select a directory), or \code{"newfile"} (set path for a new file).}
+
\item{preselct}{a vector, coerced into a character vector, items to be
preselected.}
}
@@ -88,21 +108,29 @@ preselected.}
it returns \code{NA} for \bold{Cancel} actions.
\code{rk.select.list} returns the value of \code{\link{select.list}}.
+
+\code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target.
}
\description{
-Multi-purpose pop-up message boxes and selection list using native KDE GUI
-elements. The message boxes can be used either to show some information or
+Multi-purpose pop-up message boxes, selection list and file selectors using native
+KDE GUI elements. The message boxes can be used either to show some information or
ask some question. The selection list can be used to get a vector of
-selected items.
+selected items. The file selector opens a file system browser to chose one or
+multiple files, a directory, or a path for a new file.
}
\details{
For \code{rk.show.question}, the R interpreter always waits for the user's
choice.
-\code{rk.select.list} replaces \code{utils::select.list} for the running
-session acting as a drop-in replacement for \code{tk_select.list}. Use
-\code{.rk.backups$select.list} for the original \code{utils::select.list}
+\code{rk.select.list} replaces \code{\link[utils:select.list]{utils::select.list}}
+for the running session acting as a drop-in replacement for \code{tk_select.list}.
+Use \code{.rk.backups$select.list} for the original \code{utils::select.list}
function (see Examples).
+
+\code{rk.select.file} combines the functionality of \code{\link[base:file.choose]{file.choose}}
+and \code{utils::choose.dir}. The latter is only available in R for Windows, but
+\code{rk.select.file} can be used on all systems where RKWard is available. \code{rk.choose.dir}
+simply is a wrapper for \code{rk.select.file(mode="dir")}.
}
\examples{
@@ -123,7 +151,8 @@ rk.select.list (LETTERS, preselect = c("A", "E", "I", "O", "U"),
multiple = TRUE, title = "vowels")
}
\seealso{
-\code{\link{system}}, \code{\link{select.list}}
+\code{\link{system}}, \code{\link{select.list}},
+ \code{\link[base:file.choose]{file.choose}}
}
\author{
Thomas Friedrichsmeier \email{rkward-devel at kde.org}
More information about the rkward-tracker
mailing list