gWidgets (version 0.0-53)

gWidgets-handlers: Methods to add event handlers to objects

Description

In the gWidgets API handlers are called in reponse to certain events such as keystrokes or clicks. This set of methods makes a consistent interface to some typical events. Not all handlers are defined for each widget.

Usage

addHandlerChanged(obj, handler = NULL, action = NULL, ...) 
addHandlerKeystroke(obj, handler = NULL, action = NULL, ...) 
addHandlerClicked(obj, handler = NULL, action = NULL, ...) 
addHandlerDoubleclick(obj, handler = NULL, action = NULL, ...) 
addHandlerRightclick(obj, handler = NULL, action = NULL, ...) 
addHandlerFocus(obj, handler = NULL, action = NULL, ...) 
addHandlerBlur(obj, handler = NULL, action = NULL, ...) 
addHandlerMouseMotion(obj, handler = NULL, action = NULL, ...)
addHandlerExpose(obj, handler = NULL, action = NULL, ...) 
addHandlerUnrealize(obj, handler = NULL, action = NULL, ...) 
addHandlerDestroy(obj, handler = NULL, action = NULL, ...) 
addHandlerIdle (obj, handler = NULL, action = NULL, interval = 1000,   ...) 
addPopupmenu(obj, menulist, action=NULL, ...)
add3rdMousePopupmenu(obj, menulist, action=NULL, ...)
removeHandler(obj, ID=NULL, ...)
blockHandler(obj, ID=NULL, ...)
unblockHandler(obj, ID=NULL, ...)

Arguments

obj

The object to assign handler to

handler

A function to call if the given event occurs. The function's first argument is a list with some specific components. The component obj contains the object that the handler was assigned to. The action component con

action

Used to pass extra information into handlers

interval

For addHandleridle this specifies the time in milliseconds between calls to the handler.

menulist

For addpopupmenu and add3rdmousepopupmenu this specifies a menubar using a list which is in turn passed to gmenu.

ID

When a handler is assigned, an id is returned. This id can be used to remove or block a handler from an object.

...

Not documented, currently has no role.

Details

At first these handlers were all lowercase. These functions are still availabe, although the mixed case usage is encouraged In GTK, and other toolkits, an event causes a signal to be triggered and these handlers are called in response to that signal.

These signals have various names known to the GTK programmer. say. These functions attempt to shield the gWidgets user from needing to learn these signals. For gWidgetsRGtk, if these handlers prove insufficient then the non-exported addHandler function has an additional signal argument: (obj,signal,handler, action,...) for specifying a GTK signal. By avoiding this, we can make the gWidgets API non-toolkit specific.

The signals are defined to match the event described by the method name, e.g., "doubleclick."

The handlers all have signature (h,...) where the first argument is a list with components obj containing the widget the handler is added to and action containing the values passed along to the action argument. This can be used to pass in other widget's names, when they can not be found from a function closure, say.

The handlers do not have lazy evaluation. The value of action is the one at the time of creation of the widget. (See the example). In GTK, a means to cheat this is to pass in a gWidget instance, as the underlying GTK objects are stored as pointers, not copies, so that when queried, their current state is used.

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Although not handlers, the addPopupMenu method adds a popup menu to a mouse click. The popup menu is specified using a list that is passed to gmenu.

A refinement of this is the add3rdMousePopupmenu method which puts the popupmenu on the right mouse click.

The method removeHandler is used to remove a handler from an object. If an ID is specified, just that handler is removed, otherwise all handlers will be. To temporarily disable a handler, use blockHandler then unblockHandler.

See Also

gWidgets-methods

Examples

## a default handler, useful for when action is enough to
	## specify desired results

	handler.default = function(h,...) do.call(h$action,list(svalue(h$obj)))
	group = ggroup(horizontal=FALSE, container=gwindow("Click
		button"))
        button = gbutton("Click me", container=group)
	addhandlerclicked(button, handler=handler.default, action="print")


	## use two widgets, one to update the other
	group = ggroup(horizontal=FALSE, container=gwindow("two widgets"))
	button = gbutton("click me", container=group)
	label = glabel("Button has not been clicked", container=group)
	addhandlerclicked(button, handler = function(h,...) {
	svalue(h$obj) <-"click me again"
	svalue(h$action) <- "Button has been clicked"
	}, action = label)


	## lazy evaluation is not used here
	obj = 4
	gbutton("click",container=TRUE, handler=function(h,...)
	print(h$action), action=obj)
	obj = 2
	## now click button and value of 4 will be printed, not 2

	## Whereas, if one uses a gWidget we get the same as lazy
       ## loading
       obj = gedit("4")		 
	gbutton("click",container=TRUE, handler=function(h,...)
		print(svalue(h$action)), action=obj)
	svalue(obj) <- "2"
	## Now click and "2" is printed.

      ## remove handler, block handler, unblockhandler (latter two may not be implemented)
      b <- gbutton("click", container=gwindow())
      id <- addHandlerClicked(b, handler=function(h,...) print("ouch"))
      ## click --> "ouch"
      blockHandler(b, id) ## now click -- nothing
      unblockHandler(b, id) ## now click -- "ouch"
      removeHandler(b, id)  ## all gone now