Native Client

pp::Instance Class Reference

List of all members.

Public Functions

 Instance (PP_Instance instance)
virtual ~Instance ()
PP_Instance pp_instance () const
virtual bool Init (uint32_t argc, const char *argn[], const char *argv[])
void AddPerInstanceObject (const std::string &interface_name, void *object)
void RemovePerInstanceObject (const std::string &interface_name, void *object)
PPP_Instance methods for the module to override:
virtual void DidChangeView (const View &view)
virtual void DidChangeView (const Rect &position, const Rect &clip)
virtual void DidChangeFocus (bool has_focus)
virtual bool HandleInputEvent (const pp::InputEvent &event)
virtual bool HandleDocumentLoad (const URLLoader &url_loader)
virtual void HandleMessage (const Var &message)
PPB_Instance methods for querying the browser:
bool BindGraphics (const Graphics2D &graphics)
bool BindGraphics (const Graphics3D &graphics)
bool IsFullFrame ()
int32_t RequestInputEvents (uint32_t event_classes)
int32_t RequestFilteringInputEvents (uint32_t event_classes)
void ClearInputEventRequest (uint32_t event_classes)
void PostMessage (const Var &message)

Static Public Member Functions

static void RemovePerInstanceObject (const InstanceHandle &instance, const std::string &interface_name, void *object)
static void * GetPerInstanceObject (PP_Instance instance, const std::string &interface_name)

Constructor and Destructor Details

pp::Instance::Instance ( PP_Instance  instance) [explicit]

Default constructor.

Construction of an instance should only be done in response to a browser request in Module::CreateInstance. Otherwise, the instance will lack the proper bookkeeping in the browser and in the C++ wrapper.

Init() will be called immediately after the constructor. This allows you to perform initialization tasks that can fail and to report that failure to the browser.

virtual pp::Instance::~Instance ( ) [virtual]

Destructor.

When the instance is removed from the web page, the pp::Instance object will be deleted. You should never delete the Instance object yourself since the lifetime is handled by the C++ wrapper and is controlled by the browser's calls to the PPP_Instance interface.

The PP_Instance identifier will still be valid during this call so the instance can perform cleanup-related tasks. Once this function returns, the PP_Instance handle will be invalid. This means that you can't do any asynchronous operations such as network requests or file writes from this destructor since they will be immediately canceled.

Note: This function may be skipped in certain call so the instance can perform cleanup-related tasks. Once this function returns, the PP_Instance handle will be invalid. This means that you can't do any asynchronous operations such as network requests or file writes from this destructor since they will be immediately canceled.


Function Details

void pp::Instance::AddPerInstanceObject ( const std::string &  interface_name,
void *  object 
)

AddPerInstanceObject() associates an instance with an interface, creating an object.

Many optional interfaces are associated with a plugin instance. For example, the find in PPP_Find interface receives updates on a per-instance basis. This "per-instance" tracking allows such objects to associate themselves with an instance as "the" handler for that interface name.

In the case of the find example, the find object registers with its associated instance in its constructor and unregisters in its destructor. Then whenever it gets updates with a PP_Instance parameter, it can map back to the find object corresponding to that given PP_Instance by calling GetPerInstanceObject.

This lookup is done on a per-interface-name basis. This means you can only have one object of a given interface name associated with an instance.

If you are adding a handler for an additional interface, be sure to register with the module (AddPluginInterface) for your interface name to get the C calls in the first place.

Refer to RemovePerInstanceObject() and GetPerInstanceObject() for further information.

Parameters:
[in]interface_nameThe name of the interface to associate with the instance
[in]object
bool pp::Instance::BindGraphics ( const Graphics2D graphics)

BindGraphics() binds the given graphics as the current display surface.

The contents of this device is what will be displayed in the instance's area on the web page. The device must be a 2D or a 3D device.

You can pass an is_null() (default constructed) Graphics2D as the device parameter to unbind all devices from the given instance. The instance will then appear transparent. Re-binding the same device will return true and will do nothing.

Any previously-bound device will be released. It is an error to bind a device when it is already bound to another instance. If you want to move a device between instances, first unbind it from the old one, and then rebind it to the new one.

Binding a device will invalidate that portion of the web page to flush the contents of the new device to the screen.

Parameters:
[in]graphicsA Graphics2D to bind.
Returns:
true if bind was successful or false if the device was not the correct type. On success, a reference to the device will be held by the instance, so the caller can release its reference if it chooses.
bool pp::Instance::BindGraphics ( const Graphics3D graphics)

Binds the given Graphics3D as the current display surface.

Refer to BindGraphics(const Graphics2D& graphics) for further information.

Parameters:
[in]graphicsA Graphics3D to bind.
Returns:
true if bind was successful or false if the device was not the correct type. On success, a reference to the device will be held by the instance, so the caller can release its reference if it chooses.
void pp::Instance::ClearInputEventRequest ( uint32_t  event_classes)

ClearInputEventRequest() requests that input events corresponding to the given input classes no longer be delivered to the instance.

By default, no input events are delivered. If you have previously requested input events using RequestInputEvents() or RequestFilteringInputEvents(), this function will unregister handling for the given instance. This will allow greater browser performance for those events.

Note: You may still get some input events after clearing the flag if they were dispatched before the request was cleared. For example, if there are 3 mouse move events waiting to be delivered, and you clear the mouse event class during the processing of the first one, you'll still receive the next two. You just won't get more events generated.

Parameters:
[in]event_classesA combination of flags from PP_InputEvent_Class that identifies the classes of events the instance is no longer interested in.
virtual void pp::Instance::DidChangeFocus ( bool  has_focus) [virtual]

DidChangeFocus() is called when an instance has gained or lost focus.

Having focus means that keyboard events will be sent to the instance. An instance's default condition is that it will not have focus.

Note:Clicks on instances will give focus only if you handle the click event. Return true from HandleInputEvent to signal that the click event was handled. Otherwise the browser will bubble the event and give focus to the element on the page that actually did end up consuming it. If you're not getting focus, check to make sure you're returning true from the mouse click in HandleInputEvent.

Parameters:
[in]has_focusIndicates the new focused state of the instance.
virtual void pp::Instance::DidChangeView ( const View view) [virtual]

DidChangeView() is called when the view information for the Instance has changed.

See the View object for information.

Most implementations will want to check if the size and user visibility changed, and either resize themselves or start/stop generating updates.

You should not call the default implementation. For backwards-compatibility, it will call the deprecated version of DidChangeView below.

virtual void pp::Instance::DidChangeView ( const Rect position,
const Rect clip 
) [virtual]

Deprecated backwards-compatible version of DidChangeView().

New code should derive from the version that takes a ViewChanged object rather than this version. This function is called by the default implementation of the newer DidChangeView function for source compatibility with older code.

A typical implementation will check the size of the position argument and reallocate the graphics context when a different size is received. Note that this function will be called for scroll events where the size doesn't change, so you should always check that the size is actually different before doing any reallocations.

Parameters:
[in]positionThe location on the page of the instance. The position is relative to the top left corner of the viewport, which changes as the page is scrolled. Generally the size of this value will be used to create a graphics device, and the position is ignored (most things are relative to the instance so the absolute position isn't useful in most cases).
[in]clipThe visible region of the instance. This is relative to the top left of the instance's coordinate system (not the page). If the instance is invisible, clip will be (0, 0, 0, 0).

It's recommended to check for invisible instances and to stop generating graphics updates in this case to save system resources. It's not usually worthwhile, however, to generate partial updates according to the clip when the instance is partially visible. Instead, update the entire region. The time saved doing partial paints is usually not significant and it can create artifacts when scrolling (this notification is sent asynchronously from scolling so there can be flashes of old content in the exposed regions).

static void* pp::Instance::GetPerInstanceObject ( PP_Instance  instance,
const std::string &  interface_name 
) [static]

Look up an object previously associated with an instance.

Returns NULL if the instance is invalid or there is no object for the given interface name on the instance.

Refer to AddPerInstanceObject() for further information.

Parameters:
[in]instance
[in]interface_nameThe name of the interface to associate with the instance.
virtual bool pp::Instance::HandleDocumentLoad ( const URLLoader url_loader) [virtual]

HandleDocumentLoad() is called after Init() for a full-frame instance that was instantiated based on the MIME type of a DOMWindow navigation.

This situation only applies to modules that are pre-registered to handle certain MIME types. If you haven't specifically registered to handle a MIME type or aren't positive this applies to you, your implementation of this function can just return false.

The given url_loader corresponds to a URLLoader object that is already opened. Its response headers may be queried using GetResponseInfo(). If you want to use the URLLoader to read data, you will need to save a copy of it or the underlying resource will be freed when this function returns and the load will be canceled.

This method returns false if the module cannot handle the data. In response to this method, the module should call ReadResponseBody() to read the incoming data.

Parameters:
[in]url_loaderAn open URLLoader instance.
Returns:
true if the data was handled, false otherwise.
virtual bool pp::Instance::HandleInputEvent ( const pp::InputEvent event) [virtual]

HandleInputEvent() handles input events from the browser.

The default implementation does nothing and returns false.

In order to receive input events, you must register for them by calling RequestInputEvents() or RequestFilteringInputEvents(). By default, no events are delivered.

If the event was handled, it will not be forwarded to the web page or browser. If it was not handled, it will bubble according to the normal rules. So it is important that an instance respond accurately with whether event propagation should continue.

Event propagation also controls focus. If you handle an event like a mouse event, typically the instance will be given focus. Returning false from a filtered event handler or not registering for an event type means that the click will be given to a lower part of the page and your instance will not receive focus. This allows an instance to be partially transparent, where clicks on the transparent areas will behave like clicks to the underlying page.

In general, you should try to keep input event handling short. Especially for filtered input events, the browser or page may be blocked waiting for you to respond.

The caller of this function will maintain a reference to the input event resource during this call. Unless you take a reference to the resource to hold it for later, you don't need to release it.

Note: If you're not receiving input events, make sure you register for the event classes you want by calling RequestInputEvents or RequestFilteringInputEvents. If you're still not receiving keyboard input events, make sure you're returning true (or using a non-filtered event handler) for mouse events. Otherwise, the instance will not receive focus and keyboard events will not be sent.

Refer to RequestInputEvents and RequestFilteringInputEvents for further information.

Parameters:
[in]eventThe event to handle.
Returns:
true if the event was handled, false if not. If you have registered to filter this class of events by calling RequestFilteringInputEvents, and you return false, the event will be forwarded to the page (and eventually the browser) for the default handling. For non-filtered events, the return value will be ignored.
virtual void pp::Instance::HandleMessage ( const Var message) [virtual]

HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element for the instance in JavaScript.

Note that PostMessage() in the JavaScript interface is asynchronous, meaning JavaScript execution will not be blocked while HandleMessage() is processing the message.

Example:

The following JavaScript code invokes HandleMessage, passing the instance on which it was invoked, with message being a string Var containing "Hello world!"

<body> <object id="plugin" type="application/x-ppapi-postMessage-example"> <script type="text/javascript"> document.getElementById('plugin').postMessage("Hello world!"); </script> </body>

Refer to PostMessage() for sending messages to JavaScript.

Parameters:
[in]messageA Var containing the data sent from JavaScript. Message can have an int32_t, double, bool, or string value (objects are not supported).
virtual bool pp::Instance::Init ( uint32_t  argc,
const char *  argn[],
const char *  argv[] 
) [virtual]

Init() initializes this instance with the provided arguments.

This function will be called immediately after the instance object is constructed.

Parameters:
[in]argcThe number of arguments contained in argn and argv.
[in]argnAn array of argument names. These argument names are supplied in the <embed> tag, for example: <embed id="nacl_module" dimensions="2"> will produce two argument names: "id" and "dimensions".
[in]argvAn array of argument values. These are the values of the arguments listed in the <embed> tag, for example <embed id="nacl_module" dimensions="2"> will produce two argument values: "nacl_module" and "2". The indices of these values match the indices of the corresponding names in argn.
Returns:
true on success. Returning false causes the instance to be deleted and no other functions to be called.
bool pp::Instance::IsFullFrame ( )

IsFullFrame() determines if the instance is full-frame (repr).

Such an instance represents the entire document in a frame rather than an embedded resource. This can happen if the user does a top-level navigation or the page specifies an iframe to a resource with a MIME type registered by the module.

Returns:
true if the instance is full-frame, false if not.
void pp::Instance::PostMessage ( const Var message)

PostMessage() asynchronously invokes any listeners for message events on the DOM element for the given instance.

A call to PostMessage() will not block while the message is processed.

Example:

<body> <object id="plugin" type="application/x-ppapi-postMessage-example"> <script type="text/javascript"> var plugin = document.getElementById('plugin'); plugin.addEventListener("message", function(message) { alert(message.data); }, false); </script> </body>

The instance then invokes PostMessage() as follows:

PostMessage(pp::Var("Hello world!"));

The browser will pop-up an alert saying "Hello world!"

Listeners for message events in JavaScript code will receive an object conforming to the HTML 5 MessageEvent interface. Specifically, the value of message will be contained as a property called data in the received MessageEvent.

This messaging system is similar to the system used for listening for messages from Web Workers. Refer to http://www.whatwg.org/specs/web-workers/current-work/ for further information.

Refer to HandleMessage() for receiving events from JavaScript.

Parameters:
[in]messageA Var containing the data to be sent to JavaScript. Message can have a numeric, boolean, or string value; arrays and dictionaries are not yet supported. Ref-counted var types are copied, and are therefore not shared between the instance and the browser.
PP_Instance pp::Instance::pp_instance ( ) const [inline]

This function returns the PP_Instance identifying this object.

Returns:
A PP_Instance identifying this object.
static void pp::Instance::RemovePerInstanceObject ( const InstanceHandle instance,
const std::string &  interface_name,
void *  object 
) [static]

Static version of AddPerInstanceObject that takes an InstanceHandle.

As with all other instance functions, this must only be called on the main thread.

void pp::Instance::RemovePerInstanceObject ( const std::string &  interface_name,
void *  object 
)

Refer to AddPerInstanceObject() for further information.

Parameters:
[in]interface_nameThe name of the interface to associate with the instance
[in]object
int32_t pp::Instance::RequestFilteringInputEvents ( uint32_t  event_classes)

RequestFilteringInputEvents() requests that input events corresponding to the given input events are delivered to the instance for filtering.

By default, no input events are delivered. In most cases you would register to receive events by calling RequestInputEvents(). In some cases, however, you may wish to filter events such that they can be bubbled up to the DOM. In this case, register for those classes of events using this function instead of RequestInputEvents(). Keyboard events must always be registered in filtering mode.

Filtering input events requires significantly more overhead than just delivering them to the instance. As such, you should only request filtering in those cases where it's absolutely necessary. The reason is that it requires the browser to stop and block for the instance to handle the input event, rather than sending the input event asynchronously. This can have significant overhead.

Example:

RequestInputEvents(PP_INPUTEVENT_CLASS_MOUSE); RequestFilteringInputEvents( PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);

Parameters:
event_classesA combination of flags from PP_InputEvent_Class that identifies the classes of events the instance is requesting. The flags are combined by logically ORing their values.
Returns:
PP_OK if the operation succeeded, PP_ERROR_BADARGUMENT if instance is invalid, or PP_ERROR_NOTSUPPORTED if one of the event class bits were illegal. In the case of an invalid bit, all valid bits will be applied and only the illegal bits will be ignored.
int32_t pp::Instance::RequestInputEvents ( uint32_t  event_classes)

RequestInputEvents() requests that input events corresponding to the given input events are delivered to the instance.

By default, no input events are delivered. Call this function with the classes of events you are interested in to have them be delivered to the instance. Calling this function will override any previous setting for each specified class of input events (for example, if you previously called RequestFilteringInputEvents(), this function will set those events to non-filtering mode).

Input events may have high overhead, so you should only request input events that your plugin will actually handle. For example, the browser may do optimizations for scroll or touch events that can be processed substantially faster if it knows there are no non-default receivers for that message. Requesting that such messages be delivered, even if they are processed very quickly, may have a noticable effect on the performance of the page.

When requesting input events through this function, the events will be delivered and not bubbled to the page. This means that even if you aren't interested in the message, no other parts of the page will get the message.

Example:

RequestInputEvents(PP_INPUTEVENT_CLASS_MOUSE); RequestFilteringInputEvents( PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);

Parameters:
event_classesA combination of flags from PP_InputEvent_Class that identifies the classes of events the instance is requesting. The flags are combined by logically ORing their values.
Returns:
PP_OK if the operation succeeded, PP_ERROR_BADARGUMENT if instance is invalid, or PP_ERROR_NOTSUPPORTED if one of the event class bits were illegal. In the case of an invalid bit, all valid bits will be applied and only the illegal bits will be ignored.

The documentation for this class was generated from the following file:

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.