Pepper_47_C++_interfaces
view.h
Go to the documentation of this file.
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  explicit 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_
float GetDeviceScale() const
Definition: view.cc:105
A 2 dimensional point with 0,0 being the upper-left starting coordinate.
Definition: point.h:16
Definition: rect.h:19
bool IsFullscreen() const
Definition: view.cc:49
bool IsPageVisible() const
Definition: view.cc:73
Definition: view.h:20
Rect GetClipRect() const
Definition: view.cc:87
bool IsVisible() const
Definition: view.cc:63
float GetCSSScale() const
Definition: view.cc:113
A reference counted module resource.
Definition: resource.h:20
View()
Default constructor for creating an is_null() View object.
Definition: view.cc:28
Rect GetRect() const
Definition: view.cc:34
Point GetScrollOffset() const
Definition: view.cc:121