Find Method

Summary

Searches the pages of a document to find matches to provided text options.

Syntax

C++/CLI

public IList<DocumentViewerMultiLineTextItem> Find( 
   DocumentViewerFindText options 
)

public:  
   IList<DocumentViewerMultiLineTextItem^>^ Find( 
      DocumentViewerFindText^ options 
   )

Parameters

options

An instance of DocumentViewerFindText that carries options for bounds, start location, matching options, and post-result actions.

Return Value

A list of type DocumentViewerMultiLineTextItem, where each item in the list is a match for the search. If no matches are found, null is returned instead of an empty list.

Remarks

Find searches the pages of a Document to find matches to search text. Options can be passed via DocumentViewerFindText, which allows for specification of bounds, start location, matching options, rendering, and selection.

Find is a synchronous operation and should return a list of DocumentViewerMultiLineTextItem, one for each match. If no matches are found, null is returned instead of an empty array.

Find will report its progress via the DocumentViewer.Operation event with the DocumentViewerOperationEventArgs.Operation property set to DocumentViewerOperation.FindText. Find will send the results of each page as it searches, and sends all results at the conclusion of the operation. Setting DocumentViewerOperationEventArgs.Abort to true will cancel the operation, but not render any of the results (even if DocumentViewerFindText.RenderResults is true).

If a page’s DocumentPageText has not been retrieved when the page is being searched, Find may retrieve the DocumentPageText data for that page based on the value of AutoGetText. If no DocumentPageText is found, the page will return null as the result for searches on that page.

Search Options

DocumentViewerFindText.BeginPosition and [DocumentViewerFindText.EndPosition] set the bounds and direction of the search. The find text operation will always search in the direction of DocumentViewerFindText.BeginPosition to [DocumentViewerFindText.EndPosition], even if [DocumentViewerFindText.EndPosition] is a lower page number and/or character index. Switching these two properties will change the direction of search.

By default, DocumentViewerFindText.Start is set to DocumentViewerFindTextStart.BeginPosition, meaning the search will always begin at DocumentViewerFindText.BeginPosition. Other values for DocumentViewerFindText.Start allow the search to start somewhere between the provided bounds (either at a text selection with SelectedTextBegin or SelectedTextEnd, or a manually-set position with DocumentViewerFindText.ManualStartPosition), which may then create two sub-searches:

A search from the new starting position to [DocumentViewerFindText.EndPosition]
A search from DocumentViewerFindText.BeginPosition through the character before the new start position The second search will only be run if DocumentViewerFindText.FindAll or DocumentViewerFindText.Loop is used.

The results can be automatically highlighted with DocumentViewerFindText.RenderResults and FoundTextBrush. It is important to note that subsequent calls will continue to add onto the internal list of results to render, so it is best to clear the render of the last results before each call to Find with ClearRenderedFoundText. All results are returned in order from the start position to the stop position, and the first result can be automatically selected and scrolled to with DocumentViewerFindText.SelectFirstResult.

A short description of each option is provided below:

Option	Description
DocumentViewerFindText.BeginPosition	Sets one of the bounds of the search area and helps determine the direction.
[DocumentViewerFindText.EndPosition]	Sets one of the bounds of the search area and helps determine the direction.
DocumentViewerFindText.Text	Sets the text to match.
DocumentViewerFindText.MatchCase	Indicates whether case matters for the search.
DocumentViewerFindText.WholeWordsOnly	Indicates whether DocumentViewerFindText.Text should only match whole words in the page text.
DocumentViewerFindText.FindAll	Indicates whether all matches in the bounds should be searched, or just the first.
DocumentViewerFindText.RenderResults	Sets whether to highlight the results in the DocumentViewer.View.
DocumentViewerFindText.SelectFirstResult	Automatically sets the first in-order result to the selected text.
DocumentViewerFindText.Start	Sets a new starting position for the search inside of the bounds, like a text selection.
DocumentViewerFindText.ManualStartPosition	Allows for a character index to be manually chosen based on the value of DocumentViewerFindText.Start.
DocumentViewerFindText.Loop	Indicates whether to wrap back around to search the rest of the bounds not covered before DocumentViewerFindText.Start.

A copy of the last options supplied to a completed Find is available at LastFindText until ClearLastFindText is called. Unlike previous versions, DocumentViewerFindText does not hold any internal state, so unless something about the document has changed (such as the selected text when using DocumentViewerFindTextStart.InSelection or DocumentViewerFindTextStart.AfterSelection), the same DocumentViewerFindText input instance should return the same set of results.

Multi-line and Multipage Searches

Find will automatically search between lines of text and pages of text, using the concept of "hidden spaces" at line endings. Find will recognize the end of a word/line and allow text on the next line to be matched with a space delimiter. If Find can recognize the end of a paragraph, the next line of text will not be matched.

Some examples for the search term "Hello World":

Search Applications

A common scenario when finding text on the page is supporting the "Incremental Find", "Find Next", and "Find Previous" operations. "Find Next" and "Find Previous" are used to continue searching from a match to the next match in a certain direction, while "Incremental Find" attempts to continue matching from _within the current position_, then tries to "Find Next" when the match fails. These operations are possible using the different options in DocumentViewerFindText:

Set the bounds of the search using DocumentViewerFindText.BeginPosition and [DocumentViewerFindText.EndPosition] as usual. For example, one may search from Page 1, Character 0 to Page 3, Character -1 (end of page). Switching the values in DocumentViewerFindText.BeginPosition and [DocumentViewerFindText.EndPosition] will change whether the operation is a "Find Next" or "Find Previous".
Set DocumentViewerFindText.Start to one of two options:
- DocumentViewerFindTextStart.InSelection to continue searching from within the currently selected text. This is ideal for an "Incremental Find" operation where, for example, "L" is already selected from a previous find and you wish to continue matching the remaining text "EADTOOLS" right after it, instead of finding the next or previous match.
- DocumentViewerFindTextStart.AfterSelection to start the search after the selection ends, in the direction of search. This is useful for "Find Next" or "Find Previous". If no selection exists, the DocumentViewerFindText.BeginPosition] is used as the starting point. To continue the example from above, this would search for the next complete "LEADTOOLS" after the "L" already selected.
Ensure DocumentViewerFindText.SelectFirstResult is true so that the first match becomes the new selected item. This is the critical step that makes it possible to keep sending the same DocumentViewerFindText instance but move to the next or previous result.
Optionally, use DocumentViewerFindText.RenderResults and DocumentViewerFindText.FindAll or DocumentViewerFindText.Loop to ensure the entire bounds area is checked and highlighted.

Note: For a demo, refer to the source code at <installdir>\Examples\Viewers\DotNet\DocumentViewerDemo. The LEADTOOLS Document Viewer demo uses Find to perform text search operations.

Otherwise, For a practice start with the example created in DocumentViewer, remove all the code in the Example function and add the code below. When the user clicks the Example button, all occurrences of the word "LEAD" will be found.

Example

using Leadtools; 
using Leadtools.Controls; 
using Leadtools.Document; 
using Leadtools.Document.Viewer; 
using Leadtools.Codecs; 
using Leadtools.Caching; 
using Leadtools.Annotations.Engine; 
using Leadtools.Ocr; 
 
 
var text = _documentViewer.Text; 
 
// Make sure we get the page text if necessary 
text.AutoGetText = true; 
 
// We will find all matches of "LEAD", ignoring the case 
var options = new DocumentViewerFindText(); 
 
// The text 
options.Text = "LEAD"; 
// Ignore case 
options.MatchCase = false; 
// Any word that contains the phrase 
options.WholeWordsOnly = false; 
 
// Find all results in the bounds, not just the first 
options.FindAll = true; 
 
// Highlight the results in the View 
options.RenderResults = true; 
// Optionally change the highlight color 
//DocumentViewerText.FoundTextBrush = new SolidBrush(Color.FromArgb(52, Color.Brown)); 
 
// Set the bounds 
bool isFindingNext = true; 
// We set the bounds as the whole document, but below we can specify to start wherever text is selected 
// or at the current page 
var topOfFirstPage = DocumentViewerTextPosition.CreateBeginOfPage(1); 
var bottomOfLastPage = DocumentViewerTextPosition.CreateEndOfPage(_documentViewer.PageCount); 
if (isFindingNext) 
{ 
   // Make the beginning bound "higher up" the page so we search "down" the page. 
   options.BeginPosition = topOfFirstPage; 
   options.EndPosition = bottomOfLastPage; 
} 
else 
{ 
   // Make the beginning bound "lower down" the page so we search "up" the page. 
   options.BeginPosition = bottomOfLastPage; 
   options.EndPosition = topOfFirstPage; 
} 
 
// Select the first result in the View (automatically scrolls View also) 
options.SelectFirstResult = true; 
 
if (text.HasAnySelectedText) 
{ 
   // Setting this value to AfterSelection allows us to search forward from the selection, so multiple 
   // uses of this same options object will cycle us through all the matches! 
   // (If no selected text actually exists, search will default to beginPosition.) 
   options.Start = DocumentViewerFindTextStart.AfterSelection; 
} 
else 
{ 
   // We could start at the begin position, but it makes more UI sense to start from the user's current page. 
   // Search will loop back around to the begin position - this just changes the starting point and order of results. 
   options.Start = DocumentViewerFindTextStart.ManualPosition; 
   if (isFindingNext) 
      options.ManualStartPosition = DocumentViewerTextPosition.CreateBeginOfPage(_documentViewer.CurrentPageNumber); 
   else 
      options.ManualStartPosition = DocumentViewerTextPosition.CreateEndOfPage(_documentViewer.CurrentPageNumber); 
} 
 
// If we were just looking for the first match, we could use "Loop" to loop around 
// if we found nothing between the start position and the end bound. 
//options.Loop = true; 
 
// You will likely want to clear the previous highlighted results 
// on the screen so only our new results will show. 
text.ClearRenderedFoundText(); 
 
// Search 
var results = text.Find(options); 
int resultsCount = results != null ? results.Count : 0; 
 
if (resultsCount > 0) 
   Console.WriteLine(string.Format("Found {0} results", resultsCount)); 
else 
   Console.WriteLine("No matches found.");

Requirements

Target Platforms

Reference

DocumentViewerText Class

DocumentViewerText Members

Leadtools.Document.Viewer Namespace

Download our FREE evaluation

Help Version 23.0.2024.2.29