15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_CPP_VIEW_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_CPP_VIEW_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/resource.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/rect.h" 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/cpp/size.h" 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @file 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This file defines the API for getting the state of a the view for an 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// instance. 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace pp { 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This class represents the state of the view for an instance and contains 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// functions for retrieving the current state of that view. 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class View : public Resource { 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Default constructor for creating an is_null() <code>View</code> object. 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) View(); 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Creates a View resource, taking and holding an additional reference to 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the given resource handle. 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) View(PP_Resource view_resource); 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetRect() retrieves the rectangle of the module instance associated 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// with a view changed notification relative to the upper-left of the browser 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// viewport. This position changes when the page is scrolled. 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// The returned rectangle may not be inside the visible portion of the 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// viewport if the module instance is scrolled off the page. Therefore, the 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// position may be negative or larger than the size of the page. The size 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// will always reflect the size of the module were it to be scrolled 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// entirely into view. 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// In general, most modules will not need to worry about the position of the 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) ///module instance in the viewport, and only need to use the size. 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return The rectangle of the instance. The default return value for 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// an invalid View is the empty rectangle. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Rect GetRect() const; 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// IsFullscreen() returns whether the instance is currently 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// displaying in fullscreen mode. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return <code>true</code> if the instance is in full screen mode, 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// or <code>false</code> if it's not or the resource is invalid. 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool IsFullscreen() const; 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// IsVisible() determines whether the module instance might be visible to 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the user. For example, the Chrome window could be minimized or another 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// window could be over it. In both of these cases, the module instance 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// would not be visible to the user, but IsVisible() will return true. 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Use the result to speed up or stop updates for invisible module 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// instances. 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This function performs the duties of GetRect() (determining whether the 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// module instance is scrolled into view and the clip rectangle is nonempty) 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// and IsPageVisible() (whether the page is visible to the user). 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return <code>true</code> if the instance might be visible to the 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// user, <code>false</code> if it is definitely not visible. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool IsVisible() const; 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// IsPageVisible() determines if the page that contains the module instance 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// is visible. The most common cause of invisible pages is that 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the page is in a background tab in the browser. 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Most applications should use IsVisible() instead of this function since 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the module instance could be scrolled off of a visible page, and this 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// function will still return true. However, depending on how your module 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// interacts with the page, there may be certain updates that you may want 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// to perform when the page is visible even if your specific module instance 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// is not visible. 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return <code>true</code> if the instance might be visible to the 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// user, <code>false</code> if it is definitely not visible. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool IsPageVisible() const; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// GetClipRect() returns the clip rectangle relative to the upper-left corner 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// of the module instance. This rectangle indicates the portions of the 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// module instance that are scrolled into view. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// If the module instance is scrolled off the view, the return value will be 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// visibility. Therefore, if the module instance is scrolled into view, but 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the page itself is on a tab that is not visible, the return rectangle will 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// contain the visible rectangle as though the page were visible. Refer to 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// IsPageVisible() and IsVisible() if you want to account for page 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// visibility. 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Most applications will not need to worry about the clip rectangle. The 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// recommended behavior is to do full updates if the module instance is 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// visible, as determined by IsVisible(), and do no updates if it is not 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// visible. 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// However, if the cost for computing pixels is very high for your 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// application, or the pages you're targeting frequently have very large 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// module instances with small visible portions, you may wish to optimize 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// further. In this case, the clip rectangle will tell you which parts of 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the module to update. 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Note that painting of the page and sending of view changed updates 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// happens asynchronously. This means when the user scrolls, for example, 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// it is likely that the previous backing store of the module instance will 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// be used for the first paint, and will be updated later when your 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// application generates new content with the new clip. This may cause 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// flickering at the boundaries when scrolling. If you do choose to do 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// partial updates, you may want to think about what color the invisible 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// portions of your backing store contain (be it transparent or some 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// background color) or to paint a certain region outside the clip to reduce 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// the visual distraction when this happens. 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return The rectangle representing the visible part of the module 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// instance. If the resource is invalid, the empty rectangle is returned. 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Rect GetClipRect() const; 121c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 122c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// GetDeviceScale returns the scale factor between device pixels and DIPs 123c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// (also known as logical pixels or UI pixels on some platforms). This allows 124c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// the developer to render their contents at device resolution, even as 125c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// coordinates / sizes are given in DIPs through the API. 126c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 127c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// Note that the coordinate system for Pepper APIs is DIPs. Also note that 128c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// one DIP might not equal one CSS pixel - when page scale/zoom is in effect. 129c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 130c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @return A <code>float</code> value representing the number of device 131c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// pixels per DIP. 132c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) float GetDeviceScale() const; 133c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) 134c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// GetCSSScale returns the scale factor between DIPs and CSS pixels. This 135c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// allows proper scaling between DIPs - as sent via the Pepper API - and CSS 136c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// pixel coordinates used for Web content. 137c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// 138c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// @return A <code>float</code> value representing the number of DIPs per CSS 139c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) /// pixel. 140c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles) float GetCSSScale() const; 1416d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) 1426d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) /// GetScrollOffset returns the scroll offset of the window containing the 1436d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) /// plugin. 1446d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) /// 1456d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) /// @return A <code>Point</code> which is set to the value of the scroll 1466d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) /// offset in CSS pixels. 1476d86b77056ed63eb6871182f42a9fd5f07550f90Torne (Richard Coles) Point GetScrollOffset() const; 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace pp 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_CPP_VIEW_H_ 153