Multifunktionsleisten-Objektmodellübersicht
Aktualisiert: Juli 2008
Betrifft |
|---|
Die Informationen in diesem Thema gelten nur für die angegebenen Visual Studio Tools for Office-Projekte und Versionen von Microsoft Office. Projekttyp
Microsoft Office-Version
Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp. |
Visual Studio Tools for Office macht ein Objektmodell mit starker Typisierung verfügbar, das zum Abrufen und Festlegen der Eigenschaften von Multifunktionsleisten-Steuerelementen 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, einer Multifunktionsleiste Registerkarten, Gruppen und Steuerelemente hinzuzufügen. Dies muss jedoch vor dem Laden der Multifunktionsleiste durch die Office-Anwendung erfolgen. Informationen hierzu finden Sie unter Festlegen von Eigenschaften, die schreibgeschützt werden.
Dieses Multifunktionsleisten-Objektmodell besteht hauptsächlich aus der Multifunktionsklasse, Multifunktionsleistenereignissen und Multifunktionsleisten-Steuerelementklassen.
Multifunktionsleistenklasse
Beim Hinzufügen eines neuen Elements von Multifunktionsleiste (Visual Designer) zu einem Projekt fügt Visual Studio Tools for Office dem Projekt eine Klasse hinzu, die von der OfficeRibbon-Klasse erbt.
Diese Klasse wird als partielle Klasse angezeigt, die zwischen der Multifunktionsleisten-Codedatei und der Codedatei des Multifunktionsleisten-Designers aufgeteilt ist.
Multifunktionsleistenereignisse
Die OfficeRibbon-Klasse beinhaltet die folgenden drei Ereignisse:
Das Load-Ereignis wird ausgelöst, wenn die Multifunktionsleistenanpassung von der Office-Anwendung geladen wird. Der Load-Ereignishandler wird automatisch der Multifunktionsleisten-Codedatei hinzugefügt. Führen Sie beim Laden der Multifunktionsleiste mithilfe dieses Ereignishandlers benutzerdefinierten Code aus.
Das LoadImage-Ereignis ermöglicht beim Laden der Multifunktionsleiste die Zwischenspeicherung von Bildern in der Multifunktionsleistenanpassung. Eine leichte Leistungsverbesserung wird erzielt, wenn Code zum Zwischenspeichern der Multifunktionsleistenbilder in diesem Ereignishandler geschrieben wird. Weitere Informationen hierzu finden Sie unter LoadImage.
Das Close-Ereignis wird beim Schließen der Multifunktionsleisteninstanz ausgelöst.
Multifunktionsleisten-Steuerelementklassen
Der Microsoft.Office.Tools.Ribbon-Namespace beinhaltet eine Multifunktionsleistenklasse für jedes Steuerelement, das in der Gruppe Steuerelemente für Office-Multifunktionsleisten der Toolbox angezeigt wird.
In der folgenden Tabelle wird die Klasse für jedes Multifunktionsleisten-Steuerelement angezeigt. Eine Beschreibung jedes Steuerelements finden Sie unter Übersicht über die Multifunktionsleiste.
Steuerelementname |
Klassenname |
|---|---|
Feld |
|
Schaltfläche |
|
ButtonGroup |
|
CheckBox |
|
ComboBox |
|
DropDown |
|
EditBox |
|
Katalog |
|
Gruppe |
|
Bezeichnung |
|
Menü |
|
Trennzeichen |
|
SplitButton |
|
Registerkarte |
|
ToggleButton |
Der Microsoft.Office.Tools.Ribbon-Namespace verwendet für diese Klassen das "Multifunktionsleisten"-Präfix, um einen Namenskonflikt mit den Namen der Steuerelementklassen im System.Windows.Forms-Namespace zu verhindern.
Beim Hinzufügen eines Steuerelements zum Multifunktionsleisten-Designer deklariert der Multifunktionsleisten-Designer die Klasse für dieses Steuerelement als Feld in der Codedatei des Multifunktionsleisten-Designers.
Allgemeine Aufgaben mithilfe der Eigenschaften von Multifunktionsleisten-Steuerelementklassen
Jede Multifunktionsleisten-Steuerelementklasse 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 die Multifunktionsleiste 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 Multifunktionsleisten-Steuerelements 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 der Multifunktionsleiste in die Office-Anwendung Steuerelemente hinzugefügt werden, muss die Dynamic-Eigenschaft vor dem Laden der Multifunktionsleiste 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 der Multifunktionsleiste festgelegt werden. Diese Eigenschaften können an drei Orten festgelegt werden:
Im Fenster Eigenschaften von Visual Studio.
Im Konstruktor der Multifunktionsleistenklasse.
In der CreateRibbonExtensibilityObject-Methode der ThisAddin-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 der Multifunktionsleiste mit dem Menü.
Ab Visual Studio 2008 Service Pack 1 (SP1) können die Eigenschaften der einem dynamischen Menü hinzugefügten Steuerelemente jederzeit festgelegt werden. Wenn SP1 jedoch nicht installiert ist, werden einige Eigenschaften nach dem Hinzufügen von Steuerelementen zum Menü schreibgeschützt.
Weitere Informationen hierzu finden Sie unter Eigenschaften, die schreibgeschützt werden.
Festlegen von Eigenschaften im Konstruktor der Multifunktionsleiste
Sie können die Eigenschaften eines Multifunktionsleisten-Steuerelements im Konstruktor der Multifunktionsleistenklasse 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.
<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";
}
}
Festlegen der Eigenschaften in der CreateRibbonExtensibilityObject-Methode
Sie können die Eigenschaften eines Multifunktionsleisten-Steuerelements 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 Multifunktionsleisteneigenschaften in der CreateRibbonExtensibilityObject-Methode der ThisWorkbook-Klasse eines Excel 2007-Arbeitsmappenprojekts festgelegt.
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 der Multifunktionsleiste festgelegt werden können.
.gif "Hinweis") Hinweis: |
|---|
Wenn Sie SP1 installieren, können Sie die Eigenschaften der Steuerelemente in dynamischen Menüs jederzeit festlegen. Diese Tabelle ist in diesem Fall nicht gültig. |
Eigenschaft |
Multifunktionsleisten-Steuerelementklasse |
|---|---|
BoxStyle |
|
ButtonType |
|
ColumnCount |
|
ControlId |
|
DialogLauncher |
|
Dynamic |
|
Global |
|
Gruppen |
|
ImageName |
|
ItemSize |
|
MaxLength |
|
Name |
|
Position |
|
RibbonType |
|
RowCount |
|
ShowItemImage |
|
ShowItemLabel |
|
ShowItemSelection |
|
SizeString |
|
StartFromScratch |
|
Tabstopps |
|
Titel |
Festlegen von Eigenschaften für in Outlook-Inspektoren angezeigte Multifunktionsleisten
Bei jedem Öffnen eines Inspektors, in dem die Multifunktionsleiste angezeigt wird, wird eine neue Instanz der Multifunktionsleiste erstellt. Allerdings können die in der Tabelle oben aufgeführten Eigenschaften nur vor dem Erstellen der ersten Instanz der Multifunktionsleiste 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 der Multifunktionsleiste verwendet wird.
Sofern Sie über bedingte Logik verfügen, mit der alle diese Eigenschaften auf einen anderen Wert festgelegt werden, wenn andere Instanzen der Multifunktionsleiste erstellt werden, bleibt dieser Code ohne Wirkung.
| Hinweis: |
|---|
Stellen Sie sicher, dass die Name-Eigenschaft für jedes einer Outlook-Multifunktionsleiste hinzugefügte Steuerelement festgelegt wird. Wird einer Outlook-Multifunktionsleiste während der Laufzeit ein Steuerelement hinzugefügt, muss diese Eigenschaft im Code festgelegt werden. Wird einer Outlook-Multifunktionsleiste während der Entwurfszeit ein Steuerelement hinzugefügt, wird die Name-Eigenschaft automatisch festgelegt. |
Multifunktionsleisten-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 Microsoft.Office.Core.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 |
Beschreibung |
|---|---|
sender |
Ein Object, das das Steuerelement darstellt, durch das das Ereignis ausgelöst wurde. |
e |
RibbonControlEventArgs, die ein Microsoft.Office.Core.IRibbonControl beinhalten. Greifen Sie mithilfe dieses Steuerelements auf eine beliebige Eigenschaft zu, die im Visual Studio Tools for Office-Multifunktionsleisten-Objektmodell nicht verfügbar ist. |
Siehe auch
Aufgaben
Gewusst wie: Erste Schritte beim Anpassen der Multifunktionsleiste
Gewusst wie: Anpassen einer integrierten Registerkarte
Gewusst wie: Anpassen des Microsoft Office-Menüs
Gewusst wie: Anzeigen von Add-In-Benutzeroberflächenfehlern
Konzepte
Zugreifen auf die Multifunktionsleiste zur Laufzeit
Übersicht über die Multifunktionsleiste
Multifunktionsleisten-Designer
Anpassen einer Multifunktionsleiste in Outlook
Referenz
Änderungsprotokoll
Date |
Versionsgeschichte |
Grund |
|---|---|---|
|
Juli 2008 |
Informationen über das Festlegen von Eigenschaften der Steuerelemente in dynamischen Menüs nach der Installation von SP1 überarbeitet. |
SP1-Featureänderung. |