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