Metodo IViewObjectEx::QueryHitPoint (ocidl.h)

Articolo
02/29/2024

Indica se un punto si trova all'interno di un determinato aspetto di un oggetto.

Sintassi

HRESULT QueryHitPoint(
  [in]  DWORD   dwAspect,
  [in]  LPCRECT pRectBounds,
  [in]  POINT   ptlLoc,
  [in]  LONG    lCloseHint,
  [out] DWORD   *pHitResult
);

Parametri

[in] dwAspect

Aspetto del disegno richiesto.

[in] pRectBounds

Rettangolo di delimitazione di oggetti nelle coordinate client della finestra contenente. Questo rettangolo viene calcolato e passato dal contenitore in modo che l'oggetto possa interpretare significativamente la posizione di hit.

[in] ptlLoc

Posizione di hit nelle coordinate client della finestra contenente.

[in] lCloseHint

Distanza suggerita nelle unità HIMETRIC che il contenitore considera vicino. Questo valore è un hint e gli oggetti possono interpretarlo in modo personalizzato. Gli oggetti possono anche usare questo hint per dedurre approssimativamente la risoluzione di output per scegliere l'espansione dell'implementazione di hit test.

[out] pHitResult

Puntatore per restituire informazioni sull'hit espresso come valori di enumerazione HITRESULT .

Valore restituito

Questo metodo restituisce S_OK sull'esito positivo. Gli altri valori restituiti possibili includono i seguenti:

Codice restituito	Descrizione
E_FAIL	Questo metodo non viene implementato per l'aspetto richiesto. Usare DVASPECT_CONTENT invece.

Commenti

Per supportare il rilevamento degli hit su oggetti non rettangolari, il contenitore deve richiedere un modo affidabile per chiedere a un oggetto se una determinata posizione si trova all'interno di uno dei relativi aspetti di disegno. Questa funzione viene fornita da IViewObjectEx::QueryHitPoint.

Nota Poiché questo metodo fa parte dell'interfaccia IViewObjectEx , il contenitore può determinare se un hit del mouse è su un oggetto senza dover necessariamente avviare il server. Se l'hit si trova all'interno dell'oggetto, è probabile che l'oggetto venga attivato sul posto e che il server sia avviato.

In genere, il contenitore determina prima di tutto se una determinata posizione si trova all'interno dell'estensione rettangolare di un oggetto. Se la posizione si trova all'interno dell'estensione rettangolare di un oggetto, il contenitore chiama IViewObjectEx::QueryHitPoint per verificare che la posizione sia effettivamente all'interno dell'oggetto. Il percorso di hit viene passato nelle coordinate client della finestra del contenitore. Poiché l'oggetto può essere inattivo quando questo metodo viene chiamato, il rettangolo di associazione dell'oggetto nello stesso sistema di coordinate viene passato anche a questo metodo, analogamente a ciò che accade in IPointerInactive::OnInactiveSetCursor.

I valori restituiti possibili includono:

All'esterno, in un'area trasparente
Abbastanza vicino da essere considerato un colpo (può essere usato da oggetti piccoli o sottili)
Colpire

IViewObjectEx::QueryHitPoint non è interessato dagli oggetti secondari dell'oggetto che viene chiamato. Indica semplicemente se il colpo del mouse era all'interno dell'oggetto o meno.

IViewObjectEx::QueryHitPoint può essere chiamato per uno qualsiasi degli aspetti di disegno supportati da un oggetto. Se l'elemento non è supportato per l'aspetto di disegno richiesto, deve avere esito negativo.

Gli oggetti trasparenti possono voler implementare un meccanismo di rilevamento degli hit-detection complesso in cui l'utente può selezionare l'oggetto trasparente o un oggetto dietro di esso, a seconda della posizione in cui si verifica esattamente il clic all'interno dell'oggetto. Ad esempio, una casella di testo trasparente che mostra testo abbastanza grande può consentire all'utente di selezionare l'oggetto dietro, ad esempio una bitmap, quando l'utente fa clic tra i caratteri. Per questo motivo, le informazioni restituite da IViewObjectEx::QueryHitPoint includono un'indicazione su se l'hit si verifica su un'area opaca o trasparente.

Un esempio di rilevamento dei colpi non rettangolari e trasparenti è un controllo cerchio trasparente con un oggetto dietro di esso (una riga nell'esempio seguente):

Diagramma di un cerchio con una linea diagonale attraverso di esso, che mostra i valori di rilevamento degli hit per le aree all'interno e all'esterno del cerchio e vicino alla linea.

I valori visualizzati sono per i test di hit sul cerchio; le aree grigie non fanno parte del controllo, ma vengono visualizzate qui per indicare un'area intorno all'immagine considerata chiusa. Ogni oggetto implementa la propria definizione di chiusura, ma è assistito da un suggerimento fornito dal contenitore in modo che la vicinanza possa essere regolata come immagini zoomno più grandi o più piccole.

Nell'immagine precedente, i punti contrassegnati Hit, Close e Transparent sarebbero tutti colpi di forza variabile sul cerchio, con l'eccezione di quella contrassegnata Transparent, (ma per la linea, chiudere). Questo illustra l'effetto della diversa forza dei colpi. Poiché il cerchio risponde trasparente mentre le attestazioni di riga si chiude e trasparente è più debole rispetto alla chiusura, la riga prende il colpo.

Note per gli implementatori

Un oggetto che supporta IViewObjectEx è necessario per implementare questo metodo almeno per l'aspetto DVASPECT_CONTENT . L'oggetto non deve eseguire alcuna altra azione in risposta a questo metodo diverso da quello di restituire le informazioni; non ci dovrebbero essere effetti collaterali.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ocidl.h

Vedi anche

HITRESULT

IPointerInactive::OnInactiveSetCursor

IViewObjectEx

Condividi tramite