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; 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; 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; 148 }; 149 150 } // namespace pp 151 152 #endif // PPAPI_CPP_VIEW_H_ 153
