Control Callbacks

Most RibbonX customization can be defined at design-time and can thereby be included directly within the XML file. If, however, there are some attributes that need to be set at startup or can change at run time, you can use the equivalent get attribute to provide the name of a callback function. When Excel starts, it calls the function and the function provides the value of the attribute. Unlike the OnAction calls you're used to, Excel does not automatically scope the callback to the workbook containing the RibbonX definition; if multiple workbooks contain a procedure with the same callback name, there is no guarantee which one will be called!

For example, the following line was originally included in the XML to hard code the group label: <group id="rxAuditMisc" label="Miscellaneous">

To use a callback instead, add the following VBA procedure to the Auditing.xlam workbook to provide the label at run time. The VBA procedure's parameters must match those that RibbonX expects to provide. Most of them pass in a reference to the RibbonX control and a ByRef parameter for the return value:

Sub

rxAuditMisc_

_getLabel(ByRef Control As IRibbonControl, _

ByRef ReturnValue As Variant)

ReturnValue

= "Miscellaneous - " & Format(Date, "dddd")

End

Sub

Save the add-in, unload it, and use the Custom UI Editor to change the RibbonX XML to use the getLabel attribute, calling the procedure you just added:

<group id="rxAuditMisc" getLabel="rxAuditMisc_getLabel">

If you reload the add-in and click the Auditing tab, the first group should now include the day of the week in its name.

The Control reference passed into the callback is an extremely simple object, having only three read-only properties and no methods:

□ tag—The control's tag attribute, if defined in the XML

The id property can be used to distinguish between controls if you specify a common callback name for multiple controls. For example, in a multilingual application, you could include getLabel="rxGetLabel" in the definition for all controls and read the appropriate text from a language lookup table, matching on the control ID:

Sub rxGetLabel(ByRef Control As IRibbonControl, _ ByRef ReturnValue As Variant)

ReturnValue = Application.WorksheetFunction.VLookup(Control.ID, _ shtLanguages.Range("rngLabels"), glLanguagelD, False)

End Sub

ReturnValue = Application.WorksheetFunction.VLookup(Control.ID, _ shtLanguages.Range("rngLabels"), glLanguagelD, False)

End Sub

In addition to the get equivalents of all the design-time attributes, the following control callbacks are available only at run time.

Callback

Used By

Description

getContent

dynamicMenu

Provides the XML for the menu's content.

getPressed

toggleButton, checkBox

Specifies whether or not the control is pressed/ticked.

getItemCount

comboBox, dropdown, gallery

Specifies how many items there are in a list populated at run time.

getItemID, getItemLabel, getItemImage, getItemScreentip, getItemSupertip

comboBox, dropdown, gallery

Called once for each item, to provide the attributes for that item.

getSelectedItemID

dropdown, gallery

Specifies which is the selected item, by providing the item's ID.

getSelectedItemIndex

dropdown, gallery

Specifies which is the selected item, by providing the item's index in the list.

getText

comboBox, editBox

Provides the text shown in the control

onAction

button, toggleButton, checkBox, dropdown, gallery

Called when the control is clicked. Note that the signatures are different depending on the control (see the following table).

onChange

editBox, comboBox

Called when the text of the control has changed.

The following tables show the function signatures for all the available control callbacks. If you use the Office 2007 Custom UI Editor, it can generate the correct callback signatures for any callbacks included in the XML, ready for you to paste into your VBA project.

Callback

getContent, getDescription,getEnabled, getlmage, getltemCount, getltemHeight, getltemWidth, getKeytip, getLabel, getPressed, getSize, getScreentip, getSelectedltemID, getSelectedltemlndex, getShowlmage, getShowLabel, getSupertip, getText, getTitle, getVisible

Signature

Sub ProcName(ByRef Control As IRibbonControl, _ ByRef ReturnValue As Variant)

Callback

getItemID, getItemImage, getItemLabel, getItemScreentip, getItemSupertip

Signature

Sub ProcName(ByRef Control As IRibbonControl,

ByRef Index As Integer,__

ByRef ReturnValue As Variant)

Callback

onAction for a button control

Signature

Sub ProcName(ByRef Control As IRibbonControl)

Callback

onAction for a checkBox and toggleButton control

Signature

Sub ProcName(ByRef Control As IRibbonControl, ByRef Pressed As Boolean)

Callback

onAction for a dropDown and gallery control

Signature

Sub ProcName(ByRef Control As IRibbonControl, ByRef SelectedIDAs String, _ ByRef SelectedIndex As Integer)

Callback

onChange for an editBox or comboBox

Signature

Sub ProcName(ByRef Control As IRibbonControl, _ ByRef Text As String)

+2 -1

Responses

Post a comment