Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 1 | // Copyright (c) 2012 The Chromium Authors. All rights reserved. |
| 2 | // Use of this source code is governed by a BSD-style license that can be |
| 3 | // found in the LICENSE file. |
| 4 | |
| 5 | #ifndef PPAPI_CPP_VIEW_H_ |
| 6 | #define PPAPI_CPP_VIEW_H_ |
| 7 | |
| 8 | #include "ppapi/cpp/resource.h" |
| 9 | #include "ppapi/cpp/rect.h" |
| 10 | #include "ppapi/cpp/size.h" |
| 11 | |
| 12 | /// @file |
| 13 | /// This file defines the API for getting the state of a the view for an |
| 14 | /// instance. |
| 15 | |
| 16 | namespace pp { |
| 17 | |
| 18 | /// This class represents the state of the view for an instance and contains |
| 19 | /// functions for retrieving the current state of that view. |
| 20 | class View : public Resource { |
| 21 | public: |
| 22 | /// Default constructor for creating an is_null() <code>View</code> object. |
| 23 | View(); |
| 24 | |
| 25 | /// Creates a View resource, taking and holding an additional reference to |
| 26 | /// the given resource handle. |
| 27 | View(PP_Resource view_resource); |
| 28 | |
| 29 | /// GetRect() retrieves the rectangle of the module instance associated |
| 30 | /// with a view changed notification relative to the upper-left of the browser |
| 31 | /// viewport. This position changes when the page is scrolled. |
| 32 | /// |
| 33 | /// The returned rectangle may not be inside the visible portion of the |
| 34 | /// viewport if the module instance is scrolled off the page. Therefore, the |
| 35 | /// position may be negative or larger than the size of the page. The size |
| 36 | /// will always reflect the size of the module were it to be scrolled |
| 37 | /// entirely into view. |
| 38 | /// |
| 39 | /// In general, most modules will not need to worry about the position of the |
| 40 | ///module instance in the viewport, and only need to use the size. |
| 41 | /// |
| 42 | /// @return The rectangle of the instance. The default return value for |
| 43 | /// an invalid View is the empty rectangle. |
| 44 | Rect GetRect() const; |
| 45 | |
| 46 | /// IsFullscreen() returns whether the instance is currently |
| 47 | /// displaying in fullscreen mode. |
| 48 | /// |
| 49 | /// @return <code>true</code> if the instance is in full screen mode, |
| 50 | /// or <code>false</code> if it's not or the resource is invalid. |
| 51 | bool IsFullscreen() const; |
| 52 | |
| 53 | /// IsVisible() determines whether the module instance might be visible to |
| 54 | /// the user. For example, the Chrome window could be minimized or another |
| 55 | /// window could be over it. In both of these cases, the module instance |
| 56 | /// would not be visible to the user, but IsVisible() will return true. |
| 57 | /// |
| 58 | /// Use the result to speed up or stop updates for invisible module |
| 59 | /// instances. |
| 60 | /// |
| 61 | /// This function performs the duties of GetRect() (determining whether the |
| 62 | /// module instance is scrolled into view and the clip rectangle is nonempty) |
| 63 | /// and IsPageVisible() (whether the page is visible to the user). |
| 64 | /// |
| 65 | /// @return <code>true</code> if the instance might be visible to the |
| 66 | /// user, <code>false</code> if it is definitely not visible. |
| 67 | bool IsVisible() const; |
| 68 | |
| 69 | /// IsPageVisible() determines if the page that contains the module instance |
| 70 | /// is visible. The most common cause of invisible pages is that |
| 71 | /// the page is in a background tab in the browser. |
| 72 | /// |
| 73 | /// Most applications should use IsVisible() instead of this function since |
| 74 | /// the module instance could be scrolled off of a visible page, and this |
| 75 | /// function will still return true. However, depending on how your module |
| 76 | /// interacts with the page, there may be certain updates that you may want |
| 77 | /// to perform when the page is visible even if your specific module instance |
| 78 | /// is not visible. |
| 79 | /// |
| 80 | /// @return <code>true</code> if the instance might be visible to the |
| 81 | /// user, <code>false</code> if it is definitely not visible. |
| 82 | bool IsPageVisible() const; |
| 83 | |
| 84 | /// GetClipRect() returns the clip rectangle relative to the upper-left corner |
| 85 | /// of the module instance. This rectangle indicates the portions of the |
| 86 | /// module instance that are scrolled into view. |
| 87 | /// |
| 88 | /// If the module instance is scrolled off the view, the return value will be |
| 89 | /// (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page |
| 90 | /// visibility. Therefore, if the module instance is scrolled into view, but |
| 91 | /// the page itself is on a tab that is not visible, the return rectangle will |
| 92 | /// contain the visible rectangle as though the page were visible. Refer to |
| 93 | /// IsPageVisible() and IsVisible() if you want to account for page |
| 94 | /// visibility. |
| 95 | /// |
| 96 | /// Most applications will not need to worry about the clip rectangle. The |
| 97 | /// recommended behavior is to do full updates if the module instance is |
| 98 | /// visible, as determined by IsVisible(), and do no updates if it is not |
| 99 | /// visible. |
| 100 | /// |
| 101 | /// However, if the cost for computing pixels is very high for your |
| 102 | /// application, or the pages you're targeting frequently have very large |
| 103 | /// module instances with small visible portions, you may wish to optimize |
| 104 | /// further. In this case, the clip rectangle will tell you which parts of |
| 105 | /// the module to update. |
| 106 | /// |
| 107 | /// Note that painting of the page and sending of view changed updates |
| 108 | /// happens asynchronously. This means when the user scrolls, for example, |
| 109 | /// it is likely that the previous backing store of the module instance will |
| 110 | /// be used for the first paint, and will be updated later when your |
| 111 | /// application generates new content with the new clip. This may cause |
| 112 | /// flickering at the boundaries when scrolling. If you do choose to do |
| 113 | /// partial updates, you may want to think about what color the invisible |
| 114 | /// portions of your backing store contain (be it transparent or some |
| 115 | /// background color) or to paint a certain region outside the clip to reduce |
| 116 | /// the visual distraction when this happens. |
| 117 | /// |
| 118 | /// @return The rectangle representing the visible part of the module |
| 119 | /// instance. If the resource is invalid, the empty rectangle is returned. |
| 120 | Rect GetClipRect() const; |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 121 | |
| 122 | /// GetDeviceScale returns the scale factor between device pixels and DIPs |
| 123 | /// (also known as logical pixels or UI pixels on some platforms). This allows |
| 124 | /// the developer to render their contents at device resolution, even as |
| 125 | /// coordinates / sizes are given in DIPs through the API. |
| 126 | /// |
| 127 | /// Note that the coordinate system for Pepper APIs is DIPs. Also note that |
| 128 | /// one DIP might not equal one CSS pixel - when page scale/zoom is in effect. |
| 129 | /// |
| 130 | /// @return A <code>float</code> value representing the number of device |
| 131 | /// pixels per DIP. |
| 132 | float GetDeviceScale() const; |
| 133 | |
| 134 | /// GetCSSScale returns the scale factor between DIPs and CSS pixels. This |
| 135 | /// allows proper scaling between DIPs - as sent via the Pepper API - and CSS |
| 136 | /// pixel coordinates used for Web content. |
| 137 | /// |
| 138 | /// @return A <code>float</code> value representing the number of DIPs per CSS |
| 139 | /// pixel. |
| 140 | float GetCSSScale() const; |
Torne (Richard Coles) | 6d86b77 | 2014-06-25 10:30:53 +0100 | [diff] [blame] | 141 | |
| 142 | /// GetScrollOffset returns the scroll offset of the window containing the |
| 143 | /// plugin. |
| 144 | /// |
| 145 | /// @return A <code>Point</code> which is set to the value of the scroll |
| 146 | /// offset in CSS pixels. |
| 147 | Point GetScrollOffset() const; |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 148 | }; |
| 149 | |
| 150 | } // namespace pp |
| 151 | |
| 152 | #endif // PPAPI_CPP_VIEW_H_ |