WordScale
Text and Word Capture SDK
Document
WordScaleä
Text and Word Capture SDK Document
Copyright Ó 2008 TMA Software Inc.
WordScale
Installation Location
WordScale
Coordinate & Window Retrieval APIs.
WordScale
License and Information APIs
Using
WordScale APIs from Visual C++
Using
WordScale APIs from .Net C#
Using
WordScale APIs from Visual Basic
Using
WordScale APIs from JavaScript
Installing
WordScale from InstallShield X
Installing
WordScale using a C++ Application
The WordScale Text Capture
Engine API provides an easy to use set of functions to extract text from any
window.
The captured text can be
returned in rich text or plain text format.
WordScale captures: The
entire text of a window using WSGetWindowText, a rectangle area of a
window using WSGetWindowTextFromRect, a word from a point on the window
using WSGetWordFromPoint or an entire line of text from a point on the
window using WSGetLineFromPoint.
The current selection can be obtained using WSGetLineTextFromPointSel.
It is also possible to
retrieve a word with context using the WSGetLineFromPoint and WSWordFromIndex
functions. See the function GetWordFromPointwithContext
function in the C++ example program.
WordScale API provides
functionality so text can be extracted from the screen easily using the mouse
or other input device. Text can be
extracted from a user selected rectangle using the WSSelectRect API or
text can be extracted from a window using the Window finder APIs WSChooseWindowFinder
or WSChoosePointFinder.
The WordScale APIs can be
used from a variety of applications and languages such as Visual C++
applications, Visual Studio .Net applications using C#, VB# etc. Visual Basic and
JavaScript applications.
WordScale
works with the following Windows versions:
Windows
2000
Windows
XP
Windows
XP SP2
Windows
Server 2003
Windows
Vista
Windows
Vista with User Account Control Enabled
Windows
Vista SP1
Windows
7
WordScale
on Windows 2000 requires Internet Explorer 6 or higher.
The
WordScale.dll is installed to the following location and registered there:
Windows 2000 and
Windows XP
C:\Documents
and Settings\All Users\Application Data\TMA Software\WordScale
Windows Vista
and Windows 7
C:\Users\All
Users\TMA Software\WordScale
Syntax
HRESULT
WSAppInit();
Parameters
Return Value
Description
Call
during application startup to initialize WordScale. If this method is not
called WordScale does not work. Method
only needs to be called once.
Syntax
HRESULT
WSAppTerm();
Parameters
Return Value
Description
Call
when application is shutting down.
Syntax
HRESULT
WSGetWindowText([in] long
hwnd, [in] eTextType textType, [out, retval] BSTR
*pwindowText);
Parameters
Hwnd [in] – Window to retrieve text from.
textType
[in] – Returned text format and layout.
eTextType_RichText = 0
eTextType_PlainText = 1
eTextType_RichText_NoLayout =
2
eTextType_PlainText_NoLayout =
3
eTextType_UniText = 5
eTextType_UniTextNoLayout = 6
Return Value
A
string which contains the captured text in the specified format or NULL if no
text is captured.
If
NULL is returned WSGetLastError can be called to determine if an error
occurred.
Description
Returns
all text from the specified window.
Syntax
HRESULT
WSGetWindowTextFromRect([in] long hwnd, [in]
eTextType textType, [in] long left, [in] long top, [in] long right, [in] long bottom, [out, retval] BSTR *pwindowText);
Parameters
Hwnd [in] – Window to retrieve text from.
textType
[in] – Returned text format and layout.
eTextType_RichText = 0
eTextType_PlainText = 1
eTextType_RichText_NoLayout =
2
eTextType_PlainText_NoLayout =
3
eTextType_UniText = 5
eTextType_UniTextNoLayout = 6
left [in] – Left screen coordinate of
rectangle.
top [in] – Top screen coordinate of
rectangle.
right [in] – Right screen coordinate of
rectangle.
bottom [in] – Bottom screen coordinate of
rectangle.
Return Value
A
string which contains the captured text in the specified format or NULL if no
text is captured.
If
NULL is returned WSGetLastError can be called to determine if an error
occurred.
Description
Returns
text from rectangle in specified window.
Syntax
HRESULT
WSGetWordFromPoint([in] long hwnd, [in] long x, [in] long y, [out, retval] BSTR * pwordText);
Parameters
Hwnd [in] – Window to retrieve text from.
x [in] – X screen coordinate of point.
y [in] – Y screen coordinate of point.
Return Value
A
string which contains the word at the specified point.
If
NULL is returned WSGetLastError can be called to determine if an error
occurred.
Description
Returns
word at specified coordinates in specified window.
Syntax
HRESULT
WSGetLineFromPoint([in] long hwnd, [in] long x, [in] long y, [OUT] long
*pcharIndexPt, [out, retval]
BSTR *plineText);
Parameters
Hwnd [in] – Window to retrieve text from.
x [in] – X screen coordinate of point.
y [in] – Y screen coordinate of point.
pcharIndexPt[out]
– Index of character at specified point.
Return Value
A
string which contains the entire line of captured text.
If
NULL is returned WSGetLastError can be called to determine if an error
occurred.
Description
Returns
line of text from point in specified window.
On
return the variable pcharIndexPt contains the index of the character at the
specified point position. So it is
possible to determine the word at the specified point. The word at the point is retrieved using
WSWordFromIndex function.
Syntax
HRESULT
WSGetLineTextFromPointSel([in] long hwnd, [in]
eTextType textType, [in] long x, [in] long y, [in] long wantSel,[OUT] long *pcharIndexPt, [out,
retval] BSTR *pwindowText);
Parameters
Hwnd [in] – Window to retrieve text from.
textType
[in] – Returned text format and layout.
eTextType_UniTextNoLayout =
6
x [in] – X screen coordinate of point.
y [in] – Y screen coordinate of point.
WantSel [in] – Set to one if selected text should be
returned.
pcharIndexPt[out]
– Index of character at specified point.
Return Value
A
string which contains the entire line of captured text plain text format or
NULL if no text is captured.
If
NULL is returned WSGetLastError can be called to determine if an error
occurred.
Description
Returns
line of text from point in specified window.
Only returns text in Plain Text format.
If
wantSel parameter is set then WordScale attempts to retrieve the selected
text. The selection can be obtained
from applications like Outlook, Office
Applications, Notepad, WordPad and Internet Explorer.
The
WSGetSelectionText must be used after to retrieve the selected text.
Retrieving
text selection can add overhead to the amount of time this function takes to
execute.
On return the variable pcharIndexPt contains the index of the character point
position. So it is possible to determine
the word at the specified point.
Syntax
HRESULT
WSGetSelectionText ([out, retval] BSTR * pselection);
Parameters
Return Value
A
string which contains the selected text if any was detected.
Description
Returns
the current selection determined from a previous call to
WSGetLineTextFromPointSel.
Syntax
HRESULT
WSChooseWindowFinder( [out, retval] long *phwnd);
Parameters
None.
Return Value
Window
handle of the window found using the finder or NUL if no window selected.
If
NULL is returned WSGetLastError can be called to determine if an error occurred
or the action was cancelled.
Description
Activates
the WordScale Finder tool. This allows
the user to select a window to capture text from. As the user moves the cursor around the
screen a highlighting rectangle is drawn around the selected window.
A
user can cancel this action by pressing the escape key.
Syntax
HRESULT
WSChoosePointFinder([out] long *pX, [out] long *pY, [out, retval] long *phwnd);
Parameters
pX [out] – X screen coordinate of point.
pY [out] – Y screen coordinate of point.
Return Value
Window
handle of the window found using the finder or NULL if no window selected.
If
NULL is returned WSGetLastError can be called to determine if an error occurred
or the action was cancelled.
Description
Activates
the WordScale Finder tool. This allows
the user to select a window to capture text from. As the user moves the cursor around the
screen a highlighting rectangle is drawn around the selected window.
A
user can cancel this action by pressing the escape key.
Syntax
HRESULT
WSSelectRect([out]long
*pcancelled, [out] long
*pleft, [out] long
*ptop, [out] long
*pright, [out] long
*pbottom, [out, retval]
long *phwnd);
Parameters
pcancelled
[out] – Non zero if the action is cancelled.
pleft [out] – Left screen coordinate of
rectangle.
ptop [out] – Top screen coordinate of
rectangle.
pright [out] – Right screen coordinate of
rectangle.
pbottom [out] – Bottom screen coordinate of
rectangle.
Return Value
Window
handle of the window or NULL if no window selected.
If
NULL is returned WSGetLastError can be called to determine if an error occurred
or the action was cancelled.
Description
Activates
the WordScale rectangle selection tool.
The use can select a rectangle area of the window to select text from.
A
user can cancel this action by pressing the escape key.
Syntax
WSGetActiveWindow([out, retval] long *phwnd);
Parameters
phwnd [out] – Handle to the active window.
Return Value
Window
handle to the active window.
Description
Returns
the WordScale identified active window.
This is usually the window that has the focus.
Syntax