IUIFramework

IUIFramework インターフェイスは Windows リボン フレームワークによって実装され、フレームワークの中核機能を提供するメソッドを定義します。

このインターフェイスは、リボン フレームワークの初期化と破棄に使用します。

リボン フレームワークの UI 機能は View によって区別されます。View とは、本質的には Ribbon や ContextPopup といった、組み込みのコア コントロールです。

IUIFramework の実装へのインターフェイス ポインターを取得するには、CoCreateInstance を使用して、クラス識別子 (CLSID) が CLSID_UIRibbonFramework の COM オブジェクトを作成します。

ホスト アプリケーションを Windows リボン フレームワークに接続します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、次の一覧のエラー値を返します。

このメソッドは、リボンを必要とするトップレベル ウィンドウごとに、ホスト アプリケーションから呼び出す必要があります。

このメソッドは、リボン フレームワークがホスト アプリケーション内のコールバックを呼び出せるようにするためのフックを設定するために使用されます。

リボンを正しく初期化するには、コンパイル済みのリボン マークアップ ファイルがリソースとして利用可能であり、後続の 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 リボン フレームワークのインスタンスに関するすべてのオブジェクト、フック、参照を終了して解放します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

このメソッドは、IUIFramework のインスタンスごとに 1 回呼び出す必要があります。

IUIFramework::Initialize を呼び出した場合は、リソースを解放してフレームワークを適切に破棄するために、IUIFramework::Destroy を呼び出す必要があります。IUIFramework::Destroy を呼び出さないと、メモリ リークが発生する可能性があります。

Windows リボン フレームワークの UI リソース ファイル (コンパイル済みマークアップ) を読み込みます。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

IUIFramework::LoadUI は初期化時に呼び出す必要があります。このメソッドは、間に IUIFramework::Destroy の呼び出しを挟むことを条件として、アプリケーションのライフサイクル中に複数回呼び出すことができます (たとえば、リボンの表示や非表示を切り替える場合)。

OnCreateUICommand と OnViewChanged は、IUIFramework::LoadUI の実行中に呼び出されます。

例

次の例は、基本的なフレームワーク初期化関数を示しています。

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

IUIRibbon や IUIContextualUI など、Windows リボン フレームワークの View を表すインターフェイスへのポインターのアドレスを取得します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、次の一覧のエラー値を返します。

リボン フレームワークの UI 機能は View によって区別されます。View とは、本質的には Ribbon や ContextPopup といった、組み込みのコア フレームワークです。

アプリケーションの存続期間を通じてインターフェイスへのポインターを保持するのではなく、IUIFramework::GetView を使用することで、ホスト アプリケーションは一時的なインターフェイス ポインターを作成し、必要に応じてメソッドを呼び出すことができます。

例

次の例は、IUIFramework::GetView メソッドを使用して Ribbon View オブジェクトを取得し、GetHeight メソッドを呼び出してリボンの高さを取得し、その高さに基づいて Context Popup コントロールの表示位置を計算する方法を示しています。

void GetDisplayLocation(POINT &pt, HWND hWnd)
{
  if (pt.x == -1 && pt.y == -1)
  {
    HRESULT hr = E_FAIL;

    // Display the menu in the upper-left corner of the client area, below the ribbon.
    IUIRibbon* pRibbon;
    hr = g_pFramework->GetView(0, IID_PPV_ARGS(&pRibbon));
    if (SUCCEEDED(hr))
    {
      UINT32 uRibbonHeight = 0;
      hr = pRibbon->GetHeight(&uRibbonHeight);
      if (SUCCEEDED(hr))
      {
        pt.x = 0;
        pt.y = uRibbonHeight;
        // Convert client coordinates of a specified point to screen coordinates.
        ClientToScreen(hWnd, &pt);
      }
      pRibbon->Release();
    }
    if (FAILED(hr))
    {
      // Default to just the upper-right corner of the entire screen.
      pt.x = 0;
      pt.y = 0;
    }
  }
}

コマンドのプロパティ、値、または状態を取得します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、次の一覧のエラー値を返します。

            </td>

コマンドのプロパティ、値、または状態を設定します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、次の一覧のエラー値を返します。

IUIFramework::SetUICommandProperty で設定できるプロパティ キーは限られています。IUIFramework::SetUICommandProperty が HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED) を返すプロパティについては、代わりに IUIFramework::InvalidateUICommand を使用してください。

特定のコントロールに対してプロパティ キーを設定する方法の詳細については、そのコントロールの Windows Ribbon Framework Control Library のページを参照してください。

Windows リボン フレームワークのコマンドのプロパティ、値、または状態を無効化します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、次の一覧のエラー値を返します。

リボン フレームワークのマークアップで定義されたリソースは、マークアップ ファイルがバイナリ形式にコンパイルされるときに作成されるリソース テーブルに格納されます。リソースはいったん無効化されると、マークアップ リソース テーブルから復元することはできません。

無効化の後、フレームワークはホスト アプリケーションにリソースの詳細を問い合わせます。

コマンドの値が無効化される場合 (flags に UI_INVALIDATIONS_VALUE が含まれる場合)、key の値は NULL になります。

IUIFramework::InvalidateUICommand が複数回呼び出され、各呼び出しで渡される UI_INVALIDATIONS の値が UI_INVALIDATIONS_STATE と UI_INVALIDATIONS_ALLPROPERTIES のように重複するプロパティを指定している場合、ホスト アプリケーションへのコールバックは 1 回だけ生成されます。

保留中のすべてのコマンド更新を処理します。

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合はエラー値を返します。

有効にするアプリケーション モードを指定します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラー コードを返します。

モードは、必要な機能を示すものであり、したがってアプリケーションの状態やコンテキストに応じて、実行時にどの要素を表示 (または非表示に) すべきかを示します。たとえば、ネットワーク接続はアプリケーションの機能に直接影響する可能性があり、接続が検出されたときにネットワーク関連のコマンドから成る "ネットワーク" モードが必要になることがあります。

モードはリボン マークアップ内の要素に対して指定され、実行時に個々のコントロールにバインドされます。

モードはリボンの Tab および Group に適用できます。