Screen Scraping Library
Screen Text Capture OCR Library
for Windows 95/98/ME/NT/2000/XP/2003/Vista
User’s Manual
Copyright © 1995-2009 Bridges
Software, Inc
Screen Scraping Library support: support@ScreenScrapingLibrary.com
Screen Scraping Library on the web: http://www.ScreenScrapingLibrary.com/
This document describes Screen Scraping Library. The
software is provided to you in accordance with your license agreement.
Screen Scraping Library allows grabbing text from
Windows 98/95/NT/2000/XP screen, under the control of another program. Screen
Scraping Library is a development tool in the form of DLL and EXE, which can be
integrated by the software developer into another product or software solution.
Software QA departments can use Screen Scraping
Library to grab text from testing applications and compare the captured text
with intended screen content.
Screen Scraping Library is well suited for corporate
environment as an application connectivity tool, to feed an application with
text from another text "source" application. Screen Scraping Library
is especially useful if this source application is a third-party; the source
application cannot be changed or hard and time-wasting to change, and has no
adequate embedded support for communication.
Screen Scraping Library can grab text from any part of
any application, even from clipboard and OLE-unaware applications e.g.: from
folder trees, file lists, database reports, text contents of messages and
dialog boxes, menus, status lines, legacy systems. The technology is copyrighted
1995-2009 Bridges Software, Inc.
Part of Screen Scraping Library, OCRSDKcl.EXE is a
standalone console mode Win32 application with a simple, yet powerful, command
line interface. OCRSDKcl.EXE can recognize text from the screen or a bitmap
file and store it into a file in plain text, Rich Text Format (RTF) and
proprietary binary and verbose text formats.
Another part of Screen Scraping Library, OCRSDK.DLL,
has a simple API to call from programs that are written in C++, Visual Basic,
Power Builder or any other DLL-aware programming language. You can use it as a
building block of the whole product, which requires text capturing, like
driving you proprietary hardware by text, captured from a legacy system.
OCRSDK.DLL can store results into memory or into a file.
Screen Scraping Library contains an MFC example, which
shows how to use all features of OCRSDK.DLL. This example is a great help for
the developer to play with the DLL before implementing actual code. Screen
Scraping Library also contains C++ console mode examples of the DLL use, which
show the simplest possible form of use of each input and output mode. Both, MFC
and console mode, examples are supplied with source texts and they are ready to use
as compiled EXEs.
Screen Scraping Library also contains TxtrCtl, which
is a 32-bit Windows DLL based ActiveX control OCROCX.DLL is written using ATL
C++ language. TxtrCtl, which is built on COM-based technology, provides a
convenient way of using all OCRSDK.DLL functionality. OCROCX.DLL is compatible
with any environment that supports the use of ActiveX control, such as Visual
C++, Visual Basic, Power Builder, etc.
There is a Visual Basic 5 example of using TxtrCtl ActiveX
control.
You can order Screen Scraping Library Commercial
online, by phone, fax, check, mail order or purchase order. Screen Scraping
Library license includes 30 day money back guarantee.
Please visit Screen Scraping Library web page at
http://www.ScreenScrapingLibrary.com/ to order Screen Scraping Library.
You can download Screen Scraping Library Trial for
free from the Screen Scraping Library web page, valid for 45 days. You should
also consider trying Scrape Text utility to evaluate the recognition quality
and the speed of the technology. Scrape Text and Screen Scraping Library use the
same technology engine for capturing text. Scrape Text Trial Version is
included into Screen Scraping Library.
If you have any questions or comments please contact
us: e-mail (preferred): support@ScreenScrapingLibrary.com, phone: 206-202-3257
Table of Contents:
Introduction. Screen Scraping Library purpose,
scenario examples, contents, ordering
License agreement. Redistribution policy
Screen Scraping Library installation. Description of
installed files
Screen Scraping Library Uninstall
Screen Scraping Library control flags and output
formats
OCRSDKcl.EXE
Context of
use of OCRSDKcl.EXE
Command
line parameters
Operational
environment. Font database, INI
Examples of
command line use
OCRSDK.DLL
Context of
use of OCRSDK.DLL
API
description for each function
Operational
environment. Font database, INI file
MFC example
of OCRSDK.DLL use
Interrelations
between example dialog and Screen Scraping Library control flags
How
to control the example
How
to compile example
Console
mode examples
Interrelations between examples and Screen
Scraping Library control flags
How
to compile example
TxtrCtl ActiveX control (OCROCX.DLL)
Installation/uninstallation
of TxtrCtl
Context of
use of OCROCX.DLL
TxtrCtl
properties and methods reference
Visual
Basic example of TxtrCtl use
OCRSDK.INI file description
General
options
Font
database and capturing options
Log file
support options
Debug
options
License agreement.
Redistribution policy
End-User License Agreement.
This End-User License Agreement (EULA) is a legal
agreement between you (either an individual or a single entity) and Bridges
Software, Inc for the software accompanying.
The
software product and any related documentation is provided "as is".
The
entire risk arising out of use or performance of the software product remains
with you.
In
no event shall Bridges Software, Inc or its suppliers be liable for any damages
whatsoever (including, without limitation, damages for loss of business
profits, business interruption, loss of business information, or any other
pecuniary loss arising out of the use of or inability to use this product, even
if Bridges Software, Inc has been advised of the possibility of such damages.
Because some states/jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental
damages, the above limitation may not apply to you.
If you acquired this product in the
Screen Scraping Library Trial Edition License
Agreement
You are granted the right to use the trial edition of
this software, without any functional limitation.
You are granted the right to distribute the trial
edition of this software, on the following conditions: the distribution package must not be changed
and no fee must be charged for this package.
The information, code and executables provided are
provided as is. By
using this software, you are agreeing to the above terms.
Screen Scraping Library Commercial Edition License
Agreement
You are granted the right to use this software on 1
(one) computer in private, government commercial, institutional and any other environment.
For the Pack
license, you are granted the right to use this software on computers according to the number of licenses
purchased.
You may not distribute the Commercial edition of this
software.
You may not reverse engineer, decompile, disassemble
and change this software.
The information, code and executables provided are
provided as is. By using this software, you are
agreeing to the above terms.
Should you
have any questions concerning any of the License Agreements or if you desire to
contact Bridges Software, Inc for any reason, please write us or email at
support@ScreenScrapingLibrary.com
Screen Scraping
Library installation. Description of installed files
Install
Directory: Screen Scraping Library is installed into a specified folder (you’ll
be asked to specify it at the beginning of the installation process.) No
other files are installed elsewhere; no files are installed into \Windows and
\Windows\System folders. All installed files are described below.
Capturing engine
OCRSDK.DLL - Text capture library in the
form of a dynamic link library.
OCRSDKcl.EXE - Text capture module in the
form of a Win32 console mode executable.
OCROCX.DLL - TxtrCtl ActiveX control.
OCRSDK.INI - An INI file to control DLL and
EXE.
Development support
!Readme.Txt - A short description of the
package.
OCRSDK.DOC - Screen Scraping Library
user’s manual. (This document).
OCRSDK.H - A C/C++ header file, with API
for OCRSDK.DLL.
OCRSDK.LIB - A stub library for C/C++
linker to link to OCRSDK.DLL.
ScrapeText.EXE – Scrape Text
Trial Version, installation package. (Run to install).
MFC example for OCRSDK.DLL
ExGUI.EXE - A compiled example of DLL use,
based on MFC.
ExGUI\ - A source folder for the
example.
ExGUI.cpp,
ExGUI.h, ExGUIDlg.cpp, ExGUIDlg.h,
strform.cpp,
strform.h, StdAfx.cpp, StdAfx.h, resource.h
ExGUI.rc -
Source files.
ExGUI.dsp,
ExGUI.dsw, ExGUI.clw, ExGUI.mak - project files
res\
ExGUI.ico, ExGUI.rc2 - resources
Console mode simple examples for OCRSDK.DLL
For each example out of total 16, there is an
executable (.EXE) compiled example in the root folder and sample source (.CPP)
file, project (.DSP) file and make (.MAK) file in the ExSimple\
subfolder. Examples are described in OCRSDK.DLL section of this user’s manual.
Compiled example executables:
Bmp_File_Ascii.exe, Bmp_File_Binary.exe,
Bmp_File_Rtf.exe, Bmp_File_Verbose.exe
Bmp_Memo_Ascii.exe, Bmp_Memo_Binary.exe,
Bmp_Memo_Rtf.exe, Bmp_Memo_Verbose.exe
Scr_File_Ascii.exe, Scr_File_Binary.exe,
Scr_File_Rtf.exe, Scr_File_Verbose.exe
Scr_Memo_Ascii.exe, Scr_Memo_Binary.exe,
Scr_Memo_Rtf.exe, Scr_Memo_Verbose.exe
ExSimple\ - source folder for these
examples.
ExSimple.dsp,
ExSimple.dsw - project files.
Xxx_Yyy_Zzz.Cpp,
Xxx_Yyy_Zzz.Dsp, Xxx_Yyy_Zzz.Mak - C++ source file, project file
and make file for each example.
ExSimple.pl -
perl script, that is used to generate .cpp, .dsp and .mak files for each
example
ExSimple.mpp -
C++ pattern, used by ExSimple.pl to generate example .cpps
Visual Basic 5 example of TxtrCtl ActiveX control
VBTxtr.EXE - compiled VB5 example of
TxtrCtl ActiveX control use
ExVB\ - source folder for the example
frmVBTxtr.frm,
frmVBTxtr.frx, OCRSDK.bas, frmSrcBmp.frm - source
files
VBTxtr.vbp -
project file
Screen Scraping
Library Uninstall
Screen Scraping Library installs all files into one
folder and it’s subfolders. This folder is specified at installation time, the
subfolders are described above.
To uninstall Screen Scraping Library, remove the
installation folder, subfolders and all their files.
Screen Scraping
Library control flags and output formats
OCRSDK.DLL and OCRSDKcl.EXE get the input image from a
BMP file or from a specified screen rectangle (OCRSDK.DLL also supports getting
the image from a specified window), then recognise the text from this image and
then store the result in one out of 4 output data formats.
DLL can store the result into memory or into a file;
EXE can store the result only into a file.
This section describes output format details and
associated control flags for this 5 formats:
1
plain
text format - /ascii, dfText
2
RTF
format - /rtf, dfRtf
3 verbose
text format - /verbose, dfVerbose.
Flags to control verbose format:
/bol /eol /space /char /font /charhex /charfont /charcolor
dfBol dfEol dfSpace dfChar dfFont dfCharHex dfCharFont dfCharColor
4
binary
format - /binary, dfBinary
5
bitmap
format - /bmp, dfBmp
Plain
text format
The result is a plain ASCII text. Terminated with
trailing 0, if stored by DLL into memory. If the text is stored into a file the
trailing 0 is absent.
The text is properly spaced and divided into lines by CR/LF pairs (standard for
Microsoft operating systems). Font face, pitch size, style, colour information
and exact location of characters on the screen/bitmap aren’t present in this format.
/ascii - command line parameter for OCRSDKcl.EXE.
dfText - a flag for OCRSDK.DLL format parameter of function
Textract().
Xxx_Yyy_Ascii.Exe - console
mode examples that show the use of this format.
RTF format
The result is a Rich Text Format. Font face, pitch
size, style, colour information are present in RTF format. Exact location of
characters on the screen/bitmap is dropped.
/rtf - command line parameter for OCRSDKcl.EXE.
dfRtf - a flag for OCRSDK.DLL format parameter of function
Textract().
Xxx_Yyy_Rtf.Exe - console
mode examples that show the use of this format.
Verbose text format
The result is a text format, which keeps all the
information gathered on recognition step. Captured data is considered as a sequence
of lines, which are composed from characters and spaces. Verbose output format
consists of lines, that describe this sequence of elements. Each line is
terminated with CR/LF pair.
/verbose - command line parameter for
OCRSDKcl.EXE.
dfVerbose - a flag for OCRSDK.DLL format
parameter of function Textract().
Xxx_Yyy_Verbose.Exe - console
mode examples, that demonstrate the use of this format.
Format of verbose output lines.
BOL <x> <y> - Begin Of
the Line.
<x> and <y> are decimal specifiers of line
position on the image, relative to the upper left corner.
EOL - End Of the Line.
CHAR <char> <hex> <x> <y>
<pitch> <fontName> <color> - character
description.
<char> - a character, as is.
<hex> - hexadecimal code of the character (e.g.
4B or 2E.)
<x> and <y> - offset of the character sign
place relative to the upper left corner of the image.
<pitch> - pitch size of the font.
<fontName> - font face name. It can contain
spaces in the name.
<color> - color of character in hex format %06X
(RRGGBB).
SPACE <spacing> <e> -
spacing in a line between characters.
<spacing> - decimal spacing between characters,
measured in pixels.
<e> - EXACT if the spacing is proper in
accordance with the space width for this font face/pitch. INEXACT if the
spacing is not equal to the space width for this font face/pitch.
FONT <pitch> <fontName> -
(is emitted if next character is a character of another font then previous
one.) = this string is typed-out if the
next character is a character of another font then the current one. Also typed-out before the first CHAR of the
output.
<pitch> - pitch size of the font
<fontName> - font face name. It can contain
spaces in the name.
The description above shows the full form of the
output. Some output lines and/or fields can be switched off using the following flags:
/xxx - to
control OCRSDKcl.EXE command lines
dfXxx - to control output format argument of Screen
Scraping Library function of OCRSDK.DLL.
If the flag is present, then the function outputs
‘---‘; if not - omits.
/bol, dfBol - ‘BOL lines’
/eol, dfEol - ‘EOL lines’
/space, dfSpace - ‘SPACE
lines’
/char, dfChar - ‘CHAR lines’
/font, dfFont - ‘FONT lines’
/charhex, dfCharHex -
‘<hex> fields of CHAR lines’
/charfont, dfCharFont -
‘<pitch> and <fontName> fields of CHAR lines’
/charcolor, dfCharColor -
‘<color> field of CHAR lines’
Binary format
The result is a binary format, which keeps all the
information gathered on recognition step. Captured data is considered as a
sequence of lines, which consists of characters and spaces. Binary output
format is an array of structures, describing this sequence of elements.
/binary - command line parameter for
OCRSDKcl.EXE.
dfBinary - a flag for OCRSDK.DLL format
parameter of function Textract().
Xxx_Yyy_Binary.Exe - console
mode examples that show the use of this format.
Output array consists of structures, defined in Screen
Scraping Library.H as a class TextractItem.
class TextractItem {
public:
TextractItemType Type :8;
short OffsetX,
OffsetY;
unsigned short
FontIndex;
const char
*FontName;
char Ch;
long Color;
unsigned char
Pitch;
short Spacing;
int
IsExactSpacing : 8;
};
TextractItemType Type :8; - type of
the array item. It can be one of the
following: itChar, itSpace, itLineStart, itLineTerm, itFont.- this corresponds to CHAR, SPACE, BOL, EOL and
FONT lines of verbose text format, which is described above.
short OffsetX, OffsetY; - for itChar
and itLineStart, specifies the offset of the character or line relative to the
upper left corner of the image.
unsigned short FontIndex; - for
itChar, index of the font, unique for this font face/style. It can be used to
compare fonts of different characters for equivalence.
const char *FontName; - for itChar
and itFont, font face/style name.
char Ch; - for itChar, the captured
character.
long Color; - for itChar, colour of the
captured character in RGB format.
unsigned char Pitch; - for
itChar, font pitch size
short Spacing; - for
itSpace, spacing between characters, measured in pixels.
int IsExactSpacing : 8; - for
itSpace, 1 - if the spacing is proper in accordance with space width for this
font face/pitch. 0 - if the spacing is not equal to the space width for this
font face/pitch.
This description shows a full form of the output. Some
output items can be omitted by means of the following flags:
/xxx - to control OCRSDKcl.EXE command line,
dfXxx - to control output format argument of Screen
Scraping Library function of OCRSDK.DLL.
If the flag is present, then the function outputs
‘---‘; if not - omits.
/bol, dfBol - ‘BOL lines’
/eol, dfEol - ‘EOL lines’
/space, dfSpace - ‘SPACE
lines’
/char, dfChar - ‘CHAR lines’
/font, dfFont - ‘FONT lines’
Bitmap format
The result is a bitmap file in true-colour 24 bits per
pixel unpacked Windows BMP format. Recognition is not used in this format, this
is just a pure bitmap capture. For Bitmap format the appropriate file name
extension -“.bmp” - will be appended to the file name string if the extension
is omitted. To prevent this put “.” as a
trailing symbol in the file name.
/bmp - command line parameter for OCRSDKcl.EXE.
dfBmp - a flag for OCRSDK.DLL format parameter of function
Textract().
OCRSDKcl.EXE
Context of use of OCRSDKcl.EXE
OCRSDKcl.EXE is a 32-bit Windows console mode
application which realize the recognition functionality.
Command line parameters
/build - builds the font database, according to the INI file
specification.
If /build is specified, other options are not allowed.
Font database file name can be specified in OCRSDK.INI
file, in section [Options] entry Database Path. If this is not specified,
OCRSDKcl.EXE will build the base in a current folder, with the name OCRSDK.PAT,
and will add the path and the name of this file to INI [Options] Database Path.
/capture <ax> <ay> <bx> <by> -
captures rectangle from the screen, recognises the text and stores the results
into an output file.
ax,ay - bx,by - rectangle location.
ax,ay - inclusive, bx,by - exclusive. All co-ordinates
are decimal.
outputReportFile - name of an output file, where the
results are stored. Default file extension is not added.
/recognize <inputBitmapFile> -
recognizes the bitmap, specified in a command line.
inputBitmapFile - BMP file in the 1, 4, 16, 24,
32 bits per pixel unpacked as well as
RLE-encoded. If the extension is not specified in the command line .BMP is
added.
Output file name and output format flags must be
specified, when using /capture and
/recognize modes.
/ascii - for plain text output mode
/rtf - for RTF output mode
/verbose - for verbose text output mode
/binary - for binary output mode
For
verbose text output format /bol, /eol, /space,
/char, /font, /charhex, /charfont and
/charcolor may be used.
For
binary output format /bol, /eol, /space,
/char and /font
may be used.
Operational environment. Font database, INI file
At the beginning OCRSDKcl.EXE searches for the
OCRSDK.INI file to load parameters. OCRSDKcl.EXE
searches for the following folders:
1
current
folder.
2 folder
where OCRSDKcl.EXE is located.
3
\Windows
folder.
If OCRSDK.INI cannot be found, OCRSDKcl.EXE is
terminated with the following error message: "File OCRSDK.INI not
found".
For /capture
and /recognize modes, OCRSDKcl.EXE loads the font database file, specified in
INI [Options] Database Path =<path>\OCRSDK.PAT. If this file is not
found, OCRSDKcl.EXE is terminated with: "Font database OCRSDK.PAT not
found". If this file is found, but invalid, font database will be rebuild
automatically, an error message will not appear.
Examples of command line use
OCRSDKcl /build
Builds or rebuilds the font database OCRSDK.PAT.
OCRSDKcl /capture 0 0 800 600 /ascii whole.txt
Captures the screen area at location (0, 0) to
(800, 600) and stores the result into "whole.txt" in plain text
format.
OCRSDKcl /capture 2 580 798 600 /rtf taskbar.rtf
Captures the screen area at location (2, 580) to (798, 600) and stores
the result into "taskbar.rtf" in RTF format.
OCRSDKcl /recognize alphabet /verbose /font /char
alphabet.txt
Recognizes "alphabet.BMP" file and stores
the result to "alphabet.txt" in verbose text format, emitting only
FONT and CHAR lines.
OCRSDK.DLL
Context of use of OCRSDK.DLL
OCRSDK.DLL is a 32-bit Windows dynamic-link library
(DLL) which provides the recognition functionality.
<to be written>
API description for each function
OCRSDK.DLL API is a header file OCRSDK.H.
TextractExport TextractSuccess TextractInit();
TextractExport TextractSuccess TextractTerm();
- Initialises and terminates the library: You have to
call TextractInit() to use other functions of the library; call TextractTerm to
clean up. Multiple TextractInit()/TextractTerm() is allowed during one session.
Init preloads the font database, Term frees some resources.
TextractExport TextractSuccess TextractBuild();
- Builds the font databse. TextractBuild is a silent
version (without user’s interface).
TextractExport TextractSuccess
TextractBuildWithDialog();
- TextractBuildWithDialog opens the dialog box to ask
the user about building the font database, and shows process progress.
typedef long TextractSuccess;
// success
returning code for Screen Scraping Library functions
enum { // value definitions for TextractSuccess
tsOK = 0,
...
Each Screen Scraping Library function returns a
success code. Each function specifies possible return codes.
tsOK is returned if a function has been done properly.
tsReject is returned if the user
rejected the operation.
tsBadArgs
is returned if function arguments are incorrect
tsBadBitmap is returned if the bitmap file format isn’t supported. Screen
Scraping Library supports files in the 1, 4, 16, 24, 32 bits per pixel unpacked as well as
RLE-encoded.
tsOutOfWindow is returned if the co-ordinates of a specified screen area are
out of the desktop window.
tsIniNotFound is returned if an INI file
isn’t found.
tsBaseNotFound is returned
if a font pattern database file isn’t
found.
tsBitmapNotFound is returned
if a Bitmap (BMP) file isn’t found.
tsInitFailed TextractInit() is returned if
the call to TextractInit() failed.
tsTermFailed TextractTerm() is returned if
the call to TextractTerm() failed.
tsFormat is returned in case of an
incorrect file format.
tsNoAccess is returned when a file cannot
be accessed for reading and/or writing.
tsCrash is returned if a Screen Scraping Library internal error
occurs.
TextractExport const char *TextractIniFileName();
TextractExport const char *TextractBaseFileName();
TextractExport const char *TextractBitmapFileName();
Return name of the file, corresponding to the last
operation. Useful for making qualified error descriptions.
TextractExport TextractSuccess
Textract(TextractSource&, TextractDest&, TextractDestFormat);
Text capturing and recognition.
TextractSource class reference defines where to get a
source image for recognition. It can be a file or an area of the screen, see
details below.
TextractDest class reference defines where to store
the results of recognition. It can be memory area or a file with a specified
name, see details below.
TextractDestFormat specifies output format with the
use of format flags dfText, dfRtf, etc , which are described in "Screen
Scraping Library control flags and output formats" section.
class TextractSource {
public:
TextractSource();
TextractSource& BmpFile(const char *bmpFileName);
TextractSource& Wnd(HWND);
TextractSource& Rect(int ax, int ay, int bx, int by);
TextractSource& DesktopWnd();
TextractSource& TopWnd(const char *windowClass, const char
*windowText);
TextractSource& DeepWnd(const char *windowClass, const char
*windowText);
TextractSource& SubWnd(const char *windowClass, const char
*windowText);
TextractSource& SubDeepWnd(const char *windowClass, const char
*windowText);
TextractSource& FindLargestWindow();
const char
*BmpFileName; // used if != NULL
HWND W; //
used if != NULL
int AX, AY,
BX, BY; // used if BmpFileName == NULL and Wnd == NULL
};
TextractSource& BmpFile(const char *bmpFileName);
Specifies the file name of a bitmap, designed for
recognition.
TextractSource& Wnd(HWND);
Specifies the handle of a window, designed for
recognition.
TextractSource& Rect(int ax, int ay, int bx, int
by);
Specifies the screen area, designed for recognition.
ax,ay and bx,by are upper left (inclusive) and lower
right (exclusive) corners of area.
TextractSource& DesktopWnd();
Specifies the desktop window as a window designed for
recognition.
TextractSource& TopWnd(const char *windowClass,
const char *windowText);
Specifies the top-level window, with windowClass as a window class name and windowText
as a window caption (title) name.
TextractSource& DeepWnd(const char *windowClass,
const char *windowText);
Specifies the child window with a desktop window as a
parent window, with windowClass as the
window class name and windowText
as the window caption (title) name.
TextractSource& SubWnd(const char *windowClass,
const char *windowText);
Specifies the child window in any match of a tree,
with W as a parent window, with windowClass
as the window class name and windowText
as the window caption (title) name.
TextractSource& SubDeepWnd(const char
*windowClass, const char *windowText);
Specifies the child window in any match of a tree,
with W as a parent window with windowClass
as the window class name and windowText
as the window caption (title) name.
TextractSource& FindLargestWindow();
Specifies the largest child window of an active window
as a window for recognition.
TextractSource is used to specify what to capture and
what to recognise.
Typical uses are:
Textract(TextractSource().BmpFile("MyImage.Bmp")
... to recognise the text from a
bitmap, captured from the screen some other way.
Textract(TextractSource().Rect(0,0, 100,200) ...
to grab text from a rectangle, located
at (0,0) - (100,200).
TextractCapture(TextractSource()
.TopWnd(NULL,
"Inbox - Outlook Express")
.SubDeepWnd("SysTreeView32", "") ...
to grab text from the visible area of a window (HWND) with the class name
SysTreeView32, find anywhere in the child windows (HWNDs) of top level window
with a title "Inbox - Outlook Express". Methods DesktopWnd, TopWnd
and DeepWnd... are designed to work together to specify the required window
with known accuracy.
Textract(TextractSource().FindLargestWindow() ...
to catch the largest visible subwindow on the screen. It's useful to capture
terminal emulator window.
class TextractDest {
public:
TextractDest(const char *destFileName);
TextractDest();
const char
*FileName; // NULL if area specifeid, else dest file name
void *Area; //
NULL if file name specified, else memory area
int AreaSize;
};
TextractExport TextractSuccess
TextractDestFree(TextractDest&);
TextractDest -
is used to specify where to save captured results.
Typical uses:
Textract(... , TextractDest("Results.Txt")
... to save results in a specified
file.
TextractDest dest;
Textract(... , dest, ...);
... use dest.Area of size dest.AreaSize ...
TextractDestFree(dest);
to use results in memory. TextractDestFree is used to
free memory, allocated for results of recognition, if memory output mode is
used.
enum TextractDestFormat {
enum TextractItemType { ...
class TextractItem { ...
Specifies output formats and layouts of binary
(dfBinary) or verbose (dfVerbose) modes. They are all described in "Screen
Scraping Library control flags and output formats" section.
Operational environment. Font database, INI
TextractInit() searches for the OCRSDK.INI file to
load parameters, see OCRSDKcl.EXE description.
If OCRSDK.INI cannot be found, tsIniNotFound is
returned.
TextractInit() loads the font database file, specified
in INI
[Options]
Database Path =<path>\OCRSDK.PAT.
If this file is not found, TextractInit returns
tsPatNotFound.
MFC example of OCRSDK.DLL use
ExGUI MFC-based application allows to try OCRSDK.DLL
functions step by step, manually, in any order.
1 Click
"Build font pattern database" button to build the font database. It
must be created before any recognition. Note, that the database could be
created by either OCRSDK.DLL or OCRSDKcl.EXE. "Build" asks to confirm
rebuilding the database and calls TextractBuildWithDialog() function.
2 Recognition
use example consists of these simple 4 steps:
3 Adjust
the recognition source to be a screen rectangle, a bitmap (BMP) file or a
window, by “Rectange” / “Bitmap file” / “Window” radio buttons. Specify the
screen rectangle’s coordinates, BMP file
name or a window. ax,ay are upper left corner co-ordinates, inclusive, bx,by
stand for the lower right corner,
exclusive.
4
Adjust the
recognition destination by “Memory” / “File” radio buttons. Specify the file’s name if File option
used.
5 Adjust
the output format. Output formats are described in "Screen Scraping
Library control flags and output formats" section. Set Text, Rtf, Binary,
Verbose or Bitmap format. For Binary and Verbose format, specify subset Bol,
Eol, Space, Char and Font output data/lines to generate. For Verbose format,
also specify CharHex and CharFont by putting a check in the according box.
6
Click "Recognize" button to recognize the
image in accordance with the specified source, destination and output format.
ExGUI creates TextractSource class instance, TextractDest class instance and
calls Textract() function of OCRSDK.DLL for the actual operation. DLL captures
the image from the specified screen area, the specified window or loads it from
the BMP file. Then it recognizes the image. After that it gives the result in
the specified output format. Then it puts it into memory or writes it into a
file, in accordance with specified destination. Then ExGUI converts the
returned data into text human-readable format, writes it to temp file and shows
it using Notepad, WordPad text editors or MSPaint. For Text, Binary and Verbose
output formats Notepad is used. For Rtf format WordPad is used. For Bitmap
MSPaint is used. See
ExGUI code for details.
ExGUI
processes the success code returned from Textract() function and shows the
error message if function fails. Possible
errors:
7 A
"Rectangle is out of window" or "Incorrect arguments" occur
if source is incorrect.
8 A
”Incorrect BMP file. Only 1, 4, 8, 16, 24, 32 bpp Windows BMP files are
supported” occurs if specified unsupported format of bitmap file in case of
file recognition.
9 A
“Initialization failed" or "Termination failed" occur in case
the unsuccessful calls of TextractInit()
and TextractTerm() functions.
10 A
“File <full specified file name> not found” occurs if one of INI, font
database or bitmap files not found.
ExGUI sources are located in ExGUI\ folder. Use ExGUI.DSW project file to
compile the example and try it under the debugger. Make sure that OCRSDK.DLL is
available for the system to load when you start ExGUI.EXE.
Console mode examples
There
is an example for each combination of source types (BMP file or screen
rectangle), destination types (file or memory) and output formats (text,
binary, RTF, verbose). Examples are named like Src_Dest_Output.EXE, where
11 Src is Bmp or
Scr, stands for BMP source file or for capturing an image from the screen.
12 Dest is File or
Memo, stands for whether the result is being output to a file or to memory.
13 Output is Acsii,
Binary, Rtf or Verbose.
All
other fine tuning is hard-coded into sources. You may change the sources to try
any combination.
All
sources are very simple for better understanding. Here is an example of one of
them.
=== Scr_File_Verbose.Cpp ===
// Scr_File_Verbose.Cpp
// Source of recognition: Captured
rect of screen
// Destignation results of
recognition: Output file
// Output format of recognition:
Verbore
#include <memory.h>
#include <stdio.h>
#include "../Screen Scraping
Library.H"
bool errorIf(TextractSuccess code){
if(code < 0){
switch(code){
case tsReject: puts("User rejected the operation"); break;
case tsBadArgs: puts("Incorrect argumens"); break;
case tsOutOfWindow: puts("Rectangle is out of window"); break;
case tsIniNotFound:
printf("File %s not found\n",
TextractIniFileName()); break;
case tsBaseNotFound:
printf("File %s not found\n",
TextractBaseFileName()); break;
case tsBitmapNotFound:
printf("File %s not found\n",
TextractBitmapFileName());break;
case tsCrash: puts("Internal error"); break;
}
return false;
} else
return true;
}
int main(void){
if(!errorIf(TextractInit()))
return -1;
if(!errorIf(Textract(
TextractSource(0,0,200,100),
TextractDest("test.dat"),
TextractDestFormat(dfVerbose | dfBol | dfEol | dfSpace |
dfChar | dfFont |
dfCharHex | dfCharFont)
)))
return -2;
errorIf(TextractTerm());
return 0;
}
============================
Building examples
To
build examples, load ExSimple\ExSimple.DSW project file into MS VC++.
Or
run NMAKE <selected_example.mak> from the command line.
TxtrCtl ActiveX control
(OCROCX.DLL)
Context of use of TxtrCtl
TxtrCtl
is a 32-bit Windows DLL based ActiveX control. OCROCX.DLL is written, using ATL
C++ language. OCROCX.DLL may be used with any environment that supports the use
of ActiveX controls such as Visual C++, Visual Basic, Power Builder and other.
OCROCX.DLL is needed in OCRSDK.DLL for its work. TxtrCt must be properly
installed before using.
Installation/uninstallation of TxtrCtl
To
install/uninstall TxtrCtl ActiveX control you may use
either regsvr32, or tstcon32 program to register the control.
To
install TxtrCtl, using regsvr32, use the following command line: regsvr32
OCROCX.DLL.
To
uninstall TxtrCtl, using regsvr32, use the following command line: regsvr32 /u
OCROCX.DLL. This command will unregister TxtrCtl control.
TxtrCtl properties and methods reference
All
properties and methods of TxtrCtl ActiveX control are described here using IDL.
Examples
of usage in Visual Basic are also available.
[propget, id(1),
helpstring("File name for recognition result. Empty for store result in
memory")) HRESULT Dest((out, retval] BSTR *pVal);
[propput, id(1),
helpstring("File name for recognition result. Empty for store result in
memory")) HRESULT Dest((in] BSTR newVal);
Allows
to set or to inquire a file (name) for the results of recognition. If this property
contains an empty string, then the results of the recognition are saved in
memory.
Examples of use in Visual Basic:
TxtrCtl1.Dest
= “C:\results.dat”
Sets a file named C:\results.dat for result of
recognition.
Dim
L As String
L
= TxtrCtl1.Dest
Returns a file name for the result of
recognition.
[propget, id(2),
helpstring("Boolean values describing output format details"))
HRESULT Flags((out, retval] long *pVal);
[propput, id(2),
helpstring("Boolean values describing output format details")) HRESULT
Flags((in] long newVal);
Allows
setting or querying additional flags for Binary (dfBinary) or Verbose
(dfVerbose) formats. Full list of these flags are available in “Screen Scraping
Library control flags and output formats” section.
Examples of use in Visual Basic:
TxtrCtl1.Flags
= dfBol And dfEol and dfChar
Sets the dfBol, dfEol and dfChar flags for
binary or verbose format.
Dim
L As Long
L
= TxtrCtl1.Flags
Returns flags for binary or verbose format
[propget, id(3),
helpstring("0-Text, 1-RTF, 2-Verbose
3-Binary,
4-Bmp")) HRESULT TextType((out,
retval] long *pVal);
[propput, id(3),
helpstring("0-Text, 1-RTF, 2-Verbose, 3-Binary,
4-Bmp")) HRESULT TextType((in]
long newVal);
Allows
setting or inquiring an output format. For more information about formats see “Screen
Scraping Library control flags and output formats” section.
Examples of use in Visual Basic:
TxtrCtl1.TextType
= 3
Sets the Verbose format.
Dim
Type As Long
Type
= TxtrCtl1.TextType
Gets the type of an output data format.
[propget, id(4),
helpstring("Output Text or RTF")) HRESULT Text((out, retval] BSTR
*pVal);
Returns
the result of recognition. This property is read only. One of the following
methods ReadScreen, ReadFile, ReadDesktopWindow, ReadLargestWindow, ReadWindow,
ReadTopWindow, ReadDeepWindow must be called before inquiring this property.
Example of use in Visual Basic:
Dim
Res As String
Res
= TxtrCtl1.Text
(id(5), helpstring("Initialize Screen
Scraping Library")) HRESULT Init();
(id(6), helpstring("Terminate Screen
Scraping Library")) HRESULT Term();
Initializes
and terminates the recognition module of ActiveX control.
Examples of use in Visual Basic:
TxtrCtl1.Init
TxtrCtl1.Term
(id(7), helpstring("Build font
dictionary")) HRESULT Build(long lWithDialog);
Builds
the font database. If lWithDialog == 0
then runs the building process without showing a dialog window, if 1WithDialog ¹ 0 - shows
a dialog window.
Example of use in Visual Basic:
TxtrCtl1.Build
0
(id(8), helpstring("Recognize
text from screen")) HRESULT ReadScreen(long Ax, long Ay, long Bx, long
By);
Captures
text from the screen rectangle with co-ordinates (Ax,
Ay) - (Bx, By) and
recognizes it.
Example of use in Visual Basic:
TxtrCtl1.ReadScreen
0 0 400 90
(id(9), helpstring("Recognize
text from bitmap file")) HRESULT ReadFile(BSTR BitmapFileName);
Loads
BMP file BitmapFileName and recognizes it’s contents.
Example of use in Visual Basic:
TxtrCtl1.BitmapFileName
“example.bmp”
(id(10), helpstring("Recognize
text from desktop window")) HRESULT ReadDesktopWindow();
Recognizes
the text from a desktop window.
Example of use in Visual Basic:
TxtrCtl1.ReadDesktopWindown
(id(11), helpstring("Recognize
text from largest window")) HRESULT ReadLargestWindow();
Recognizes
the text from the largest child window.
Example of use in Visual Basic:
TxtrCtl1.ReadLargestWindow
(id(12), helpstring("Recognize
text from window with specified handle")) HRESULT ReadWindow(long W);
Recognizes
the text from a window with a specified handle.
Example of use in Visual Basic:
TxtrCtl1.ReadWindow
1044
(id(13), helpstring("Recognize
text from top window with specified class name and caption")) HRESULT
ReadTopWindow(BSTR WindowClass, BSTR WindowCaption);
(id(14), helpstring("Recognize
text from deep window with specified class name and caption")) HRESULT ReadDeepWindow(BSTR
WindowClass, BSTR WindowCaption);
Recognizes
the text from a window with a specified class name and caption name.
Example of use in Visual Basic:
TxtrCtl1.ReadTopWindow
“SciCalc” “Calculator”
Visual Basic example of TxtrCtl use
VBTxtr
is a VB5 example of using TxtrCtl ActiveX control that allows you to try it.
User’s interface of this example is the
same as in ExGUI example. (See “MFC example of OCRSDK.DLL use” section.)
Exploring all functions is available in
VTBxtr, as it is in ExGUI, except the Binary output format, because VTBxtr
doesn’t have a decoder from binary to plain text..
VBTxtr
catches error exceptions raised in TxtrCtl ActiveX control and shows an error
message if a function fails. Possible errors:
14 A "Rectangle is out of
window" or "Incorrect arguments" occur if the source is
incorrect.
15 A ”Incorrect BMP file. Only 24bit
per pixel Windows BMP files are supported” occurs in case of file recognition
if the specified bitmap format is not supported.
16 A “Initialization failed" or
"Termination failed" occur in case the calls to TextractInit() and TextractTerm() functions
are unsuccessful.
17 A “File <full specified file
name> not found” occurs if INI, font
database or bitmap file(s) are not found.
VBTxtr
sources are located in ExVB\ folder. Use VBTxtr.vbp project file to compile the
example and try it under the debugger. Make sure that the TxtrCtl ActiveX
control is installed. For description of the installation procedure see
“Installation/uninstallation of TxtrCtl” section. You should have WordPad on
your machine, so the data returned in Text is shown properly.
OCRSDK.INI file
description
OCRSDK.INI file is used to define the configuration of
OCRSDKcl.EXE and OCRSDK.DLL. It may be present in current folder, folder where
OCRSDKcl.EXE or OCRSDK.DLL is located, or in WINDOWS system folder as it was
described in “Operational environment, Font database, INI file” topic.
OCRSDK.INI is a plain text file and it’s contents may be changed using any text
editor. OCRSDK.INI is a set of sections and entries that have the following
format:
[Section_name]
Entry_Name=Entry_Value
[Section_name] is a section
name
Entry_Name is an entry name
Enrty_Value is an entry value. Must be a
string or a number.
Each section can contain several entries that are
separated by a newline symbol (“\n”).
OCRSDK.INI uses the following sections and entries:
[Options]
Language=%sE
Database Path=C:\Screen Scraping Library\OCRSDK.Pat
[Recognition]
Include1=MS Sans Serif,Arial*,Helv*,Times*,Courier*,MS
Serif*,
Fixedsys,
Terminal,System,Lucida*,Verdana,Tahoma
Include2=*
Exclude=*
CE,Wingdings*,Webdings*,Marlett*,Algerian*,Brush Script*,
Italic=0
Bold=1
Underlined=1
Chars=\21-\7F
Sizes=8-12,14
Multicolor=0
Multifont=0
Line align=10
[Textra]
...
[Log]
...
[Debug]
...
Font database file name is defined by reading INI
[Options] Database Path entry.
If the pass is not specified, the program uses a
default pass: <location of OCRSDK.DLL or OCRSDKcl.EXE>\OCRSDK.PAT.
[Recognition], [Log], [Debug] sections are used by the
Screen Scraping Library recognition module.
A set of fonts, that includes fonts in font pattern
database by building font database process, is defined in [Recognition] Include1 and Include2 entries
(asterisk is possible). A set of excluding fonts is defined in [Recognition] Exclude entry.
Whether there are italic, bold and underlined styles
enabled in the font
pattern database is defined by [Recognition] Italic, [Recognition] Bold and
[Recognition] Underlined entries: 1 - enabled, 0 - disabled.
A set of font chars is defined in [Recognition] Chars
entry, using hexadecimal codes of chars. Possible entries: \21,\22,\23 is equal
to \21-\23.
The height of fonts, included in font pattern
database, is defined in [Recognition] Sizes entry. Values of height are defined
in logical units. Individual values and range of values are possible.