src/ppapi/api/ppb_view.idl

   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   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