[education/rkward] rkward/rbackend/rpackages/rkward: updated the docs for the file/dir selection functions regarding return values and KDE's one click mode

[m.eik michalke]

Git commit 347cd6919650202a79ba8d0ea18abcd90009f6d3 by m.eik michalke.
Committed on 10/09/2023 at 12:36.
Pushed by meikm into branch 'master'.

updated the docs for the file/dir selection functions regarding return values and KDE's one click mode

M  +8    -3    rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
M  +8    -3    rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd

https://invent.kde.org/education/rkward/-/commit/347cd6919650202a79ba8d0ea18abcd90009f6d3

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 467034b79..4df464741 100755
--- a/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
+++ b/rkward/rbackend/rpackages/rkward/R/rk.KDE_GUI-functions.R
@@ -21,7 +21,10 @@
 #' \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")}.
+#' simply is a wrapper for \code{rk.select.file(mode="dir")}. Please note that if users have configured
+#' KDE to change directories with just one click, they may find the \code{OK} button not to work as
+#' they expect. In those cases, the name of the target directory must be entered into the name
+#' input field of the dialog manually.
 #'
 #' @aliases rk.show.message rk.show.question rk.select.list
 #' @param message a string for the content of the message box.
@@ -66,9 +69,11 @@
 #' \code{rk.askYesNo} has the same return values as \code{rk.show.question}, except
 #'   it returns \code{NA} for \bold{Cancel} actions.
 #' 
-#' \code{rk.select.list} returns the value of \code{\link{select.list}}.
+#' \code{rk.select.list} returns the value of \code{\link{select.list}}, or an empty string
+#'    \code{""} if cancelled.
 #'
-#' \code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target.
+#' \code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target,
+#'    or \code{character(0)} if cancelled.
 #' @author Thomas Friedrichsmeier \email{rkward-devel@@kde.org}
 #' @seealso \code{\link{system}}, \code{\link{select.list}},
 #'    \code{\link[base:file.choose]{file.choose}}
diff --git a/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd b/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
index c0c1a7d30..8cdb2d90a 100644
--- a/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
+++ b/rkward/rbackend/rpackages/rkward/man/rk.show.messages.Rd
@@ -107,9 +107,11 @@ preselected.}
 \code{rk.askYesNo} has the same return values as \code{rk.show.question}, except
   it returns \code{NA} for \bold{Cancel} actions.
 
-\code{rk.select.list} returns the value of \code{\link{select.list}}.
+\code{rk.select.list} returns the value of \code{\link{select.list}}, or an empty string
+   \code{""} if cancelled.
 
-\code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target.
+\code{rk.select.file} and \code{rk.choose.dir} return the path to the selected target,
+   or \code{character(0)} if cancelled.
 }
 \description{
 Multi-purpose pop-up message boxes, selection list and file selectors using native
@@ -130,7 +132,10 @@ 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")}.
+simply is a wrapper for \code{rk.select.file(mode="dir")}. Please note that if users have configured
+KDE to change directories with just one click, they may find the \code{OK} button not to work as
+they expect. In those cases, the name of the target directory must be entered into the name
+input field of the dialog manually.
 }
 \examples{