1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
\name{gmenu}
\alias{gaction}
\alias{gmenu}
\alias{gtoolbar}
\title{ Constructors to make menubars or toolbars}
\description{
A menubar or toolbar are created using these
constructors. These are specified using a lists, and these may
be seen as simply mapping these lists into the corresponding widget.
}
\usage{
gmenu(menulist, popup = FALSE, action=NULL, container = NULL, ...,
toolkit = guiToolkit())
gtoolbar (toolbarlist, style = c("both", "icons", "text",
"both-horiz"),
action=NULL, container = NULL,
..., toolkit = guiToolkit())
gaction(label, tooltip = NULL, icon = NULL, key.accel = NULL,
handler = NULL, action = NULL, parent=NULL, ...,
toolkit = guiToolkit())
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{menulist}{A list defining a menu bar}
\item{popup}{Logical indicating if this should return a popup menu}
\item{toolbarlist}{A list defining a toolbar}
\item{style}{What style to use}
\item{action}{Passed to menubar handlers}
\item{container}{Container to attach widget to. Should be a gwindow instance.}
\item{label}{Label for action item}
\item{tooltip}{tooltip}
\item{icon}{icon to decorate instance of action}
\item{key.accel}{keyboard accelerator. If specified, a parent window must also be specified.}
\item{parent}{Needed if key.accel is specified}
\item{handler}{Handler called when object attached to action is activated}
\item{\dots}{Passed to the \code{add} method of the container}
\item{toolkit}{Which GUI toolkit to use}
}
\details{
The gaction constructor creates reusable objects for use with
buttons, menubars and toolbars. Once constructed, the main
methods are \code{svalue}, and \code{svalue<-} for getting and
setting the label text and \code{enabled<-} which can changes
whether the widgets depending on the action are sensitive to
user input. An action object contains a label, an optional
icon, an optional keyboard accelerator, a handler and a parent
window. The handler does not have the widget from which it is
called passed in to the \code{obj} component of the first
argument, but one can parametrize the argument with the
\code{action} argument. The icon, tooltip, and keyboard
accelerator are very much toolkit and OS dependent, and so may
not always be available by the widget using the gaction
object. The keyboard accelerator may use modifiers
\code{Control}, \code{Alt} or \code{Shift} along with a
letter, such as \code{Control-c}. For \pkg{gWidgetstcltk} the
value is passed to \code{tkbind}. For \pkg{gWidgetsQt} the
value is passed to \code{Qt$QKeySequence}. For
\pkg{gWidgetsRGtk2} the value is parsed and manipulated. The
keyboard accelerator requires a parent container so that the
corresponding window for which the accelerator applies can be
found.
The lists defining a menubar or toolbar are very similar.
Each is a list with \emph{named} components. A component is a
terminal node if it a) is a \code{gaction} instance or b) has a
\code{handler} component, which is a function to be called
(without arguments) when the menu item or toolbar item is
selected. Optionally, an \code{icon} component can be given
specifying a stock icon to accompany the text. A non-null
component named \code{separator} will also indicate a terminal
node. In this case, a visible separator will be displayed.
A menubar list can use the hierarchical nature of a list to
generate submenus. For toolbars this is not the case.
These constructors map the list into the widget. The methods
for the constructors refer to these list defining the widget.
The \code{svalue} method returns the list.
The \code{svalue<-} method can be used to change the list, and
hence redo the menubar.
The \code{"["} method refers to the components of the list.
The \code{"[<-"} method can be used to change pieces of the
menubar or toolbar.
The \code{add} method with signature \code{(obj,lst)} or
\code{(obj,gmenu.instance)} can be used to apped to the
current menubar/toolbar. The second argument is a list or an
gmenu or gtoolbar instance.
The \code{delete} method
can be used to delete part of the menubar/toolbar. The
\code{value} argument can be either a character vector with
the top-level names to delete, or a named list, or an instance
of either gmenu or gtoolbar.
Popular usage reserves toolbars and menubars for top-level
windows -- not dialog sub windows, or sub groups within a GUI
-- as such, the container, specified at construction, should
be a top-level gwindow instance
}
% \value{}
% \references{}
% \author{}
% \note{}
% \seealso{}
\examples{
\dontrun{
mbl <- list()
mbl$File$Open$handler = function(h,...) print("open")
mbl$File$Quit$handler = function(h,...) print("quit")
mbl$File$Quit$icon = "quit"
mbl$Edit$Find$handler = function(h,...) print("Find")
mbl$Edit$Replace$handler = function(h,...) print("Replace")
w <- gwindow("gmenu test")
mb <- gmenu(mbl, container=w)
tbl <- list()
tbl$New <- list(icon="new",handler = function(...) print("new"))
tbl$Print <- list(icon="print",handler = function(...) print("print"))
tb <- gtoolbar(tbl, container=w)
## example of using gaction
## works in gWidgetstcltk, but much better in gWidgetsRGtk2
## stub for handler
f <- function(h,...) print("stub")
## some actions. The icon is optional, as is tooltip
aOpen <- gaction(label="Open", icon="open", handler=f)
aClose <- gaction(label="Close", icon="close", handler=f)
aQuit <- gaction(label="Quit", icon="quit", handler=function(h,...) dispose(w))
aCut <- gaction(label="Cut", icon="cut", handler=f)
aCopy <- gaction(label="Copy", icon="copy", handler=f)
aPaste <- gaction(label="Paste", icon="paste", handler=f)
## set up groups of actions so that they can be disabled/enabled
## all at once
allActionsGroup <- list(aOpen, aClose, aQuit, aCut, aCopy, aPaste)
editActionsGroup <- list(aCut, aCopy, aPaste)
## define menubar list
ml <- list(File = list(
open = aOpen,
close = aClose,
sep = list(separator = TRUE), # must be named component
quit = aQuit),
Edit = list(
copy = aCopy,
paste = aPaste))
## toolbar list has only one level
tl <- list(
Open=aOpen,
sep = list(separator = TRUE), # must be named component
Quit = aQuit)
## set up main window
w <- gwindow()
gmenu(ml, container = w)
gtoolbar(tl, container = w)
## Now add a widget
gbutton(action = aQuit, container = w)
## disable a group of action
sapply(editActionsGroup, function(i) enabled(i) <- FALSE)
}
}
\keyword{interface }% at least one, from doc/KEYWORDS
|
