toggleButton Element

The toggleButton Element specifies a toggle button control that can be toggled between the pressed and un-pressed states by the end-user.

Graphical View of toggleButton Attributes

The following figure shows all the visible graphical attributes you can set on the toggleButton control.

This is specified using the following XML:

<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
	<!-- true: show only your tab in Excel -->
	<ribbon startFromScratch="true">
		<tabs>
			<tab id="customTab"
			     label="Custom Tab">
				<group id="customGroup"
				       label="Custom Group">
					<toggleButton id="tgbDemo1"
					              image="custom-icon"
					              label="toggleButton Label 1"
					              size="large"
					              onAction="tgbDemo1_Action"/>
					<toggleButton id="tgbDemo2"
					              imageMso="HappyFace"
					              label="toggleButton Label 2"
					              size="normal"
					              keytip="T"
					              screentip="screentip string"
					              supertip="supertip string"
					              onAction="tgbDemo2_Action"/>
				</group>
			</tab>
		</tabs>
	</ribbon>
</customUI>

Note: image="custom-icon": you need to create a custom icon yourself.

Parent Elements

box
buttonGroup
dynamicMenu
group
menu
officeMenu
splitButton

Children Elements

The toggleButton control does not support child objects of any kind.

Required Attributes

The id, idQ, and idMso attributes are mutually exclusive. At least one of these attributes MUST be specified.

ATTRIBUTE	WHEN TO USE
id	Create your own toggleButton
idMso	Use an existing built-in toggleButton
idQ	Create a toggleButton shared between namespaces

Required Callback

DYNAMIC ATTRIBUTE	ALLOWED VALUES	VBA CALLBACK SIGNATURE
onAction	1 to 4096 characters	Sub OnAction (control as IRibbonControl, pressed as Boolean)

Optional insert Attributes

The insertAfterMso, insertAfterQ, insertBeforeMso, and insertBeforeQ attributes are mutually exclusive. If none of these attributes are specified, the controls SHOULD be appended to the existing set of controls, in the order they are defined in the XML.

INSERT ATTRIBUTE	ALLOWED VALUES	DEFAULT VALUE	WHEN TO USE
insertAfterMso	Valid Mso Group	Insert at end of group	Insert after built-in control
insertBeforeMso	Valid Mso Group	Insert at end of group	Insert before built-in control
insertAfterQ	Valid Group idQ	Insert at end of group	Insert after shared namespace control
insertBeforeQ	Valid Group idQ	Insert at end of group	Insert before shared namespace control

Optional Attributes and Callbacks

STATIC ATTRIBUTE	DYNAMIC ATTRIBUTE	ALLOWED VALUES	DEFAULT VALUE	VBA CALLBACK SIGNATURE FOR DYNAMIC ATTRIBUTE
description	getDescription	1 to 4096 characters	(none)	Sub GetDescription (control As IRibbonControl, ByRef returnedVal)
enabled	getEnabled	true, false, 1, 0	true	Sub GetEnabled (control As IRibbonControl, ByRef returnedVal)
image	getImage	1 to 1024 characters	(none)	Sub GetImage (control As IRibbonControl, ByRef returnedVal)
imageMso	getImage	1 to 1024 characters	(none)	Sub GetImage (control As IRibbonControl, ByRef returnedVal)
keytip	getKeytip	1 to 3 characters	(none)	Sub GetKeytip (control As IRibbonControl, ByRef returnedVal)
label	getLabel	1 to 1024 characters	(none)	Sub GetLabel (control As IRibbonControl, ByRef returnedVal)
(none)	getPressed	true, false, 1, 0	(none)	Sub GetPressed (control As IRibbonControl, ByRef returnedVal)
screentip	getScreentip	1 to 1024 characters	(none)	Sub GetScreentip (control As IRibbonControl, ByRef returnedVal)
showImage	getShowImage	true, false, 1, 0	true	Sub GetShowImage (control As IRibbonControl, ByRef returnedVal)
showLabel	getShowLabel	true, false, 1, 0	true	Sub GetShowLabel (control As IRibbonControl, ByRef returnedVal)
size	getSize	normal, large	normal	Sub GetSize (control As IRibbonControl, ByRef returnedVal)
supertip	getSupertip	1 to 1024 characters	(none)	Sub GetSupertip (control As IRibbonControl, ByRef returnedVal)
tag	(none)	1 to 1024 characters	(none)	(none)
visible	getVisible	true, false, 1, 0	true	Sub GetVisible (control As IRibbonControl, ByRef returnedVal)

Using Built-in toggleButton Controls

The following example adds four built-in toggleButtons to a custom tab. The horizontal box contains the Bold, Italic, Underline and Double Underline toggleButton controls.

This is specified using the following XML:

<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
	<!-- true: show only your tab in Excel -->
	<ribbon startFromScratch="true">
		<tabs>
			<tab id="customTab"
			     label="Custom Tab">
				<group id="customGroup"
				       label="Custom Group">
					<box id="box"
					     boxStyle="horizontal">
						<toggleButton idMso="Bold"/>
						<toggleButton idMso="Italic"/>
						<toggleButton idMso="Underline"/>
						<toggleButton idMso="UnderlineDouble"/>
					</box>
				</group>
			</tab>
		</tabs>
	</ribbon>
</customUI>

Creating Custom toggleButton Controls

The following example creats an toggleButton that enables the user to switch from the Page Break view in Excel.

XML

Copy and paste the following XML code into customUI14.xml:

<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui"
          onLoad="IRibbonUI_onLoad">
	<!--true: show only your tab in Excel-->
	<ribbon startFromScratch="true">
		<tabs>
			<tab id="customTab"
			     label="Custom Tab">
				<group id="customGroup"
				       label="Custom Group">
					<toggleButton id="PageBreakPreview"
					              imageMso="ViewPageBreakPreviewView"
					              label="Page Break Preview"
					              keytip="I"
					              size="large"
					              getPressed="PageBreakPreview_getPressed"
					              onAction="PageBreakPrevie_Action"/>
				</group>
			</tab>
		</tabs>
	</ribbon>
</customUI>

VBA

Copy and paste the following VBA code into a normal module:

'------------------ Modules ------------------

Option Explicit

Public MyRibbon As IRibbonUI

'Callback for customUI.onLoad
Sub IRibbonUI_onLoad(ribbon As IRibbonUI)
    Set MyRibbon = ribbon
End Sub

'Callback for PageBreakPreview getPressed
Sub PageBreakPreview_getPressed(control As IRibbonControl, ByRef returnedVal)
    If ActiveWindow.View = xlPageBreakPreview Then returnedVal = True
End Sub

'Callback for PageBreakPrevie onAction
Sub PageBreakPrevie_Action(control As IRibbonControl, pressed As Boolean)
    Select Case pressed
        Case True
            ActiveWindow.View = xlPageBreakPreview
        Case False
            ActiveWindow.View = xlNormalView
    End Select
End Sub

Copy and paste the following VBA code into ThisWorkbook:

'------------------ ThisWorkbook ------------------
Option Explicit

Private Sub Workbook_SheetActivate(ByVal Sh As Object)
    'Invalidate the tab each time a worksheet is activated
    MyRibbon.InvalidateControl ("PageBreakPreview") ' Invalidates the cache of a single control
End Sub

Download

Download Custom toggleButton Demo.