Metodo ITaskbarList3::SetProgressState (shobjidl_core.h)

Articolo
08/26/2023

Imposta il tipo e lo stato dell'indicatore di stato visualizzato su un pulsante della barra delle applicazioni.

Sintassi

HRESULT SetProgressState(
  [in] HWND    hwnd,
  [in] TBPFLAG tbpFlags
);

Parametri

[in] hwnd

Tipo: HWND

Handle della finestra in cui viene visualizzato lo stato di avanzamento di un'operazione. Il pulsante della barra delle applicazioni associato alla finestra visualizzerà la barra di stato.

[in] tbpFlags

Tipo: TBPFLAG

Contrassegna che controlla lo stato corrente del pulsante di avanzamento. Specificare solo uno dei flag seguenti; tutti gli stati si escludono reciprocamente di tutti gli altri.

TBPF_NOPROGRESS (0x00000000)

Arresta la visualizzazione dello stato di avanzamento e restituisce il pulsante allo stato normale. Chiamare questo metodo con questo flag per ignorare la barra di stato quando l'operazione viene completata o annullata.

TBPF_INDETERMINATE (0x00000001)

L'indicatore di stato non aumenta di dimensioni, ma cicli ripetutamente lungo la lunghezza del pulsante della barra delle applicazioni. Ciò indica l'attività senza specificare la percentuale di avanzamento completata. Lo stato di avanzamento è in corso, ma non esiste alcuna stima per quanto tempo richiederà l'operazione.

TBPF_NORMAL (0x00000002)

L'indicatore di avanzamento aumenta di dimensioni da sinistra a destra in proporzione alla quantità stimata dell'operazione completata. Si tratta di un indicatore di stato determinato; viene eseguita una stima in base alla durata dell'operazione.

TBPF_ERROR (0x00000004)

L'indicatore di stato diventa rosso per mostrare che si è verificato un errore in una delle finestre in cui viene trasmesso lo stato di avanzamento. Questo è uno stato determinato. Se l'indicatore di stato si trova nello stato indeterminato, passa a una visualizzazione rossa determinata di una percentuale generica non indicativa dello stato effettivo.

TBPF_PAUSED (0x00000008)

L'indicatore di stato diventa giallo per mostrare che lo stato di avanzamento è attualmente arrestato in una delle finestre, ma può essere ripreso dall'utente. Nessuna condizione di errore esiste e nulla impedisce che lo stato di avanzamento continui. Questo è uno stato determinato. Se l'indicatore di stato si trova nello stato indeterminato, passa a una visualizzazione gialla determinata di una percentuale generica non indicativa dello stato effettivo.

Valore restituito

Tipo: HRESULT

Se questo metodo ha esito positivo, restituisce S_OK. In caso contrario, restituisce un codice di errore HRESULT .

Commenti

Le informazioni sulla barra di avanzamento non vengono visualizzate nelle combinazioni di colori a contrasto elevato per garantire che non vengano compromesse le esigenze di accessibilità.

Gli sviluppatori abituati al controllo barra di stato esistente devono trovare l'indicatore di stato del pulsante della barra delle applicazioni per essere un'esperienza simile sia nei concetti che negli oggetti visivi. In questo caso, il pulsante della barra delle applicazioni diventa una barra di avanzamento. Un indicatore di stato della barra delle applicazioni deve essere un riflesso di una barra di avanzamento più dettagliata nella finestra associata. Ciò consente all'utente di visualizzare specifiche, ad esempio il numero percentuale e la quantità di tempo rimanente, che non possono essere visualizzate in un pulsante della barra delle applicazioni. Inoltre, poiché un pulsante della barra delle applicazioni può visualizzare lo stato di avanzamento solo di una singola finestra in un gruppo, consente all'utente di controllare lo stato di avanzamento di singole finestre. Fornisce anche informazioni sullo stato dell'utente quando il pulsante della barra delle applicazioni non può, ad esempio in una combinazione di colori a contrasto elevato.

Si noti che una barra di stato del pulsante della barra delle applicazioni non è destinata all'uso con azioni normalmente periferiche, ad esempio il caricamento di una pagina Web o la stampa di un documento. Tale tipo di stato deve continuare a essere visualizzato nella barra di stato di una finestra.

L'indicatore di stato viene visualizzato tra l'icona o il testo del pulsante della barra delle applicazioni e lo sfondo. Se lo stato viene visualizzato sia per il pulsante della barra delle applicazioni attiva che per un pulsante inattivo, l'ombreggiatura nelle rispettive barre di stato è tale che il pulsante attivo sia ancora ovvio per l'utente. Inoltre, la funzionalità del pulsante, ad esempio la visualizzazione delle anteprime, continua a funzionare normalmente quando il pulsante viene usato per visualizzare lo stato di avanzamento.

Quando si chiude un errore o uno stato sospeso, chiamare di nuovo questo metodo con il flag TBPF_NORMAL o TBPF_INDETERMINATE per continuare nello stato originale o TBPF_NOPROGRESS se l'operazione viene annullata.

Come il pulsante barra delle applicazioni sceglie l'indicatore di stato per un gruppo

Il pulsante della barra delle applicazioni può visualizzare un indicatore di stato per una sola finestra alla volta. Ciò include la situazione in cui il pulsante della barra delle applicazioni rappresenta un gruppo e più finestre di tale gruppo trasmetteno informazioni sullo stato di avanzamento. In tal caso, il pulsante della barra delle applicazioni sceglie la visualizzazione dello stato in base alla priorità dello stato. La priorità dello stato viene visualizzata nella tabella seguente con priorità 1 che è la più alta.

Priorità	State
1	TBPF_ERROR
2	TBPF_PAUSED
3	TBPF_NORMAL
4	TBPF_INDETERMINATE

La modifica dello stato di una finestra cambia la priorità rispetto ad altre finestre del gruppo che a sua volta potrebbe modificare quale finestra in un gruppo viene usata per l'indicatore di stato nel pulsante della barra delle applicazioni.

Nel caso di una collisione con priorità tra due finestre che trasmettono lo stato di avanzamento determinato, viene usata la finestra con il minimo stato di avanzamento.

In base a questa priorità, l'indicatore di stato indeterminato può essere visualizzato nel pulsante della barra delle applicazioni solo in questi casi:

Il pulsante della barra delle applicazioni non rappresenta un gruppo e la singola finestra che rappresenta ha impostato TBPF_INDETERMINATE.
Il pulsante della barra delle applicazioni rappresenta un gruppo, una sola finestra del gruppo sta trasmettendo informazioni sullo stato di avanzamento e tale finestra ha impostato TBPF_INDETERMINATE.
Il pulsante della barra delle applicazioni rappresenta un gruppo, più finestre in tale gruppo stanno trasmettendo informazioni sullo stato di avanzamento e tutte queste finestre hanno impostato TBPF_INDETERMINATE.

Un indicatore di stato determinato può essere visualizzato in questi casi:

Il pulsante della barra delle applicazioni non rappresenta un gruppo e la singola finestra che rappresenta sta trasmettendo informazioni di stato determinate.
Il pulsante della barra delle applicazioni rappresenta un gruppo, una sola finestra di tale gruppo trasmette informazioni sullo stato di avanzamento e tale finestra trasmette informazioni di stato determinate.
Il pulsante della barra delle applicazioni rappresenta un gruppo, più finestre in tale gruppo stanno trasmettendo informazioni sullo stato di avanzamento, almeno una di queste finestre trasmette informazioni di stato determinate e nessuna finestra ha impostato TBPF_ERROR o TBPF_PAUSED.

Si noti che una chiamata a SetProgressValue cambierà un indicatore di stato attualmente in modalità indeterminato (TBPF_INDETERMINATE) a una visualizzazione normale (determinata) e deselezionare il flag di TBPF_INDETERMINATE .

Requisiti


Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shobjidl_core.h (include Shobjidl.h)
Libreria	Explorerframe.lib
DLL	Explorerframe.dll