Multifunktionsleisten-Objektmodellübersicht

Artikel
03/22/2013

Visual Studio-Tools für Office-Laufzeit macht ein Objektmodell mit starker Typisierung verfügbar das Sie verwenden können, um abzurufen und die Eigenschaften des Menübands festzulegen zur Laufzeit steuert.Beispielsweise können neue Menüsteuerelemente dynamisch ausgefüllt oder Steuerelemente kontextbezogen angezeigt und ausgeblendet werden.Sie können einem Menüband Registerkarten, Gruppen und Steuerelemente auch hinzufügen, jedoch vor dem Menüband wird von der Office-Anwendung geladen.Informationen hierzu finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokument- und auf Anwendungsebene für die folgenden Anwendungen: Excel 2013 und Excel 2010, InfoPath 2013 und InfoPath 2010, Outlook 2013 und Outlook 2010, PowerPoint 2013 und PowerPoint 2010, Project 2013 und Project 2010, Visio 2013 und Visio 2010, Word 2013 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 ein neues Menüband (Visueller Designer)-Element einem Projekt hinzufügen, fügt Visual Studio eine Klasse Ribbon dem Projekt hinzu.Die Ribbon-Klasse erbt von der RibbonBase-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 Ribbon-Klasse enthält die folgenden drei Ereignisse:

Ereignis	Description
RibbonBase.Load	Wird ausgelöst, wenn die Menübandanpassung von der Office-Anwendung geladen wird.Der Load-Ereignishandler wird automatisch der Menübandcodedatei hinzugefügt.Verwenden Sie diesen Ereignishandler, um benutzerdefinierten Code aus beim Laden.
RibbonBase.LoadImage	Ermöglicht es Ihnen, Bilder in der Menübandanpassung zwischenzuspeichern beim Laden.Sie können einen Eine leichte abrufen, wenn Sie Code schreiben, um Zwischenspeichern der Menübandbilder in diesem Ereignishandler zwischenzuspeichern.Weitere Informationen finden Sie unter LoadImage.
RibbonBase.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 Steuerelement Ribbon an.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 Ribbon-Steuerelement enthält Eigenschaften, die Sie verwenden können, um verschiedene Aufgaben, wie Zuweisen einer Bezeichnung zu einem Steuerelement oder Ausblenden und Anzeigen von Steuerelementen.

In einigen Fällen werden Eigenschaften schreibgeschützt, nachdem das Menüband geladen oder einem Steuerelement zu einem dynamischen 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 ausführen können, indem Sie Ribbon-Steuerelementeigenschaften verwenden.

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. Um Steuerelemente hinzuzufügen RibbonMenu nach dem Laden des Menübands in die Office-Anwendung geladen wurde, müssen Sie die - Eigenschaft auf festlegen Dynamictrue vor dem Laden des Menübands in die Office-Anwendung.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 Klasse Ribbon.
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, nachdem das Menüband, das das Menü enthält, geladen wird.

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 Steuerelements Ribbon im Konstruktor der Klasse Ribbon 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 den 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);
    }
}

In Visual C# projiziert, die Sie von Visual Studio 2008 aktualisiert haben, wird der Konstruktor wird in der Menübandcodedatei.

In Visual Basic-Projekten oder in Visual C# projiziert, dass Sie in Visual Studio 2012 erstellt haben, der Konstruktor wird in der Codedatei des Menüband-Designers.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 Steuerelements Ribbon festlegen, wenn Sie die CreateRibbonExtensibilityObject-Methode in ThisAddin, in ThisWorkbook oder in ThisDocument-Klasse des Projekts überschreiben.Weitere Informationen zur CreateRibbonExtensibilityObject-Methode finden Sie unter Übersicht über die Multifunktionsleiste.

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

Fügen Sie den 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 });
    }
}

Eigenschaften, die schreibgeschützt werden

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

Hinweis
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
Dynamisch	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

Eine neue Instanz des Menübands wird jedes Mal erstellt, eines Inspektors, in dem das Menüband angezeigt.Sie können jedoch die Eigenschaften festlegen, die in der Tabelle oben aufgeführten, nur vor der ersten Instanz des Menübands erstellt wird.Nach dem Erstellen der ersten Instanz ist, werden diese Eigenschaften schreibgeschützt, da die erste Instanz die XML-Datei definiert, der Outlook verwendet, um das Menüband zu laden.

Wenn Sie bedingte Logik verfügen, die alle diese Eigenschaften auf einen anderen Wert festgelegt werden, wenn andere Instanzen des Menübands erstellt werden, hat dieser Code keine Auswirkung.

Hinweis
Stellen Sie sicher, dass die Eigenschaft Name für jedes Steuerelement festgelegt wird, den Sie einem Outlook-Menüband hinzufügen.Wenn Sie einem Outlook-Menüband während der Laufzeit ein Steuerelement hinzufügen, müssen Sie die Eigenschaft im Code festlegen.Wenn Sie einem Outlook-Menüband während der Entwurfszeit ein Steuerelement hinzufügen, wird die Name-Eigenschaft automatisch festgelegt.

Stellen Sie sicher, dass die Eigenschaft Name für jedes Steuerelement festgelegt wird, den Sie einem Outlook-Menüband hinzufügen.Wenn Sie einem Outlook-Menüband während der Laufzeit ein Steuerelement hinzufügen, müssen Sie die Eigenschaft im Code festlegen.Wenn Sie einem Outlook-Menüband während der Entwurfszeit ein Steuerelement hinzufügen, wird die Name-Eigenschaft automatisch festgelegt.

Menüband-Steuerelementereignisse

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

Ereignis	Description
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-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	Description
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 für Office-Laufzeit bereitgestellten Menüband-Objektmodell nicht verfügbar ist.

Siehe auch

Freigeben über