Creating an rxCustomUI object with local dispatch scope in VBA
From Ribbon Commander Documentation
Revision as of 10:01, 21 October 2013 by Rxdff15551 bb53 (Talk | contribs) (→Creating a new local context with a drop down)
Contents
Prerequisites
We recommend you go through Creating our first button in VBA before getting into this example.
Background
In previous examples we worked with the default rxCustomUI instance of the current session. This is fine for example code, but in real life it is preferable that each add-in/application creates its own context (or virtual add-in) to isolate its UI from other add-ins/applications.
The framework currently supports up to 1000 contexts/session so there are enough contexts to go around!
In VBA you can create rxCustomUI objects with two types of dispatch scopes (see rxCustomUI.create, make_delegate):
- Global dispatch. Intended to be used with VBA standard modules. Delegates created by the rxCustomUI object dispatch to public functions in standard VBA modules. The rxCustomUI object returned by the static function rxCustomUI.defaultInstance has global dispatch.
- Local context. Intended to be used with VBA classes. Delegates created by the rxCustomUI object dispatch to public methods of a user-supplied dispatch object, usually the owning class.
Creating a new local context with a drop down
- Add a new class to your VBA project and name it clsMyLocalContext
- Enter the following code to the class module
Private m_customUI As rxCustomUI
Private Sub Class_Initialize()
' Create a new local contextSet m_customUI = rxCustomUI.Create("my_local_context", "My Local Context", DispatchScope_local)
' Make the new context dispatch callbacks to member methods of this classSet m_customUI.dispatchObject_weakRef = Me' Initialize the context's UICreateUI
End Sub
' Initializes the context's UIPrivate Sub CreateUI()
With m_customUI.Clear
' Create a new tabWith .ribbon.tabs.Add(New rxTab)
.Label = "Local Ctx Tab"' Create a new groupWith .groups.Add(New rxGroup)
.Label = "Local Ctx Group"' Create a new drop downWith .DropDowns.Add(New rxDropDownRegular)
.Label = "Local Ctx Drop-down"' Add a few items to the dropdown.items.Add(New rxItem).Label = "Item1"
.items.Add(New rxItem).Label = "Item2"
.items.Add(New rxItem).Label = "Item3"
.items.Add(New rxItem).Label = "Item4"
.items.Add(New rxItem).Label = "Item5"
.OnAction = m_customUI.make_delegate("MyDropdownOnAction")End With
End With
End With
' Render the UI.Refresh
End With
End Sub
Sub MyDropdownOnAction(ByVal control As RibbonCommander.IRibbonControl, itemID As String, ByVal itemIndex As Long)
MsgBox "Item @index " & itemIndex & " clicked"
End Sub
- Add a new standard module to your VBA project and name it mMyLocalContext
- Enter the following code to the module
Private myContext As clsMyLocalContext
Public Sub ShowLocalContextUI()
Set myContext = New clsMyLocalContext
End Sub
- Run sub ShowLocalContextUI to create a new drop-down labeled Local Ctx Tab in its own local context:
Code Analysis
Private m_customUI As rxCustomUI
A member rxCustomUI variable. Notice that the m_customUI is owned by the class.
Private Sub Class_Initialize()
' Create a new local contextSet m_customUI = rxCustomUI.Create("my_local_context", "My Local Context", DispatchScope_local)
' Make the new context dispatch callbacks to member methods of this classSet m_customUI.dispatchObject_weakRef = Me' Initialize the context's UICreateUI
End Sub
This is the constructor of our class. Here we
- Instantiate member m_customUI into a new context with contextId 'my_local_context' and with local dispatch.
- Designate our class as the dispatch object for m_customUI. This is convenient as we can have both UI construction code and delegate callback code in the same class, but we need to use method dispatchObject_weakRef instead of dispatchObject to avoid creating a circular reference.
