# Gadgets module

## Introduction

The gadgets module implement management of Web Widgets. It is called gadgets simply because the name widgets was already taken, and in its documentation the words “widgets” and “gadgets” are used interchangibly. All user-visible and customer-visible documentation should document it as “widgets”.

The gadgets module currently support regular widgets (both the old Opera widgets and the W3C Widgets 1.0 specification), and, if enabled by the feature system, Unite applications and Opera Extensions.

Please note that the implementation of most of the APIs accessible to Widgets are implemented elsewhere, for example in the DOM module.

## Interface overview and API documentation

For detailed information on how to use the gadgets module in Opera and the module's public API, please refer to the API documentation. The documentation needs to be generated by Doxygen.

The visible API consists largely of the following classes:

OpGadgetManager

  Responsible for the over-all managing of active and inactive widgets. It maintains a list of all OpGadget instances (be they Widgets, Unite Applications or Opera Extensions), as well as a list of all OpGadgetClass instances. Its API consists mainly of managerial functionality, like creating, destroying, enumerating and querying widgets, as well as some utility functionality used by the other classes in the widget, and which need access to state information.

OpGadget

  Representation of a single instance of a widget. Responsible for holding state information about the widget instance. Its API contains of interface functions used to connect the information about the widget to the DOM interface and other parts of the code. It also has several APIs that proxy information from the OpGadgetClass instance; each OpGadget has a pointer to an OpGadgetClass instance.

OpGadgetClass

  Representation of an installed widget. Responsible for parsing its configuration and hold its configuration information. The OpGadgetClass API has access to the information about the widget's configuration and installed files, most of which are proxied through the OpGadget class, so it does not need to be accessed directly that often.

Gadget update classes

  TODO: Document OpGadgetUpdateObject, OpGadgetDownloadObject, OpGadgetDownloadCallbackToken, and OpGadgetUpdateInfo.

OpGadgetInstallObject

  Represents a temporary widget which can be installed later on. The installer can be filled with data incrementally by appending bytes to it. This is quite useful if you need to transfer widget data from remote and need to transfer only a certain amount of data at a time. Note: Only available if API_GADGET_INSTALLER is imported.

Utility classes
  In addition to these, there are some utility classes: OperaWidgets generates the opera:widgets and opera:extensions documents (Widget Manager and Extensions Manager), OperaUnite generates the opera:unite document (Unite Application Manager), and GadgetsModule contains initialization and termination support.

## Use-cases

### Installing a widget

To install a widget, parsing its configuration file and returning an OpGadget instance to be used, the OpGadgetManager class provides `CreateGadget()`. The gadget retrieved through this interface will be added to the list of gadgets managed by OpGadgetManager.

This does not copy any files, this has to be done by the caller.

### Displaying a widget

The OpGadgetManager class provides `OpenGadget()` in several variations, which can be used to display a widget.

If you provide it with a path to a gadget, an OpGadget instance will be created and opened. If provided with an OpGadget instance, it will cause this to be displayed.

### Uninstalling a widget

The OpGadgetManager class provides `RemoveGadget()`, which removes the widget and its related data from disk.

## Supported standards

Please note that the gadgets module implements the packaging, installation and upgrading related parts of the specifications below. The specifications also define specific DOM interfaces. These interfaces are implemented by the dom module.

### W3C published standards

TODO-document the extent of support TODO-document all standards supported

- Widgets 1.0: Packaging and Configuration
- Widgets 1.0: APIs and Events
- Widgets 1.0: Digital Signatures

### Opera published standards

TODO-document the extent of support TODO-document all standards supported

- Opera Widgets Specification 1.0 third edition
- Opera Unite
- Opera Extensions
  - Opera Extensions: Background Process
  - Opera Extensions: Buttons
  - Opera Extensions: Clipboard
  - Opera Extensions: Menus
  - Opera Extensions: Panels
  - Opera Extensions: Scope
  - Opera Extensions: Tabs
  - Opera Extensions: User Content

### Other published standards

TODO-document all standards supported

## Implementation and design

### Design principles

### Initialisation

The initialisation of the module is handled through the `Opera::InitL()` API.

### Memory management

#### Stack usage

#### Static memory usage

There is one global instance of the OpGadgetManager class, which is created when `GadgetsModule::InitL()` is called and destroyed in `GadgetsModule::Destroy()`.

#### OOM policies

Most functions detect out-of-memory errors and return them to the caller, making it up to the caller to make any necessary measures for such problems.

### Performance

The OpGadgetManager does enumerate all installed widgets on start-up, which can cause delays if many widgets are installed, especially if the file system is slow.

## See also

## References