IInkAnalyzer::BackgroundAnalyze method

Performs asynchronous ink analysis.

Syntax

HRESULT BackgroundAnalyze();

Parameters

This method has no parameters.

Return value

For a description of the return values, see Classes and Interfaces - Ink Analysis.

Remarks

When this method is called, the IInkAnalyzer performs the ink analysis on a background thread.

This method returns S_FALSE and does not start a new background analysis operation under the following circumstances.

• The IInkAnalyzer is currently performing background analysis.
• the dirty region (see IInkAnalyzer::GetDirtyRegion Method) represents an empty area.

The IInkAnalyzer analyzes ink within its dirty region during a call to IInkAnalyzer::Analyze Method or IInkAnalyzer::BackgroundAnalyze Method. However, the IInkAnalyzer may expand the analysis operation to include neighboring regions.

This method sets the dirty region to an empty region.

If stroke data was added to the IInkAnalyzer after the call to IInkAnalyzer::BackgroundAnalyze Method, the IInkAnalyzer may update the dirty region during the reconcile phase of ink analysis.

The analysis modes setting (see IInkAnalyzer::GetAnalysisModes Method) specifies how the IInkAnalyzer performs background analysis. For more information about ink analysis, see Ink Analysis Overview.

This method returns an error code under the following circumstances.

• Your application has set AnalysisModes value AnalysisModes_IntermediateResults in the IInkAnalyzer (see IInkAnalyzer::SetAnalysisModes Method) and does not handle the _IAnalysisEvents::IntermediateResults event.
• Your application has cleared AnalysisModes value AnalysisModes_AutomaticReconciliation in the IInkAnalyzer (see IInkAnalyzer::SetAnalysisModes Method) and does not handle the _IAnalysisEvents::ReadyToReconcile event.
• Your application does not handle the _IAnalysisEvents::Results event.
• Your application does not handle the _IAnalysisEvents::UpdateStrokesCache event.

Examples

The following example checks the ink analyzer's dirty region, and then initiates background ink analysis if the dirty region is not empty.

// Check that the ink analyzer's dirty region is not empty.
IAnalysisRegion *pDirtyRegion;
hr = this->m_spIInkAnalyzer->GetDirtyRegion(&pDirtyRegion);

if (SUCCEEDED(hr))
{
    VARIANT_BOOL bIsEmpty;
    hr = pDirtyRegion->IsEmpty(&bIsEmpty);

    if (SUCCEEDED(hr))
    {
        if (!bIsEmpty)
        {
            // Insert code that prepares the application for background
            // ink analysis here.

            // Start background ink analysis. The _IAnalysisEvents::Results
            // event signals when background ink analysis is complete.
            hr = this->m_spIInkAnalyzer->BackgroundAnalyze();
        }
    }
}

// Free the memory for the dirty region.
if (pDirtyRegion != NULL)
{
    pDirtyRegion->Release();
}

Requirements

See also

IInkAnalyzer

AnalysisModes

IInkAnalyzer::Analyze Method

IInkAnalyzer::GetAnalysisModes Method

IInkAnalyzer::SetAnalysisModes Method

IInkAnalyzer::GetDirtyRegion Method

IInkAnalyzer::SetDirtyRegion Method

IInkAnalyzer::GetRootNode Method

Ink Analysis Reference