Initial skeleton for System Indicator API

chrome/common/extensions/api/experimental_system_indicator.idl

Index: chrome/common/extensions/api/experimental_system_indicator.idl
diff --git a/chrome/common/extensions/api/experimental_system_indicator.idl b/chrome/common/extensions/api/experimental_system_indicator.idl
new file mode 100644
index 0000000000000000000000000000000000000000..37c65d42759c8f3cf7c9749ef3053fef8279443a
--- /dev/null
+++ b/chrome/common/extensions/api/experimental_system_indicator.idl
@@ -0,0 +1,53 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// Manages an app's system indicator icon, an image displayed in the system's
+// menubar, system tray, or other visible area provided by the OS.
+namespace experimental.systemIndicator {

[not at google - send to devlin, 2012/11/14 19:53:20]

We should avoid making APIs experimental, it complicates the permission model
(particularly with respect to the comment below). Instead, while it's in
development, restrict it to trunk and in this patch set up the required
permissions/manifest/etc.

[dewittj, 2012/11/16 00:56:28]

Fixed, now restricted to dev channel, but not experimental.

+  enum MenuItemType {separator, normal};
+
+  dictionary MenuDescription {
+    MenuItemNode [] nodes;

[not at google - send to devlin, 2012/11/14 19:53:20]

For better or for worse, we already have an API for constructing and updating
context menus. Have you considered re-using its idioms? We may even be able to
re-use parts of the API and its implementation.

[dewittj, 2012/11/16 00:56:28]

I removed the menuing APIs here and will add access to this menu to the
contextMenus API.

+  };
+
+  dictionary MenuItemNode {
+    MenuItemType type;
+    DOMString id;
+    DOMString? title;
+  };
+
+  dictionary MenuItemClickInfo {
+    DOMString id;
+  };
+
+  interface Functions {

[not at google - send to devlin, 2012/11/14 19:53:20]

This API looks very similar to the extension action APIs (pageAction and
browserAction). I'd like to see that here too -

The system indicator is setup via a manifest property, like pageAction and
browserAction. Like pageAction it's hidden by default but the app/extension can
choose to show it.

It seems to me like a lot of the methods on page actions are valid here -
hide/show/setTitle/setIcon (which neatly combines both the URL and Data
aspects).

The one difference would be the event model, and the menu, but that's fine.

[dewittj, 2012/11/16 00:56:28]

I've changed the names and parameters to more closely match the extension action
APIs.  I haven't added a setTitle method since I was planning to require the
title = the app name for attribution purposes.  Spoofing another app would be
made a little harder in that case.

+    // Set the image to be used as an indicator icon, using a URL relative
+    // to the application root.  This will only allow extension-local resources
+    // to be loaded, so that the offline app experience is better.
+    static void setIconURL(DOMString path);

[not at google - send to devlin, 2012/11/14 19:53:20]

separating each of these methods with blank lines (like one usually does in
header files) would make this easier to read.

[dewittj, 2012/11/16 00:56:28]

New IDL has spaces

+    // Set the image to be used as an indicator icon, using a set of ImageData
+    // objects. These objects should have multiple resolutions so that an
+    // appropriate size can be selected for the given icon size and DPI scaling
+    // settings. Only square ImageData objects will be accepted.
+    static void setIconData([instanceOf=ImageData] object [] images);
+    // Set the list of menu items to be displayed when the user interacts with
+    // the indicator icon.  Use an empty list to disable the menu, sending
+    // click events for both mouse buttons.
+    static void setMenu(MenuDescription menu);
+
+    // Show the icon in the status tray.
+    static void show();
+    // Hide the icon from the status tray.
+    static void hide();
+  };
+
+  interface Events {
+    // fired only when a click on the icon does not result in a menu being

[jianli, 2012/11/14 19:27:41]

nit: capitalize "fired"

[dewittj, 2012/11/16 00:56:28]

Fixed.

+    // shown.

[not at google - send to devlin, 2012/11/14 19:53:20]

It's confusing to me that we have onClicked meaning that the menu *wasn't*
clicked, where for the context menu API we have onClicked meaning that it *was*
clicked.

From the user's perspective - if I was to click an icon and then *not* choose a
menu item, I would expect that to be a no-op, and not give the app/extension a
chance to react to it.

My proposal would be for there to be a single onClicked event, to be called with
a null item if something in the menu wasn't clicked - but to only fire this
event if a menu hasn't been specified.

[dewittj, 2012/11/16 00:56:28]

I think that the confusion is actually in when this event fires.  (I'm removing
onMenuClicked in favor of contextMenus.onClicked)  The systemIndicator.onClicked
event will fire if the system's default behavior for that click is not to open a
menu at all.

For example, on Windows the behavior that is most familiar to users is
right-click opens menu, left-click does either nothing or some app-specific
behavior like focusing the app's main window.  In that case, the onClicked event
will fire on left click, and will not fire if the user right-clicks but does not
select any menu item.

Alternatively, on Mac the standard is for either button to open a menu.  On
these systems, the onClicked event will never fire.

[not at google - send to devlin, 2012/11/16 17:42:04]

Yep that's exactly what I meant.

+    static void onClicked();
+    // Which button fires a click event is system-dependent and will reflect
+    // the most common behavior of icons found in native applications.
+    static void onMenuClicked(MenuItemClickInfo item);
+  };
+};