handleError: Error handling

Description

The handleError function is an internal utility for use by packages extending RGtk2. It decides how to handle an error emitted by GTK+ or one of the other libraries.

Usage

handleError(x, .errwarn)

Arguments

The result of a call to an underlying library.

.errwarn

Whether to emit a warning if there is an error and getOption("RGtk2::newErrorHandling") is not TRUE. The value for this is usually passed by the user through the wrapper.

Value

x, with the error removed if the "RGtk2::newErrorHandling" option is TRUE.

Details

There are currently two modes of error handling in RGtk2. One was introduced with RGtk2 2.20.0 and will eventually replace the older one. Setting the option RGtk2::newErrorHandling to TRUE enables the newer error handling. It is currently not enabled by default, to ease the transition of code.

The original behavior is to return a list from every library function that might raise an error. The error component of the list holds the error, while the primary return value of the underlying function is named retval (and there might be additional return values). If there is no error, the error component is NULL. Otherwise, it holds an object of type simpleError (actually until 2.20.0 this was just a list with a very similar structure).

The new approach, active when getOption("RGtk2::newErrorHandling") returns TRUE, will throw any error (as a simpleError object). An error in the underlying library is an error in R. No error object is returned. This often results in a simpler return value, as a list is no longer necessary unless there are multiple return values from the wrapped function. The .errwarn argument is ignored and will soon be removed from the wrappers along with the old error handling, resulting in a simpler API.