blob: 3894b0135bdd406043368455579736cd447af8c4 [file] [log] [blame]
{{+bindTo:partials.standard_nacl_api}}
<h1>pp::Instance Class Reference</h1>
<div id="doxygen-ref">
{{- dummy div to appease doxygen -}}
<div>
<!-- Generated by Doxygen 1.7.6.1 -->
</div>
<!--header-->
<div class="contents">
<!-- doxytag: class="pp::Instance" -->
<p><a href="classpp_1_1_instance-members.html">List of all members.</a></p>
<h2>
Public Member Functions</h2><table class="memberdecls">
<tr><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a398b1946805872334781dac993cfe704">Instance</a> (PP_Instance instance)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a5e475ef135a235029bc0515e9e3ff832">~Instance</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">PP_Instance&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#aeb29ff4201f9ae0e356c5ed0bb4a2679">pp_instance</a> () const </td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a4f915e70caaef514a49ef8afcddde30f">Init</a> (uint32_t argc, const char *argn[], const char *argv[])</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a9773263ee281405030548fc224eeec08">AddPerInstanceObject</a> (const std::string &amp;interface_name, void *object)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a33c633189c7c321dac8e0c5dc6e67f5b">RemovePerInstanceObject</a> (const std::string &amp;interface_name, void *object)</td></tr>
<tr><td colspan="2"><div class="groupHeader">PPP_Instance methods for the module to override:</div></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#ad952f05e42f0e036157beb216f12f3f3">DidChangeView</a> (const <a class="el" href="classpp_1_1_view.html">View</a> &amp;view)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a72ac4ec0b62c4cd8dedae3cf0fc577c2">DidChangeView</a> (const <a class="el" href="classpp_1_1_rect.html">Rect</a> &amp;position, const <a class="el" href="classpp_1_1_rect.html">Rect</a> &amp;clip)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a42c67b21f11bef29c5b341c78926bad3">DidChangeFocus</a> (bool has_focus)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a46aa2feb657fa14263a29375fe458b00">HandleInputEvent</a> (const <a class="el" href="classpp_1_1_input_event.html">pp::InputEvent</a> &amp;event)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a6cd99065ef0a55555647253442563225">HandleDocumentLoad</a> (const <a class="el" href="classpp_1_1_u_r_l_loader.html">URLLoader</a> &amp;url_loader)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8">HandleMessage</a> (const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;message)</td></tr>
<tr><td colspan="2"><div class="groupHeader">PPB_Instance methods for querying the browser:</div></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899">BindGraphics</a> (const <a class="el" href="classpp_1_1_graphics2_d.html">Graphics2D</a> &amp;graphics)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#abcfd0eb0995e6273271b4ff4c3df16ae">BindGraphics</a> (const <a class="el" href="classpp_1_1_graphics3_d.html">Graphics3D</a> &amp;graphics)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a845a8736f87b78538c73c9f8d192b77a">BindGraphics</a> (const <a class="el" href="classpp_1_1_compositor.html">Compositor</a> &amp;compositor)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a451fb956e64fd3db891608148a044c01">IsFullFrame</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5">RequestInputEvents</a> (uint32_t event_classes)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017">RequestFilteringInputEvents</a> (uint32_t event_classes)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a286bc22174e2f7b6e917c56aa5c7de86">ClearInputEventRequest</a> (uint32_t event_classes)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9">PostMessage</a> (const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;message)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a5b5b1a66eda2d0e6884de8f7e25e2346">RegisterMessageHandler</a> (<a class="el" href="classpp_1_1_message_handler.html">MessageHandler</a> *message_handler, const <a class="el" href="classpp_1_1_message_loop.html">MessageLoop</a> &amp;message_loop)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a5e37f26ebc58915574819542a41a6329">UnregisterMessageHandler</a> ()</td></tr>
<tr><td colspan="2"><div class="groupHeader">PPB_Console methods for logging to the console:</div></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a192ab89f4acf2e1e25df14e22d0cff43">LogToConsole</a> (PP_LogLevel level, const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;value)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a48286ccf1217b3ae02138049d00af48f">LogToConsoleWithSource</a> (PP_LogLevel level, const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;source, const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;value)</td></tr>
</table><h2>
Static Public Member Functions</h2><table class="memberdecls">
<tr><td class="memItemLeft" align="right" valign="top">static void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#ad1b6c19954ff9446349a6fa5684eea2d">RemovePerInstanceObject</a> (const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;instance, const std::string &amp;interface_name, void *object)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classpp_1_1_instance.html#a6dec498f1d49571be9fd40e23745327f">GetPerInstanceObject</a> (PP_Instance instance, const std::string &amp;interface_name)</td></tr>
</table>
<hr /><h2>Constructor &amp; Destructor Documentation</h2>
<a class="anchor" id="a398b1946805872334781dac993cfe704"></a><!-- doxytag: member="pp::Instance::Instance" ref="a398b1946805872334781dac993cfe704" args="(PP_Instance instance)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classpp_1_1_instance.html#a398b1946805872334781dac993cfe704">pp::Instance::Instance</a> </td>
<td>(</td>
<td class="paramtype">PP_Instance&#160;</td>
<td class="paramname"><em>instance</em></td><td>)</td>
<td><code> [explicit]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default constructor. </p>
<p>Construction of an instance should only be done in response to a browser request in <code><a class="el" href="classpp_1_1_module.html#a648f236af50501bac40ce40296611825" title="CreateInstance() should be overridden to create your own module type.">Module::CreateInstance</a></code>. Otherwise, the instance will lack the proper bookkeeping in the browser and in the C++ wrapper.</p>
<p><a class="el" href="classpp_1_1_instance.html#a4f915e70caaef514a49ef8afcddde30f" title="Init() initializes this instance with the provided arguments.">Init()</a> 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. </p>
</div>
</div>
<a class="anchor" id="a5e475ef135a235029bc0515e9e3ff832"></a><!-- doxytag: member="pp::Instance::~Instance" ref="a5e475ef135a235029bc0515e9e3ff832" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual <a class="el" href="classpp_1_1_instance.html#a5e475ef135a235029bc0515e9e3ff832">pp::Instance::~Instance</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destructor. </p>
<p>When the instance is removed from the web page, the <code><a class="el" href="classpp_1_1_instance.html">pp::Instance</a></code> object will be deleted. You should never delete the <code><a class="el" href="classpp_1_1_instance.html">Instance</a></code> object yourself since the lifetime is handled by the C++ wrapper and is controlled by the browser's calls to the <code>PPP_Instance</code> interface.</p>
<p>The <code>PP_Instance</code> identifier will still be valid during this call so the instance can perform cleanup-related tasks. Once this function returns, the <code>PP_Instance</code> 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.</p>
<p><b>Note:</b> This function may be skipped in certain call so the instance can perform cleanup-related tasks. Once this function returns, the <code>PP_Instance</code> 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. </p>
</div>
</div>
<hr /><h2>Member Function Documentation</h2>
<a class="anchor" id="a9773263ee281405030548fc224eeec08"></a><!-- doxytag: member="pp::Instance::AddPerInstanceObject" ref="a9773263ee281405030548fc224eeec08" args="(const std::string &amp;interface_name, void *object)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a9773263ee281405030548fc224eeec08">pp::Instance::AddPerInstanceObject</a> </td>
<td>(</td>
<td class="paramtype">const std::string &amp;&#160;</td>
<td class="paramname"><em>interface_name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>object</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a9773263ee281405030548fc224eeec08" title="AddPerInstanceObject() associates an instance with an interface, creating an object.">AddPerInstanceObject()</a> associates an instance with an interface, creating an object. </p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>Refer to <a class="el" href="classpp_1_1_instance.html#a33c633189c7c321dac8e0c5dc6e67f5b" title="Refer to AddPerInstanceObject() for further information.">RemovePerInstanceObject()</a> and <a class="el" href="classpp_1_1_instance.html#a6dec498f1d49571be9fd40e23745327f" title="Look up an object previously associated with an instance.">GetPerInstanceObject()</a> for further information.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">interface_name</td><td>The name of the interface to associate with the instance </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">object</td><td></td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a147a1c1817a7a1fb2b76f5c87ab08899"></a><!-- doxytag: member="pp::Instance::BindGraphics" ref="a147a1c1817a7a1fb2b76f5c87ab08899" args="(const Graphics2D &amp;graphics)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899">pp::Instance::BindGraphics</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_graphics2_d.html">Graphics2D</a> &amp;&#160;</td>
<td class="paramname"><em>graphics</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899" title="BindGraphics() binds the given graphics as the current display surface.">BindGraphics()</a> binds the given graphics as the current display surface. </p>
<p>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.</p>
<p>You can pass an <code>is_null()</code> (default constructed) <a class="el" href="classpp_1_1_graphics2_d.html">Graphics2D</a> 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 <code>true</code> and will do nothing.</p>
<p>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.</p>
<p>Binding a device will invalidate that portion of the web page to flush the contents of the new device to the screen.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">graphics</td><td>A <code><a class="el" href="classpp_1_1_graphics2_d.html">Graphics2D</a></code> to bind.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>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. </dd></dl>
</div>
</div>
<a class="anchor" id="abcfd0eb0995e6273271b4ff4c3df16ae"></a><!-- doxytag: member="pp::Instance::BindGraphics" ref="abcfd0eb0995e6273271b4ff4c3df16ae" args="(const Graphics3D &amp;graphics)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899">pp::Instance::BindGraphics</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_graphics3_d.html">Graphics3D</a> &amp;&#160;</td>
<td class="paramname"><em>graphics</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Binds the given <a class="el" href="classpp_1_1_graphics3_d.html" title="This class represents a 3D rendering context in the browser.">Graphics3D</a> as the current display surface. </p>
<p>Refer to <code><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899" title="BindGraphics() binds the given graphics as the current display surface.">BindGraphics(const Graphics2D&amp; graphics)</a></code> for further information.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">graphics</td><td>A <code><a class="el" href="classpp_1_1_graphics3_d.html" title="This class represents a 3D rendering context in the browser.">Graphics3D</a></code> to bind.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>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. </dd></dl>
</div>
</div>
<a class="anchor" id="a845a8736f87b78538c73c9f8d192b77a"></a><!-- doxytag: member="pp::Instance::BindGraphics" ref="a845a8736f87b78538c73c9f8d192b77a" args="(const Compositor &amp;compositor)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899">pp::Instance::BindGraphics</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_compositor.html">Compositor</a> &amp;&#160;</td>
<td class="paramname"><em>compositor</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Binds the given <a class="el" href="classpp_1_1_compositor.html" title="The Compositor interface is used for setting CompositorLayer layers to the Chromium compositor for co...">Compositor</a> as the current display surface. </p>
<p>Refer to <code><a class="el" href="classpp_1_1_instance.html#a147a1c1817a7a1fb2b76f5c87ab08899" title="BindGraphics() binds the given graphics as the current display surface.">BindGraphics(const Graphics2D&amp; graphics)</a></code> for further information.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">compositor</td><td>A <code><a class="el" href="classpp_1_1_compositor.html" title="The Compositor interface is used for setting CompositorLayer layers to the Chromium compositor for co...">Compositor</a></code> to bind.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>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. </dd></dl>
</div>
</div>
<a class="anchor" id="a286bc22174e2f7b6e917c56aa5c7de86"></a><!-- doxytag: member="pp::Instance::ClearInputEventRequest" ref="a286bc22174e2f7b6e917c56aa5c7de86" args="(uint32_t event_classes)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a286bc22174e2f7b6e917c56aa5c7de86">pp::Instance::ClearInputEventRequest</a> </td>
<td>(</td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>event_classes</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a286bc22174e2f7b6e917c56aa5c7de86" title="ClearInputEventRequest() requests that input events corresponding to the given input classes no longe...">ClearInputEventRequest()</a> requests that input events corresponding to the given input classes no longer be delivered to the instance. </p>
<p>By default, no input events are delivered. If you have previously requested input events using <a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a> or <a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents()</a>, this function will unregister handling for the given instance. This will allow greater browser performance for those events.</p>
<p><b>Note: </b> 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.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">event_classes</td><td>A combination of flags from <code>PP_InputEvent_Class</code> that identifies the classes of events the instance is no longer interested in. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a42c67b21f11bef29c5b341c78926bad3"></a><!-- doxytag: member="pp::Instance::DidChangeFocus" ref="a42c67b21f11bef29c5b341c78926bad3" args="(bool has_focus)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual void <a class="el" href="classpp_1_1_instance.html#a42c67b21f11bef29c5b341c78926bad3">pp::Instance::DidChangeFocus</a> </td>
<td>(</td>
<td class="paramtype">bool&#160;</td>
<td class="paramname"><em>has_focus</em></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a42c67b21f11bef29c5b341c78926bad3" title="DidChangeFocus() is called when an instance has gained or lost focus.">DidChangeFocus()</a> is called when an instance has gained or lost focus. </p>
<p>Having focus means that keyboard events will be sent to the instance. An instance's default condition is that it will not have focus.</p>
<p>The focus flag takes into account both browser tab and window focus as well as focus of the plugin element on the page. In order to be deemed to have focus, the browser window must be topmost, the tab must be selected in the window, and the instance must be the focused element on the page.</p>
<p><b>Note:</b>Clicks on instances will give focus only if you handle the click event. Return <code>true</code> from <code>HandleInputEvent</code> in <code>PPP_InputEvent</code> (or use unfiltered events) 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 either requesting them via <code><a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a></code><code> (which implicitly marks all input events as consumed) or via </code><code><a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents()</a></code> and returning true from your event handler.</p>
<p><code></code><code> </code></p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">has_focus</td><td>Indicates the new focused state of the instance. </td></tr>
</table>
</dd>
</dl>
<p></p>
</div>
</div>
<a class="anchor" id="ad952f05e42f0e036157beb216f12f3f3"></a><!-- doxytag: member="pp::Instance::DidChangeView" ref="ad952f05e42f0e036157beb216f12f3f3" args="(const View &amp;view)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual void <a class="el" href="classpp_1_1_instance.html#ad952f05e42f0e036157beb216f12f3f3">pp::Instance::DidChangeView</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_view.html">View</a> &amp;&#160;</td>
<td class="paramname"><em>view</em></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#ad952f05e42f0e036157beb216f12f3f3" title="DidChangeView() is called when the view information for the Instance has changed.">DidChangeView()</a> is called when the view information for the <a class="el" href="classpp_1_1_instance.html">Instance</a> has changed. </p>
<p>See the <code><a class="el" href="classpp_1_1_view.html" title="This class represents the state of the view for an instance and contains functions for retrieving the...">View</a></code> object for information.</p>
<p>Most implementations will want to check if the size and user visibility changed, and either resize themselves or start/stop generating updates.</p>
<p>You should not call the default implementation. For backwards-compatibility, it will call the deprecated version of DidChangeView below. </p>
</div>
</div>
<a class="anchor" id="a72ac4ec0b62c4cd8dedae3cf0fc577c2"></a><!-- doxytag: member="pp::Instance::DidChangeView" ref="a72ac4ec0b62c4cd8dedae3cf0fc577c2" args="(const Rect &amp;position, const Rect &amp;clip)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual void <a class="el" href="classpp_1_1_instance.html#ad952f05e42f0e036157beb216f12f3f3">pp::Instance::DidChangeView</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_rect.html">Rect</a> &amp;&#160;</td>
<td class="paramname"><em>position</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_rect.html">Rect</a> &amp;&#160;</td>
<td class="paramname"><em>clip</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Deprecated backwards-compatible version of <code><a class="el" href="classpp_1_1_instance.html#ad952f05e42f0e036157beb216f12f3f3" title="DidChangeView() is called when the view information for the Instance has changed.">DidChangeView()</a></code>. </p>
<p>New code should derive from the version that takes a <code>ViewChanged</code> object rather than this version. This function is called by the default implementation of the newer <code>DidChangeView</code> function for source compatibility with older code.</p>
<p>A typical implementation will check the size of the <code>position</code> 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.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">position</td><td>The 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).</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">clip</td><td>The 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, <code>clip</code> will be (0, 0, 0, 0).</td></tr>
</table>
</dd>
</dl>
<p>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 scrolling so there can be flashes of old content in the exposed regions). </p>
</div>
</div>
<a class="anchor" id="a6dec498f1d49571be9fd40e23745327f"></a><!-- doxytag: member="pp::Instance::GetPerInstanceObject" ref="a6dec498f1d49571be9fd40e23745327f" args="(PP_Instance instance, const std::string &amp;interface_name)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static void* <a class="el" href="classpp_1_1_instance.html#a6dec498f1d49571be9fd40e23745327f">pp::Instance::GetPerInstanceObject</a> </td>
<td>(</td>
<td class="paramtype">PP_Instance&#160;</td>
<td class="paramname"><em>instance</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const std::string &amp;&#160;</td>
<td class="paramname"><em>interface_name</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Look up an object previously associated with an instance. </p>
<p>Returns NULL if the instance is invalid or there is no object for the given interface name on the instance.</p>
<p>Refer to <a class="el" href="classpp_1_1_instance.html#a9773263ee281405030548fc224eeec08" title="AddPerInstanceObject() associates an instance with an interface, creating an object.">AddPerInstanceObject()</a> for further information.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">instance</td><td></td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">interface_name</td><td>The name of the interface to associate with the instance. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a6cd99065ef0a55555647253442563225"></a><!-- doxytag: member="pp::Instance::HandleDocumentLoad" ref="a6cd99065ef0a55555647253442563225" args="(const URLLoader &amp;url_loader)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual bool <a class="el" href="classpp_1_1_instance.html#a6cd99065ef0a55555647253442563225">pp::Instance::HandleDocumentLoad</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_u_r_l_loader.html">URLLoader</a> &amp;&#160;</td>
<td class="paramname"><em>url_loader</em></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a6cd99065ef0a55555647253442563225" title="HandleDocumentLoad() is called after Init() for a full-frame instance that was instantiated based on ...">HandleDocumentLoad()</a> is called after <a class="el" href="classpp_1_1_instance.html#a4f915e70caaef514a49ef8afcddde30f" title="Init() initializes this instance with the provided arguments.">Init()</a> for a full-frame instance that was instantiated based on the MIME type of a DOMWindow navigation. </p>
<p>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.</p>
<p>The given url_loader corresponds to a <code><a class="el" href="classpp_1_1_u_r_l_loader.html" title="URLLoader provides an API for loading URLs.">URLLoader</a></code> object that is already opened. Its response headers may be queried using GetResponseInfo(). If you want to use the <code><a class="el" href="classpp_1_1_u_r_l_loader.html" title="URLLoader provides an API for loading URLs.">URLLoader</a></code> 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.</p>
<p>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.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">url_loader</td><td>An open <code><a class="el" href="classpp_1_1_u_r_l_loader.html" title="URLLoader provides an API for loading URLs.">URLLoader</a></code> instance.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>true if the data was handled, false otherwise. </dd></dl>
</div>
</div>
<a class="anchor" id="a46aa2feb657fa14263a29375fe458b00"></a><!-- doxytag: member="pp::Instance::HandleInputEvent" ref="a46aa2feb657fa14263a29375fe458b00" args="(const pp::InputEvent &amp;event)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual bool <a class="el" href="classpp_1_1_instance.html#a46aa2feb657fa14263a29375fe458b00">pp::Instance::HandleInputEvent</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_input_event.html">pp::InputEvent</a> &amp;&#160;</td>
<td class="paramname"><em>event</em></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a46aa2feb657fa14263a29375fe458b00" title="HandleInputEvent() handles input events from the browser.">HandleInputEvent()</a> handles input events from the browser. </p>
<p>The default implementation does nothing and returns false.</p>
<p>In order to receive input events, you must register for them by calling <a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a> or <a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents()</a>. By default, no events are delivered.</p>
<p>If the event was handled, it will not be forwarded to any default handlers. If it was not handled, it may be dispatched to a default handler. So it is important that an instance respond accurately with whether event propagation should continue.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p><b>Note: </b>If you're not receiving input events, make sure you register for the event classes you want by calling <code>RequestInputEvents</code> or <code>RequestFilteringInputEvents</code>. 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.</p>
<p>Refer to <code>RequestInputEvents</code> and <code>RequestFilteringInputEvents</code> for further information.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">event</td><td>The event to handle.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>true if the event was handled, false if not. If you have registered to filter this class of events by calling <code>RequestFilteringInputEvents</code>, 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. </dd></dl>
</div>
</div>
<a class="anchor" id="a5dce8c8b36b1df7cfcc12e42397a35e8"></a><!-- doxytag: member="pp::Instance::HandleMessage" ref="a5dce8c8b36b1df7cfcc12e42397a35e8" args="(const Var &amp;message)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual void <a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8">pp::Instance::HandleMessage</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;&#160;</td>
<td class="paramname"><em>message</em></td><td>)</td>
<td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8" title="HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element...">HandleMessage()</a> is a function that the browser calls when <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> is invoked on the DOM element for the instance in JavaScript. </p>
<p>Note that <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> in the JavaScript interface is asynchronous, meaning JavaScript execution will not be blocked while <a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8" title="HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element...">HandleMessage()</a> is processing the message.</p>
<p>When converting JavaScript arrays, any object properties whose name is not an array index are ignored. When passing arrays and objects, the entire reference graph will be converted and transferred. If the reference graph has cycles, the message will not be sent and an error will be logged to the console.</p>
<p><b>Example:</b></p>
<p>The following JavaScript code invokes <code>HandleMessage</code>, passing the instance on which it was invoked, with <code>message</code> being a string <code><a class="el" href="classpp_1_1_var.html" title="A generic type used for passing data types between the module and the page.">Var</a></code> containing "Hello world!"</p>
<div class="fragment"><pre class="fragment"> {.html}
&lt;body&gt;
&lt;<span class="keywordtype">object</span> <span class="keywordtype">id</span>=<span class="stringliteral">&quot;plugin&quot;</span>
type=<span class="stringliteral">&quot;application/x-ppapi-postMessage-example&quot;</span>/&gt;
&lt;script type=<span class="stringliteral">&quot;text/javascript&quot;</span>&gt;
document.getElementById(<span class="stringliteral">&#39;plugin&#39;</span>).postMessage(<span class="stringliteral">&quot;Hello world!&quot;</span>);
&lt;/script&gt;
&lt;/body&gt;
</pre></div><p>Refer to <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> for sending messages to JavaScript.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">message</td><td>A <code><a class="el" href="classpp_1_1_var.html" title="A generic type used for passing data types between the module and the page.">Var</a></code> which has been converted from a JavaScript value. JavaScript array/object types are supported from Chrome M29 onward. All JavaScript values are copied when passing them to the plugin. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="a4f915e70caaef514a49ef8afcddde30f"></a><!-- doxytag: member="pp::Instance::Init" ref="a4f915e70caaef514a49ef8afcddde30f" args="(uint32_t argc, const char *argn[], const char *argv[])" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">virtual bool <a class="el" href="classpp_1_1_instance.html#a4f915e70caaef514a49ef8afcddde30f">pp::Instance::Init</a> </td>
<td>(</td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>argc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>argn</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>argv</em>[]&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [virtual]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a4f915e70caaef514a49ef8afcddde30f" title="Init() initializes this instance with the provided arguments.">Init()</a> initializes this instance with the provided arguments. </p>
<p>This function will be called immediately after the instance object is constructed.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">argc</td><td>The number of arguments contained in <code>argn</code> and <code>argv</code>.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">argn</td><td>An array of argument names. These argument names are supplied in the &lt;embed&gt; tag, for example: <code>&lt;embed id="nacl_module" dimensions="2"&gt;</code> will produce two argument names: "id" and "dimensions".</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">argv</td><td>An array of argument values. These are the values of the arguments listed in the &lt;embed&gt; tag, for example <code>&lt;embed id="nacl_module" dimensions="2"&gt;</code> will produce two argument values: "nacl_module" and "2". The indices of these values match the indices of the corresponding names in <code>argn</code>.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>true on success. Returning false causes the instance to be deleted and no other functions to be called. </dd></dl>
</div>
</div>
<a class="anchor" id="a451fb956e64fd3db891608148a044c01"></a><!-- doxytag: member="pp::Instance::IsFullFrame" ref="a451fb956e64fd3db891608148a044c01" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool <a class="el" href="classpp_1_1_instance.html#a451fb956e64fd3db891608148a044c01">pp::Instance::IsFullFrame</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a451fb956e64fd3db891608148a044c01" title="IsFullFrame() determines if the instance is full-frame (repr).">IsFullFrame()</a> determines if the instance is full-frame (repr). </p>
<p>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.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>true if the instance is full-frame, false if not. </dd></dl>
</div>
</div>
<a class="anchor" id="a192ab89f4acf2e1e25df14e22d0cff43"></a><!-- doxytag: member="pp::Instance::LogToConsole" ref="a192ab89f4acf2e1e25df14e22d0cff43" args="(PP_LogLevel level, const Var &amp;value)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a192ab89f4acf2e1e25df14e22d0cff43">pp::Instance::LogToConsole</a> </td>
<td>(</td>
<td class="paramtype">PP_LogLevel&#160;</td>
<td class="paramname"><em>level</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;&#160;</td>
<td class="paramname"><em>value</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Logs the given message to the JavaScript console associated with the given plugin instance with the given logging level. </p>
<p>The name of the plugin issuing the log message will be automatically prepended to the message. The value may be any type of <a class="el" href="classpp_1_1_var.html" title="A generic type used for passing data types between the module and the page.">Var</a>. </p>
</div>
</div>
<a class="anchor" id="a48286ccf1217b3ae02138049d00af48f"></a><!-- doxytag: member="pp::Instance::LogToConsoleWithSource" ref="a48286ccf1217b3ae02138049d00af48f" args="(PP_LogLevel level, const Var &amp;source, const Var &amp;value)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a48286ccf1217b3ae02138049d00af48f">pp::Instance::LogToConsoleWithSource</a> </td>
<td>(</td>
<td class="paramtype">PP_LogLevel&#160;</td>
<td class="paramname"><em>level</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;&#160;</td>
<td class="paramname"><em>source</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;&#160;</td>
<td class="paramname"><em>value</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Logs a message to the console with the given source information rather than using the internal PPAPI plugin name. </p>
<p>The name must be a string var.</p>
<p>The regular log function will automatically prepend the name of your plugin to the message as the "source" of the message. Some plugins may wish to override this. For example, if your plugin is a Python interpreter, you would want log messages to contain the source .py file doing the log statement rather than have "python" show up in the console. </p>
</div>
</div>
<a class="anchor" id="a67e888a4e4e23effe7a09625e73ecae9"></a><!-- doxytag: member="pp::Instance::PostMessage" ref="a67e888a4e4e23effe7a09625e73ecae9" args="(const Var &amp;message)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9">pp::Instance::PostMessage</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_var.html">Var</a> &amp;&#160;</td>
<td class="paramname"><em>message</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> asynchronously invokes any listeners for message events on the DOM element for the given instance. </p>
<p>A call to <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> will not block while the message is processed.</p>
<p><b>Example:</b></p>
<div class="fragment"><pre class="fragment"> {.html}
&lt;body&gt;
&lt;<span class="keywordtype">object</span> <span class="keywordtype">id</span>=<span class="stringliteral">&quot;plugin&quot;</span>
type=<span class="stringliteral">&quot;application/x-ppapi-postMessage-example&quot;</span>/&gt;
&lt;script type=<span class="stringliteral">&quot;text/javascript&quot;</span>&gt;
var plugin = document.getElementById(<span class="stringliteral">&#39;plugin&#39;</span>);
plugin.addEventListener(<span class="stringliteral">&quot;message&quot;</span>,
<span class="keyword">function</span>(message) { alert(message.data); },
<span class="keyword">false</span>);
&lt;/script&gt;
&lt;/body&gt;
</pre></div><p>The instance then invokes <a class="el" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage()</a> as follows:</p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classpp_1_1_instance.html#a67e888a4e4e23effe7a09625e73ecae9" title="PostMessage() asynchronously invokes any listeners for message events on the DOM element for the give...">PostMessage</a>(<a class="code" href="classpp_1_1_var.html" title="A generic type used for passing data types between the module and the page.">pp::Var</a>(<span class="stringliteral">&quot;Hello world!&quot;</span>));
</pre></div><p>The browser will pop-up an alert saying "Hello world!"</p>
<p>When passing array or dictionary <code>PP_Var</code>s, the entire reference graph will be converted and transferred. If the reference graph has cycles, the message will not be sent and an error will be logged to the console.</p>
<p>Listeners for message events in JavaScript code will receive an object conforming to the HTML 5 <code>MessageEvent</code> interface. Specifically, the value of message will be contained as a property called data in the received <code>MessageEvent</code>.</p>
<p>This messaging system is similar to the system used for listening for messages from Web Workers. Refer to <code><a href="http://www.whatwg.org/specs/web-workers/current-work/">http://www.whatwg.org/specs/web-workers/current-work/</a></code> for further information.</p>
<p>Refer to <a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8" title="HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element...">HandleMessage()</a> for receiving events from JavaScript.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">message</td><td>A <code><a class="el" href="classpp_1_1_var.html" title="A generic type used for passing data types between the module and the page.">Var</a></code> containing the data to be sent to JavaScript. Message can have a numeric, boolean, or string value. Array/Dictionary types are supported from Chrome M29 onward. All var types are copied when passing them to JavaScript. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="aeb29ff4201f9ae0e356c5ed0bb4a2679"></a><!-- doxytag: member="pp::Instance::pp_instance" ref="aeb29ff4201f9ae0e356c5ed0bb4a2679" args="() const " -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">PP_Instance <a class="el" href="classpp_1_1_instance.html#aeb29ff4201f9ae0e356c5ed0bb4a2679">pp::Instance::pp_instance</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td> const<code> [inline]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This function returns the <code>PP_Instance</code> identifying this object. </p>
<dl class="return"><dt><b>Returns:</b></dt><dd>A <code>PP_Instance</code> identifying this object. </dd></dl>
</div>
</div>
<a class="anchor" id="a5b5b1a66eda2d0e6884de8f7e25e2346"></a><!-- doxytag: member="pp::Instance::RegisterMessageHandler" ref="a5b5b1a66eda2d0e6884de8f7e25e2346" args="(MessageHandler *message_handler, const MessageLoop &amp;message_loop)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_instance.html#a5b5b1a66eda2d0e6884de8f7e25e2346">pp::Instance::RegisterMessageHandler</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="classpp_1_1_message_handler.html">MessageHandler</a> *&#160;</td>
<td class="paramname"><em>message_handler</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="classpp_1_1_message_loop.html">MessageLoop</a> &amp;&#160;</td>
<td class="paramname"><em>message_loop</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Dev-Channel Only. </p>
<p>Registers a handler for receiving messages from JavaScript. If a handler is registered this way, it will replace the <a class="el" href="classpp_1_1_instance.html">Instance</a>'s HandleMessage method, and all messages sent from JavaScript via postMessage and postMessageAndAwaitResponse will be dispatched to <code>message_handler</code>.</p>
<p>The function calls will be dispatched via <code>message_loop</code>. This means that the functions will be invoked on the thread to which <code>message_loop</code> is attached, when <code>message_loop</code> is run. It is illegal to pass the main thread message loop; RegisterMessageHandler will return PP_ERROR_WRONG_THREAD in that case. If you quit <code>message_loop</code> before calling Unregister(), the browser will not be able to call functions in the plugin's message handler any more. That could mean missing some messages or could cause a leak if you depend on Destroy() to free hander data. So you should, whenever possible, Unregister() the handler prior to quitting its event loop.</p>
<p>Attempting to register a message handler when one is already registered will cause the current <a class="el" href="classpp_1_1_message_handler.html" title="MessageHandler is an abstract base class that the plugin may implement if it wants to receive message...">MessageHandler</a> to be unregistered and replaced. In that case, no messages will be sent to the "default" message handler (<a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8" title="HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element...">pp::Instance::HandleMessage()</a>). Messages will stop arriving at the prior message handler and will begin to be dispatched at the new message handler.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">message_handler</td><td>The plugin-provided object for handling messages. The instance does not take ownership of the pointer; it is up to the plugin to ensure that |message_handler| lives until its WasUnregistered() function is invoked. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">message_loop</td><td>Represents the message loop on which <a class="el" href="classpp_1_1_message_handler.html" title="MessageHandler is an abstract base class that the plugin may implement if it wants to receive message...">MessageHandler</a>'s functions should be invoked. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>PP_OK on success, or an error from pp_errors.h. </dd></dl>
</div>
</div>
<a class="anchor" id="a33c633189c7c321dac8e0c5dc6e67f5b"></a><!-- doxytag: member="pp::Instance::RemovePerInstanceObject" ref="a33c633189c7c321dac8e0c5dc6e67f5b" args="(const std::string &amp;interface_name, void *object)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a33c633189c7c321dac8e0c5dc6e67f5b">pp::Instance::RemovePerInstanceObject</a> </td>
<td>(</td>
<td class="paramtype">const std::string &amp;&#160;</td>
<td class="paramname"><em>interface_name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>object</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Refer to <a class="el" href="classpp_1_1_instance.html#a9773263ee281405030548fc224eeec08" title="AddPerInstanceObject() associates an instance with an interface, creating an object.">AddPerInstanceObject()</a> for further information. </p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">interface_name</td><td>The name of the interface to associate with the instance </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">object</td><td></td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ad1b6c19954ff9446349a6fa5684eea2d"></a><!-- doxytag: member="pp::Instance::RemovePerInstanceObject" ref="ad1b6c19954ff9446349a6fa5684eea2d" args="(const InstanceHandle &amp;instance, const std::string &amp;interface_name, void *object)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static void <a class="el" href="classpp_1_1_instance.html#a33c633189c7c321dac8e0c5dc6e67f5b">pp::Instance::RemovePerInstanceObject</a> </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="classpp_1_1_instance_handle.html">InstanceHandle</a> &amp;&#160;</td>
<td class="paramname"><em>instance</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const std::string &amp;&#160;</td>
<td class="paramname"><em>interface_name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>object</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Static version of AddPerInstanceObject that takes an <a class="el" href="classpp_1_1_instance_handle.html" title="An instance handle identifies an instance in a constructor for a resource.">InstanceHandle</a>. </p>
<p>As with all other instance functions, this must only be called on the main thread. </p>
</div>
</div>
<a class="anchor" id="a6341c14fc54427e45349f5158483e017"></a><!-- doxytag: member="pp::Instance::RequestFilteringInputEvents" ref="a6341c14fc54427e45349f5158483e017" args="(uint32_t event_classes)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017">pp::Instance::RequestFilteringInputEvents</a> </td>
<td>(</td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>event_classes</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents()</a> requests that input events corresponding to the given input events are delivered to the instance for filtering. </p>
<p>By default, no input events are delivered. In most cases you would register to receive events by calling <a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a>. 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 <a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a>. Keyboard events must always be registered in filtering mode.</p>
<p>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.</p>
<p><b>Example:</b></p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents</a>(PP_INPUTEVENT_CLASS_MOUSE);
<a class="code" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents</a>(
PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
</pre></div><dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">event_classes</td><td>A combination of flags from <code>PP_InputEvent_Class</code> that identifies the classes of events the instance is requesting. The flags are combined by logically ORing their values.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><code>PP_OK</code> if the operation succeeded, <code>PP_ERROR_BADARGUMENT</code> if instance is invalid, or <code>PP_ERROR_NOTSUPPORTED</code> 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. </dd></dl>
</div>
</div>
<a class="anchor" id="a2e2d63280786c0cc41b7c6f656cc81b5"></a><!-- doxytag: member="pp::Instance::RequestInputEvents" ref="a2e2d63280786c0cc41b7c6f656cc81b5" args="(uint32_t event_classes)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int32_t <a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5">pp::Instance::RequestInputEvents</a> </td>
<td>(</td>
<td class="paramtype">uint32_t&#160;</td>
<td class="paramname"><em>event_classes</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p><a class="el" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents()</a> requests that input events corresponding to the given input events are delivered to the instance. </p>
<p>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 <a class="el" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents()</a>, this function will set those events to non-filtering mode).</p>
<p>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 noticeable effect on the performance of the page.</p>
<p>When requesting input events through this function, the events will be delivered and <em>not</em> 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.</p>
<p><b>Example:</b></p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classpp_1_1_instance.html#a2e2d63280786c0cc41b7c6f656cc81b5" title="RequestInputEvents() requests that input events corresponding to the given input events are delivered...">RequestInputEvents</a>(PP_INPUTEVENT_CLASS_MOUSE);
<a class="code" href="classpp_1_1_instance.html#a6341c14fc54427e45349f5158483e017" title="RequestFilteringInputEvents() requests that input events corresponding to the given input events are ...">RequestFilteringInputEvents</a>(
PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
</pre></div><dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">event_classes</td><td>A combination of flags from <code>PP_InputEvent_Class</code> that identifies the classes of events the instance is requesting. The flags are combined by logically ORing their values.</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><code>PP_OK</code> if the operation succeeded, <code>PP_ERROR_BADARGUMENT</code> if instance is invalid, or <code>PP_ERROR_NOTSUPPORTED</code> 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. </dd></dl>
</div>
</div>
<a class="anchor" id="a5e37f26ebc58915574819542a41a6329"></a><!-- doxytag: member="pp::Instance::UnregisterMessageHandler" ref="a5e37f26ebc58915574819542a41a6329" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void <a class="el" href="classpp_1_1_instance.html#a5e37f26ebc58915574819542a41a6329">pp::Instance::UnregisterMessageHandler</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Unregisters the current message handler for this instance if one is registered. </p>
<p>After this call, the message handler (if one was registered) will have "WasUnregistered" called on it and will receive no further messages. After that point, all messages sent from JavaScript using postMessage() will be dispatched to <a class="el" href="classpp_1_1_instance.html#a5dce8c8b36b1df7cfcc12e42397a35e8" title="HandleMessage() is a function that the browser calls when PostMessage() is invoked on the DOM element...">pp::Instance::HandleMessage()</a> on the main thread. Attempts to call postMessageAndAwaitResponse() from JavaScript after that point will fail.</p>
<p>Attempting to unregister a message handler when none is registered has no effect. </p>
</div>
</div>
<hr />The documentation for this class was generated from the following file:<ul>
<li><a class="el" href="instance_8h.html">instance.h</a></li>
</ul>
</div><!-- contents -->
</div>
{{/partials.standard_nacl_api}}