Přehled objektového modelu pásu karet

Visual Studio Tools for Office runtime zveřejňuje objektový model silného typu, který můžete použít k získání a nastavení vlastností ovládacích prvků pásu karet za běhu. Můžete například dynamicky naplnit ovládací prvky nabídky nebo zobrazit a skrýt ovládací prvky kontextově. Na pás karet můžete také přidat karty, skupiny a ovládací prvky, ale teprve před načtením pásu karet aplikace Office licací. Informace naleznete v tématu Nastavení vlastností, které se stanou jen pro čtení.

Platí pro: Informace v tomto tématu platí pro projekty na úrovni dokumentů a projekty doplňků VSTO pro následující aplikace: Excel; InfoPath 2013 a InfoPath 2010; Aplikace outlook; Powerpoint; Projektu; Aplikace visio; Slovo. Další informace naleznete v tématu Funkce dostupné aplikace Office lication a typu projektu.

Tento objektový model pásu karet se skládá hlavně z třídy pásu karet, událostí pásu karet a tříd ovládacích prvků pásu karet.

Ribbon – třída

Když do projektu přidáte novou položku pásu karet (Visual Designer), Visual Studio do projektu přidá třídu pásu karet . Třída pásu RibbonBase karet dědí z třídy.

Tato třída se zobrazí jako částečná třída, která je rozdělena mezi soubor kódu pásu karet a soubor kódu Návrhář pásu karet.

Události pásu karet

Třída pásu karet obsahuje následující tři události:

Událost	Popis
Load	Vyvolá se, když aplikace Office lication načte přizpůsobení pásu karet. Obslužná rutina Load události se automaticky přidá do souboru kódu pásu karet. Tuto obslužnou rutinu události použijte ke spuštění vlastního kódu při načtení pásu karet.
LoadImage	Umožňuje ukládat obrázky do mezipaměti v přizpůsobení pásu karet při načítání pásu karet. Pokud napíšete kód pro ukládání obrázků pásu karet do mezipaměti v této obslužné rutině události, můžete získat mírné zvýšení výkonu. Další informace najdete na webu LoadImage.
Close	Vyvolá se při zavření instance pásu karet.

Ovládací prvky pásu karet

Obor Microsoft.Office.Tools.Ribbon názvů obsahuje typ pro každý ovládací prvek, který vidíte ve skupině Ovládací prvky pásu karet Office na panelu nástrojů.

Následující tabulka uvádí typ jednotlivých Ribbon ovládacích prvků. Popis jednotlivých ovládacích prvků najdete v přehledu pásu karet.

Název ovládacího prvku	Název třídy
Box	RibbonBox
Tlačítko	RibbonButton
Skupina tlačítek	RibbonButtonGroup
CheckBox	RibbonCheckBox
ComboBox	RibbonComboBox
DropDown	RibbonDropDown
EditBox	RibbonEditBox
Galerie	RibbonGallery
Skupina	RibbonGroup
Popisek	RibbonLabel
Nabídka	RibbonMenu
Oddělovač	RibbonSeparator
SplitButton	RibbonSplitButton
Kartě	RibbonTab
Togglebutton	RibbonToggleButton

Obor Microsoft.Office.Tools.Ribbon názvů používá pro tyto typy předponu "Pás karet", aby nedocházelo ke kolizi názvů s názvy tříd ovládacích prvků v System.Windows.Forms oboru názvů.

Když přidáte ovládací prvek do Návrháře pásu karet, Návrhář pásu karet deklaruje třídu pro tento ovládací prvek jako pole v souboru kódu Návrhář pásu karet.

Běžné úlohy používající vlastnosti ovládacích prvků pásu karet

Každý Ribbon ovládací prvek obsahuje vlastnosti, které můžete použít k provádění různých úloh, jako je přiřazení popisku k ovládacímu prvku nebo skrytí a zobrazení ovládacích prvků.

V některých případech se vlastnosti stanou jen pro čtení po načtení pásu karet nebo po přidání ovládacího prvku do dynamické nabídky. Další informace naleznete v tématu Nastavení vlastností, které se stanou jen pro čtení.

Následující tabulka popisuje některé úlohy, které můžete provádět pomocí Ribbon vlastností ovládacího prvku.

Pro tento úkol:	Postupujte takto:
Skryjte nebo zobrazte ovládací prvek.	Použijte vlastnost Visible.
Povolení nebo zakázání ovládacího prvku	Použijte vlastnost Enabled.
Nastavte velikost ovládacího prvku.	Použijte vlastnost ControlSize.
Získejte obrázek, který se zobrazí v ovládacím prvku.	Použijte vlastnost Image.
Změňte popisek ovládacího prvku.	Použijte vlastnost Popisek.
Přidejte uživatelem definovaná data do ovládacího prvku.	Použijte vlastnost Tag.
Získání položek v položkách RibbonBox, RibbonDropDownRibbonGallerynebo RibbonSplitButton Ovládací prvek.	Použijte vlastnost Items.
Umožňuje přidat položky do RibbonComboBoxovládacího prvku , RibbonDropDownnebo RibbonGallery ovládacího prvku.	Použijte vlastnost Items.
Přidání ovládacích prvků do souboru RibbonMenu.	Použijte vlastnost Items. Chcete-li přidat ovládací prvky po RibbonMenu načtení pásu karet do aplikace Office lication, je nutné nastavit Dynamic vlastnost na true před načtením pásu karet do aplikace Office lication. Informace naleznete v tématu Nastavení vlastností, které se stanou jen pro čtení.
Získání vybrané položky RibbonComboBox RibbonDropDownnebo RibbonGallery.	Použijte vlastnost SelectedItem. Pro hodnotu RibbonComboBoxpoužijte Text vlastnost.
Získejte skupiny na .RibbonTab	Groups Použijte vlastnost.
Zadejte počet řádků a sloupců, které se zobrazí v souboru RibbonGallery.	Použijte vlastnosti RowCount a ColumnCount vlastnosti.

Nastavení vlastností, které se stanou jen pro čtení

Některé vlastnosti lze nastavit pouze před načtením pásu karet. Existují tři místa pro nastavení těchto vlastností:

• V okně Vlastnosti sady Visual Studio.

• V konstruktoru třídy pásu karet .

• CreateRibbonExtensibilityObject V metodě ThisAddin, ThisWorkbooknebo ThisDocument třídy projektu.

  Dynamické nabídky poskytují některé výjimky. Můžete vytvořit nové ovládací prvky, nastavit jejich vlastnosti a pak je přidat do dynamické nabídky za běhu, a to i po načtení pásu karet, který obsahuje nabídku.

  Vlastnosti ovládacích prvků, které přidáte do dynamické nabídky, lze kdykoli nastavit.

  Další informace naleznete v tématu Vlastnosti, které se stanou jen pro čtení.

Nastavení vlastností v konstruktoru pásu karet

Vlastnosti Ribbon ovládacího prvku můžete nastavit v konstruktoru třídy pásu karet . Tento kód se musí objevit po volání InitializeComponent metody. Následující příklad přidá do skupiny nové tlačítko, pokud je aktuální čas 17:00 Tichomoří (UTC-8) nebo novější.

Přidejte následující kód.

C#

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

VB

<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

V projektech Visual C#, které jste upgradovali ze sady Visual Studio 2008, se konstruktor zobrazí v souboru kódu pásu karet.

V projektech jazyka Visual Basic nebo v projektech Visual C#, které jste vytvořili v sadě Visual Studio 2013, se konstruktor zobrazí v souboru kódu Návrhář pásu karet. Tento soubor má název YourRibbonItem. Designer.cs nebo YourRibbonItem. Designer.vb. Chcete-li zobrazit tento soubor v projektech jazyka Visual Basic, musíte nejprve kliknout na tlačítko Zobrazit všechny soubory v Průzkumník řešení.

Nastavení vlastností v metodě CreateRibbonExtensibilityObject

Vlastnosti Ribbon ovládacího prvku můžete nastavit při přepsání CreateRibbonExtensibilityObject metody v ThisAddin, ThisWorkbooknebo ThisDocument třídy projektu. Další informace o metodě najdete v tématu Přehled pásu CreateRibbonExtensibilityObject karet.

Následující příklad nastaví vlastnosti pásu karet v CreateRibbonExtensibilityObject metodě ThisWorkbook třídy projektu excelového sešitu.

Přidejte následující kód.

C#

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

VB

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

Vlastnosti, které se stanou jen pro čtení

Následující tabulka ukazuje vlastnosti, které lze nastavit pouze před načtením pásu karet.

Poznámka:

Vlastnosti ovládacích prvků můžete kdykoli nastavit v dynamických nabídkách. Tato tabulka se v takovém případě nepoužije.

Vlastnost	Pás karet – třída ovládacího prvku
BoxStyle	RibbonBox
Buttontype	RibbonSplitButton
Columncount	RibbonGallery
Controlid	RibbonTab
DialogLauncher	RibbonGroup
dynamicky,	RibbonMenu
Globální	OfficeRibbon
Skupiny	RibbonTab
Imagename	RibbonButton RibbonComboBox RibbonDialogLauncher RibbonDropDown RibbonEditBox RibbonGallery RibbonMenu RibbonSplitButton RibbonToggleButton
ItemSize	RibbonMenu RibbonSplitButton
Maxlength	RibbonComboBox RibbonEditBox
Název	RibbonComponent
Pozice	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
Karty	OfficeRibbon
Název	RibbonSeparator

Nastavení vlastností pásů karet, které se zobrazují v inspektorech Outlooku

Při každém otevření inspektoru, ve kterém se zobrazí pás karet, se vytvoří nová instance pásu karet. Vlastnosti uvedené v tabulce výše však můžete nastavit pouze před vytvořením první instance pásu karet. Po vytvoření první instance se tyto vlastnosti stanou jen pro čtení, protože první instance definuje soubor XML, který Outlook používá k načtení pásu karet.

Pokud máte podmíněnou logiku, která při vytváření jiných instancí pásu karet nastaví některou z těchto vlastností na jinou hodnotu, nebude mít tento kód žádný vliv.

Poznámka:

Ujistěte se, že je vlastnost Název nastavená pro každý ovládací prvek, který přidáte na pás karet Aplikace Outlook. Pokud přidáte ovládací prvek na pás karet Outlooku za běhu, musíte tuto vlastnost nastavit v kódu. Pokud přidáte ovládací prvek na pás karet Outlooku v době návrhu, nastaví se vlastnost Name automaticky.

Události ovládacích prvků pásu karet

Každá třída ovládacího prvku obsahuje jednu nebo více událostí. Následující tabulka popisuje tyto události.

Událost	Popis
Klikněte na	Nastane při kliknutí na ovládací prvek.
Textchanged	Nastane, když se změní text textového pole nebo pole se seznamem.
ItemsLoading	Nastane v případě, že Sada Office požaduje kolekci Položek ovládacího prvku. Office ukládá kolekci Items do mezipaměti, dokud kód nezmění vlastnosti ovládacího prvku nebo zavoláte metodu InvalidateControl .
ButtonClick	Nastane, když je tlačítko v RibbonGallery nebo RibbonDropDown je kliknutí.
Selectionchanged	Nastane, když se výběr změní RibbonDropDown nebo RibbonGallery změní.
DialogLauncherClick	Vyvolá se při kliknutí na ikonu spouštěče dialogového okna v pravém dolním rohu skupiny.

Obslužné rutiny událostí pro tyto události mají následující dva parametry.

Parametr	Popis
Odesílatele	Představuje Object ovládací prvek, který vyvolal událost.
E	ARibbonControlEventArgs, který obsahuje .IRibbonControl Pomocí tohoto ovládacího prvku můžete získat přístup k jakékoli vlastnosti, která není k dispozici v objektovém modelu pásu karet, který poskytuje Visual Studio Tools for Office runtime .

Související obsah

• Přístup k pásu karet za běhu
• Přehled pásu karet
• Postupy: Začínáme s přizpůsobením pásu karet
• Návrhář pásu karet
• Návod: Vytvoření vlastní karty pomocí Návrháře pásu karet
• Návod: Aktualizace ovládacích prvků na pásu karet za běhu
• Přizpůsobení pásu karet pro Outlook
• Postupy: Přizpůsobení předdefinované karty
• Postupy: Přidání ovládacích prvků do zobrazení Backstage
• Postupy: Export pásu karet z Návrháře pásu karet do XML pásu karet
• Postupy: Zobrazení chyb uživatelského rozhraní doplňku