TSelection SDK

From Screen Scraper Studio

Introduction

TSelection was created to enable the user to invoke a screen object selection UI and get the selected area in a controlled way. The screen scraping selection can be a rectangular area or a point, with some additional features.

Creating the TSelection object

To work with UIElement, you must use the following interfaces:

- "TSelection.Selection"/ITSelection2         - used for invoking the selection methods
- "TSelection.SelectionInfo"/ITSelectionInfo2 - used for getting information about the selected area

 #import “<path>\TSelection.dll” named_guids
 using namespace TSelectionLib;
 
 int CreateTSelectionObjects()
 {
     //Be sure to call the CoInitialize API before attempting these instantiations
     //This sample uses the smart pointer classes in ATL because the code is more compact
     //Feel free to implement using the low level COM API if you want
     HRESULT hr;
     CComPtr<ITSelection2> pSel;
     hr = pSel.CoCreateInstance(CLSID_TSelection);
     if(FAILED(hr) || !pSel)
         return ERROR;
     //The selection objects are created by the selection functions as an output and you do not need to
     //"CoCreateInstance" them. Just declare them like this and then pass them as output parameters:
     CComPtr<ITSelectionInfo2>	pSelInfo;
 
     return SUCCESS;
 }

 using TSelectionLib;
 
 void CreateUIElemObject()
 {
     SelectionClass objSel   = new SelectionClass();
 }

 Dim objSelection   As New Selection

TSelectionInfo Properties

Type

Declared in the ITSelectionInfo interface.

 LONG Type;

Specifies the type of the selection which this object is used for. For a list of possible values, see the selection_type parameter of the Start function.

WindowHandle

Declared in the ITSelectionInfo interface.

 LONG WindowHandle;

Specifies the handle of the window which the selected area belongs to.

Points

Declared in the ITSelectionInfo interface.

 VARIANT Points;

A VARIANT structure of type VT_ARRAY which contains an array of VT_UI4 variants. Each of the VT_UI4 array members is a 32-bit value. The low order word contains the X coordinate and the high order word contains the Y value.

Image

Declared in the ITSelectionInfo interface.

 IPictureDisp *Image;

Pointer to an interface that describes the bitmap representation of the selected area.

TSelectionInfo2 Properties

UIElementID

Declared in the ITSelectionInfo2 interface.

 BSTR UIElementID;

Specifies the Selector of the selected UIElement object, if it was requested.

TSelection Methods

Start

Declared in the ITSelection Interface

HRESULT Start([in] LONG selection_type, [in] LONG options, [out, retval] IDispatch** selection_result);

Overview

This method starts the UI selection mode and returns information about the selected area. In addition to the Start method, this method supports the selection of UIElement objects.

Parameters

selection_type   - the type of selection that the user wants to initiate. It must be one of the following values:
                     tsSelectionNone            = 0x0000
                     tsSelectionPoint           = 0x0001
                     tsSelectionRectangle       = 0x0002
                     tsSelectionPointRectangle  = 0x0003
                     tsSelectionFreeFrom        = 0x0004
                     tsSelectionPointFreeFrom   = 0x0005
                     tsSelectionWindow          = 0x0008
                     tsSelectionObject          = 0x0010
                     tsSelectionScrollingWindow = 0x0020
                     tsSelectionRoundRectangle  = 0x0040
                     tsSelectionEllipse         = 0x0080
                     tsSelectionColorPick       = 0x0100
                     tsSelectionFixedRegion     = 0x0200
                     tsSelectionUIElement       = 0x0400
options          - additional options regarding the selection. 
                   It must be a combination of the following flags ('|' means 'bitwise OR'):
                     tsSelFlagNone           = 0x0000
                     tsSelFlagShowPreview    = 0x0001
                     tsSelFlagLockScreen     = 0x0002
                     tsSelFlagHighlight      = 0x0004
                     tsSelSchemeBlue         = 0x0008
                     tsSelSchemeRed          = 0x0010
                   There are also some predefined values for the common usage scenarios: 
                     tsSelFlagDefaultText    = tsSelFlagHighlight | tsSelSchemeBlue
                     tsSelFlagDefaultGraphic = tsSelFlagShowPreview | tsSelFlagLockScreen | tsSelSchemeRed
                     tsSelFlagDefault        = tsSelFlagDefaultText
selection_result - pointer to an ITSelectionInfo2 object address which will receive the information about the selected area.
result           - API-specific error code indicating the outcome of the selection operation.
                   It will have one of the following values:
                     tsSelResultSuccess   = 0x0000
                     tsSelResultCancelled = 0x0001
                     tsSelResultError     = 2*tsSelResultCancelled

Examples

//Add this to your "stdafx" header or any header with commonly used stuff
#using namespace TSelectionLib 
 
CComPtr<ITSelection>     pSelection;
CComPtr<ITSelectionInfo> pSelInfo;
LONG    nRes;
HRESULT hr = pSelection.CoCreateInstance(CLSID_TSelection);
if(FAILED(hr) || !pSelection)
    return ERROR;
//Start the UI selection and use the "rectangular selection" mode
CComPtr<IDispatch>  spDispResult;
spDispResult = pSelection->Start(tsSelectionRectangle, tsSelFlagDefaultText);
if(spDispResult)
            spDispResult->QueryInterface(IID_ITSelectionInfo, (void**)&pSelInfo);
 
nRes = pSelInfo->SelectionResult;
if(nRes != tsSelResultSuccess)
    return ERROR;
//Collect the selection data
CComSafeArray<VT_VARIANT, VT_VARIANT> arSafePoints;
VARIANT points;
//Get the handle of the window containing the selected rectangular area
HWND    hCapturedWnd = (HWND)pSelInfo->WindowHandle;
//Get the (top left) and (bottom right) corners of the selection rectangle as a raw
//VARIANT of ARRAY type
pSelInfo->get_Points(&points);
//Convert them to the more comfortable CComSafeArray object
arSafePoints.CopyFrom(points.parray);
//'nCount' should be 2
nCount = (int)arSafePoints.GetCount();
 
//Successfully exit
return SUCCESS;

Error Codes

0x80040211: Trial version expired. Please activate the library.
0x80040212: Internal selection error.