Copyright © 2005-2012 Opera Software ASA. All rights reserved. This file is part of the Opera web browser. It may not be distributed under any circumstances.
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.
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:
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.
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.
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.
TODO: Document OpGadgetUpdateObject, OpGadgetDownloadObject, OpGadgetDownloadCallbackToken, and OpGadgetUpdateInfo.
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.
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.
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.
The OpGadgetManager class
provides RemoveGadget(), which removes the widget and its
related data from disk.
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.
TODO-document the extent of support TODO-document all standards supported
TODO-document the extent of support TODO-document all standards supported
TODO-document all standards supported
The initialisation of the module is handled through the
Opera::InitL() API.
There is one global instance of the
OpGadgetManager
class, which is created when
GadgetsModule::InitL()
is called and destroyed in
GadgetsModule::Destroy().
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.
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.