Informazioni sui controlli descrizione comando

Le descrizioni comando vengono visualizzate automaticamente o popup quando l'utente sospende il puntatore del mouse su uno strumento o su un 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, verrà visualizzata anche una descrizione comando in tempo reale contenente testo descrittivo.

Questa sezione descrive il funzionamento dei controlli della descrizione comando e il modo in cui vengono creati.

• Comportamento e aspetto della descrizione comando
• Creazione di controlli descrizione comando
• Attivazione dei controlli descrizione comando
• Strumenti di supporto
• Visualizzazione del testo
• Messaggistica e notifica
• Hit Testing
• Elaborazione dei messaggi predefinita

Comportamento e aspetto della descrizione comando

I controlli descrizione comando 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 un fumetto di cartone animato. Il testo della descrizione comando può essere stazionario o può spostarsi con il puntatore del mouse, detto rilevamento. 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 quadrati e non hanno stelo che punta allo strumento.

Tenere traccia delle descrizioni comando supportate dalla versione 4.70 dei controlli comuni, modificare la posizione sullo schermo in modo dinamico. Aggiornando rapidamente la posizione, questi controlli descrizione comando sembrano spostarsi senza problemi o "traccia". Questi sono utili quando si desidera che il testo della descrizione comando segua la posizione del puntatore del mouse mentre si sposta. Per altre informazioni sul rilevamento delle descrizioni comando e un esempio con codice che mostra come crearli, vedere Rilevamento delle descrizioni comando.

Le descrizioni comando su più righe, supportate anche dalla versione 4.70 dei controlli comuni, visualizzano testo su più righe. Sono utili per la visualizzazione di messaggi lunghi. Per altre informazioni e un esempio che illustra 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 comando balloon con il gambo e il rettangolo nelle posizioni predefinite. Per altre informazioni sulle descrizioni comandi di balloon e un esempio che illustra come crearli, vedere Uso dei controlli descrizione comando.

Una descrizione comando può anche avere testo del 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 vengono usate per visualizzare stringhe di testo per gli oggetti ritagliati, ad esempio il nome del file nella figura seguente. Per un esempio che mostra come creare descrizioni comando sul posto, vedere Descrizioni comando sul posto.

Il cursore deve passare il puntatore del mouse 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 il controllo della descrizione comando a un messaggio TTM_edizione Standard TDELAYTIME.

Creazione di controlli descrizione comando

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 funzione InitCommonControlsEx 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 descrizione comando 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 di dispositivo per il controllo descrizione comando. La larghezza varia in base alla lunghezza della stringa attualmente presente nella finestra della descrizione comando.

Attivazione dei controlli descrizione comando

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

Strumenti di supporto

Un controllo descrizione comando può supportare un numero qualsiasi di strumenti. Per supportare uno strumento specifico, è necessario registrare lo strumento con il controllo descrizione comando inviando il controllo il messaggio TTM_ADDTOOL. Il messaggio include l'indirizzo di una struttura TOOLINFO , che fornisce informazioni che il controllo descrizione comando deve 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 è obbligatorio e deve specificare le dimensioni della struttura.

Un controllo descrizione comando 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 per la 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 allo strumento. Inoltre, il membro uFlags deve specificare il valore TTF_IDISHWND , che indica al controllo descrizione comando di interpretare il membro uID come handle di finestra.

Visualizzazione del testo

Quando si aggiunge uno strumento a un controllo descrizione comando, 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 di TTM_UPDATETIPTEXT.

Se la parola di ordine elevato di lpszText è zero, la parola con ordine basso deve essere l'identificatore di una risorsa 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 descrizione comando notifica la finestra specificata nel membro hwnd della struttura TOOLINFOogni volta che il controllo descrizione comando 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 struttura NMTTDISPINFO , che contiene l'handle della finestra e l'identificatore definito dall'applicazione per lo strumento. La finestra esamina la struttura per determinare lo strumento per il quale è necessario il testo e riempie i membri della struttura appropriati con 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, è utile per il controllo descrizione comando visualizzare lo stesso testo della voce di menu corrispondente. Il sistema rimuove automaticamente i caratteri dell'acceleratore e commerciale (&) 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.

Messaggistica e notifica

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 puntatore, non il controllo descrizione comando stesso. Le informazioni relative al mouse devono essere inoltrate al controllo descrizione comando per visualizzare il testo della descrizione comando nel momento e nella posizione appropriati.

È 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 TTF_SUBCLASS nel membro uFlags della struttura TOOLINFO dello strumento quando si aggiunge lo strumento al controllo descrizione comando con TTM_ADDTOOL. I messaggi del mouse necessari verranno quindi inoltrati automaticamente al controllo descrizione comando.

L'impostazione di TTF_SUBCLASS in modo che i messaggi del mouse inoltrati al controllo siano sufficienti 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 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 Rilevamento delle descrizioni comando.

Quando un controllo descrizione comando riceve un messaggio WM_MOUedizione Standard MOVE, 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 descrizione comando recupera il testo per lo strumento e visualizza la descrizione comando. Il controllo descrizione comando continua a visualizzare la finestra fino a quando non riceve un messaggio di spostamento verso l'alto o il pulsante verso il basso del pulsante o fino a quando un messaggio WM_MOUedizione Standard MOVE indica che il puntatore è stato spostato all'esterno del rettangolo di delimitazione dello strumento.

Un controllo descrizione comando 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 della visualizzazione è la lunghezza del ritardo prima che vengano visualizzate le finestre di descrizione comando successive quando il puntatore passa da uno strumento a un altro. La durata popup è l'ora in cui la finestra della descrizione comando rimane visualizzata prima che venga 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_edizione Standard TDELAYTIME.

Se un'applicazione include uno strumento implementato come area rettangolare e le dimensioni o la posizione del controllo cambia, l'applicazione può usare 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 del proprietario un codice di notifica TTN_SHOW . La finestra del proprietario 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 .

Hit Testing

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 descrizione comando determina se uno strumento occupa il punto e, in caso affermativo, riempie TOOLINFO con informazioni sullo strumento.

Elaborazione dei messaggi predefinita

Nella tabella seguente vengono descritti i messaggi gestiti dalla routine della finestra per il controllo descrizione comando.