Contents
Overview
Display API
Overview
Getting Started
Google Desktop can host applications and plug-ins
that provide useful visual information to the user.
GD can display content from these applications and
plug-ins in the Google Desktop Sidebar and the Notifier/alert window.
To create a display module that works with Google Desktop,
you need
-
Programming tools to create a plug-in and an
installer.
-
Programming knowledge of the Microsoft Windows Component Object
Model (COM).
|
|
|
Development Process Overview
To develop a display plug-in, start by downloading the SDK, in
particular the GoogleDesktopDisplayAPI.idl
file. We recommend using Microsoft Visual Studio for developing
the plug-in.
You will then need to write code (in any COM compatible
language) to:
-
Register your plug-in with Google Desktop (required).
-
Implement the interfaces required by Google Desktop Display API.
-
Unregister your plug-in with Google Desktop when
uninstalling.
We recommend that you look over the sample code provided with
the SDK. Please note that the sample code examples have their GUIDs hardcoded,
so if you choose to reuse code from there you must change the interfaceIDs,
classIDs, and libIDs.
Display API
Registering Display Components
Google Desktop does not accept unregistered components.
Display
component registration is a one-time process done using the IGoogleDesktopRegistrar
interface, and should be done during component installation. As part of the
registration process, the component must provide its GUID as well as
information about itself that will be added to the GD preferences UI.
As part of its own uninstallation process, a component should
unregister itself with Google Desktop.
Component Registration Interface Summary
The following summarizes the interface and its methods. All
method return values are of type HRESULT .
interface IGoogleDesktopComponentRegister: IDispatch
-
Note: Components are required to to call this
interface to register themselves with Google Desktop before they can interact
with any APIs or other provided services.
-
Note: The registration process consists of a call to
StartComponentRegistration followed by individual
registrations for various services
obtained through GetRegistrationInterface
and finished by a call to FinishComponentRegistration.
For display components, the
registration progid is "GoogleDesktop.DisplayPluginRegistration"
and the interface is IGoogleDesktopRegisterDisplayPlugin .
-
StartComponentRegistration : Must be invoked by any
component to initiate the registration process.
-
Arguments:
-
BSTR component_guid_or_progid : The component's GUID
or ProgID.
-
VARIANT component_description: A SAFEARRAY
of pairs, where the first element is a descriptive parameter name
and the second element is that parameter's value. The method expects only the
following three required parameters, which should be given in this order.
-
"
Title ": Component title that
will be displayed on the GD preferences page.
-
"
Description ": Component
description that will be displayed on the GD preferences page.
-
"
Icon ": A string pointing to
an ICON resource, of the form "c:\program files\boo\comp.dll,23 ".
This icon may be used to indicate the component and its results on various GD
pages.
-
Returns:
-
S_OK if successful.
-
E_COMPONENT_ALREADY_REGISTERED if this component has
already been registered with GD.
-
Appropriate error on failure, such as an unregistered component
classID or appID, component prohibited by policy, etc.
-
GetRegistrationInterface : Provides the requested
type of registration interface.
-
Arguments:
-
BSTR registration_type : a stringified CLSID or a
progid to the type of registration required. The following progids are defined:
"GoogleDesktop.ExtensionRegistration",
"GoogleDesktop.DisplayPluginRegistration",
"GoogleDesktop.ActionRegistration".
-
[out, retval] IUnknown **registration_interface :
provides the requested registration mechanism.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
FinishComponentRegistration : Must be invoked
to finish the registration process.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure, such as an unregistered component
classID or appID, component prohibited by policy, etc.
-
UnregisterComponent
-
Arguments:
-
BSTR component_guid_or_progid : the same GUID used
when registering the component.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
Component Registration Code Template
The following template registers a component.
Note that this
registration should only be done once, not every time the plug-in starts.
To register a component in C++ (for C#, please
see below):
CComPtr<IGoogleDesktopRegistrar> spRegistrar;
HRESULT hr;
hr = spRegistrar.CoCreateInstance(CLSID_GoogleDesktopRegistrar);
if (SUCCEEDED(hr)) {
ATLASSERT(spRegistrar != NULL);
// Component description is 6 strings
CComSafeArray<VARIANT> arr_descr(6);
arr_descr.SetAt(0, CComVariant(L"Title"));
arr_descr.SetAt(1, CComVariant(title));
arr_descr.SetAt(2, CComVariant(L"Description"));
arr_descr.SetAt(3, CComVariant(description));
arr_descr.SetAt(4, CComVariant(L"Icon"));
arr_descr.SetAt(5, CComVariant(icon));
// our CLSID in string format
CComBSTR our_clsid(clsid);
// Wrap description array in variant
CComVariant descr(arr_descr.m_psa);
// and register
hr = spRegistrar->StartComponentRegistration(our_clsid, descr);
if (FAILED(hr))
return hr;
// success, now register as a display component.
// This two step registration allows the same plugin to implement multiple
// components
CComPtr<IGoogleDesktopRegisterDisplayPlugin> spRegistration;
CComBSTR sidebar_registrar_progid("GoogleDesktop.DisplayPluginRegistration");
hr = spRegistrar->GetRegistrationInterface(sidebar_registrar_progid,
reinterpret_cast<IUnknown**>(&spRegistration));
ATLASSERT(FAILED(hr) || spRegistration);
if (SUCCEEDED(hr)) {
// set to true if you use the notifier
bool show_notifications = false;
hr = spRegistration->RegisterPlugin(our_clsid, (shows_notifications) ?
VARIANT_TRUE : VARIANT_FALSE);
if (SUCCEEDED(hr)) {
hr = spRegistrar->FinishComponentRegistration();
}
}
To
register a component in C#:
try {
// Create the registrar object
GoogleDesktopRegistrarClass registrar = new GoogleDesktopRegistrarClass();
// Start component registration by specifying our attributes
object[] descriptions = {
"Title", pluginName, // a string
"Description", pluginName,
"Icon", ""
};
registrar.StartComponentRegistration(controlGuid, descriptions);
// A single component can register for multiple plugins with Google
// Desktop. Here we register a single display plugin.
IGoogleDesktopRegisterDisplayPlugin displayRegistration =
(IGoogleDesktopRegisterDisplayPlugin)
registrar.GetRegistrationInterface("GoogleDesktop.DisplayPluginRegistration");
displayRegistration.RegisterPlugin(controlGuid, false);
// Done with component registration.
registrar.FinishComponentRegistration();
} catch (Exception e) {
MessageBox.Show("Exception thrown during registration. Description=" +
e.Message);
}
To unregister a component in C++:
CComPtr<IGoogleDesktopRegistrar> spRegistrar;
HRESULT hr;
hr = spRegistrar.CoCreateInstance(CLSID_GoogleDesktopRegistrar);
if (SUCCEEDED(hr)) {
// our CLSID in string format
CComBSTR bstrClsid(clsid);
hr = spRegistrar->UnregisterComponent(bstrClsid);
}
To unregister a component in C#:
try {
// Create the registrar object
GoogleDesktopRegistrarClass registrar = new GoogleDesktopRegistrarClass();
// Unregister ourselves
registrar.UnregisterComponent(controlGuid);
} catch (Exception e) {
MessageBox.Show("Exception thrown during registration. Description=" + e.Message);
}
Displaying and Interacting with Display Plug-ins
After a successful registration with Google Desktop, a component
can use the Display APIs to display itself and interact with the
GD
framework.
Each Sidebar plug-in is given a
rectangular window of space (negotiated between the Sidebar and the plug-in) and
optionally a title bar. (Notifier display plug-ins appear off to
the side without a title bar.)
The title bar holds an icon and a title string. The
entire region devoted to a plug-in is called the plug-in's
tile
. The users will be able to resize a plug-in's tile according to their
preference.
The Display API is a set of COM interfaces, some of which are
exposed by Google Desktop and the rest implemented by the plug-ins.
Plug-ins must be implemented as ActiveX controls. They
may optionally expose
some of the interfaces defined in the Display API.
(It is possible to create plug-ins that don't use the Display API.
However as expected these plug-ins can not use the features offered
by Google Desktop.)
The Display API defines the following interfaces:
-
IGoogleDesktopDisplaySite: This
is the interface exposed by GD most useful to its display plug-ins.
-
IGoogleDesktopDisplayPlugin: All
display plug-ins aware of GD must implement this interface.
-
IGoogleDesktopDisplayPluginHelper: A
helper interface. This interface implements a complete display plug-in and can
display and manage data given by the plug-in. Plug-in developers are recommended
to use this component (through COM aggregation)
to maintain a standard look and feel to the Sidebar.
-
IGoogleDesktopDisplayContentItem:
Plug-ins create objects implementing this interface and pass them
the display Plug-in Helper functions to display and manage their
content.
-
IGoogleDesktopDisplayContentItemHandler:
Plug-ins which aggregate and use the above helper object implement this to
receive callbacks about user interaction with the displayed
content.
-
IGoogleDesktopDisplayDetailsViewHelper:
A Display component that can be instantiated and used by plug-ins to
show more details about a particular content item.
-
IGoogleDesktopDisplayDetailsViewHandler:
Plug-ins using the above helper object implement this interface to receive
callbacks about user interaction with the displayed content
details.
In addition to the above interfaces, Google Desktop also uses the following
standard COM interfaces.
-
IContextMenu: Google Desktop displays a
context menu when the user right-clicks or selects the appropriate icon in a
Sidebar panel. This context menu will include standard menu items created by
Google Desktop and can also include items added by the plug-in.
Display plug-ins that need to
add items to the context menu must implement the IContextMenu interface and
Google Desktop will use this interface to add and invoke plug-in
specific context menu items.
-
IPersistStreamInit:
Display plug-ins with persistent data (such as settings) must implement this
interface and Google Desktop will use this interface to load and
store the plug-in's persistent data.
-
ISpecifyPropertyPages/IPropertyPage:
Plug-ins having configurable options will implement these two interfaces to
manage their options in property pages.
A display plug-in developer can implement a UI himself
or use the helper UI framework to
display information and get the user input in a uniform way.
In the first case the developer is required to
implement only the IGoogleDesktopDisplayPlugin
interface.
interface IGoogleDesktopDisplayPlugin
-
OnCommand : Called by GD with any of the
GDD_CMD_* identifiers to execute the specific command.
-
Arguments:
-
GoogleDesktopDisplayPluginCommand command : One of
the GoogleDesktopDisplayPluginCommand (e.g. GDD_CMD_STATE_MINIMIZED).
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
OnDisplayStateChange : Called by GD with any of the
GDD_TILE_DISPLAY_STATE_* identifiers to inform about display
state changes. One especially interesting state is
GDD_TILE_DISPLAY_STATE_POPPED_OUT; this signals that the user
clicked the pop-out button (labeled <<).
Your plug-in might handle this by
displaying more content. By default all content shown in the
plug-in's tile in the sidebar will be shown in the pop-out view.
-
Arguments:
-
GoogleDesktopDisplayTileDisplayState state : One of
the GoogleDesktopDisplayTileDisplayState (e.g. GDD_TILE_DISPLAY_STATE_MINIMIZED).
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
GetInfo : Called by GD to get plug-in
info and inform it about its position.
-
Arguments:
-
[in, out] GoogleDesktopDisplayTileInfo *tile_info :
Data structure containing in/out information. The plug-in need to set the
required information in this struct.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
Several methods are available on the IGoogleDesktopDisplaySite
interface that can be used by a plug-in to control its title, context menu,
display details windows etc.
Developers who wish to take advantage of the helper UI framework
can use the IGoogleDesktopDisplayPluginHelper interface
(together with (IGoogleDesktopDisplayContentItem and
IGoogleDesktopDisplayPluginHandler)
which implements a complete display plug-in. The developer can add content items
and receive callbacks about the user interaction with the content. Below are
some of the interesting methods on these interfaces.
interface IGoogleDesktopDisplayPluginHelper: IDispatch
-
put_title : Set the plug-in's title string.
-
Arguments:
-
BSTR title : String to use for the title.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
SetFlags : Set the plug-in's flags that will be passed
onto GD when requested and content flags specifying properties of
all content items.
-
Arguments:
-
GoogleDesktopDisplayPluginFlags plugin_flag :
Combination of plug-in flags.
-
GoogleDesktopDisplayContentFlags content_flags :
Combination of content flags.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
SetIcons : Set the icons used for this plug-in.
The small icon is used in the title and the large icon is used for
notifications/about dialog.
-
Arguments:
-
IPicture *small_icon :
Picture to use for small icon (10x10 pixels).
-
IPicture *large_icon :
Picture to use for large icon (32x32 pixels).
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
put_about_text : Set the text to display
in the plug-in's about dialog. If you do not call this function, the plug-in will receive
the GDD_CMD_ABOUT_DLG command when the about dialog is invoked.
-
Arguments:
-
BSTR about_text :
Text to show in the about dialog.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
AddContentItem : Add the given item to the displayed
content.
-
Arguments:
-
IGoogleDesktopDisplayContentItem *item : Item to add.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
RemoveContentItem : Removes the item to the displayed
content.
-
Arguments:
-
IGoogleDesktopDisplayContentItem *item : Item to
remove.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
RemoveAllContentItems : Removes all the displayed
content.
-
Arguments: none
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
get_content_items : Get the current list of items.
This list includes both currently displayed items and those that were added
recently and not yet displayed.
-
Arguments:
-
[out, retval] SAFEARRAY(VARIANT)* items :
OUT parameter where the array of items is stored and returned.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
get_max_content_items : Get method for the max number
of items that this plug-in can display.
-
Arguments:
-
UINT *max_items : OUT parameter
where the max number of items is returned.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
The IGoogleDesktopDisplayContentItem interface encapsulates one content
item. Typical content items include an icon, some text and flags indicating how
the item should be rendered. For example a plug-in showing a list of contacts
can have 5 content items (one for each contact) and each of these items show
the presence status and the name of the contact. When the user clicks on a
content item the plug-in will receive a notification in it's ContentHandler
interface. A plug-in can create COM objects implementing the IGoogleDesktopDisplayContentItem
interface or it can use the helper implementation provided by the
ContentItemHelper object.
The IGoogleDesktopDisplayContentItemHandler interface handles events
related to a content item. The IGoogleDesktopDisplayContentItemHelper object
provided by the API implements this interface and provides default
implementations for DrawItem and ToggleItemPinnedState methods. If a plug-in
wishes to handle the other methods or to override the default implementations
it can implement this interface in it's ContentItem object and it will be
called before the default processing is done. If the plug-in's implementation
returns E_NOTIMPL then default processing is done for the method.
Details View
The Details View is a UI feature that allows a display
plug-in to display additional
information in a separate window/panel outside the Sidebar. Plug-ins taking advantage of this
feature can also receive notifications and events from the details view. The Detail View is
exposed through the interface IGoogleDesktopDisplayDetailsViewHelper.
interface IGoogleDesktopDisplayDetailsViewHelper: IDispatch
-
SetContent : Set the content to be displayed in the details view content pane.
-
Arguments:
-
BSTR source : Origin of the content, NULL if not relevant.
-
DATE time_created : Time at which the content was created (in UTC).
-
BSTR text : Actual text of the content, without any formatting.
-
VARIANT_BOOL time_absolute : True if the time displayed is in absolute format or relative to current.
-
GoogleDesktopDisplayContentItemLayout content_layout : Layout of the details, usually the same layout as plug-in content.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
-
SetContentFromItem : Set the content to be displayed directly from an item.
-
Arguments:
-
IGoogleDesktopDisplayContentItem* item : The item to be displayed.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
Plug-ins should implement the IGoogleDesktopDisplayDetailsViewHandler interface
if they use the DetailsViewHelper object and want to receive notifications and events from the details view.
interface IGoogleDesktopDisplayDetailsViewHandler: IUnknown
-
ProcessDetailsViewFeedback : Called when the details view shown by this plug-in is closed.
-
Arguments:
-
GoogleDesktopDisplayDetailsViewFlags flags : Combination of GoogleDesktopDisplayDetailsViewFlags indicating why it
was closed and additional info such as if the user had given negative feedback in the details view.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
Notifier
The Google Desktop Sidebar offers a visual notification mechanism. Content items can be displayed
in a special UI panel that slides from the Sidebar.
These are known as "notifiers" or "alerts."
interface IGoogleDesktopDisplayNotifier: IDispatch
-
AddNotification : Queues a new content item to the notifier.
-
Arguments:
-
IGoogleDesktopDisplayContentItem* item : Item to be displayed in the UI.
-
Returns:
-
S_OK if successful.
-
Appropriate error on failure.
|