Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference
Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference |
|
The PluginInterface class provides an interface for Qtopia Desktop's GUI plugins. More...
#include <interfaces/plugin.h>
A PluginInterface is usually implemented when the user needs to interact with a widget in Qtopia Desktop. Often, widgets are created to view or enter information for a particular data set or to transfer files between the desktop the palmtop.
A standard set of PluginInterface plugins is supplied with Qtopia Desktop. These include Contacts (called addressbook in the source), Calendar (datebook), Todo List (todo), Documents (fileinstaller) and Packages (packageinstaller).
In many cases, there is a data set associated with a particular plugin. For example, Contacts has an associated addressbook file. This data set can easily be made syncable by using a MergeInterface and a SyncAppInterface. If the PluginInterface supports a syncable data set the mergeInterface() function must return an appropriate MergeInterface.
The PluginInterface has several methods for integrating the plugin into the Qtopia Desktop user interface. For example, the view() function returns the viewable widget. The plugin can also supply an icon(), a settings() widget (which will appear on a tab in the Qtopia Desktop settings dialog), and a list of actions to be integrated into the menu bar and toolbar.
This interface also defines some state change methods that Qtopia Desktop uses to communicate with the plugins. The plugins get informed about the connection state and about changes to categories with the connected(), disconnected() and categoriesChanged() functions.
The PluginInterface inherits from QComponentInformationInterface which defines some pure virtual methods that are also used by Qtopia Desktop. Most notably, the name() function should return the name that is associated with the plugin in the plugin selector. This is also the display name that is used in the menu bar and toolbar for syncing and in the sync dialog, showing that the plugin is syncing.
Writing an input interface plugin is achieved by subclassing this base class, reimplementing the pure virtual functions init(), cleanup(), icon(), view(), settings(), actionList(), uiDescription(), mergeInterface(), receivedQCopMessage(), connected(), disconnected() and categoriesChanged() and exporting the class with the Q_EXPORT_PLUGIN macro. See the Plugins documentation for details.
See also MergeInterface, SyncAppInterface, ImportInterface, ExportInterface, and Qtopia Desktop Classes.
This enum describes the different sections available on a Qtopia device.
Returns a list of menu and toolbar Actions. This function is used in conjunction with the uiDescription() function.
This function is called whenever a plugin is selected. We recommend initializing the list once internally (e.g. in the plugin's init() function), and then returning it from this function.
Example -- actions that might be used with a Contacts application. (See also the uiDescription() function.)
editCopy = new Action(
"copy", tr( "Copy" ),
IconLoader::loadIcon( "editcopy" ), tr( "&Copy" ),
QAccel::stringToKey( tr("Ctrl+C") ), mainwindow );
editCut = new Action(
"cut", tr( "Cut" ),
IconLoader::loadIcon( "editcut" ), tr( "&Cut" ),
QAccel::stringToKey( tr("Ctrl+X") ), mainwindow );
editPaste = new Action(
"paste", tr( "Paste" ),
IconLoader::loadIcon( "editpaste" ), tr( "&Paste" ),
QAccel::stringToKey( tr("Ctrl+V") ), mainwindow );
editSelectAll = new Action(
"selectall", tr( "Select All" ),
tr( "&Select All" ),
QAccel::stringToKey( tr("Ctrl+A") ), mainwindow );
connect( editCopy, SIGNAL( activated() ), SLOT( slotCopy() ) );
connect( editCut, SIGNAL( activated() ), SLOT( slotCut() ) );
connect( editPaste, SIGNAL( activated() ), SLOT( slotPaste() ) );
connect( editSelectAll, SIGNAL( activated() ), SLOT( slotSelectAll() ) );
actions.append( editCopy );
actions.append( editCut );
actions.append( editPaste );
actions.append( editSelectAll );
This function is called if any of the categories have been changed. Such changes can occur due to synchronization or because they have been edited in Qtopia Desktop.
Categories are used extensively within the Qtopia environment as a means by which users can filter their views. If there is a category change and the plugin makes use of categories, any relevant updating should occur here.
This function is called whenever the plugin is destroyed, e.g. when it is unloaded. This is the appropriate place to perform any cleanups or to save plugin data.
There is no need to destroy widgets since these will be destroyed in the normal Qt way.
When a connection is established by Qtopia Desktop with a Qtopia device, this method is called. The pdaMajorVersion and pdaMinorVersion provide version information about the Qtopia device to the plugins. The arch provide information about the device architecture.
The protocols may change over time, so the plugins may need to know the version of the Qtopia device that they are talking to, for example, to know which QCop messages can be sent or for details of the filesystem.
If your plugin presents live information about the Qtopia device (such as Documents that are currently on the device), then this live information should be initialized here.
This function is called to notify the plugin that Qtopia Desktop is no longer connected with the Qtopia device.
If live information about the Qtopia device is being shown by the plugin, we recommend that the information is shown to be no longer live, for example by disabling the widgets that display it.
Returns a 32x32 QPixmap which will be displayed in the plugin selector panel on the left hand side of Qtopia Desktop's main window.
This function is called whenever the plugin is loaded. It is passed an interface to Qtopia Desktop, iface. It is also passed Qtopia Desktop's mainwindow, which is useful if any QActions need to be set up. It is safe for the plugin to keep both these pointers.
If this plugin supports syncing, it must return a MergeInterface from this function. If it does not support syncing it should return 0.
When a QCop message is received from the Qtopia device, Qtopia Desktop notifies those plugins for which the message is relevant. Applications on the Qtopia device can communicate with Qtopia Desktop using this inter-process communication mechanism.
See also QCopEnvelope.
Returns which section this plugin belongs to. This is not currently used, but might be used in the future to make the interface of Qtopia Desktop more similar to Qtopia on the device.
Returns a widget that the user can use to set any options that apply to this plugin. The returned widget will appear in a tab of the Qtopia Desktop settings dialog, which is also its parent widget.
May return 0 if there are no user-settable options.
See also SettingsWidget.
Returns the details of the plugin's menu items and toolbar buttons in an XML formatted QString.
This function is used in conjunction with actionList().
The XML format used by this function is modelled on the following:
<XMLUI>
<MenuBar>
<Menu name="[menu item name]" text="[translated display name]">
<Action name="[the associated Action string id]"/>
<Separator/>
</Menu>
</MenuBar>
<ToolBar>
<Action name="[the associated Action string id]"/>
</Separator>
</ToolBar>
</XMLUI>
Example -- the XML string that corresponds with the example given in the actionList() function:
QString toXML( const QString& source )
{
QString dest = source;
dest = dest.replace( QRegExp( "&" ), "&" );
dest = dest.replace( QRegExp( "<" ), "<" );
dest = dest.replace( QRegExp( ">" ), ">" );
return dest;
}
QString MyApp::uiDescription()
{
if ( !ui.isEmpty() )
return ui;
QTextOStream ts( &ui );
// XML header
ts << "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
ts << "<!DOCTYPE QXMLUI>\n";
ts << "<XMLUI>\n";
// menu bar
ts << "<MenuBar>\n";
// edit menu
ts << "<Menu name=\"edit\" text=\"" <<
toXML( tr( "&Edit" ) ) << "\">\n";
ts << "<Action name=\"copy\"/>\n";
ts << "<Action name=\"cut\"/>\n";
ts << "<Action name=\"paste\"/>\n";
ts << "<Separator/>\n";
ts << "<Action name=\"selectall\"/>\n";
ts << "</Menu>\n";
// main toolbar
ts << "<ToolBar name=\"" <<
toXML( tr("Main") ) << "\" location=\"top\">\n";
ts << "<Action name=\"copy\"/>\n";
ts << "<Action name=\"cut\"/>\n";
ts << "<Action name=\"paste\"/>\n";
ts << "</ToolBar>\n";
ts << "</XMLUI>\n";
return ui;
}
Returns the widget that should be shown in Qtopia Desktop's main window to represent this plugin. The parent is used for the plugin widget's constructor.
This file is part of the Qtopia platform, copyright © 1995-2005 Trolltech, all rights reserved.
| Copyright © 2005 Trolltech | Trademarks | Qtopia version 2.2.0
|