text: // 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);
  
    /// 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 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 module were it to be scrolled
    /// entirely into view.
    ///
    /// 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;
  
    /// 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;
  
    /// 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.
    ///
    /// Use the result to speed up or stop updates for invisible module
    /// instances.
    ///
    /// 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;
  
    /// 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 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 might be visible to the
    /// user, <code>false</code> if it is definitely not visible.
    bool IsPageVisible() const;
  
    /// 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 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 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
    /// 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 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 module
    /// instance. If the resource is invalid, the empty rectangle is returned.
    Rect GetClipRect() const;
  };
  
  }  // namespace pp
  
  #endif  // PPAPI_CPP_VIEW_H_
  