Documentation for C++ version of ppb_view.

ppapi/cpp/view.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_CPP_VIEW_H_
 #define PPAPI_CPP_VIEW_H_
 
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/rect.h"
 #include "ppapi/cpp/size.h"
 
 /// @file
 /// This file defines the API for getting the state of a the view for an
 /// instance.
 
 namespace pp {
 
 /// This class represents the state of the view for an instance and contains
 /// functions for retrieving the current state of that view.
 class View : public Resource {
  public:
   /// Default constructor for creating an is_null() <code>View</code> object.
   View();
 
   /// Creates a View resource, taking and holding an additional reference to
   /// the given resource handle.
   View(PP_Resource view_resource);
 
-  /// <code>GetRect()</code> returns the rectangle of the instance
-  /// associated with the view changed notification relative to the upper left
-  /// of the browser viewport. This position changes when the page is scrolled.
+  /// GetRect() retrieves the rectangle of the module instance associated
+  /// with a view changed notification relative to the upper-left of the browser
+  /// viewport. This position changes when the page is scrolled.
   ///
   /// The returned rectangle may not be inside the visible portion of the
-  /// viewport if the instance is scrolled off the page. Therefore, the
+  /// viewport if the module instance is scrolled off the page. Therefore, the
   /// position may be negative or larger than the size of the page. The size
-  /// will always reflect the size of the plugin were it to be scrolled
+  /// will always reflect the size of the module were it to be scrolled
   /// entirely into view.
   ///
-  /// In general, most plugins will not need to worry about the position of the
-  /// instance in the viewport, and only need to use the size.
+  /// In general, most modules will not need to worry about the position of the
+  ///module instance in the viewport, and only need to use the size.
   ///
   /// @return The rectangle of the instance. The default return value for
   /// an invalid View is the empty rectangle.
   Rect GetRect() const;
 
-  /// <code>IsFullscreen()</code> returns whether the instance is currently
+  /// IsFullscreen() returns whether the instance is currently
   /// displaying in fullscreen mode.
   ///
   /// @return <code>true</code> if the instance is in full screen mode,
   /// or <code>false</code> if it's not or the resource is invalid.
   bool IsFullscreen() const;
 
-  /// <code>IsVisible()</code> returns true if the instance is plausibly
-  /// visible to the user. You should use this flag to throttle or stop updates
-  /// for invisible plugins.
+  /// IsVisible() determines whether the module instance might be visible to
+  /// the user. For example, the Chrome window could be minimized or another
+  /// window could be over it. In both of these cases, the module instance
+  /// would not be visible to the user, but IsVisible() will return true.
   ///
-  /// Thie measure incorporates both whether the instance is scrolled into
-  /// view (whether the clip rect is nonempty) and whether the page is
-  /// plausibly visible to the user (<code>IsPageVisible()</code>).
+  /// Use the result to speed up or stop updates for invisible module
+  /// instances.
   ///
-  /// @return <code>true</code> if the instance is plausibly visible to the
+  /// This function performs the duties of GetRect() (determining whether the
+  /// module instance is scrolled into view and the clip rectangle is nonempty)
+  /// and IsPageVisible() (whether the page is visible to the user).
+  ///
+  /// @return <code>true</code> if the instance might be visible to the
   /// user, <code>false</code> if it is definitely not visible.
   bool IsVisible() const;
 
-  /// <code>IsPageVisible()</code> determines if the page that contains the
-  /// instance is visible. The most common cause of invisible pages is that
+  /// IsPageVisible() determines if the page that contains the module instance
+  /// is visible. The most common cause of invisible pages is that
   /// the page is in a background tab in the browser.
   ///
-  /// Most applications should use <code>IsVisible()</code> rather than
-  /// this function since the instance could be scrolled off of a visible
-  /// page, and this function will still return true. However, depending on
-  /// how your plugin interacts with the page, there may be certain updates
-  /// that you may want to perform when the page is visible even if your
-  /// specific instance isn't.
+  /// Most applications should use IsVisible() instead of this function since
+  /// the module instance could be scrolled off of a visible page, and this
+  /// function will still return true. However, depending on how your module
+  /// interacts with the page, there may be certain updates that you may want
+  /// to perform when the page is visible even if your specific module instance
+  /// is not visible.
   ///
-  /// @return <code>true</code> if the instance is plausibly visible to the
+  /// @return <code>true</code> if the instance might be visible to the
   /// user, <code>false</code> if it is definitely not visible.
   bool IsPageVisible() const;
 
-  /// <code>GetClip()</code> returns the clip rectangle relative to the upper
-  /// left corner of the instance. This rectangle indicates which parts of the
-  /// instance are scrolled into view.
+  /// GetClipRect() returns the clip rectangle relative to the upper-left corner
+  /// of the module instance. This rectangle indicates the portions of the
+  /// module instance that are scrolled into view.
   ///
-  /// If the instance is scrolled off the view, the return value will be
-  /// (0, 0, 0, 0). this state. This clip rect does <i>not</i> take into account
-  /// page visibility. This means if the instance is scrolled into view but the
-  /// page itself is in an invisible tab, the return rect will contain the
-  /// visible rect assuming the page was visible. See
-  /// <code>IsPageVisible()</code> and <code>IsVisible()</code> if you want
-  /// to handle this case.
+  /// If the module instance is scrolled off the view, the return value will be
+  /// (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page
+  /// visibility. Therefore, if the module instance is scrolled into view, but
+  /// the page itself is on a tab that is not visible, the return rectangle will
+  /// contain the visible rectangle as though the page were visible. Refer to
+  /// IsPageVisible() and IsVisible() if you want to account for page
+  /// visibility.
   ///
-  /// Most applications will not need to worry about the clip. The recommended
-  /// behavior is to do full updates if the instance is visible as determined by
-  /// <code>IsUserVisible()</code> and do no updates if not.
+  /// Most applications will not need to worry about the clip rectangle. The
+  /// recommended behavior is to do full updates if the module instance is
+  /// visible, as determined by IsVisible(), and do no updates if it is not
+  /// visible.
   ///
   /// However, if the cost for computing pixels is very high for your
-  /// application or the pages you're targeting frequently have very large
-  /// instances with only portions visible, you may wish to optimize further.
-  /// In this case, the clip rect will tell you which parts of the plugin to
-  /// update.
+  /// application, or the pages you're targeting frequently have very large
+  /// module instances with small visible portions, you may wish to optimize
+  /// further. In this case, the clip rectangle will tell you which parts of
+  /// the module to update.
   ///
   /// Note that painting of the page and sending of view changed updates
   /// happens asynchronously. This means when the user scrolls, for example,
-  /// it is likely that the previous backing store of the instance will be used
-  /// for the first paint, and will be updated later when your application
-  /// generates new content. This may cause flickering at the boundaries when
-  /// scrolling. If you do choose to do partial updates, you may want to think
-  /// about what color the invisible portions of your backing store contain
-  /// (be it transparent or some background color) or to paint a certain
-  /// region outside the clip to reduce the visual distraction when this
-  /// happens.
+  /// it is likely that the previous backing store of the module instance will
+  /// be used for the first paint, and will be updated later when your
+  /// application generates new content with the new clip. This may cause
+  /// flickering at the boundaries when scrolling. If you do choose to do
+  /// partial updates, you may want to think about what color the invisible
+  /// portions of your backing store contain (be it transparent or some
+  /// background color) or to paint a certain region outside the clip to reduce
+  /// the visual distraction when this happens.
   ///
-  /// @return The rectangle representing the visible part of the instance.
-  /// If the resource is invalid, the empty rect is returned.
+  /// @return The rectangle representing the visible part of the module
+  /// instance. If the resource is invalid, the empty rectangle is returned.
   Rect GetClipRect() const;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_VIEW_H_