IUIFramework::Initialize 메서드(uiribbon.h)

아티클
03/03/2024

호스트 애플리케이션을 Windows 리본 프레임워크에 연결합니다.

구문

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

매개 변수

[in] frameWnd

형식: HWND

리본을 포함할 최상위 창에 대한 핸들입니다.

[in] application

형식: IUIApplication*

호스트 애플리케이션의 IUIApplication 구현에 대한 포인터입니다.

반환 값

형식: HRESULT

성공하면 S_OK 반환합니다. 그렇지 않으면 다음 목록의 오류 값입니다.

값	Description
HRESULT_FROM_WIN32(ERROR_INVALID_WINDOW_HANDLE)	frameWnd 는 NULL이거나, 기존 창을 가리키지 않거나, 데스크톱의 최상위 창이 아닙니다. 참고frameWnd가 자식 창(WS_CHILD)이거나 도구 창(WS_EX_TOOLWINDOW)으로 선언되거나 캡션 속성이 없는 경우에도 이 오류가 반환됩니다(WS_CAPTION 필수임).
HRESULT_FROM_WIN32(ERROR_WINDOW_OF_OTHER_THREAD)	frameWnd 는 실행 스레드가 소유하지 않습니다.
E_POINTER	애플리케이션 이 NULL 이거나 잘못된 포인터입니다.

설명

이 메서드는 리본이 필요한 각 최상위 창에 대해 호스트 애플리케이션에서 호출해야 합니다.

이 메서드는 리본 프레임워크가 호스트 애플리케이션에서 콜백을 호출할 수 있도록 하는 후크를 설정하는 데 사용됩니다.

리본을 성공적으로 초기화하려면 컴파일된 리본 태그 파일을 리소스로 사용할 수 있어야 하며 IUIFramework::LoadUI에 대한 후속 호출에서 지정해야 합니다. 이 태그 파일은 프레임워크의 필수 구성 요소입니다. 사용할 컨트롤과 해당 레이아웃을 지정합니다.

IUIFramework::Initialize가 성공적으로 반환되면 다음을 수행합니다.

리본과 기존 명령 모델 간의 불일치, 중복성 및 비호환성을 제거하기 위해 리본 프레임워크는 호스트 애플리케이션에서 최상위 창의 표준 메뉴 모음을 제거합니다.
프레임워크는 WS_EX_CLIENTEDGE 스타일에 대한 참조를 제거합니다.
참고 WS_EX_CLIENTEDGE 스타일은 창에 침몰한 가장자리가 있는 테두리가 있음을 지정합니다. 이 스타일은 리본 및 호스트 애플리케이션의 통합을 시각적으로 방해합니다.
프레임워크를 사용하려면 WS_SYSMENU 스타일을 사용하도록 설정해야 합니다. WS_SYSMENU 사용하도록 설정되지 않은 경우 프레임워크는 대체 기능을 제공하지 않으며 리본의 예기치 않은 렌더링이 발생할 수 있습니다.
참고 WS_SYSMENU 스타일은 애플리케이션 창의 제목 표시줄에 시스템 메뉴가 있음을 지정합니다. 연결별로 WS_CAPTION 스타일도 지정해야 합니다(위의 반환 값 에서 ERROR_INVALID_WINDOW_HANDLE 참조).

예제

다음 예제에서는 기본 프레임워크 초기화 함수를 보여 줍니다.

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

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	uiribbon.h
DLL	Mshtml.dll