Freigeben über

Übersicht über das Menübandobjektmodell

  • Artikel

Die Visual Studio-Tools für Office-Laufzeit macht ein stark typiertes Objektmodell verfügbar, mit dem Sie die Eigenschaften von Menübandsteuerelementen zur Laufzeit abrufen und festlegen können. 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. Weitere Informationen finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.

Gilt für: Die Informationen in diesem Thema gelten für Projekte auf Dokumentebene und VSTO-Add-In-Projekte für die folgenden Anwendungen: Excel; InfoPath 2013 und InfoPath 2010; Outlook; Powerpoint; Projekt; Visio; Wort. Weitere Informationen finden Sie unter features available by Office-App lication and project type.

Dieses Menübandobjektmodell besteht Standard der Menübandklasse, der Menübandereignisse und der Menüband-Steuerelementklassen.

Menübandklasse

Wenn Sie einem Projekt ein neues Menübandelement (Visual Designer) hinzufügen, fügt Visual Studio Ihrem Projekt eine Menübandklasse hinzu. Die Menübandklasse 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 Menübandklasse enthält die folgenden drei Ereignisse:

Ereignis BESCHREIBUNG
Load Wird ausgelöst, wenn die Office-App lizenzierung die Menübandanpassung lädt. Der Load Ereignishandler wird automatisch der Codedatei des Menübands hinzugefügt. Führen Sie beim Laden des Menübands mithilfe dieses Ereignishandlers benutzerdefinierten Code aus.
LoadImage Ermöglicht das Zwischenspeichern von Bildern in der Menübandanpassung, wenn das Menüband geladen wird. Sie können einen leichten Leistungsgewinn erzielen, wenn Sie Code schreiben, um die Menübandbilder in diesem Ereignishandler zwischenzuspeichern. Weitere Informationen finden Sie unter LoadImage.
Close Wird ausgelöst, wenn die Menübandinstanz geschlossen wird.

Menüband-Steuerelemente

Der Microsoft.Office.Tools.Ribbon Namespace enthält einen Typ für jedes Steuerelement, das in der Gruppe "Office Ribbon Controls " der Toolbox angezeigt wird.

In der folgenden Tabelle wird der Typ für jedes Ribbon-Steuerelement angezeigt. Eine Beschreibung der einzelnen Steuerelemente finden Sie in der Übersicht über das Menüband.

Steuerelementname Klassenname
Feld RibbonBox
Schaltfläche RibbonButton
ButtonGroup RibbonButtonGroup
CheckBox RibbonCheckBox
ComboBox RibbonComboBox
DropDown RibbonDropDown
Bearbeitungsfeld RibbonEditBox
Galerie RibbonGallery
Gruppieren RibbonGroup
Bezeichnung RibbonLabel
Menü RibbonMenu
Trennzeichen RibbonSeparator
SplitButton RibbonSplitButton
Tab 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 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 werden Eigenschaften nach dem Laden des Menübands oder nach dem Hinzufügen eines Steuerelements zu einem dynamischen Menü schreibgeschützt. 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 Ribbon-Steuerelements ausführen können.

Aufgabe: Aktion
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 dem RibbonMenu Menüband Steuerelemente hinzuzufügen, nachdem das Menüband in die Office-App lizenzierung geladen wurde, müssen Sie die Dynamic Eigenschaft auf "true" festlegen, bevor das Menüband in die Office-App lication geladen wird. Weitere Informationen 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 Ribbon-Klasse .

  • 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 Ribbon Steuerelements im Konstruktor der Ribbon-Klasse 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:

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#-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 2013 erstellt haben, wird der Konstruktor in der Codedatei des Menüband-Designers angezeigt. Diese Datei heißt "YourRibbonItem". Designer.cs oder YourRibbonItem. Designer.vb. Um diese Datei in Visual Basic-Projekten anzuzeigen, müssen Sie zuerst in Projektmappen-Explorer auf die Schaltfläche "Alle Dateien anzeigen" klicken.

Festlegen von Eigenschaften in der CreateRibbonExtensibilityObject-Methode

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

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

Fügen Sie den folgenden Code hinzu:

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 sind Eigenschaften aufgeführt, 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
Dialogfeld Startprogramm 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
Registerkarten OfficeRibbon
Titel RibbonSeparator

Festlegen von Eigenschaften für Menübänder, die in Outlook-Inspektoren angezeigt werden

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.

Hinweis

Stellen Sie sicher, dass die Name-Eigenschaft für jedes Steuerelement festgelegt ist, das Sie einem Outlook-Menüband hinzufügen. Wenn Sie einem Outlook-Menüband zur Laufzeit ein Steuerelement hinzufügen, müssen Sie diese Eigenschaft in Ihrem Code festlegen. Wenn Sie einem Outlook-Menüband zur 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 BESCHREIBUNG
Klicken Sie auf 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 speichert die Items-Auflistung zwischen, bis Ihr Code die Eigenschaften des Steuerelements ändert, oder Sie rufen die InvalidateControl Methode auf.
Buttonclick Tritt beim Klicken auf eine Schaltfläche in RibbonGallery oder RibbonDropDown auf.
SelectionChanged Tritt beim Ändern der Auswahl in RibbonDropDown oder RibbonGallery auf.
Dialogfeld Startprogramm Click 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
Absender Ein Object, das das Steuerelement darstellt, durch das das Ereignis ausgelöst wurde.
e Ein RibbonControlEventArgs, das ein IRibbonControl enthält. Verwenden Sie dieses Steuerelement, um auf alle Eigenschaften zuzugreifen, die im Vom Visual Studio-Tools für Office-Laufzeit bereitgestellten Menübandobjektmodell nicht verfügbar sind.

Zugehöriger Inhalt