Método IUIFramework::Initialize (uiribbon.h)

Artículo
03/13/2024

Conecta la aplicación host al marco de la cinta de Windows.

Sintaxis

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

Parámetros

[in] frameWnd

Tipo: HWND

Identificador de la ventana de nivel superior que contendrá la cinta de opciones.

[in] application

Tipo: IUIApplication*

Puntero a la implementación IUIApplication de la aplicación host.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente; de lo contrario, un valor de error de la lista siguiente.

Valor	Descripción
HRESULT_FROM_WIN32(ERROR_INVALID_WINDOW_HANDLE)	frameWnd es NULL, no apunta a una ventana existente o no es una ventana de nivel superior del escritorio. Nota Este error también se devuelve si frameWnd es una ventana secundaria (WS_CHILD), se declara como una ventana de herramientas (WS_EX_TOOLWINDOW) o carece de una propiedad subtítulo (WS_CAPTION es obligatoria).
HRESULT_FROM_WIN32(ERROR_WINDOW_OF_OTHER_THREAD)	frameWnd no es propiedad del subproceso de ejecución.
E_POINTER	la aplicación es NULL o un puntero no válido.

Comentarios

La aplicación host debe llamar a este método para cada ventana de nivel superior que requiera una cinta de opciones.

Este método se usa para configurar los enlaces que permiten que el marco de la cinta de opciones invoque devoluciones de llamada en la aplicación host.

Para inicializar correctamente la cinta de opciones, un archivo de marcado de cinta compilado debe estar disponible como un recurso y se especifica en una llamada posterior a IUIFramework::LoadUI. Este archivo de marcado es un componente integral del marco; especifica los controles que se van a usar y su diseño.

Si IUIFramework::Initialize devuelve correctamente:

Para eliminar la incoherencia, la redundancia y la incompatibilidad entre la cinta de opciones y los modelos de comandos tradicionales, el marco de la cinta de opciones quita la barra de menús estándar de la ventana de nivel superior de la aplicación host.
El marco quita las referencias al estilo WS_EX_CLIENTEDGE.
Nota El estilo WS_EX_CLIENTEDGE especifica que una ventana tiene un borde con un borde hundido. Este estilo interfiere visualmente con la integración de la cinta de opciones y la aplicación host.
El marco requiere que se habilite el estilo WS_SYSMENU. Si WS_SYSMENU no está habilitado, el marco no proporciona funcionalidad alternativa ni representación impredecible de la cinta de opciones.
Nota El estilo WS_SYSMENU especifica que la ventana de la aplicación tiene un menú del sistema en su barra de título. Por asociación, también se debe especificar el estilo WS_CAPTION (vea ERROR_INVALID_WINDOW_HANDLE en Valores devueltos arriba).

Ejemplos

En el ejemplo siguiente se muestra una función básica de inicialización del marco.

//
//  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;
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	uiribbon.h
Archivo DLL	Mshtml.dll