
<refentry id="OfxProgressSuiteV1">
  <refmeta>
    <refentrytitle><type>OfxProgressSuiteV1</type></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxProgressSuiteV1</function></refname>
    <refpurpose>A suite that provides progress feedback from a plugin to an application</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
     <blockquote><programlisting>
#include "ofxProgress.h"
typedef struct OfxProgressSuiteV1 {
  OfxStatus (*progressStart)(void *effectInstance,
                             const char *label);
  OfxStatus (*progressUpdate)(void *effectInstance, double progress);
  OfxStatus (*progressEnd)(void *effectInstance);
} OfxProgressSuiteV1 ;

</programlisting></blockquote>
     </refsynopsisdiv>
    <refsect1>
      <title>Description</title><para>
A plugin instance can initiate, update and close a progress indicator with
this suite.
</para>
<para>
This is an optional suite in the Image Effect API.
</para>
<para>
API V1.4: Amends the documentation of progress suite V1 so that it is
expected that it can be raised in a modal manner and have a "cancel"
button when invoked in instanceChanged. Plugins that perform analysis
post an appropriate message, raise the progress monitor in a modal manner
and should poll to see if processing has been aborted. Any cancellation
should be handled gracefully by the plugin (eg: reset analysis parameters
to default values), clear allocated memory...
</para>
<para>
Many hosts already operate as described above. kOfxStatReplyNo should be
returned to the plugin during progressUpdate when the user presses
cancel.
</para>
<para>
Suite V2: Adds an ID that can be looked up for internationalisation and
so on. When a new version is introduced, because plug-ins need to support
old versions, and plug-in's new releases are not necessary in synch with
hosts (or users don't immediately update), best practice is to support
the 2 suite versions. That is, the plugin should check if V2 exists; if
not then check if V1 exists. This way a graceful transition is
guaranteed.  So plugin should fetchSuite passing 2,
(OfxProgressSuiteV2) fetchSuite(mHost-&gt;mHost-&gt;host, kOfxProgressSuite,2);
and if no success pass (OfxProgressSuiteV1)
fetchSuite(mHost-&gt;mHost-&gt;host, kOfxProgressSuite,1);
</para>
    </refsect1>
</refentry>

<refentry id="OfxProgressSuiteV1_progressStart">
  <refmeta>
    <refentrytitle><function>OfxProgressSuiteV1::progressStart</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxProgressSuiteV1::progressStart</function></refname>
       <refpurpose>Initiate a progress bar display.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxProgress.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*progressStart)</function></funcdef>
              <paramdef>void *<parameter>effectInstance</parameter></paramdef>
              <paramdef>const char *<parameter>label</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>effectInstance - the instance of the plugin this progress bar is
associated with. It cannot be NULL.
</listitem>
<listitem>label - a text label to display in any message portion of the
progress object's user interface. A UTF8 string.
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
Call this to initiate the display of a progress bar.
</para>
<para>
\pre                   - There is no currently ongoing progress display for this instance.
</para>
<para>
\returns

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the handle is now valid for use</listitem>
  <listitem><link linkend="kOfxStatFailed"><code>kOfxStatFailed</code></link> - the progress object failed for some reason</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - effectInstance was invalid</listitem>
</itemizedlist>
</para>

  </refsect2>

</refentry>

<refentry id="OfxProgressSuiteV1_progressUpdate">
  <refmeta>
    <refentrytitle><function>OfxProgressSuiteV1::progressUpdate</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxProgressSuiteV1::progressUpdate</function></refname>
       <refpurpose>Indicate how much of the processing task has been completed and reports on any abort status.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxProgress.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*progressUpdate)</function></funcdef>
              <paramdef>void *<parameter>effectInstance</parameter></paramdef>
              <paramdef>double<parameter>progress</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>effectInstance - the instance of the plugin this progress bar is
associated with. It cannot be NULL.
</listitem>
<listitem>progress - a number between 0.0 and 1.0 indicating what proportion of the current task has been processed.
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
\returns

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the progress object was successfully updated and the task should continue</listitem>
  <listitem><link linkend="kOfxStatReplyNo"><code>kOfxStatReplyNo</code></link> - the progress object was successfully updated and the task should abort</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - the progress handle was invalid,</listitem>
</itemizedlist>
</para>

  </refsect2>

</refentry>

<refentry id="OfxProgressSuiteV1_progressEnd">
  <refmeta>
    <refentrytitle><function>OfxProgressSuiteV1::progressEnd</function></refentrytitle>
  </refmeta>
  <refnamediv>
    <refname><function>OfxProgressSuiteV1::progressEnd</function></refname>
       <refpurpose>Signal that we are finished with the progress meter.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include "ofxProgress.h" </funcsynopsisinfo>
      <funcprototype>
        <funcdef><typename>OfxStatus</typename><function>(*progressEnd)</function></funcdef>
              <paramdef>void *<parameter>effectInstance</parameter></paramdef>
        </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect2>
   <title>Arguments</title>
   <itemizedlist>

<listitem>effectInstance - the instance of the plugin this progress bar is
associated with. It cannot be NULL.
</listitem>
    </itemizedlist>
  </refsect2>
  <refsect2>
    <title>Description</title>
      <para>
Call this when you are done with the progress meter and no
longer need it displayed.
</para>
<para>
\post - you can no longer call progressUpdate on the instance
</para>
<para>
\returns

<itemizedlist>
  <listitem><link linkend="kOfxStatOK"><code>kOfxStatOK</code></link> - the progress object was successfully closed</listitem>
  <listitem><link linkend="kOfxStatErrBadHandle"><code>kOfxStatErrBadHandle</code></link> - the progress handle was invalid,</listitem>
</itemizedlist>
</para>

  </refsect2>

</refentry>
