리본 개체 모델 개요

Microsoft Visual Studio Tools for Office Runtime에서는 런타임에 리본 컨트롤의 속성을 가져오고 설정하는 데 사용할 수 있는 강력한 형식의 개체 모델을 노출합니다. 예를 들어 메뉴 컨트롤을 동적으로 채우거나, 컨트롤을 상황에 따라 표시하고 숨길 수 있습니다. 리본 메뉴에 탭, 그룹 및 컨트롤을 추가할 수도 있지만 Office 응용 프로그램에서 리본 메뉴를 로드하기 전에만 가능합니다. 자세한 내용은 읽기 전용이 되는 속성 설정을 참조하십시오.

적용 대상: 이 항목의 정보는 Excel 2007 및 Excel 2010, InfoPath 2007 및 InfoPath 2010, Outlook 2007 및 Outlook 2010, PowerPoint 2007 및 PowerPoint 2010, Project 2010, Visio 2010, Word 2007 및 Word 2010의 문서 수준 프로젝트 및 응용 프로그램 수준 프로젝트에 적용됩니다. 자세한 내용은 Office 응용 프로그램 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하십시오.

이 리본 개체 모델은 주로 리본 클래스, 리본 이벤트 및 리본 컨트롤 클래스로 구성됩니다.

리본 클래스

프로젝트에 새 리본(비주얼 디자이너) 항목을 추가하는 경우 Visual Studio에서는 프로젝트에 리본 클래스를 추가합니다. 프로젝트가 .NET Framework 4를 대상으로 하는 경우 리본 클래스는 RibbonBase 클래스에서 상속됩니다. 프로젝트가 .NET Framework 3.5를 대상으로 하는 경우 리본 클래스는 OfficeRibbon 클래스에서 상속합니다.

이 클래스는 리본 코드 파일과 리본 디자이너 코드 파일로 나뉘는 partial 클래스로 나타납니다.

리본 이벤트

리본 클래스에는 다음 세 개의 이벤트가 포함되어 있습니다.

.NET Framework 4를 대상으로 하는 프로젝트	.NET Framework 3.5를 대상으로 하는 프로젝트	설명
RibbonBase.Load	OfficeRibbon.Load	Office 응용 프로그램에서 리본 사용자 지정을 로드할 때 발생합니다. Load 이벤트 처리기는 리본 코드 파일에 자동으로 추가됩니다. 리본 메뉴가 로드될 때 이 이벤트 처리기를 사용하여 사용자 지정 코드를 실행합니다.
RibbonBase.LoadImage	OfficeRibbon.LoadImage	리본 메뉴가 로드될 때 리본 사용자 지정의 이미지를 캐시할 수 있도록 합니다. 이 이벤트 처리기에서 리본 이미지를 캐시하는 코드를 작성하면 성능이 약간 향상됩니다. 자세한 내용은 LoadImage를 참조하십시오.
RibbonBase.Close	OfficeRibbon.Close	리본 인스턴스가 닫힐 때 발생합니다.

리본 컨트롤

Microsoft.Office.Tools.Ribbon 네임스페이스에는 도구 상자의 Office 리본 컨트롤 그룹에 표시되는 각 컨트롤에 대한 형식이 포함되어 있습니다.

다음 표에서는 각 리본 컨트롤의 형식을 보여 줍니다. 각 컨트롤에 대한 설명은 리본 개요을 참조하십시오.

컨트롤 이름	클래스 이름
Box	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Gallery	RibbonGallery
Group	RibbonGroup
레이블	RibbonLabel
Menu	RibbonMenu
Separator	RibbonSeparator
SplitButton	RibbonSplitButton
Tab	RibbonTab
ToggleButton	RibbonToggleButton

Microsoft.Office.Tools.Ribbon 네임스페이스에서는 이러한 형식에 대해 "Ribbon" 접두사를 사용하여 System.Windows.Forms 네임스페이스에 있는 컨트롤 클래스와의 이름 충돌을 방지합니다.

리본 디자이너에 컨트롤을 추가하면 리본 디자이너에서 해당 컨트롤에 대한 클래스를 리본 디자이너 코드 파일의 필드로 선언합니다.

리본 컨트롤의 속성을 사용한 일반적인 작업

각 리본 컨트롤에는 컨트롤에 레이블을 할당하거나 컨트롤을 숨기고 표시하는 등의 다양한 작업을 수행하는 데 사용할 수 있는 속성이 포함되어 있습니다.

일부 경우에는 리본 메뉴가 로드되거나 동적 메뉴에 컨트롤이 추가된 후 속성이 읽기 전용이 됩니다. 자세한 내용은 읽기 전용이 되는 속성 설정을 참조하십시오.

다음 표에서는 리본 컨트롤 속성을 사용하여 수행할 수 있는 작업을 설명합니다.

작업	작업 방법
컨트롤을 숨기거나 표시합니다.	Visible 속성을 사용합니다.
컨트롤을 활성화하거나 비활성화합니다.	Enabled 속성을 사용합니다.
컨트롤 크기를 설정합니다.	ControlSize 속성을 사용합니다.
컨트롤에 나타나는 이미지를 가져옵니다.	Image 속성을 사용합니다.
컨트롤의 레이블을 변경합니다.	Label 속성을 사용합니다.
컨트롤에 사용자 정의 데이터를 추가합니다.	Tag 속성을 사용합니다.
RibbonBox, RibbonDropDown, RibbonGallery 또는 RibbonSplitButton 컨트롤의 항목을 가져옵니다.	Items 속성을 사용합니다.
RibbonComboBox, RibbonDropDown 또는 RibbonGallery 컨트롤에 항목을 추가합니다.	Items 속성을 사용합니다.
RibbonMenu에 컨트롤을 추가합니다.	Items 속성을 사용합니다. Office 응용 프로그램에 리본 메뉴가 로드된 후 RibbonMenu에 컨트롤을 추가하려면 Office 응용 프로그램에 리본 메뉴가 로드되기 전에 Dynamic 속성을 true로 설정해야 합니다. 자세한 내용은 읽기 전용이 되는 속성 설정을 참조하십시오.
RibbonComboBox, RibbonDropDown 또는 RibbonGallery의 선택된 항목을 가져옵니다.	SelectedItem 속성을 사용합니다. RibbonComboBox의 경우 Text 속성을 사용합니다.
RibbonTab의 그룹을 가져옵니다.	Groups 속성을 사용합니다.
RibbonGallery에 나타나는 행 및 열의 수를 지정합니다.	RowCount 및 ColumnCount 속성을 사용합니다.

읽기 전용이 되는 속성 설정

일부 속성은 리본 메뉴가 로드되기 전에만 설정할 수 있습니다. 이러한 속성은 다음 세 위치에서 설정할 수 있습니다.

• Visual Studio 속성 창

• 리본 클래스의 생성자

• 프로젝트에 사용된 ThisAddin, ThisWorkbook 또는 ThisDocument 클래스의 CreateRibbonExtensibilityObject 메서드

동적 메뉴는 몇 가지 예외를 제공합니다. 리본 메뉴가 로드된 후에도 런타임에 새 컨트롤을 만들고 해당 속성을 설정하고 이 컨트롤을 동적 메뉴에 추가할 수 있습니다.

동적 메뉴에 추가하는 컨트롤의 속성은 아무 때나 설정할 수 있습니다.

자세한 내용은 읽기 전용이 되는 속성 설정을 참조하십시오.

리본의 생성자에서 속성 설정

리본 클래스의 생성자에서 리본 컨트롤의 속성을 설정할 수 있습니다. 이 코드는 InitializeComponent 메서드를 호출한 후에 나타나야 합니다. 다음 예제에서는 현재 시간이 태평양 표준시(UTC-8) 17:00 이후인 경우에 그룹에 새 단추를 추가합니다.

.NET Framework 4을 대상으로 하는 프로젝트의 경우 다음 코드를 추가합니다.

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

.NET Framework 3.5를 대상으로 하는 프로젝트의 경우 다음 코드를 추가합니다.

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New()

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

Visual Studio 2008에서 업그레이드한 Visual C# 프로젝트의 경우 생성자는 리본 코드 파일에 나타납니다.

Visual Studio 2010에서 만든 Visual Basic 프로젝트 또는 Visual C# 프로젝트의 경우 생성자는 리본 디자이너 코드 파일에 나타납니다. 이 파일의 이름은 YourRibbonItem.Designer.cs 또는 YourRibbonItem.Designer.vb입니다. Visual Basic 프로젝트에서 이 파일을 보려면 먼저 솔루션 탐색기에서 모든 파일 표시 단추를 클릭해야 합니다.

CreateRibbonExtensibilityObject 메서드에서 속성 설정

프로젝트의 ThisAddin, ThisWorkbook 또는 ThisDocument 클래스에 포함된 CreateRibbonExtensibilityObject 메서드를 재정의할 경우 리본 컨트롤의 속성을 설정할 수 있습니다. CreateRibbonExtensibilityObject 메서드에 대한 자세한 내용은 리본 개요을 참조하십시오.

다음 예제에서는 Excel 통합 문서 프로젝트의 ThisWorkbook 클래스에 포함된 CreateRibbonExtensibilityObject 메서드에서 리본 속성을 설정합니다.

.NET Framework 4을 대상으로 하는 프로젝트의 경우 다음 코드를 추가합니다.

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

.NET Framework 3.5를 대상으로 하는 프로젝트의 경우 다음 코드를 추가합니다.

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

읽기 전용이 되는 속성

다음 표에서는 리본 메뉴가 로드되기 전에만 설정할 수 있는 속성을 보여 줍니다.

참고

동적 메뉴의 컨트롤 속성은 아무 때나 설정할 수 있습니다. 이러한 경우 다음 표의 내용이 적용되지 않습니다.

Property	리본 컨트롤 클래스
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
그룹	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Name	RibbonComponent
위치	RibbonButton RibbonCheckBox RibbonGallery RibbonGroup RibbonMenu RibbonSeparator RibbonSplitButton RibbonTab RibbonToggleButton
RibbonType	OfficeRibbon
RowCount	RibbonGallery
ShowItemImage	RibbonComboBox RibbonDropDown RibbonGallery
ShowItemLabel	RibbonDropDown RibbonGallery
ShowItemSelection	RibbonGallery
SizeString	RibbonComboBox RibbonDropDown RibbonEditBox
StartFromScratch	OfficeRibbon
탭	OfficeRibbon
제목	RibbonSeparator

Outlook 검사기에 나타나는 리본 메뉴의 속성 설정

리본 메뉴가 나타나는 검사기를 열 때마다 리본 메뉴의 새 인스턴스가 만들어집니다. 그러나 위의 표에 나열된 속성은 리본 메뉴의 첫 번째 인스턴스가 만들어지기 전에만 설정할 수 있습니다. 첫 번째 인스턴스가 만들어진 후에는 첫 번째 인스턴스가 Outlook에서 리본 메뉴를 로드하는 데 사용되는 XML 파일을 정의하므로 이러한 속성이 읽기 전용이 됩니다.

리본 메뉴의 다른 인스턴스가 만들어질 때 이러한 속성을 다른 값으로 설정하는 조건부 논리가 있는 경우 이 코드는 아무런 영향을 주지 않습니다.

참고

Outlook 리본 메뉴에 추가하는 각 컨트롤에 대해 Name 속성을 설정해야 합니다. 런타임에 Outlook 리본 메뉴에 컨트롤을 추가할 경우에는 코드에서 이 속성을 설정해야 합니다. 디자인 타임에 Outlook 리본 메뉴에 컨트롤을 추가할 경우에는 Name 속성이 자동으로 설정됩니다.

리본 컨트롤 이벤트

각 컨트롤 클래스에는 하나 이상의 이벤트가 포함되어 있습니다. 다음 표에서는 이러한 이벤트를 설명합니다.

Event	설명
Click	컨트롤을 클릭하면 발생합니다.
TextChanged	입력란 또는 콤보 상자의 텍스트가 변경되면 발생합니다.
ItemsLoading	Office에서 컨트롤의 Items 컬렉션이 필요한 경우에 발생합니다. 코드를 통해 컨트롤의 속성이 변경될 때까지 Office에서 Items 컬렉션을 캐시하거나 사용자가 직접 IRibbonUI.InvalidateControl(String) 메서드를 호출할 수 있습니다.
ButtonClick	RibbonGallery 또는 RibbonDropDown의 단추를 클릭하면 발생합니다.
SelectionChanged	RibbonDropDown 또는 RibbonGallery의 선택 영역이 변경되면 발생합니다.
DialogLauncherClick	그룹의 오른쪽 아래에 있는 대화 상자 표시 아이콘을 클릭하면 발생합니다.

이러한 이벤트에 대한 이벤트 처리기에는 다음 두 개의 매개 변수가 사용됩니다.

Parameter	설명
sender	이벤트를 발생시킨 컨트롤을 나타내는 Object입니다.
e	Microsoft.Office.Core.IRibbonControl이 들어 있는 RibbonControlEventArgs입니다. 이 컨트롤은 Microsoft Visual Studio Tools for Office Runtime에서 제공하는 리본 개체 모델에서 사용할 수 없는 속성에 액세스하는 데 사용합니다.

참고 항목

작업

방법: 리본 메뉴 사용자 지정 시작

연습: 리본 디자이너를 사용하여 사용자 지정 탭 만들기

연습: 런타임에 리본 메뉴의 컨트롤 업데이트

방법: 기본 제공 탭 사용자 지정

방법: Microsoft Office 메뉴 사용자 지정

방법: 리본 디자이너에서 리본 XML로 리본 메뉴 내보내기

방법: 추가 기능 사용자 인터페이스 오류 표시

참조

Microsoft.Office.Tools.Ribbon

개념

런타임에 리본 메뉴에 액세스

리본 디자이너

Outlook에 대해 리본 메뉴 사용자 지정

기타 리소스

리본 개요