<chapter id="InteractActions">
  <title>Actions Passed to an Interact</title>
  <para>
    This chapter describes the actions that can be issued to an interact's main entry point. 
    Interact actions are also generic in character, they could be issued to other plug-in types rather than just Image Effects,
    however they are not issued directly to an effect's main entry point, they are rather issued to separate entry points which 
    exist on specific 'interact' objects that a plugin may create. 
  </para>
  <para>
    For nearly all the actions the <code>handle</code> passed to to main entry point for an interact will be either NULL, or a value
    that should be cast to an <code>OfxInteractHandle</code>.
  </para>
      
  <section id="kOfxActionDescribeInteract"><title>The Describe Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionDescribe "OfxActionDescribe" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the interact descriptor, cast to an <code>OfxInteractHandle</code></listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>      
    &description;
    <para>
      The kOfxActionDescribe is the first action passed to an interact. It is where an interact defines how it behaves and the resources it needs to function.
    </para>
    
    <para>
      Note that the handle passed in acts as a descriptor for, rather than an instance of the interact.
    </para>
    
    &preconditions;
    <para>
      The plugin has been loaded and the effect described.
    </para>
    
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and all was well</listitem>
	<listitem><link linkend="kOfxStatErrMemory"><code>kOfxStatErrMemory</code></link>, in which case describe may be called again after a memory purge</listitem>
	<listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, something was wrong, the host should ignore the interact</listitem>
	<listitem><link linkend="kOfxStatErrFatal"><code>kOfxStatErrFatal</code></link></listitem>
      </itemizedlist>
    </para>
    
    &defaultAction;
    <para>
      If not trapped, the default action is for the host to carry on as normal
    </para>
  </section>
  
  <section id="kOfxActionCreateInstanceInteract"><title >The Create Instance Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionCreateInstance        "OfxActionCreateInstance" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      The <link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> is the first action passed to an interact instance after its creation. 
      It is there to allow a plugin to create any per-instance data structures it may need.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionDescribe"><code>kOfxActionDescribe</code></link> has been called on this interact</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>the instance pointer will be valid until the <link linkend="kOfxActionDestroyInstance"><code>kOfxActionDestroyInstance</code></link> action is passed to the plug-in with the same instance handle</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and all was well</listitem>
	<listitem><link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was ignored, but all was well anyway</listitem>
	<listitem><link linkend="kOfxStatErrFatal"><code>kOfxStatErrFatal</code></link></listitem>
	<listitem><link linkend="kOfxStatErrMemory"><code>kOfxStatErrMemory</code></link>, in which case this may be called again after a memory purge</listitem>
	<listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, in which case the host should ignore this interact</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxActionDestroyInstanceInteract"><title >The Destroy Instance Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxActionDestroyInstance       "OfxActionDestroyInstance" </programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to the interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> is redundant and is set to NULL,</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    
    &description;
    <para>
      This action is the last passed to an interact's instance before its destruction. It is there to allow a plugin to destroy
      any per-instance data structures it may have created.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem><code>kOfxActionCreateInstance</code> has been called on the handle,</listitem>
	<listitem>the instance has not had any of its members destroyed yet, </listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>	
	<listitem>the instance pointer is no longer valid and any operation on it will be undefined</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      To some extent, what is returned is moot, a bit like throwing an exception in a C++ destructor, so the host should 
      continue destruction of the instance regardless. However...
      <itemizedlist>	
	<listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and all was well,</listitem>
	<listitem>OfxStatReplyDefault, the action was ignored as the effect had nothing to do, </listitem>
	<listitem><link linkend="kOfxStatErrFatal"><code>kOfxStatErrFatal</code></link>,</listitem>
	<listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, something went wrong, but no error code appropriate.</listitem>
      </itemizedlist>
    </para>
  </section>
    
  <section id="kOfxInteractActionDraw"><title >The Draw Action</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionDraw "OfxInteractActionDraw"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued to an interact whenever the host needs the plugin to redraw the given interact. 
      The interact should issue any openGL calls it needs at this point.
    </para>
    
    <para>
      Note that the interact may (in the case of custom parameter GUIS) or may not 
      (in the case of image effect overlays) be required to swap buffers, that is up to the kind of interact.
    </para>
    
    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the openGL context for this interact has been set</listitem>
	<listitem>the projection matrix will correspond to the interact's cannonical voew</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and all was well</listitem>
	<listitem><link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was ignored</listitem>
	<listitem><link linkend="kOfxStatErrFatal"><code>kOfxStatErrFatal</code></link>, </listitem>
	<listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link>, something went wrong, the host should ignore this interact in future</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionPenMotion"> <title >kOfxInteractActionPenMotion</title>  
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionPenMotion "OfxInteractActionPenMotion"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPosition"><code>kOfxInteractPropPenPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenViewportPosition"><code>kOfxInteractPropPenViewportPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPressure"><code>kOfxInteractPropPenPressure</code></link> - the pressure of the pen,</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued whenever the pen moves an the interact's has focus. It should be issued whether the
      pen is currently up or down.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same view.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionPenDown"> <title >kOfxInteractActionPenDown</title>
      <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionPenDown "OfxInteractActionPenDown"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPosition"><code>kOfxInteractPropPenPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenViewportPosition"><code>kOfxInteractPropPenViewportPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPressure"><code>kOfxInteractPropPenPressure</code></link> - the pressure of the pen,</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when a pen transitions for the 'up' to the 'down' state.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same view.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionPenUp"> <title >kOfxInteractActionPenUp</title>
      <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionPenUp "OfxInteractActionPenUp"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPosition"><code>kOfxInteractPropPenPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenViewportPosition"><code>kOfxInteractPropPenViewportPosition</code></link> - postion of the pen in,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPenPressure"><code>kOfxInteractPropPenPressure</code></link> - the pressure of the pen,</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when a pen transitions for the 'down' to the 'up' state.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same view.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionKeyDown"> <title >kOfxInteractActionKeyDown</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionKeyDown "OfxInteractActionKeyDown"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxPropKeySym"><code>kOfxPropKeySym</code></link>    - single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)</listitem>
	    <listitem> <link linkend="kOfxPropKeyString"><code>kOfxPropKeyString</code></link> - UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>

	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when a key on the keyboard is depressed.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same focus.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>

  </section>
  
  <section id="kOfxInteractActionKeyUp"> <title >kOfxInteractActionKeyUp</title>
        <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionKeyUp "OfxInteractActionKeyUp"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxPropKeySym"><code>kOfxPropKeySym</code></link>    - single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)</listitem>
	    <listitem> <link linkend="kOfxPropKeyString"><code>kOfxPropKeyString</code></link> - UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>

	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when a key on the keyboard is released.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same focus.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionKeyRepeat"> <title >kOfxInteractActionKeyRepeat</title>
    
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionKeyRepeat "OfxInteractActionKeyRepeat"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact has been,</listitem>
	    <listitem> <link linkend="kOfxPropKeySym"><code>kOfxPropKeySym</code></link>    - single integer value representing the key that was manipulated, this may not have a UTF8 representation (eg: a return key)</listitem>
	    <listitem> <link linkend="kOfxPropKeyString"><code>kOfxPropKeyString</code></link> - UTF8 string representing a character key that was pressed, some keys have no UTF8 encoding, in which case this is ""</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>

	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when a key on the keyboard is held down an a key repeat is issued.
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
	<listitem>the current instance handle has had <link linkend="kOfxInteractActionGainFocus"><code>kOfxInteractActionGainFocus</code></link> called on it</listitem>
      </itemizedlist>
    </para>
    
    &postconditions;
    <para>
      <itemizedlist>
	<listitem>if the instance returns <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the host should <emphasis>not</emphasis> pass
	  the pen motion to any other interactive object it may own that shares the same focus.</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped and the host should not pass the event to other objects it may own</listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped and the host can deal with it if it wants</listitem>
      </itemizedlist>
    </para>

  </section>
  
  <section id="kOfxInteractActionGainFocus"> <title >kOfxInteractActionGainFocus</title>
      <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionGainFocus "OfxInteractActionGainFocus"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact is being used on,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels,</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when an interact gains input focus.    
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped </listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped</listitem>
      </itemizedlist>
    </para>
  </section>
  
  <section id="kOfxInteractActionLoseFocus"> <title >kOfxInteractActionLoseFocus</title>
    <blockquote><programlisting>
	#include "ofxCore.h"
	#define kOfxInteractActionLoseFocus "OfxInteractActionLoseFocus"</programlisting></blockquote>
    &arguments;
    <para>
      <itemizedlist>
	<listitem><code>handle</code> handle to an interact instance, cast to an <code>OfxInteractHandle</code> </listitem>
	<listitem><code>inArgs</code> has the following properties on an image effect plugin,
	  <itemizedlist>
	    <listitem> <link linkend="kOfxPropEffectInstance"><code>kOfxPropEffectInstance</code></link> - a handle to the effect for which the interact is being used on,</listitem>
	    <listitem> <link linkend="kOfxInteractPropPixelScale"><code>kOfxInteractPropPixelScale</code></link> - the scale factor to convert cannonical pixels to screen pixels,</listitem>
	    <listitem> <link linkend="kOfxInteractPropBackgroundColour"><code>kOfxInteractPropBackgroundColour</code></link> - the background colour of the application behind the current view</listitem>
	    <listitem> <link linkend="kOfxPropTime"><code>kOfxPropTime</code></link>         - the effect time at which changed occured</listitem>
	    <listitem> <link linkend="kOfxImageEffectPropRenderScale"><code>kOfxImageEffectPropRenderScale</code></link>     - the render scale applied to any image fetched</listitem>
	  </itemizedlist>
	</listitem>
	<listitem><code>outArgs</code> is redundant and is set to NULL.</listitem>
      </itemizedlist>
    </para>
    &description;
    <para>
      This action is issued when an interact loses input focus.    
    </para>
    
    <para>
      No openGL calls should be issued by the plug-in during this action.
    </para>

    &preconditions;
    <para>
      <itemizedlist>
	<listitem><link linkend="kOfxActionCreateInstance"><code>kOfxActionCreateInstance</code></link> has been called on the instance handle,</listitem>
      </itemizedlist>
    </para>
    
    &returnValues;
    <para>
      <itemizedlist>
	<listitem> <link linkend="kOfxStatOK"><code>kOfxStatOK</code></link>, the action was trapped </listitem>
	<listitem> <link linkend="kOfxStatReplyDefault"><code>kOfxStatReplyDefault</code></link>, the action was not trapped</listitem>
      </itemizedlist>
    </para>
  </section>
  
</chapter>
  