RibbonToggleButton.ImageName Property

Definition

Namespace:

Microsoft.Office.Tools.Ribbon

Assembly:

Microsoft.Office.Tools.Common.dll

Gets or sets the name that you can use in the LoadImage event handler to identify an image for the control.

public:
 property System::String ^ ImageName { System::String ^ get(); void set(System::String ^ value); };

public string ImageName { get; set; }

member this.ImageName : string with get, set

Public Property ImageName As String

Property Value

String

A string that you can use in the LoadImage event handler to identify an image for the control.

Examples

The following example caches the images for two buttons.

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 group to the custom tab.

3. Add two buttons to the group.

4. Add two images to the project resources.

You can then run this code in the generated Ribbon class.

private void Ribbon1_LoadImage(object sender, RibbonLoadImageEventArgs e)
{
    switch (e.ImageName)
    {
        case "Button1Image":
            e.Image = Properties.Resources.Image1;
            break;
        case "Button2Image":
            e.Image = Properties.Resources.Image2;
            break;
    }
}

Private Sub Ribbon1_LoadImage(ByVal sender As Object, _
    ByVal e As RibbonLoadImageEventArgs)
    Select Case e.ImageName
        Case "Button1Image"
            e.Image = My.Resources.Image1
        Case "Button2Image"
            e.Image = My.Resources.Image2
    End Select
End Sub

Remarks

The ImageName property identifies an image that is displayed by the control. The Office application retrieves this image from your solution only once, to improve performance. This property can be set only at design time, because the image it identifies is loaded during the LoadImage event. LoadImage is raised only once per image name, when the Ribbon is displayed. After that, the control image cannot be changed by using this property.

To load the image, add code to the LoadImage event handler. Check the ImageName property of the RibbonLoadImageEventArgs and set the Image property of the RibbonLoadImageEventArgs object to the image that you want to load.

This property is ignored if either the Image property or the OfficeImageId property is set. Images identified by the ImageName property can be loaded slightly faster than images identified by the Image property, because the Office application retrieves the image from your solution only the first time the Ribbon is displayed.

The ShowImage property must be true for the control to display the image. When you set the ImageName property at design time, Visual Studio automatically sets the ShowImage property to true. If you set the ImageName property at run time, you must set the ShowImage property to true in your code.