STImgCtl – Selecting and Positioning

Overview

The methods described in this section can be used to mark and highlight areas of the document. To do this, form field mode must be deactivated.

The selected area can be freely chosen and can be controlled either by entering coordinates or by selecting with the mouse. In addition, character strings can be searched for in the document and their positions returned.

Selection by mouse must be enabled with AllowMouseSelection. The events MarkEnd or MarkChange then return the coordinates of the selection. If selection by mouse is not activated, coordinates can be transferred to the selection using SetSelection. Whether multiple selections or only one selection can be displayed at a time is controlled by AllowMultiSelection.

The selection can be indicated either by a red border around the selected rectangle or a blue background. Switching from one indication form to another always applies to all displayed selections simultaneously, i.e. both for those entered previously and subsequently.

Please note the general information on the reference system used for coordinates. Methods and events (such as MarkChange) that do not set the reference system themselves always use the system last set by another method. Therefore, it is recommended to call a method for setting the reference system at the beginning and to maintain the system throughout.

AllowMouseSelection method

This method activates or deactivates the ability to draw and modify selections with the mouse. The resulting position is returned by the events MarkEnd and MarkChange.

To configure whether only one or multiple markers can be displayed at the same time, please use the method AllowMultiSelection.

If selection by mouse is enabled, selections previously made with SetSelection can also be changed with the mouse.

void AllowMouseSelection(int nOption);

void AllowMouseSelection(long nOption);

AllowMultiSelection method

This method determines whether only one or multiple selections can be displayed. This applies to both selections made with the mouse and those set using SetSelection.

If only one selection can be set, the old selection is deleted each time a new selection is set.

void AllowMultiSelection(int nOption);

void AllowMultiSelection(long nOption);

SetSelection method

This method can be used to highlight a region in the display and jump to the selected page.

To configure the number of selections that can be displayed simultaneously, please use the AllowMultiSelection method.

C#:

int SetSelection(
                 int nPage,
                 int nLeft,
                 int nTop,
                 int nRight,
                 int nBottom,
                 int nOptions
                 );

C++:

long SetSelection(
                  long nPage,
                  long nLeft,
                  long nTop,
                  long nRight,
                  long nBottom,
                  long nOptions
                  );

GetSelectionScreenPos method

This method returns the position of the last marker that was set (provided it has not been deleted). Unlike other methods, the position is output relative to the left and top edges of the screen, and the unit of measurement is pixels.

These values can be used, for example, to communicate the position of the selection in your own application or to respond to a mouse pointer action.

int GetSelectionScreenPos(
                          ref int pnLeft,
                          ref int pnTop,
                          ref int pnRight,
                          ref int pnBottom
                         );

long GetSelectionScreenPos(
                           long* pnLeft,
                           long* pnTop,
                           long* pnRight,
                           long* pnBottom
                           );

ClearSelection method

Selections applied with the mouse (see AllowMouseSelection) or set by the SetSelection method are removed. Unlike ClearDisplay, the displayed document remains unchanged.

void ClearSelection();

void ClearSelection();

SearchText method

This method can be used to search for text passages in PDF documents. The results are then queried using GetTextPositionByIndex. Previous search results will be overwritten when the search is repeated.

int SearchText(
               string bstrSearchText,
               int nPage,
               int nOptions,
               int* pnFoundTextCount
               );

long SearchText(
                BSTR bstrSearchText,
                long nPage,
                long nOptions,
                long* pnFoundTextCount
                );

GetTextPositionByIndex method

This method allows the text positions found with SearchText to be queried individually. To do this, SearchText must have been successfully called beforehand. The positions are returned relative to the visible reference system.

int GetTextPositionByIndex(
                           int nFoundTextIndex,
                           int* pnPage, long* pnLeft,
                           int* pnTop,
                           int* pnRight,
                           int* pnBottom
                           );

long GetTextPositionByIndex(
                            long nFoundTextIndex,
                            long* pnPage,
                            long* pnLeft,
                            long* pnTop,
                            long* pnRight,
                            long* pnBottom
                            );

MarkEnd event

This event signals that a rectangle was defined with the mouse on the control element. It is triggered as soon as the mouse button is released, and outputs the position of the selected region.

The following shows an example implementation in which user-defined names have been replaced by placeholders (%…%).

public class _DSTImgCtlEvents_MarkEndEvent
{
    public int xPos1;
    public int yPos1;
    public int xPos2;
    public int yPos2;

    public _DSTImgCtlEvents_MarkEndEvent(int xPos1, int yPos1, int xPos2, int yPos2)
    {
        this.xPos1 = xPos1;
        this.yPos1 = yPos1;
        this.xPos2 = xPos2;
        this.yPos2 = yPos2;
    }
}

this.%COMPONENT_NAME%.MarkEnd += new AxSTIMGCTLLib._DSTImgCtlEvents_MarkEndEventHandler(this.%CALLBACK_FUNCTION%);

private void %CALLBACK_FUNCTION%(object sender, AxSTIMGCTLLib._DSTImgCtlEvents_MarkEndEvent e);

BEGIN_EVENTSINK_MAP(%CLASS_NAME%, CDialogEx)
    ON_EVENT(%CLASS_NAME%, %COMPONENT_ID%, 1, %CALLBACK_FUNCTION%, VTS_I4 VTS_I4 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()

void %CALLBACK_FUNCTION%(long xPos1, long yPos1, long xPos2, long yPos2);

MarkChange event

This event signals that one of the selection rectangles created manually with the mouse was clicked on the control element, repositioned, or resized. It is triggered as soon as the mouse button is released, and outputs the new position.

The following shows an example implementation in which user-defined names have been replaced by placeholders (%…%).

public class _DSTImgCtlEvents_MarkChangeEvent
{
    public short nPos;
    public int xPos1;
    public int yPos1;
    public int xPos2;
    public int yPos2;

    public _DSTImgCtlEvents_MarkChangeEvent(short nPos, int xPos1, int yPos1, int xPos2, int yPos2)
    {
        this.nPos = nPos;
        this.xPos1 = xPos1;
        this.yPos1 = yPos1;
        this.xPos2 = xPos2;
        this.yPos2 = yPos2;
    }
}

this.%COMPONENT_NAME%.MarkChange += new AxSTIMGCTLLib._DSTImgCtlEvents_MarkChangeEventHandler(this.%CALLBACK_FUNCTION%);

private void %CALLBACK_FUNCTION%(object sender, AxSTIMGCTLLib._DSTImgCtlEvents_MarkChangeEvent e);

BEGIN_EVENTSINK_MAP(%CLASS_NAME%, CDialogEx)
    ON_EVENT(%CLASS_NAME%, %COMPONENT_ID%, 3, %CALLBACK_FUNCTION%, VTS_I2 VTS_I4 VTS_I4 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()

void %CALLBACK_FUNCTION%(short nPos, long xPos1, long yPos1, long xPos2, long yPos2);