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 6 /** 7 * This file defines the <code>PPB_View</code> struct representing the state 8 * of the view of an instance. 9 */ 10 11 [generate_thunk] 12 13 label Chrome { 14 M18 = 1.0, 15 M28 = 1.1, 16 [channel=dev] M37 = 1.2 17 }; 18 19 /** 20 * <code>PPB_View</code> represents the state of the view of an instance. 21 * You will receive new view information using 22 * <code>PPP_Instance.DidChangeView</code>. 23 */ 24 [macro="PPB_VIEW_INTERFACE"] 25 interface PPB_View { 26 /** 27 * IsView() determines if the given resource is a valid 28 * <code>PPB_View</code> resource. Note that <code>PPB_ViewChanged</code> 29 * resources derive from <code>PPB_View</code> and will return true here 30 * as well. 31 * 32 * @param resource A <code>PP_Resource</code> corresponding to a 33 * <code>PPB_View</code> resource. 34 * 35 * @return <code>PP_TRUE</code> if the given resource supports 36 * <code>PPB_View</code> or <code>PP_FALSE</code> if it is an invalid 37 * resource or is a resource of another type. 38 */ 39 PP_Bool IsView([in] PP_Resource resource); 40 41 /** 42 * GetRect() retrieves the rectangle of the module instance associated 43 * with a view changed notification relative to the upper-left of the browser 44 * viewport. This position changes when the page is scrolled. 45 * 46 * The returned rectangle may not be inside the visible portion of the 47 * viewport if the module instance is scrolled off the page. Therefore, the 48 * position may be negative or larger than the size of the page. The size will 49 * always reflect the size of the module were it to be scrolled entirely into 50 * view. 51 * 52 * In general, most modules will not need to worry about the position of the 53 * module instance in the viewport, and only need to use the size. 54 * 55 * @param resource A <code>PP_Resource</code> corresponding to a 56 * <code>PPB_View</code> resource. 57 * 58 * @param rect A <code>PP_Rect</code> receiving the rectangle on success. 59 * 60 * @return Returns <code>PP_TRUE</code> if the resource was valid and the 61 * viewport rectangle was filled in, <code>PP_FALSE</code> if not. 62 */ 63 PP_Bool GetRect([in] PP_Resource resource, 64 [out] PP_Rect rect); 65 66 /** 67 * IsFullscreen() returns whether the instance is currently 68 * displaying in fullscreen mode. 69 * 70 * @param resource A <code>PP_Resource</code> corresponding to a 71 * <code>PPB_View</code> resource. 72 * 73 * @return <code>PP_TRUE</code> if the instance is in full screen mode, 74 * or <code>PP_FALSE</code> if it's not or the resource is invalid. 75 */ 76 PP_Bool IsFullscreen([in] PP_Resource resource); 77 78 /** 79 * IsVisible() determines whether the module instance might be visible to 80 * the user. For example, the Chrome window could be minimized or another 81 * window could be over it. In both of these cases, the module instance 82 * would not be visible to the user, but IsVisible() will return true. 83 * 84 * Use the result to speed up or stop updates for invisible module 85 * instances. 86 * 87 * This function performs the duties of GetRect() (determining whether the 88 * module instance is scrolled into view and the clip rectangle is nonempty) 89 * and IsPageVisible() (whether the page is visible to the user). 90 * 91 * @param resource A <code>PP_Resource</code> corresponding to a 92 * <code>PPB_View</code> resource. 93 * 94 * @return <code>PP_TRUE</code> if the instance might be visible to the 95 * user, <code>PP_FALSE</code> if it is definitely not visible. 96 */ 97 PP_Bool IsVisible([in] PP_Resource resource); 98 99 /** 100 * IsPageVisible() determines if the page that contains the module instance 101 * is visible. The most common cause of invisible pages is that 102 * the page is in a background tab in the browser. 103 * 104 * Most applications should use IsVisible() instead of this function since 105 * the module instance could be scrolled off of a visible page, and this 106 * function will still return true. However, depending on how your module 107 * interacts with the page, there may be certain updates that you may want to 108 * perform when the page is visible even if your specific module instance is 109 * not visible. 110 * 111 * @param resource A <code>PP_Resource</code> corresponding to a 112 * <code>PPB_View</code> resource. 113 * 114 * @return <code>PP_TRUE</code> if the instance is plausibly visible to the 115 * user, <code>PP_FALSE</code> if it is definitely not visible. 116 */ 117 PP_Bool IsPageVisible([in] PP_Resource resource); 118 119 /** 120 * GetClipRect() returns the clip rectangle relative to the upper-left corner 121 * of the module instance. This rectangle indicates the portions of the module 122 * instance that are scrolled into view. 123 * 124 * If the module instance is scrolled off the view, the return value will be 125 * (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page 126 * visibility. Therefore, if the module instance is scrolled into view, but 127 * the page itself is on a tab that is not visible, the return rectangle will 128 * contain the visible rectangle as though the page were visible. Refer to 129 * IsPageVisible() and IsVisible() if you want to account for page 130 * visibility. 131 * 132 * Most applications will not need to worry about the clip rectangle. The 133 * recommended behavior is to do full updates if the module instance is 134 * visible, as determined by IsVisible(), and do no updates if it is not 135 * visible. 136 * 137 * However, if the cost for computing pixels is very high for your 138 * application, or the pages you're targeting frequently have very large 139 * module instances with small visible portions, you may wish to optimize 140 * further. In this case, the clip rectangle will tell you which parts of 141 * the module to update. 142 * 143 * Note that painting of the page and sending of view changed updates 144 * happens asynchronously. This means when the user scrolls, for example, 145 * it is likely that the previous backing store of the module instance will 146 * be used for the first paint, and will be updated later when your 147 * application generates new content with the new clip. This may cause 148 * flickering at the boundaries when scrolling. If you do choose to do 149 * partial updates, you may want to think about what color the invisible 150 * portions of your backing store contain (be it transparent or some 151 * background color) or to paint a certain region outside the clip to reduce 152 * the visual distraction when this happens. 153 * 154 * @param resource A <code>PP_Resource</code> corresponding to a 155 * <code>PPB_View</code> resource. 156 * 157 * @param clip Output argument receiving the clip rect on success. 158 * 159 * @return Returns <code>PP_TRUE</code> if the resource was valid and the 160 * clip rect was filled in, <code>PP_FALSE</code> if not. 161 */ 162 PP_Bool GetClipRect([in] PP_Resource resource, 163 [out] PP_Rect clip); 164 165 /** 166 * GetDeviceScale returns the scale factor between device pixels and Density 167 * Independent Pixels (DIPs, also known as logical pixels or UI pixels on 168 * some platforms). This allows the developer to render their contents at 169 * device resolution, even as coordinates / sizes are given in DIPs through 170 * the API. 171 * 172 * Note that the coordinate system for Pepper APIs is DIPs. Also note that 173 * one DIP might not equal one CSS pixel - when page scale/zoom is in effect. 174 * 175 * @param[in] resource A <code>PP_Resource</code> corresponding to a 176 * <code>PPB_View</code> resource. 177 * 178 * @return A <code>float</code> value representing the number of device pixels 179 * per DIP. If the resource is invalid, the value will be 0.0. 180 */ 181 [version=1.1] 182 float_t GetDeviceScale([in] PP_Resource resource); 183 184 /** 185 * GetCSSScale returns the scale factor between DIPs and CSS pixels. This 186 * allows proper scaling between DIPs - as sent via the Pepper API - and CSS 187 * pixel coordinates used for Web content. 188 * 189 * @param[in] resource A <code>PP_Resource</code> corresponding to a 190 * <code>PPB_View</code> resource. 191 * 192 * @return css_scale A <code>float</code> value representing the number of 193 * DIPs per CSS pixel. If the resource is invalid, the value will be 0.0. 194 */ 195 [version=1.1] 196 float_t GetCSSScale([in] PP_Resource resource); 197 198 /** 199 * GetScrollOffset returns the scroll offset of the window containing the 200 * plugin. 201 * 202 * @param[in] resource A <code>PP_Resource</code> corresponding to a 203 * <code>PPB_View</code> resource. 204 * 205 * @param[out] offset A <code>PP_Point</code> which will be set to the value 206 * of the scroll offset in CSS pixels. 207 * 208 * @return Returns <code>PP_TRUE</code> if the resource was valid and the 209 * offset was filled in, <code>PP_FALSE</code> if not. 210 */ 211 [version=1.2] 212 PP_Bool GetScrollOffset([in] PP_Resource resource, 213 [out] PP_Point offset); 214 }; 215 216
