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
13label 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"]
25interface 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