리본 개체 모델 개요

  • 아티클

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

적용 대상: 이 항목의 정보는 Excel, InfoPath 2013, InfoPath 2010, Outlook, PowerPoint, Project, Visio, Word와 같은 애플리케이션의 문서 수준 프로젝트 및 VSTO 추가 기능 프로젝트에 적용됩니다. 자세한 내용은 Office 애플리케이션 및 프로젝트 형식에 따라 사용 가능한 기능을 참조하세요.

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

Ribbon 클래스

프로젝트에 새 리본(Visual Designer) 항목을 추가하면 Visual Studio에서 프로젝트에 Ribbon 클래스를 추가합니다. Ribbon 클래스는 RibbonBase 클래스에서 상속합니다.

이 클래스는 리본 코드 파일과 리본 디자이너 코드 파일 간에 분할되는 부분 클래스로 나타납니다.

리본 이벤트

Ribbon 클래스에는 다음 세 가지 이벤트가 포함됩니다.

이벤트 설명
Load Office 애플리케이션에서 리본 사용자 지정을 로드할 때 발생합니다. Load 이벤트 처리기는 리본 코드 파일에 자동으로 추가됩니다. 리본이 로드되면 이 이벤트 처리기를 사용하여 사용자 지정 코드를 실행합니다.
LoadImage 리본이 로드되면 리본 사용자 지정에서 이미지를 캐시할 수 있습니다. 이 이벤트 처리기에서 리본 이미지를 캐시하는 코드를 작성하면 약간의 성능이 개선될 수 있습니다. 자세한 내용은 LoadImage를 참조하세요.
Close 리본 인스턴스가 닫히면 발생합니다.

리본 컨트롤

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

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

컨트롤 이름 클래스 이름
Box RibbonBox
버튼 RibbonButton
ButtonGroup RibbonButtonGroup
CheckBox RibbonCheckBox
ComboBox RibbonComboBox
DropDown RibbonDropDown
EditBox RibbonEditBox
갤러리 RibbonGallery
그룹 RibbonGroup
Label RibbonLabel
메뉴 RibbonMenu
구분 기호 RibbonSeparator
SplitButton RibbonSplitButton
Tab RibbonTab
ToggleButton RibbonToggleButton

Microsoft.Office.Tools.Ribbon 네임스페이스는 이러한 형식에 대해 "Ribbon" 접두사를 사용하여 System.Windows.Forms 네임스페이스의 컨트롤 클래스 이름과 이름 충돌이 발생하지 않도록 합니다.

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

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

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

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

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

작업 방법:
컨트롤을 숨기거나 표시합니다. 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 속성 창에서

  • Ribbon 클래스의 생성자에서

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

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

    동적 메뉴에 추가하는 컨트롤의 속성은 언제든지 설정할 수 있습니다.

    자세한 내용은 읽기 전용이 되는 속성을 참조하세요.

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

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

다음 코드를 추가합니다.

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

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

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

CreateRibbonExtensibilityObject 메서드에서 속성 설정

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

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

다음 코드를 추가합니다.

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

읽기 전용이 되는 속성

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

참고 항목

언제든지 동적 메뉴에서 컨트롤의 속성을 설정할 수 있습니다. 이 경우에는 다음 표가 적용되지 않습니다.

속성 리본 컨트롤 클래스
BoxStyle RibbonBox
ButtonType RibbonSplitButton
ColumnCount RibbonGallery
ControlId RibbonTab
DialogLauncher RibbonGroup
동적 RibbonMenu
Global OfficeRibbon
Groups RibbonTab
ImageName RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton
ItemSize RibbonMenu

RibbonSplitButton
MaxLength RibbonComboBox

RibbonEditBox
이름 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 속성이 자동으로 설정됩니다.

리본 컨트롤 이벤트

각 컨트롤 클래스에는 이벤트가 하나 이상 포함됩니다. 다음 표에서는 이러한 열에 대해 설명합니다.

이벤트 설명
클릭 컨트롤을 클릭할 때 발생합니다.
TextChanged 편집 상자 또는 콤보 상자의 텍스트가 변경될 때 발생합니다.
ItemsLoading Office에서 컨트롤의 Items 컬렉션을 요청할 때 발생합니다. 코드가 컨트롤의 속성을 변경하거나 InvalidateControl 메서드를 호출할 때까지 Office에서 Items 컬렉션을 캐시합니다.
ButtonClick RibbonGallery 또는 RibbonDropDown에서 단추를 클릭할 때 발생합니다.
SelectionChanged RibbonDropDown 또는 RibbonGallery의 선택 영역이 변경될 때 발생합니다.
DialogLauncherClick 그룹의 오른쪽 아래 모서리에 있는 대화 상자 시작 관리자 아이콘을 클릭할 때 발생합니다.

이러한 이벤트에 대한 이벤트 처리기에는 다음 두 매개 변수가 있습니다.

매개 변수 설명
보낸 사람 Object 이벤트를 발생시킨 컨트롤을 나타내는 값입니다.
e RibbonControlEventArgs이 들어 있는 IRibbonControl입니다. Visual Studio Tools for Office 런타임에서 제공하는 리본 개체 모델에서 사용할 수 없는 속성에 액세스하려면 이 컨트롤을 사용합니다.

관련 콘텐츠