Come implementare l'interfaccia IContextMenu

IContextMenu è l'interfaccia più potente ma anche più complessa da implementare. È consigliabile implementare un verbo usando uno dei metodi del verbo statico. Per altre informazioni, vedere Scelta di un metodo di menu di scelta rapida statico o dinamico. IContextMenu ha tre metodi, GetCommandString, InvokeCommande QueryContextMenu, descritti in dettaglio.

Cosa è necessario sapere

Tecnologie

Prerequisiti

Verbo statico
Menu di scelta rapida

Disposizioni

Metodo IContextMenu::GetCommandString

Il metodo IContextMenu::GetCommandString del gestore viene usato per restituire il nome canonico per un verbo. Questo metodo è facoltativo. In Windows XP e nelle versioni precedenti di Windows, quando Esplora risorse dispone di una barra di stato, questo metodo si usa per recuperare il testo della Guida visualizzato nella barra di stato per una voce di menu.

Il parametro idCmd contiene l'offset dell'identificatore del comando che è stato definito quando è stato chiamato IContextMenu::QueryContextMenu. Se viene richiesta una stringa di aiuto, uFlags verrà impostato su GCS_HELPTEXTW. Copiare la stringa di aiuto nel buffer pszName, eseguendo il cast in un PWSTR. La richiesta della stringa del verbo avviene impostando uFlags su GCS_VERBW. Copiare la stringa appropriata in pszName, esattamente come nella stringa di aiuto. I flag GCS_VALIDATEA e GCS_VALIDATEW non vengono usati dai gestori di menu di scelta rapida.

Nell'esempio seguente viene illustrata una semplice implementazione di GetCommandString che corrisponde all'esempio QueryContextMenu illustrato nella sezione Metodo IContextMenu::QueryContextMenu di questo argomento. Poiché il gestore aggiunge una sola voce di menu, è possibile restituire un solo set di stringhe. Il metodo verifica se idCmd è valido e, in caso affermativo, restituisce la stringa richiesta.

La funzioneStringCchCopyviene usata per copiare la stringa richiesta in pszName per assicurarsi che la stringa copiata non superi le dimensioni del buffer specificato da cchName. Questo esempio implementa il supporto solo per i valori Unicode di uFlags, perché solo quelli sono stati usati in Esplora risorse a partire da Windows 2000.

IFACEMETHODIMP CMenuExtension::GetCommandString(UINT idCommand, 
                                                UINT uFlags, 
                                                UINT *pReserved, 
                                                PSTR pszName, 
                                                UINT cchName)
{
    HRESULT hr = E_INVALIDARG;

    if (idCommand == IDM_DISPLAY)
    {
        switch (uFlags)
        {
            case GCS_HELPTEXTW:
                // Only useful for pre-Vista versions of Windows that 
                // have a Status bar.
                hr = StringCchCopyW(reinterpret_cast<PWSTR>(pszName), 
                                    cchName, 
                                    L"Display File Name");
                break; 

            case GCS_VERBW:
                // GCS_VERBW is an optional feature that enables a caller
                // to discover the canonical name for the verb that is passed in
                // through idCommand.
                hr = StringCchCopyW(reinterpret_cast<PWSTR>(pszName), 
                                    cchName, 
                                    L"DisplayFileName");
                break; 
        }
    }
    return hr;
}

Metodo IContextMenu::InvokeCommand

Questo metodo viene chiamato quando un utente fa clic su una voce di menu per indicare al gestore di eseguire il comando associato. Il pici parametro punta a una struttura contenente le informazioni necessarie per eseguire il comando.

Sebbene pici sia dichiarato in Shlobj.h come una struttura CMINVOKECOMMANDINFO, in pratica spesso fa riferimento a una struttura CMINVOKECOMMANDINFOEX. Questa struttura è una versione estesa di CMINVOKECOMMANDINFO e include diversi membri aggiuntivi che consentono di passare stringhe Unicode.

Controllare il membro cbSize di pici per determinare quale struttura è stata passata. Se è una strutturaCMINVOKECOMMANDINFOEXe il membro fMask ha impostato il flag CMIC_MASK_UNICODE, effettuare il cast di pici a CMINVOKECOMMANDINFOEX. In questo modo l'applicazione può usare le informazioni Unicode contenute negli ultimi cinque membri della struttura.

Per identificare il comando da eseguire si utilizza il membro lpVerb o lpVerbW. I comandi vengono identificati in uno dei due modi seguenti:

In base alla stringa del verbo del comando
In base all'offset dell'identificatore di comando

Per distinguere tra questi due casi, controllare la parola di ordine elevato di lpVerb per il caso ANSI o lpVerbW per il caso Unicode. Se la parola di ordine elevato è diversa da zero, lpVerb o lpVerbW contiene una stringa verbo. Se la parola di ordine elevato è zero, l'offset del comando si trova nella parola in ordine basso di lpVerb.

Nell'esempio seguente viene illustrata una semplice implementazione di IContextMenu::InvokeCommand che corrisponde all'IContextMenu::QueryContextMenu e IContextMenu::GetCommandString esempi specificati prima e dopo questa sezione. Il metodo prima determina quale struttura viene passata. Determina quindi se il comando viene identificato dall'offset o dal relativo verbo. Se lpVerb o lpVerbW contiene un verbo o un offset valido, il metodo visualizza una finestra di messaggio.

STDMETHODIMP CShellExtension::InvokeCommand(LPCMINVOKECOMMANDINFO lpcmi)
{
    BOOL fEx = FALSE;
    BOOL fUnicode = FALSE;

    if(lpcmi->cbSize == sizeof(CMINVOKECOMMANDINFOEX))
    {
        fEx = TRUE;
        if((lpcmi->fMask & CMIC_MASK_UNICODE))
        {
            fUnicode = TRUE;
        }
    }

    if( !fUnicode && HIWORD(lpcmi->lpVerb))
    {
        if(StrCmpIA(lpcmi->lpVerb, m_pszVerb))
        {
            return E_FAIL;
        }
    }

    else if( fUnicode && HIWORD(((CMINVOKECOMMANDINFOEX *) lpcmi)->lpVerbW))
    {
        if(StrCmpIW(((CMINVOKECOMMANDINFOEX *)lpcmi)->lpVerbW, m_pwszVerb))
        {
            return E_FAIL;
        }
    }

    else if(LOWORD(lpcmi->lpVerb) != IDM_DISPLAY)
    {
        return E_FAIL;
    }

    else
    {
        MessageBox(lpcmi->hwnd,
                   "The File Name",
                   "File Name",
                   MB_OK|MB_ICONINFORMATION);
    }

    return S_OK;
}

Metodo IContextMenu::QueryContextMenu

Shell chiama IContextMenu::QueryContextMenu per consentire al gestore di menu di scelta rapida di aggiungere le relative voci di menu al menu. Passa l'handle HMENU nel parametro hmenu. Il parametro indexMenu viene impostato sull'indice da utilizzare per la prima voce di menu da aggiungere.

Tutte le voci di menu aggiunte dal gestore devono avere identificatori che rientrano tra i valori nei parametri idCmdFirst e idCmdLast. In genere, il primo identificatore di comando è impostato su idCmdFirst, che viene incrementato di uno (1) per ogni comando aggiuntivo. Questa procedura consente di evitare di superare idCmdLast e massimizzare il numero di identificatori disponibili nel caso in cui shell chiami più di un gestore.

L'offset del comando di un identificatore di elemento è la differenza tra l'identificatore e il valore in idCmdFirst. Archiviare l'offset di ogni elemento aggiunto dal gestore al menu di scelta rapida, perché shell potrebbe usare l'offset per identificare l'elemento se successivamente chiama IContextMenu::GetCommandString o IContextMenu::InvokeCommand.

È anche necessario assegnare un verbo a ogni comando aggiunto. Un verbo è una stringa che può essere usata anziché l'offset per identificare il comando quando viene chiamato InvokeCommand. Viene usato anche da funzioni come ShellExecuteEx per eseguire i comandi di menu di scelta rapida.

Esistono tre flag che possono essere passati tramite il parametro uFlags rilevanti per i gestori di menu di scelta rapida. Sono descritte nella tabella seguente.

Bandiera	Descrizione
CMF_DEFAULTONLY	L'utente ha selezionato il comando predefinito, in genere facendo doppio clic sull'oggetto. IContextMenu::QueryContextMenu deve restituire il controllo alla shell senza modificare il menu.
CMF_NODEFAULT	Nessuna voce nel menu deve essere l'elemento predefinito. Il metodo deve aggiungere i comandi al menu.
CMF_NORMAL	Il menu di scelta rapida verrà visualizzato normalmente. Il metodo deve aggiungere i comandi al menu.

Utilizzare InsertMenu o InsertMenuItem per aggiungere voci di menu all'elenco. Restituire quindi un valore HRESULT con la gravità impostata su SEVERITY_SUCCESS. Impostare il valore del codice sull'offset dell'identificatore di comando più grande assegnato, aggiungendo uno (1). Si supponga, ad esempio, che idCmdFirst sia impostato su 5 e si aggiungono tre voci al menu con identificatori di comando 5, 7 e 8. Il valore restituito deve essere MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 + 1).

Nell'esempio seguente viene illustrata una semplice implementazione di QueryContextMenu che inserisce un singolo comando. L'offset dell'identificatore per il comando è IDM_DISPLAY, impostato su zero. Le variabili m_pszVerb e m_pwszVerb sono variabili private usate per archiviare la stringa verbo indipendente dal linguaggio associata in formati ANSI e Unicode.

#define IDM_DISPLAY 0

STDMETHODIMP CMenuExtension::QueryContextMenu(HMENU hMenu,
                                              UINT indexMenu,
                                              UINT idCmdFirst,
                                              UINT idCmdLast,
                                              UINT uFlags)
{
    HRESULT hr;
    
    if(!(CMF_DEFAULTONLY & uFlags))
    {
        InsertMenu(hMenu, 
                   indexMenu, 
                   MF_STRING | MF_BYPOSITION, 
                   idCmdFirst + IDM_DISPLAY, 
                   "&Display File Name");

    
        
        hr = StringCbCopyA(m_pszVerb, sizeof(m_pszVerb), "display");
        hr = StringCbCopyW(m_pwszVerb, sizeof(m_pwszVerb), L"display");

        return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(IDM_DISPLAY + 1));
    }

    return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(0));}

Osservazioni

Per altre attività di implementazione dei verbi, vedere Creazione di gestori di menu di scelta rapida.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-03-21