RibbonDialogLauncher Interface

Represents a small standardized icon on a group that can be used to open a dialog box.

Namespace:  Microsoft.Office.Tools.Ribbon
Assembly:  Microsoft.Office.Tools.Common (in Microsoft.Office.Tools.Common.dll)

Syntax

'Declaration
<GuidAttribute("e143d5e9-e844-4052-9793-2070185d351d")> _
Public Interface RibbonDialogLauncher _
    Inherits IDisposable

[GuidAttribute("e143d5e9-e844-4052-9793-2070185d351d")]
public interface RibbonDialogLauncher : IDisposable

The RibbonDialogLauncher type exposes the following members.

Properties

	Name	Description
	Enabled	Gets or sets a value that indicates whether this RibbonDialogLauncher is enabled.
	Image	Gets or sets an image that appears on this RibbonDialogLauncher when it is added to the Quick Access Toolbar.
	ImageName	Gets or sets an identifier that is used to assign an image to this RibbonDialogLauncher when it is added to the Quick Access Toolbar.
	KeyTip	Gets or sets the keyboard shortcut for this RibbonDialogLauncher.
	OfficeImageId	Gets or sets the image to display on this RibbonDialogLauncher, if you want to use a built-in Microsoft Office icon.
	Parent	Gets a RibbonGroup object of which this RibbonDialogLauncher is a member.
	Ribbon	Gets the OfficeRibbon on which this RibbonDialogLauncher is placed.
	ScreenTip	Gets or sets tip text that appears when the user moves the pointer over the RibbonDialogLauncher.
	SuperTip	Gets or sets multiline tip text that appears when the user moves the pointer over the RibbonDialogLauncher.
	Visible	Gets or sets a value that indicates whether this RibbonDialogLauncher is visible.

Top

Methods

	Name	Description
	Dispose	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. (Inherited from IDisposable.)
	ResumeLayout	Reverses the effect of the SuspendLayout method.
	SuspendLayout	Prevents the Microsoft Office application from refreshing the state of controls in the OfficeRibbon.

Top

Remarks

A RibbonDialogLauncher is displayed in the lower-right corner of a group by default.

The Image, ImageName, and OfficeImageId properties have no visible effect when the RibbonDialogLauncher is displayed in a group on the Ribbon. However, when a user adds a RibbonDialogLauncher to the Quick Access Toolbar, these properties control the behavior of the image that is shown. Also, the Visible property does not hide the RibbonDialogLauncher when it is displayed on the Quick Access Toolbar. The user can add the RibbonDialogLauncher to the Quick Access Toolbar through the Ribbon (XML) item. For more information, see Ribbon Overview.

The RibbonDialogLauncher applies only to a RibbonGroup. The RibbonGroup object has a DialogLauncher member of the RibbonDialogLauncher type. For information about how to add a RibbonDialogLauncher to a RibbonGroup, see How to: Add a Dialog Box Launcher to a Ribbon Group.

You can create a RibbonDialogLauncher at run time by using the CreateRibbonDialogLauncher method of the RibbonFactory object.

There are two ways to access the RibbonFactory object:

• By using the Factory property of the Ribbon class. Use this approach from code in your Ribbon class.

• By using the Globals.Factory.GetRibbonFactory method. Use this approach from code outside your Ribbon class.

Some properties of this control can be set only before the Ribbon is loaded into the Office application. For information about setting these properties, see Ribbon Object Model Overview.

Usage

This documentation describes the version of this type that is used in Office projects that target the .NET Framework 4 and the .NET Framework 4.5. In projects that target the .NET Framework 3.5, this type might have different members and the code examples provided for this type might not work. For documentation about this type in projects that target the .NET Framework 3.5, see the following reference section in the Visual Studio 2008 documentation: https://go.microsoft.com/fwlink/?LinkId=160658.

Examples

The following example shows how to add a RibbonDialogLauncher to a Ribbon group and how to launch a custom dialog that enables users to choose advanced settings when they click on the RibbonDialogLauncher icon in the lower right corner of the RibbonGroup.

To run this code example, you must first perform the following steps:

1. Add a Ribbon (Visual Designer) item to an Office project.

2. Add a RibbonDialogLauncher to the default group Group1 as outlined in How to: Add a Dialog Box Launcher to a Ribbon Group.

3. If you are using Visual Basic, add a new Dialog item to the project. If you are using C#, add a new Windows Form item and turn it into a dialog by adding OK and Cancel buttons to the form and by creating event handlers for the buttons' click events.

4. Set the (Name) property of the dialog to advancedSettingsDialog. You can customize the dialog by adding controls and setting more properties.

5. Add the DialogLauncherClick event handler to your code.

6. Place the contents of the following method into the DialogLauncherClick event handler.

Private Sub Group1_DialogLauncherClick(ByVal sender As Object, ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) Handles Group1.DialogLauncherClick
    Dim dlg As advancedSettingsDialog = New advancedSettingsDialog()
    dlg.ShowDialog()
End Sub

void group1_DialogLauncherClick(object sender, Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs e)
{
    advancedSettingsDialog dlg = new advancedSettingsDialog();
    dlg.ShowDialog();
}

See Also

Reference

Microsoft.Office.Tools.Ribbon Namespace

Other Resources

How to: Create Event Handlers in Office Projects

Ribbon Overview

Ribbon Designer

Ribbon Object Model Overview

How to: Get Started Customizing the Ribbon