1% File src/library/utils/man/winMenus.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{winMenus}
7\title{User Menus under MS Windows (Rgui)}
8\alias{winMenuAdd}
9\alias{winMenuAddItem}
10\alias{winMenuDel}
11\alias{winMenuDelItem}
12\alias{winMenuNames}
13\alias{winMenuItems}
14\description{
15  Enables users to add, delete and program menus for the \command{Rgui} in MS Windows.
16}
17\usage{
18winMenuAdd(menuname)
19winMenuAddItem(menuname, itemname, action)
20winMenuDel(menuname)
21winMenuDelItem(menuname, itemname)
22winMenuNames()
23winMenuItems(menuname)
24}
25\arguments{
26  \item{menuname}{a character string naming a menu.}
27  \item{itemname}{a character string naming a menu item on an existing menu.}
28  \item{action}{a character string describing the action when that menu
29    is selected, or \code{"enable"} or \code{"disable"}.}
30}
31\details{
32  User menus are added to the right of existing menus, and items are
33  added at the bottom of the menu.
34
35  By default the action character string is treated as \R input, being
36  echoed on the command line and parsed and executed as usual.
37
38  If the \code{menuname} parameter of \code{winMenuAddItem} does not
39  already exist, it will be created automatically.
40
41  Normally new submenus and menu items are added to the main console
42  menu. They may be added elsewhere using the following special names:
43  \describe{
44      \item{\code{$ConsoleMain}}{The console menu (the default)}
45      \item{\code{$ConsolePopup}}{The console popup menu}
46      \item{\code{$Graph<n>Main}}{The menu for graphics window \code{<n>}}
47      \item{\code{$Graph<n>Popup}}{The popup menu for graphics window
48      \code{<n>}}
49  }
50
51  Specifying an existing item in \code{winMenuAddItem} enables the
52  action to be changed.
53
54  Submenus can be specified by separating the elements in
55  \code{menuname} by slashes: as a consequence menu names may not
56  contain slashes.
57
58  If the \code{action} is specified as \code{"none"} no action is taken:
59  this can be useful to reserve items for future expansion.
60
61  The function \code{winMenuNames} can be used to find out what menus
62  have been created by the user and returns a vector of the existing
63  menu names.
64
65  The \code{winMenuItems} function will take the name of a menu and
66  return the items that exist in that menu.  The return value is a named
67  vector where the names correspond to the names of the items and the
68  values of the vector are the corresponding actions.
69
70  The \code{winMenuDel} function will delete a menu and all of its items
71  and submenus.  \code{winMenuDelItem} just deletes one menu item.
72
73  The total path to an item (menu string plus item string) cannot exceed
74  1000 bytes, and the menu string cannot exceed 500 bytes.
75}
76\value{
77  \code{NULL}, invisibly.  If an error occurs, an informative error
78  message will be given.
79}
80\note{
81    These functions are only available on Windows and only when using
82    the \command{Rgui}, hence not in \command{ESS} nor \command{RStudio}.
83}
84\seealso{\code{\link{winDialog}}}
85\examples{\dontrun{
86winMenuAdd("Testit")
87winMenuAddItem("Testit", "one", "aaaa")
88winMenuAddItem("Testit", "two", "bbbb")
89winMenuAdd("Testit/extras")
90winMenuAddItem("Testit", "-", "")
91winMenuAddItem("Testit", "two", "disable")
92winMenuAddItem("Testit", "three", "cccc")
93winMenuAddItem("Testit/extras", "one more", "ddd")
94winMenuAddItem("Testit/extras", "and another", "eee")
95winMenuAdd("$ConsolePopup/Testit")
96winMenuAddItem("$ConsolePopup/Testit", "six", "fff")
97winMenuNames()
98winMenuItems("Testit")
99}}
100\keyword{utilities}
101