Metodo IUIFramework::Initialize (uiribbon.h)

Articolo
03/03/2024

Connette l'applicazione host al framework della barra multifunzione di Windows.

Sintassi

HRESULT Initialize(
  [in] HWND           frameWnd,
  [in] IUIApplication *application
);

Parametri

[in] frameWnd

Tipo: HWND

Gestire la finestra di primo livello che conterrà la barra multifunzione.

[in] application

Tipo: IUIApplication*

Puntatore all'implementazione IUIApplication dell'applicazione host.

Valore restituito

Tipo: HRESULT

Restituisce S_OK se ha esito positivo; in caso contrario, un valore di errore dall'elenco seguente.

Valore	Descrizione
HRESULT_FROM_WIN32(ERROR_INVALID_WINDOW_HANDLE)	frameWnd è NULL, non punta a una finestra esistente o non è una finestra di primo livello del desktop. Nota Questo errore viene restituito anche se frameWnd è una finestra figlio (WS_CHILD), viene dichiarata come finestra degli strumenti (WS_EX_TOOLWINDOW) o manca una proprietà didascalia (WS_CAPTION è obbligatoria).
HRESULT_FROM_WIN32(ERROR_WINDOW_OF_OTHER_THREAD)	frameWnd non è di proprietà del thread di esecuzione.
E_POINTER	l'applicazione è NULL o un puntatore non valido.

Commenti

Questo metodo deve essere chiamato dall'applicazione host per ogni finestra di primo livello che richiede una barra multifunzione.

Questo metodo viene usato per configurare gli hook che consentono al framework della barra multifunzione di richiamare i callback nell'applicazione host.

Per inizializzare correttamente la barra multifunzione, un file di markup della barra multifunzione compilato deve essere disponibile come risorsa e specificato in una chiamata successiva a IUIFramework::LoadUI. Questo file di markup è un componente integrale del framework; specifica i controlli da usare e il relativo layout.

Se IUIFramework::Initialize restituisce correttamente:

Per eliminare incoerenze, ridondanza e incompatibilità tra la barra multifunzione e i modelli di comando tradizionali, il framework della barra multifunzione rimuove la barra dei menu standard della finestra di primo livello nell'applicazione host.
Il framework rimuove i riferimenti allo stile WS_EX_CLIENTEDGE.
Nota Lo stile WS_EX_CLIENTEDGE specifica che una finestra ha un bordo con un bordo affondato. Questo stile interferisce visivamente con l'integrazione della barra multifunzione e dell'applicazione host.
Il framework richiede che lo stile WS_SYSMENU sia abilitato. Se WS_SYSMENU non è abilitato, il framework non fornisce funzionalità alternative e il rendering imprevedibile della barra multifunzione può causare.
Nota Lo stile WS_SYSMENU specifica che la finestra dell'applicazione ha un menu di sistema sulla barra del titolo. Per associazione, lo stile WS_CAPTION deve essere specificato anche (vedere ERROR_INVALID_WINDOW_HANDLE in Valori restituiti in precedenza).

Esempio

Nell'esempio seguente viene illustrata una funzione di inizializzazione del framework di base.

//
//  FUNCTION:    InitializeFramework(HWND)
//
//  PURPOSE:    Initialize the Ribbon framework and bind a Ribbon to the application.
//
//  PARAMETERS:    
//                hWnd - Handle to the Ribbon host application window. 
//
//  COMMENTS:
//
//    In order to get a Ribbon to display, the Ribbon framework must be initialized. 
//    This involves three important steps:
//      1) Instantiate the Ribbon framework object (CLSID_UIRibbonFramework).
//      2) Pass the host HWND and IUIApplication object to the framework.
//      3) Load the binary markup compiled by the UI Command Compiler (UICC.exe).
//
//
bool InitializeFramework(HWND hWnd)
{
    // Instantiate the Ribbon framework object.
    HRESULT hr = CoCreateInstance(
        CLSID_UIRibbonFramework, 
        NULL, 
        CLSCTX_INPROC_SERVER, 
        IID_PPV_ARGS(&g_pFramework));
    if (!SUCCEEDED(hr))
    {
        return false;
    }    

    // Create the application object (IUIApplication) and call the 
    // framework Initialize method, passing the application object and the 
    // host HWND that the Ribbon will attach itself to.
    CComObject<CApplication> *pApplication = NULL;
    CComObject<CApplication>::CreateInstance(&pApplication);
    hr = pApplication->QueryInterface(&g_pApplication);
    if (!SUCCEEDED(hr))
    {
        return false;
    } 

    hr = g_pFramework->Initialize(hWnd, g_pApplication);
    if (!SUCCEEDED(hr))
    {
        return false;
    }

    // Load the binary markup.  
    // Initiate callbacks to the IUIApplication object that was 
    // provided to the framework earlier and bind command handler(s) 
    // to individual commands.
    hr = g_pFramework->LoadUI(GetModuleHandle(NULL), L"APPLICATION_RIBBON");
    if (!SUCCEEDED(hr))
    {
        return false;
    }
    return true;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [solo app desktop]
Server minimo supportato	Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	uiribbon.h
DLL	Mshtml.dll