Add new MouseCursor interface for setting the mouse cursor.

ppapi/api/ppb_mouse_cursor.idl

+/* 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.
+ */
+
+/**
+ * This file defines the <code>PPB_MouseCursor</code> interface for setting
+ * the mouse cursor.
+ */
+
+label Chrome {
+  M19 = 1.0
+};
+
+/**
+ * The <code>PP_MouseCursor_Type</code> enumeration lists the available stock
+ * cursor types.
+ */
+[assert_size(4), notypedef]
+enum PP_MouseCursor_Type {
+  PP_MOUSECURSOR_TYPE_CUSTOM = -1,
+  PP_MOUSECURSOR_TYPE_POINTER = 0,
+  PP_MOUSECURSOR_TYPE_CROSS = 1,
+  PP_MOUSECURSOR_TYPE_HAND = 2,
+  PP_MOUSECURSOR_TYPE_IBEAM = 3,
+  PP_MOUSECURSOR_TYPE_WAIT = 4,
+  PP_MOUSECURSOR_TYPE_HELP = 5,
+  PP_MOUSECURSOR_TYPE_EASTRESIZE = 6,
+  PP_MOUSECURSOR_TYPE_NORTHRESIZE = 7,
+  PP_MOUSECURSOR_TYPE_NORTHEASTRESIZE = 8,
+  PP_MOUSECURSOR_TYPE_NORTHWESTRESIZE = 9,
+  PP_MOUSECURSOR_TYPE_SOUTHRESIZE = 10,
+  PP_MOUSECURSOR_TYPE_SOUTHEASTRESIZE = 11,
+  PP_MOUSECURSOR_TYPE_SOUTHWESTRESIZE = 12,
+  PP_MOUSECURSOR_TYPE_WESTRESIZE = 13,
+  PP_MOUSECURSOR_TYPE_NORTHSOUTHRESIZE = 14,
+  PP_MOUSECURSOR_TYPE_EASTWESTRESIZE = 15,
+  PP_MOUSECURSOR_TYPE_NORTHEASTSOUTHWESTRESIZE = 16,
+  PP_MOUSECURSOR_TYPE_NORTHWESTSOUTHEASTRESIZE = 17,
+  PP_MOUSECURSOR_TYPE_COLUMNRESIZE = 18,
+  PP_MOUSECURSOR_TYPE_ROWRESIZE = 19,
+  PP_MOUSECURSOR_TYPE_MIDDLEPANNING = 20,
+  PP_MOUSECURSOR_TYPE_EASTPANNING = 21,
+  PP_MOUSECURSOR_TYPE_NORTHPANNING = 22,
+  PP_MOUSECURSOR_TYPE_NORTHEASTPANNING = 23,
+  PP_MOUSECURSOR_TYPE_NORTHWESTPANNING = 24,
+  PP_MOUSECURSOR_TYPE_SOUTHPANNING = 25,
+  PP_MOUSECURSOR_TYPE_SOUTHEASTPANNING = 26,
+  PP_MOUSECURSOR_TYPE_SOUTHWESTPANNING = 27,
+  PP_MOUSECURSOR_TYPE_WESTPANNING = 28,
+  PP_MOUSECURSOR_TYPE_MOVE = 29,
+  PP_MOUSECURSOR_TYPE_VERTICALTEXT = 30,
+  PP_MOUSECURSOR_TYPE_CELL = 31,
+  PP_MOUSECURSOR_TYPE_CONTEXTMENU = 32,
+  PP_MOUSECURSOR_TYPE_ALIAS = 33,
+  PP_MOUSECURSOR_TYPE_PROGRESS = 34,
+  PP_MOUSECURSOR_TYPE_NODROP = 35,
+  PP_MOUSECURSOR_TYPE_COPY = 36,
+  PP_MOUSECURSOR_TYPE_NONE = 37,
+  PP_MOUSECURSOR_TYPE_NOTALLOWED = 38,
+  PP_MOUSECURSOR_TYPE_ZOOMIN = 39,
+  PP_MOUSECURSOR_TYPE_ZOOMOUT = 40,
+  PP_MOUSECURSOR_TYPE_GRAB = 41,
+  PP_MOUSECURSOR_TYPE_GRABBING = 42
+};
+
+/**
+ * The <code>PPB_MouseCursor</code> allows setting the mouse cursor.
+ */
+interface PPB_MouseCursor {
+  /**
+   * Sets the given mouse cursor. The mouse cursor will be in effect whenever
+   * the mouse is over the given instance until it is set again by another
+   * call. Note that you can hide the mouse cursor by setting it to the
+   * <code>PP_MOUSECURSOR_TYPE_NONE</code> type.
+   *
+   * This function allows setting both system defined mouse cursors and
+   * custom cursors. To set a system-defined cursor, pass the type you want
+   * and set the custom image to 0 and the hot spot to NULL. To set a custom
+   * cursor, set the type to <code>PP_MOUSECURSOR_TYPE_CUSTOM</code> and
+   * specify your image and hot spot.
+   *
+   * @param[in] instance A <code>PP_Instance</code> indentifying the instance
+   * that the mouse cursor will affect.
+   *
+   * @param[in] type A <code>PP_MouseCursor_Type</code> identifying the type of
+   * mouse cursor to show.
+   *
+   * @param[in] image A <code>PPB_ImageData</code> resource identifying the
+   * custom image to set when the type is
+   * <code>PP_MOUSECURSOR_TYPE_CUSTOM</code>. The image must be less than 32
+   * pixels in each direction and must be of the system's native image format.
+   * When you are specifying a predefined cursor, this parameter must be 0.
+   *
+   * @param[in] hot_spot When setting a custom cursor, this idenfifies the
+   * pixel position within the given image of the "hot spot" of the cursor.
+   * When specifying a stock cursor, this parameter is ignored.
+   *
+   * @return PP_TRUE on success, or PP_FALSE if the instance or cursor type
+   * was invalid, or if the image too large.

[dmichael (off chromium), 2012/03/26 17:43:17]

nit: image "is" too large

+   */
+  PP_Bool SetCursor([in] PP_Instance instance,

[dmichael (off chromium), 2012/03/26 17:43:17]

This could have been 2 functions, maybe
SetCursor(type)
SetCustomCursor(image, hot_spot)
That seems clearer from an end-developer perspective. What's the rationale for
doing it in 1?

[brettw, 2012/03/26 17:59:30]

A previous version of this patch actually did what you're suggesting. The
initial reason I gave up was that we were going to try to get this into 19 and
changing the signature would require me to write new proxies in both IPC and
NaCl, which was more work than I wanted. And we have to keep a function around
with this signature anyway since Flash needs it.

I think this is OK even though this is no longer M19 because it doesn't feel
like a function signature or behavior that's out-of-place. It seems pretty clear
and easy enough to use, and saves us the overhead of having to have thunks and
APIs and proxies for two different messages.

[dmichael (off chromium), 2012/03/27 15:48:44]

I can live with it either way. The two behaviors seem different enough (enough
so that their paramaters are effectively disjoint) that it might be easier to
understand if separated out. I still prefer that, just for the clarity of the
API. And you could still do all the backing code (except the thunking) the same
way.

But I think this way's fine too if you prefer it.

[brettw, 2012/03/27 16:10:47]

It might be nice, but I don't think it's worth the effort to change for such a
minor improvement, the API is easy enough to use.

+                    [in] PP_MouseCursor_Type type,
+                    [in] PP_Resource image,
+                    [in] PP_Point hot_spot);
+};