STImgCtl – Markierung und Positionsbestimmung

Überblick

Mit den in diesem Kapitel beschriebenen Methoden können Bereiche des Dokuments markiert und hervorgehoben werden. Dafür muss der Formularfeldmodus deaktiviert sein.

Der markierte Bereich ist frei wählbar und kann entweder durch Übergabe von Koordinaten oder durch Auswahl mit der Maus gesteuert werden. Außerdem können auch Zeichenketten im Dokument gesucht und ihre Positionen zurückgegeben werden.

Die Markierung mit der Maus muss mit AllowMouseSelection aktiviert werden. Die Events MarkEnd oder MarkChange geben dann die Koordinaten der Auswahl zurück. Ist die Markierung per Maus nicht aktiviert, können mit SetSelection Koordinaten zur Markierung übergeben werden. Ob mehrere oder nur eine Markierung gleichzeitig angezeigt werden können, wird mit AllowMultiSelection gesteuert.

Die Markierung kann entweder durch eine rote Umrandung oder eine blaue Unterlegung des gewählten Rechtecks dargestellt werden. Diese Option gilt bei Umstellung immer für alle angezeigten Markierungen gleichzeitig, sowohl für zuvor als auch für nachfolgend eingebrachte.

Bitte beachten Sie die allgemeinen Hinweise zum verwendeten Bezugssystem für Koordinaten. Methoden und Events (wie zum Beispiel MarkChange), die das Bezugssystem nicht selbst setzen, verwenden immer das zuletzt von einer anderen Methode gesetzte System. Deswegen empfiehlt es sich, am Anfang eine Methode zum Setzen des Bezugssystems aufzurufen und das System die ganze Zeit beizubehalten.

Methode AllowMouseSelection

Mit dieser Methode wird die Möglichkeit, Markierungen mit der Maus aufzuziehen und zu verändern, aktiviert oder deaktiviert. Die resultierende Position wird von den Events MarkEnd und MarkChange zurückgegeben.

Um zu konfigurieren, ob nur eine oder mehrere Markierungen gleichzeitig angezeigt werden können, nutzen Sie bitte die Methode AllowMultiSelection.

Ist die Markierung per Maus aktiviert, können auch zuvor durch SetSelection gesetzte Markierungen mit der Maus verändert werden.

void AllowMouseSelection(int nOption);

void AllowMouseSelection(long nOption);

Methode AllowMultiSelection

Mit dieser Methode wird festgelegt, ob nur eine oder mehrere Markierungen angezeigt werden können. Das gilt sowohl für die mit der Maus aufgezogenen als auch für die durch SetSelection gesetzten Markierungen.

Kann nur eine Markierung gesetzt werden, wird bei jeder neuen Markierung die alte gelöscht.

void AllowMultiSelection(int nOption);

void AllowMultiSelection(long nOption);

Methode SetSelection

Mit dieser Methode kann ein Bereich in der Anzeige hervorgehoben und zu der markierten Seite gesprungen werden.

Um die Anzahl der gleichzeitig anzeigbaren Markierungen zu konfigurieren, nutzen Sie bitte die Methode AllowMultiSelection.

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
                  );

Methode GetSelectionScreenPos

Mit dieser Methode wird die Position der zuletzt gesetzten Markierung ausgegeben (sofern diese nicht davor gelöscht wurde). Abweichend von anderen Methoden wird die Position relativ zum linken und oberen Rand des Bildschirms ausgegeben, und die Maßeinheit ist Pixel.

Diese Werte können beispielsweise dazu genutzt werden, um die Position der Markierung der eigenen Anwendung mitzuteilen, oder um auf eine Aktion des Mauszeigers zu reagieren.

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

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

Methode ClearSelection

Alle über die Maus eingebrachten (siehe AllowMouseSelection) oder durch die Methode SetSelection gesetzten Hervorhebungen werden entfernt. Im Gegensatz zu ClearDisplay bleibt das angezeigte Dokument erhalten.

void ClearSelection();

void ClearSelection();

Methode SearchText

Mit dieser Methode können Textstellen in PDF-Dokumenten gesucht werden. Die Abfrage der Ergebnisse erfolgt dann über GetTextPositionByIndex. Frühere Suchergebnisse werden bei erneutem Aufruf überschrieben.

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

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

Methode GetTextPositionByIndex

Mit dieser Methode können die mit SearchText gefundenen Textpositionen einzeln abgefragt werden. Dafür muss SearchText zuvor erfolgreich aufgerufen worden sein. Die Positionen werden relativ zum sichtbaren Bezugssystem zurückgegeben.

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
                            );

Event MarkEnd

Dieses Event signalisiert, dass ein Rechteck mit der Maus auf dem Steuerelement aufgezogen wurde. Es wird ausgelöst, sobald die Maustaste losgelassen wird, und gibt die Position des markierten Bereiches aus.

Im folgenden wird eine Beispiel-Implementation gezeigt, in der benutzerdefinierte Namen durch Platzhalter (%…%) ersetzt wurden.

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);

Event MarkChange

Dieses Event signalisiert, dass eines der selbst erstellten Markierungsrechtecke mit der Maus auf dem Steuerelement angeklickt, verschoben oder in der Größe geändert wurde. Es wird ausgelöst, sobald die Maustaste losgelassen wird, und gibt die neue Position aus.

Im folgenden wird eine Beispiel-Implementation gezeigt, in der benutzerdefinierte Namen durch Platzhalter (%…%) ersetzt wurden.

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);