Index: ppapi/cpp/view.h |
diff --git a/ppapi/cpp/view.h b/ppapi/cpp/view.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..913c99ca4258b1d5b8648360c3c2d27612d58a81 |
--- /dev/null |
+++ b/ppapi/cpp/view.h |
@@ -0,0 +1,115 @@ |
+// Copyright (c) 2011 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. |
+ |
+#ifndef PPAPI_CPP_VIEW_H_ |
+#define PPAPI_CPP_VIEW_H_ |
+ |
+#include "ppapi/cpp/resource.h" |
+#include "ppapi/cpp/rect.h" |
+#include "ppapi/cpp/size.h" |
+ |
+namespace pp { |
+ |
+class View : public Resource { |
+ public: |
+ /// Default constructor for creating an is_null() <code>View</code> object. |
+ View(); |
+ |
+ /// Creates a View resource, taking and holding an additional reference to |
+ /// the given resource handle. |
+ View(PP_Resource view_resource); |
+ |
+ /// <code>GetRect()</code> returns the rectangle of the instance |
+ /// associated with the view changed notification relative to the upper left |
+ /// of the browser viewport. This position changes when the page is scrolled. |
+ /// |
+ /// The returned rectangle may not be inside the visible portion of the |
+ /// viewport if the instance is scrolled off the page. Therefore, the |
+ /// position may be negative or larger than the size of the page. The size |
+ /// will always reflect the size of the plugin were it to be scrolled |
+ /// entirely into view. |
+ /// |
+ /// In general, most plugins will not need to worry about the position of the |
+ /// instance in the viewport, and only need to use the size. |
+ /// |
+ /// |
+ /// @return The rectangle of the instance. |
+ Rect GetRect() const; |
+ |
+ /// <code>IsFullscreen()</code> returns whether the instance is currently |
+ /// displaying in fullscreen mode. |
+ /// |
+ /// @return <code>true</code> if the instance is in full screen mode, |
+ /// or <code>false</code> if it's not or the resource is invalid. |
+ // |
+ bool IsFullscreen() const; |
+ |
+ /// <code>IsVisible()</code> returns true if the instance is plausibly |
+ /// visible to the user. You should use this flag to throttle or stop updates |
+ /// for invisible plugins. |
+ /// |
+ /// Thie measure incorporates both whether the instance is scrolled into |
+ /// view (whether the clip rect is nonempty) and whether the page is |
+ /// plausibly visible to the user (<code>IsPageVisible()</code>). |
+ /// |
+ /// @return <code>true</code> if the instance is plausibly visible to the |
+ /// user, <code>false</code> if it is definitely not visible. |
+ bool IsVisible() const; |
+ |
+ /// <code>IsPageVisible()</code> determines if the page that contains the |
+ /// instance is visible. The most common cause of invisible pages is that |
+ /// the page is in a background tab in the browser. |
+ /// |
+ /// Most applications should use <code>IsVisible()</code> rather than |
+ /// this function since the instance could be scrolled off of a visible |
+ /// page, and this function will still return true. However, depending on |
+ /// how your plugin interacts with the page, there may be certain updates |
+ /// that you may want to perform when the page is visible even if your |
+ /// specific instance isn't. |
+ /// |
+ /// @return <code>true</code> if the instance is plausibly visible to the |
+ /// user, <code>false</code> if it is definitely not visible. |
+ bool IsPageVisible() const; |
+ |
+ /// <code>GetClip()</code> returns the clip rectangle relative to the upper |
+ /// left corner of the instance. This rectangle indicates which parts of the |
+ /// instance are scrolled into view. |
+ /// |
+ /// If the instance is scrolled off the view, the return value will be |
+ /// (0, 0, 0, 0). this state. This clip rect does <i>not</i> take into account |
+ /// page visibility. This means if the instance is scrolled into view but the |
+ /// page itself is in an invisible tab, the return rect will contain the |
+ /// visible rect assuming the page was visible. See |
+ /// <code>IsPageVisible()</code> and <code>IsVisible()</code> if you want |
+ /// to handle this case. |
+ /// |
+ /// Most applications will not need to worry about the clip. The recommended |
+ /// behavior is to do full updates if the instance is visible as determined by |
+ /// <code>IsUserVisible()</code> and do no updates if not. |
+ /// |
+ /// However, if the cost for computing pixels is very high for your |
+ /// application or the pages you're targeting frequently have very large |
+ /// instances with only portions visible, you may wish to optimize further. |
+ /// In this case, the clip rect will tell you which parts of the plugin to |
+ /// update. |
+ /// |
+ /// Note that painting of the page and sending of view changed updates |
+ /// happens asynchronously. This means when the user scrolls, for example, |
+ /// it is likely that the previous backing store of the instance will be used |
+ /// for the first paint, and will be updated later when your application |
+ /// generates new content. This may cause flickering at the boundaries when |
+ /// scrolling. If you do choose to do partial updates, you may want to think |
+ /// about what color the invisible portions of your backing store contain |
+ /// (be it transparent or some background color) or to paint a certain |
+ /// region outside the clip to reduce the visual distraction when this |
+ /// happens. |
+ /// |
+ /// @return The rectangle representing the visible part of the instance. |
+ /// If the resource is invalid, the empty rect is returned. |
+ Rect GetClipRect() const; |
+}; |
+ |
+} // namespace pp |
+ |
+#endif // PPAPI_CPP_VIEW_H_ |