Informazioni sui controlli tooltip

Le descrizioni comando vengono visualizzate automaticamente o appaiono quando l'utente posiziona il puntatore del mouse su uno strumento o su qualsiasi altro elemento dell'interfaccia utente. La descrizione comando viene visualizzata vicino al puntatore e scompare quando l'utente fa clic su un pulsante del mouse, sposta il puntatore lontano dallo strumento o semplicemente attende alcuni secondi.

Il controllo descrizione comando nella figura seguente visualizza informazioni su un file sul desktop di Windows. Quando si sposta il mouse sull'illustrazione, apparirà anche un tooltip dal vivo contenente testo descrittivo.

Questa sezione descrive come funzionano i controlli tooltip e come vengono creati.

• Comportamento e aspetto del tooltip
• Creazione dei controlli Descrizione Comando
• Attivazione dei controlli dei tooltip
• strumenti di supporto
• Visualizzazione testo
• Messaggistica e Notifiche
• Test di collisione
• Elaborazione predefinita dei messaggi

I controlli dei tooltip possono visualizzare una singola riga di testo o più righe. Gli angoli possono essere arrotondati o quadrati. Potrebbero avere o meno un gambo che punta agli strumenti come una nuvoletta dei fumetti. Il testo della descrizione comando può essere stazionario o può spostarsi con il puntatore del mouse, detto tracciamento. Il testo stazionario può essere visualizzato adiacente a uno strumento o può essere visualizzato su uno strumento, detto sul posto. Le descrizioni comando standard sono fisse, visualizzano una singola riga di testo, hanno angoli squadrati e non hanno frecce che puntano verso lo strumento.

Le descrizioni comando di rilevamento, supportate da versione 4.70 dei controlli comuni, cambiano posizione sullo schermo in modo dinamico. Aggiornando rapidamente la posizione, questi controlli descrizione comando sembrano muoversi fluidamente, o "tracciare". Questi sono utili quando si desidera che il testo della descrizione comando segua la posizione del puntatore del mouse mentre esso si muove. Per ulteriori informazioni sul rilevamento delle descrizioni comando e un esempio di codice che mostra come crearle, consulta Descrizioni Comando di Rilevamento.

I suggerimenti su più righe, supportati anche dalla versione 4.70 dei controlli comuni, visualizzano testo su più righe. Sono utili per la visualizzazione di messaggi lunghi. Per ulteriori informazioni e un esempio su come creare descrizioni comando su più righe, vedere descrizioni comando su più righe.

Le descrizioni comandi balloon vengono visualizzate in una casella con angoli arrotondati e un stelo che punta allo strumento. Possono essere a riga singola o su più righe. La figura seguente mostra una descrizione comandi a nuvoletta con il gambo e il rettangolo nelle posizioni predefinite. Per ulteriori informazioni sui tooltip a forma di balloon e un esempio che illustra come crearli, consultare Using Tooltip Controls.

Un tooltip può anche avere un titolo e un'icona, come illustrato nella figura seguente. Si noti che la descrizione comando deve contenere testo; se contiene solo il testo del titolo, la descrizione comando non viene visualizzata. Anche l'icona non viene visualizzata a meno che non sia presente un titolo.

A volte le stringhe di testo vengono ritagliate perché sono troppo lunghe per essere visualizzate completamente in una piccola finestra. Le descrizioni comando sul posto possono essere usate per visualizzare stringhe di testo per gli oggetti troncati, ad esempio il nome del file nella figura seguente. Per un esempio che mostra come creare i tooltip in loco, vedere In-Place tooltip.

Il cursore deve sostare su uno strumento per un periodo di tempo prima che venga visualizzata la descrizione comando. La durata predefinita di questo timeout è controllata dall'ora di doppio clic dell'utente e in genere è di circa una metà del secondo. Per specificare un valore di timeout non predefinito, inviare al controllo della descrizione comando un messaggio di TTM_SETDELAYTIME.

Per creare un controllo descrizione comando, chiamare CreateWindowEx e specificare la classe della finestra TOOLTIPS_CLASS. Questa classe viene registrata quando viene caricata la DLL del controllo comune. Per assicurarsi che questa DLL venga caricata, includere la funzioneInitCommonControlsEx nell'applicazione. È necessario definire in modo esplicito un controllo descrizione comando come in primo piano. In caso contrario, potrebbe essere coperto dalla finestra padre. Il frammento di codice seguente illustra come creare un controllo descrizione comando.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

La procedura della finestra per il controllo descrittivo comandi imposta automaticamente le dimensioni, la posizione e la visibilità del controllo. L'altezza della finestra della descrizione comando si basa sull'altezza del tipo di carattere attualmente selezionato nel contesto del dispositivo per il controllo della descrizione comando. La larghezza varia in base alla lunghezza della stringa attualmente presente nella finestra della descrizione comando.

Un controllo tooltip può essere attivo o inattivo. Quando è attivo, il testo della descrizione comando viene visualizzato quando il puntatore del mouse si trova su uno strumento. Quando è inattivo, il testo del tooltip non appare, anche se il puntatore si trova su uno strumento. Il messaggio TTM_ACTIVATE attiva e disattiva un controllo descrizione comando.

Un controllo tooltip può supportare un numero qualsiasi di strumenti. Per supportare uno strumento specifico, è necessario registrare lo strumento con il controllo della descrizione comando inviando al controllo il messaggio TTM_ADDTOOL. Il messaggio include l'indirizzo di una struttura TOOLINFO, che fornisce le informazioni necessarie affinché il controllo descrizione comando possa visualizzare il testo per lo strumento. Il membro uID della struttura TOOLINFO è definito dall'applicazione. Ogni volta che si aggiunge uno strumento, l'applicazione fornisce un identificatore univoco. Il membro cbSize della struttura TOOLINFO è richiesto e deve specificare le dimensioni della struttura.

Un controllo tooltip supporta gli strumenti implementati come finestre (ad esempio finestre figlio o finestre di controllo) e come aree rettangolari all'interno dell'area client di una finestra. Quando si aggiunge uno strumento implementato come area rettangolare, il membro hwnd della struttura TOOLINFO deve specificare l'handle della finestra che contiene l'area, e il membro rect deve specificare le coordinate client del rettangolo di delimitazione dell'area. Inoltre, il membro uID deve specificare l'identificatore definito dall'applicazione per lo strumento.

Quando si aggiunge uno strumento implementato come finestra, il membro uID della struttura TOOLINFO deve contenere l'handle della finestra dello strumento. Inoltre, il membro uFlags deve specificare il valore TTF_IDISHWND, che indica al controllo della descrizione comando di interpretare il membro uID come handle di finestra.

Quando si aggiunge uno strumento a un controllo tooltip, il membro lpszText della struttura TOOLINFO deve specificare l'indirizzo della stringa da visualizzare per lo strumento. Dopo aver aggiunto uno strumento, è possibile modificare il testo usando il messaggio TTM_UPDATETIPTEXT.

Se la parola di alto ordine di lpszText è zero, la parola di basso ordine deve essere l'identificatore di una risorsa di stringa. Quando il controllo descrizione comando richiede il testo, il sistema carica la risorsa stringa specificata dall'istanza dell'applicazione identificata dal membro posteriore della struttura TOOLINFO.

Se si specifica il valore LPSTR_TEXTCALLBACK nel membro lpszText, il controllo tooltip notifica alla finestra specificata nel membro della struttura TOOLINFOogni volta che deve visualizzare il testo per lo strumento. Il controllo descrizione comando invia il codice di notifica TTN_GETDISPINFO alla finestra. Il messaggio include l'indirizzo di una strutturaNMTTDISPINFO, che contiene l'handle della finestra e l'identificatore definito dall'applicazione per lo strumento. La finestra esamina la struttura per determinare per quale strumento è necessario il testo e riempie i membri appropriati della struttura con le informazioni necessarie al controllo descrizione comando per visualizzare la stringa.

Molte applicazioni creano barre degli strumenti contenenti strumenti che corrispondono ai comandi di menu. Per questi strumenti, è comodo che il controllo descrizione comando visualizzi lo stesso testo della voce di menu corrispondente. Il sistema rimuove automaticamente i caratteri dell'acceleratore (&) da tutte le stringhe passate a un controllo descrizione comando e termina la stringa al primo carattere di tabulazione (\t), a meno che il controllo non abbia lo stile TTS_NOPREFIX.

Per recuperare il testo per uno strumento, usare il messaggio TTM_GETTEXT.

Il testo della descrizione comando viene in genere visualizzato quando il puntatore del mouse passa sopra un'area, in genere il rettangolo definito da uno strumento, ad esempio un controllo pulsante. Tuttavia, Microsoft Windows invia solo messaggi correlati al mouse alla finestra che contiene il cursore del mouse, non al controllo descrizione comando stesso. Le informazioni relative al mouse devono essere inoltrate al controllo della descrizione comando affinché possa visualizzare il testo della descrizione comando al momento e nel luogo appropriato.

È possibile che i messaggi vengano inoltrati automaticamente se:

• Lo strumento è un controllo o è definito come rettangolo nella struttura TOOLINFO dello strumento.
• La finestra associata allo strumento si trova nello stesso thread del controllo descrizione comando.

Se vengono soddisfatte queste due condizioni, impostare il flag di TTF_SUBCLASS nel uFlags membro della struttura TOOLINFO dello strumento quando si aggiunge lo strumento al controllo tooltip con TTM_ADDTOOL. I messaggi necessari del mouse verranno quindi inoltrati automaticamente al controllo tooltip.

Impostare TTF_SUBCLASS affinché i messaggi del mouse vengano inoltrati al controllo è sufficiente per la maggior parte degli scopi. Tuttavia, non funzionerà nei casi in cui non vi sia alcuna connessione diretta tra il controllo descrizione comando e la finestra dello strumento. Ad esempio, se uno strumento viene implementato come area rettangolare in una finestra definita dall'applicazione, la routine della finestra riceve i messaggi del mouse. L'impostazione di TTF_SUBCLASS è sufficiente per assicurarsi che vengano passate al controllo . Tuttavia, se uno strumento viene implementato come finestra definita dal sistema, i messaggi del mouse vengono inviati a tale finestra e non sono direttamente disponibili per l'applicazione. In questo caso, è necessario sottoclassare la finestra o usare un hook di messaggi per accedere ai messaggi del mouse. È quindi necessario inoltrare in modo esplicito i messaggi del mouse al controllo descrizione comando con TTM_RELAYEVENT. Per un esempio di come usare TTM_RELAYEVENT, vedere Descrizione comando di rilevamento.

Quando un controllo descrizione comando riceve un messaggio WM_MOUSEMOVE, determina se il puntatore del mouse si trova nel rettangolo di delimitazione di uno strumento. In caso affermativo, il controllo descrizione comando imposta un timer. Alla fine dell'intervallo di timeout, il controllo descrizione comando controlla la posizione del puntatore per verificare se è stato spostato. In caso contrario, il controllo tooltip ottiene il testo per lo strumento e visualizza il tooltip. Il controllo descrizione comando continua a visualizzare la finestra fino a quando non riceve un messaggio di rilascio del pulsante o di pressione del pulsante, oppure fino a quando un messaggio di WM_MOUSEMOVE indica che il puntatore è stato spostato all'esterno del rettangolo limite dello strumento.

Un controllo tooltip ha effettivamente tre durate di timeout associate. La durata iniziale è il tempo in cui il puntatore del mouse deve rimanere fermo all'interno del rettangolo di delimitazione di uno strumento prima che venga visualizzata la finestra della descrizione comando. La durata del ritardo di visualizzazione è il tempo di attesa prima che i tooltips successivi vengano visualizzati quando il puntatore si sposta da uno strumento a un altro. La durata del pop-up è il tempo in cui la finestra del suggerimento rimane visibile prima di essere nascosta. Ovvero, se il puntatore rimane fermo all'interno del rettangolo di delimitazione dopo la visualizzazione della finestra della descrizione comando, la finestra della descrizione comando viene nascosta automaticamente alla fine della durata del popup. È possibile modificare tutte le durate di timeout usando il messaggio TTM_SETDELAYTIME.

Se un'applicazione include uno strumento rappresentato come un'area rettangolare e le dimensioni o la posizione del controllo cambiano, l'applicazione può utilizzare il messaggio TTM_NEWTOOLRECT per segnalare la modifica al controllo descrizione comando. Un'applicazione non deve segnalare le modifiche di dimensioni e posizione per uno strumento implementato come finestra perché il controllo descrizione comando usa l'handle della finestra dello strumento per determinare se il puntatore del mouse si trova sullo strumento, non il rettangolo di delimitazione dello strumento.

Quando una descrizione comando sta per essere visualizzata, il controllo descrizione comando invia alla finestra proprietaria un codice di notifica TTN_SHOW. La finestra di proprietà riceve un codice di notifica TTN_POP quando una descrizione comando sta per essere nascosta. Ogni codice di notifica viene inviato nel contesto di un messaggio di WM_NOTIFY.

Il messaggio TTM_HITTEST consente di recuperare informazioni gestite da un controllo descrizione comando sullo strumento che occupa un determinato punto. Il messaggio include una struttura TTHITTESTINFO che contiene un handle di finestra, le coordinate di un punto e l'indirizzo di una struttura TOOLINFO. Il controllo tooltip determina se uno strumento occupa il punto e, in caso affermativo, riempie TOOLINFO con informazioni sullo strumento.

Nella tabella seguente vengono descritti i messaggi gestiti dalla procedura della finestra per il controllo tooltip.