IInkAnalyzer::CreateAnalysisHint method

Article
01/07/2021

Adds a new analysis hint node with an infinite area to the IInkAnalyzer.

Syntax

HRESULT CreateAnalysisHint(
  [out] IContextNode **ppAnalysisHint
);

Parameters

ppAnalysisHint [out]: The new analysis hint node.

Return value

See Classes and Interfaces - Ink Analysis for a description of the return values.

Remarks

Caution

To avoid a memory leak, call IUnknown::Release on ppAnalysisHint when you no longer need to use the object.

To provide extra context information for the IInkAnalyzer, you can add analysis hints to the ink analyzer. Analysis hints can improve recognition accuracy. For example, you can add factoid and guide information for fields in a form application.

This method creates a new IContextNode with a context node type of AnalysisHint (see IContextNode::GetType) and adds the new hint as a subnode of the IInkAnalyzer object's root node (see IContextNode::GetSubNodes and IInkAnalyzer::GetRootNode Method).

To add context information to the hint, use IContextNode::AddPropertyData with the pPropertyDataId parameter set to one of the Analysis Hint Properties constants.

If a hint is assigned an infinite area, termed a global hint, the IInkAnalyzer applies the hint's context to all ink that is not within another hint's area. Multiple hints may be attached to a single IInkAnalyzer. However, only one global hint can be attached to a single ink analyzer, and no non-global hints can overlap. For more information about the types of context information that a hint can provide, see Analysis Hint Properties.

Adding an analysis hint does not mark the hint's area for reanalysis. To mark the area within the hint for reanalysis, use IInkAnalyzer::SetDirtyRegion Method to set the dirty region to the union of the current dirty region and area of the analysis hint.

When using hints for a form application, the application should avoid mixing text context with ink in the forms. This means for example that text field names should not be created in the analysis tree. Hints are meant to associate the ink to areas on pages; any text context interferes with this ink-to-hint association. The analysis operation may merge the ink and the text context in the same writing region which would prevent the ink from being associated with the hint area.

For more information about ink analysis, see Ink Analysis Overview.

Requirements

Requirement	Value
Minimum supported client	Windows XP Tablet PC Edition [desktop apps only]
Minimum supported server	None supported
Header	IACom.h (also requires IACom_i.c)
DLL	IACom.dll