ppapi/cpp/view.h

   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_