Multifunktionsleisten-Objektmodellübersicht

Artikel
08/10/2011

Die Visual Studio Tools for Office-Laufzeit macht ein Objektmodell mit starker Typisierung verfügbar, das zum Abrufen und Festlegen der Eigenschaften von Menübandsteuerelementen während der Laufzeit verwendet werden kann. Beispielsweise können neue Menüsteuerelemente dynamisch ausgefüllt oder Steuerelemente kontextbezogen angezeigt und ausgeblendet werden. Zudem besteht die Möglichkeit, einem Menüband Registerkarten, Gruppen und Steuerelemente hinzuzufügen. Dies muss jedoch vor dem Laden des Menübands durch die Office-Anwendung erfolgen. Informationen hierzu finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokumentebene für die folgenden Anwendungen: Excel 2007 und Excel 2010, InfoPath 2010, Outlook 2007 und Outlook 2010, PowerPoint 2007 und PowerPoint 2010, Project 2010, Visio 2010, Word 2007 und Word 2010. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Dieses Menüband-Objektmodell besteht hauptsächlich aus der Multifunktionsklasse, Menübandereignissen und Menüband-Steuerelementklassen.

Menübandklasse

Wenn Sie einem Projekt ein neues Element für das Menüband (Visual Designer) hinzufügen, fügt Visual Studio dem Projekt eine Ribbon-Klasse hinzu. Ist für das Projekt .NET Framework 4 als Zielversion festgelegt, erbt die Ribbon-Klasse von der RibbonBase-Klasse. Wenn das Projekt auf .NET Framework 3.5 abzielt, erbt die Menübandklasse von der OfficeRibbon-Klasse.

Diese Klasse wird als partielle Klasse angezeigt, die zwischen der Menüband-Codedatei und der Codedatei des Menüband-Designers aufgeteilt ist.

Menübandereignisse

Die Menübandklasse beinhaltet die folgenden drei Ereignisse:

Projekte, die auf .NET Framework 4 abzielen	Projekte, die auf .NET Framework 3.5 abzielen	Beschreibung
RibbonBase.Load	OfficeRibbon.Load	Wird ausgelöst, wenn die Menübandanpassung von der Office-Anwendung geladen wird. Der Load-Ereignishandler wird automatisch der Menüband-Codedatei hinzugefügt. Führen Sie beim Laden des Menübands mithilfe dieses Ereignishandlers benutzerdefinierten Code aus.
RibbonBase.LoadImage	OfficeRibbon.LoadImage	Ermöglicht beim Laden des Menübands die Zwischenspeicherung von Bildern in der Menübandanpassung. Eine leichte Leistungsverbesserung wird erzielt, wenn Code zum Zwischenspeichern der Menübandbilder in diesem Ereignishandler geschrieben wird. Weitere Informationen finden Sie unter LoadImage.
RibbonBase.Close	OfficeRibbon.Close	Wird ausgelöst, wenn die Menübandinstanz geschlossen wird.

Menübandsteuerelemente

Der Microsoft.Office.Tools.Ribbon-Namespace beinhaltet einen Typ für jedes Steuerelement, das in der Gruppe Steuerelemente für Office-Menübänder der Toolbox angezeigt wird.

In der folgenden Tabelle wird der Typ für jedes Menübandsteuerelement angezeigt. Eine Beschreibung jedes Steuerelements finden Sie unter Übersicht über die Multifunktionsleiste.

Steuerelementname	Klassenname
Feld	RibbonBox
Button	RibbonButton
ButtonGroup	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Katalog	RibbonGallery
Gruppe	RibbonGroup
Bezeichnung	RibbonLabel
Menü	RibbonMenu
Trennzeichen	RibbonSeparator
SplitButton	RibbonSplitButton
Registerkarte	RibbonTab
ToggleButton	RibbonToggleButton

Der Microsoft.Office.Tools.Ribbon-Namespace verwendet für diese Typen das Ribbon-Präfix, um einen Namenskonflikt mit den Namen der Steuerelementklassen im System.Windows.Forms-Namespace zu verhindern.

Beim Hinzufügen eines Steuerelements zum Menüband-Designer deklariert der Menüband-Designer die Klasse für dieses Steuerelement als Feld in der Codedatei des Menüband-Designers.

Allgemeine Aufgaben mithilfe der Eigenschaften von Menübandsteuerelementen

Jedes Menübandsteuerelement beinhaltet Eigenschaften, mit denen Sie verschiedene Aufgaben ausführen können, wie das Zuweisen einer Bezeichnung zu einem Steuerelement oder das Ausblenden und Anzeigen von Steuerelementen.

In einigen Fällen sind Eigenschaften schreibgeschützt, nachdem das Menüband geladen oder einem Steuerelement ein dynamisches Menü hinzugefügt wurde. Weitere Informationen finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.

In der folgenden Tabelle werden einige der Aufgaben beschrieben, die Sie mithilfe der Eigenschaften des Menübandsteuerelements ausführen können.

Aufgabe:	Vorgehensweise:
Aus- oder Einblenden eines Steuerelements.	Verwenden Sie die Visible-Eigenschaft.
Aktivieren oder Deaktivieren eines Steuerelements.	Verwenden Sie die Enabled-Eigenschaft.
Festlegen der Größe eines Steuerelements.	Verwenden Sie die ControlSize-Eigenschaft.
Abrufen des Bilds, das auf einem Steuerelement angezeigt wird.	Verwenden Sie die Image-Eigenschaft.
Ändern der Bezeichnung eines Steuerelements.	Verwenden Sie die Label-Eigenschaft.
Hinzufügen von benutzerdefinierten Daten zu einem Steuerelement.	Verwenden Sie die Tag-Eigenschaft.
Abrufen der Elemente in einem RibbonBox-Steuerelement, einem RibbonDropDown-Steuerelement, einem RibbonGallery-Steuerelement oder einem RibbonSplitButton-Steuerelement	Verwenden Sie die Items-Eigenschaft.
Hinzufügen eines RibbonComboBox-Steuerelements, eines RibbonDropDown-Steuerelements oder eines RibbonGallery-Steuerelements.	Verwenden Sie die Items-Eigenschaft.
Hinzufügen von Steuerelementen zu RibbonMenu.	Verwenden Sie die Items-Eigenschaft. Sollen RibbonMenu nach dem Laden des Menübands in die Office-Anwendung Steuerelemente hinzugefügt werden, muss die Dynamic-Eigenschaft vor dem Laden des Menübands in die Office-Anwendung auf true festgelegt werden. Informationen hierzu finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.
Abrufen des ausgewählten Elements von RibbonComboBox, RibbonDropDown oder RibbonGallery.	Verwenden Sie die SelectedItem-Eigenschaft. Verwenden Sie für RibbonComboBox die Text-Eigenschaft.
Abrufen der Gruppen auf RibbonTab.	Verwenden Sie die Groups-Eigenschaft.
Angeben der Anzahl der Zeilen und Spalten, die in RibbonGallery angezeigt werden.	Verwenden Sie die RowCount-Eigenschaft und die ColumnCount-Eigenschaft.

Festlegen von Eigenschaften, die schreibgeschützt werden

Einige Eigenschaften können nur vor dem Laden des Menübands festgelegt werden. Diese Eigenschaften können an drei Orten festgelegt werden:

Im Fenster Eigenschaften von Visual Studio.
Im Konstruktor der Menübandklasse.
In der CreateRibbonExtensibilityObject-Methode der ThisAddin, ThisWorkbook- Klasse oder ThisDocument-Klasse des Projekts.

Dynamische Menüs bieten einige Ausnahmen. Sie können neue Steuerelemente erstellen, deren Eigenschaften festlegen und sie dann während der Laufzeit einem dynamischen Menü hinzufügen, und zwar auch nach dem Laden des Menübands mit dem Menü.

Eigenschaften von Steuerelementen, die Sie einem dynamischen Menü hinzufügen, können jederzeit festgelegt werden.

Weitere Informationen finden Sie unter Eigenschaften, die schreibgeschützt werden.

Festlegen von Eigenschaften im Konstruktor des Menübands

Sie können die Eigenschaften eines Menübandsteuerelements im Konstruktor der Menübandklasse festlegen. Dieser Code muss nach dem Aufruf der InitializeComponent-Methode angezeigt werden. Im folgenden Beispiel wird einer Gruppe eine neue Schaltfläche hinzugefügt, falls die aktuelle Uhrzeit 17:00 Pacific Time (UTC-8) oder später ist.

Fügen Sie für Projekte mit der Zielversion .NET Framework 4 folgenden Code hinzu:

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

Fügen Sie für Projekte mit der Zielversion .NET Framework 3.5 folgenden Code hinzu:

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

}

In Visual C#-Projekten, die Sie von Visual Studio 2008 aktualisiert haben, wird der Konstruktor in der Menüband-Codedatei angezeigt.

In Visual Basic-Projekten oder in Visual C#-Projekten, die Sie in Visual Studio 2010 erstellt haben, wird der Konstruktor in der Menüband-Designer-Codedatei angezeigt. Diese Datei hat den Namen "IhrMenübandElement.Designer.cs" oder "IhrMenübandElement.Designer.vb". Um diese Datei in Visual Basic-Projekten anzuzeigen, müssen Sie zuerst im Projektmappen-Explorer auf die Schaltfläche Alle Dateien anzeigen klicken.

Festlegen der Eigenschaften in der CreateRibbonExtensibilityObject-Methode

Sie können die Eigenschaften eines Menübandsteuerelements beim Überschreiben der CreateRibbonExtensibilityObject-Methode in der ThisAddin, ThisWorkbook-Klasse oder der ThisDocument-Klasse des Projekts festlegen. Weitere Informationen zur CreateRibbonExtensibilityObject-Methode finden Sie unter Übersicht über die Multifunktionsleiste.

Im folgenden Beispiel werden die Menübandeigenschaften in der CreateRibbonExtensibilityObject-Methode der ThisWorkbook-Klasse eines Excel-Arbeitsmappenprojekts festgelegt.

Fügen Sie für Projekte mit der Zielversion .NET Framework 4 folgenden Code hinzu:

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

Fügen Sie für Projekte mit der Zielversion .NET Framework 3.5 folgenden Code hinzu:

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

Eigenschaften, die schreibgeschützt werden

In der folgenden Tabelle werden Eigenschaften angezeigt, die nur vor dem Laden des Menübands festgelegt werden können.

Tipp

Sie können Sie die Eigenschaften der Steuerelemente in dynamischen Menüs jederzeit festlegen. Diese Tabelle ist in diesem Fall nicht gültig.

Eigenschaft	Menüband-Steuerelementklasse
BoxStyle	RibbonBox
ButtonType	RibbonSplitButton
ColumnCount	RibbonGallery
ControlId	RibbonTab
DialogLauncher	RibbonGroup
Dynamic	RibbonMenu
Global	OfficeRibbon
Gruppen	RibbonTab
ImageName	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
MaxLength	RibbonComboBox RibbonEditBox
Name	RibbonComponent
Position	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
Tabstopps	OfficeRibbon
Titel	RibbonSeparator

Festlegen von Eigenschaften für in Outlook-Inspektoren angezeigte Menübänder

Bei jedem Öffnen eines Inspektors, in dem das Menüband angezeigt wird, wird eine neue Instanz des Menübands erstellt. Allerdings können die in der Tabelle oben aufgeführten Eigenschaften nur vor dem Erstellen der ersten Instanz des Menübands festgelegt werden. Nach dem Erstellen der ersten Instanz werden diese Eigenschaften schreibgeschützt, da die erste Instanz die XML-Datei definiert, die von Outlook zum Laden des Menübands verwendet wird.

Sofern Sie über bedingte Logik verfügen, mit der alle diese Eigenschaften auf einen anderen Wert festgelegt werden, wenn andere Instanzen des Menübands erstellt werden, bleibt dieser Code ohne Wirkung.

Tipp

Stellen Sie sicher, dass die Name-Eigenschaft für jedes einem Outlook-Menüband hinzugefügte Steuerelement festgelegt wird. Wird einem Outlook-Menüband während der Laufzeit ein Steuerelement hinzugefügt, muss diese Eigenschaft im Code festgelegt werden. Wird einem Outlook-Menüband während der Entwurfszeit ein Steuerelement hinzugefügt, wird die Name-Eigenschaft automatisch festgelegt.

Menüband-Steuerelementereignisse

Jede Steuerelementklasse beinhaltet mindestens ein Ereignis. In der folgenden Tabelle werden diese Ereignisse beschrieben.

Ereignis	Beschreibung
Click	Tritt beim Klicken auf ein Steuerelement auf.
TextChanged	Tritt beim Ändern des Texts in einem Bearbeitungs- oder Kombinationsfeld auf.
ItemsLoading	Tritt auf, wenn die Items-Auflistung des Steuerelements von Office angefordert wird. Office nimmt eine Zwischenspeicherung der Items-Auflistung vor, bis der Code die Eigenschaften des Steuerelements ändert oder die IRibbonUI.InvalidateControl(String)-Methode aufgerufen wird.
ButtonClick	Tritt beim Klicken auf eine Schaltfläche in RibbonGallery oder RibbonDropDown auf.
SelectionChanged	Tritt beim Ändern der Auswahl in RibbonDropDown oder RibbonGallery auf.
DialogLauncherClick	Tritt auf, wenn unten rechts in einer Gruppe auf das Symbol für das Dialogfeldstartprogramm geklickt wird.

Die Ereignishandler für diese Ereignisse besitzen die folgenden zwei Parameter.

Parameter	Beschreibung
sender	Ein Object, das das Steuerelement darstellt, durch das das Ereignis ausgelöst wurde.
e	Ein RibbonControlEventArgs, das ein Microsoft.Office.Core.IRibbonControl enthält. Greifen Sie mithilfe dieses Steuerelements auf eine beliebige Eigenschaft zu, die im von der Visual Studio Tools for Office-Laufzeit bereitgestellten Menüband-Objektmodell nicht verfügbar ist.

Siehe auch

Freigeben über