Difference between revisions of "Method make delegate"

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Remarks)
(→‎Remarks)
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Description ==
 
== Description ==
−
Creates a new [[rxDelegate]] object associated to a callback function and owned by the [[rxCustomUI]] instance.
+
Creates a new [[rxDelegate]] object associated with a callback function and owned by the [[rxCustomUI]] instance.
  
 
== Parameters ==
 
== Parameters ==
−
=== Generic Form ===
+
=== rxCustomUI.make_delegate(string) -> rxDelegate ===
 
{{FuncTableBegin}}
 
{{FuncTableBegin}}
 
{{FuncTableEntry | name=methodName | type=string | value=''[none]'' | desc=The name of the target callback function}}
 
{{FuncTableEntry | name=methodName | type=string | value=''[none]'' | desc=The name of the target callback function}}
Line 9: Line 9:
 
{{FuncTableEnd}}
 
{{FuncTableEnd}}
  
−
=== .NET Delegate Override ===
+
=== rxCustomUI.make_delegate(Delegate) -> rxDelegate ===
 
{{FuncTableBegin}}
 
{{FuncTableBegin}}
 
{{FuncTableEntry | name=callbackDelegate | type=Delegate | value=''[none]'' | desc=An instance of a .NET delegate used to dispatch the callback}}
 
{{FuncTableEntry | name=callbackDelegate | type=Delegate | value=''[none]'' | desc=An instance of a .NET delegate used to dispatch the callback}}
Line 17: Line 17:
 
== Remarks ==
 
== Remarks ==
 
# (VBA-specific) If the [[rxCustomUI]] object has [[rxDispatchScope | global dispatch scope]], the target function needs to be a global member of a standard VBA module
 
# (VBA-specific) If the [[rxCustomUI]] object has [[rxDispatchScope | global dispatch scope]], the target function needs to be a global member of a standard VBA module
−
# (VBA-specific) If the [[rxCustomUI]] object has [[rxDispatchScope | local dispatch scope]], the target function needs to be a public member of the VBA class which is used to instantiate the dispatch object (see [[#VBA | VBA Examples]])
+
# Otherwise the target function needs to be a public method of the object used as the [[rxCustomUI]]'s [[Property dispatchObject | dispatch object]].
 +
# (.NET-specific) By using the second method override, Native .NET delegates can be used to instantiate [[rxDelegate]] objects. There is a *Delegates class for every Ribbon Commander control in namespace LogismiX.DynamicRibbonX.Core that specifies the callback signature of every callback (see [[#Examples|Examples]]), e.g. class rxButtonDelegates contains all delegates of rxButton.
  
 
== Examples ==
 
== Examples ==
  
 
=== VBA ===
 
=== VBA ===
−
<syntaxhighlight lang="vb" line>
+
 
 +
==== Global dispatch ====
 +
<syntaxhighlight lang="vb" line highlight="24">
 +
Public Sub MakeDelegateTest()
 +
   
 +
    ' Create a new rxCustomUI with global dispatch scope
 +
    Dim myCustomUI As rxCustomUI
 +
    Set myCustomUI = rxCustomUI.Create("my_custom_context", , DispatchScope_global)
 +
   
 +
    With myCustomUI
 +
        ' Clear old state
 +
        .Clear
 +
       
 +
        ' Add new tab and label it 'My Tab'
 +
        With .ribbon.tabs.Add(New rxTab)
 +
            .Label = "My Tab"
 +
            ' Add new group and label it 'My Group'
 +
            With .groups.Add(New rxGroup)
 +
               
 +
                ' Add a new button and label it 'Click Me!'
 +
                Dim myButton As rxButton
 +
                Set myButton = .Buttons.Add(New rxButton)
 +
               
 +
                myButton.Label = "Click Me!"
 +
               
 +
                ' Add a delegate that dispatches to a function with name 'MyCallbackFunc'
 +
                myButton.OnAction = myCustomUI.make_delegate("MyCallbackFunc")
 +
               
 +
            End With
 +
           
 +
        End With
 +
   
 +
        'Render the UI
 +
        .Refresh
 +
       
 +
    End With
 +
   
 +
End Sub
 +
 
 +
' The callback stub
 +
Public Sub MyCallbackFunc(ByVal control As DynamicRibbonX.IRibbonControl)
 +
    MsgBox "Button clicked!"
 +
End Sub
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
See also: [[Creating our first button in VBA]], [[Creating an rxCustomUI object with global dispatch scope in VBA]]
 +
 +
==== Local dispatch ====
 +
<syntaxhighlight lang="vb" line highlight="27">
 +
'
 +
' in class clsMyUI
 +
'
 +
Private m_customUI As rxCustomUI
 +
 +
Private Sub Class_Initialize()
 +
   
 +
    ' Instantiate a local dispatch rxCustomUI
 +
    Set m_customUI = rxCustomUI.Create("my_local_disp_ctxt", , DispatchScope_local)
 +
   
 +
    With m_customUI
 +
        .Clear
 +
   
 +
        ' IMPORTANT: We need to specify a dispatch object through which callbacks are dispatched
 +
        '            Here we have chosen to use the same class for the UI and the callbacks, which
 +
        '            is convenient but also means we need to use the *_weakRef version of the method
 +
        '            to avoid circular references.
 +
        Set .dispatchObject_weakRef = Me
 +
       
 +
        With .ribbon.tabs.Add(New rxTab)
 +
            .Label = "Local Dispatch Tab"
 +
            With .groups.Add(New rxGroup)
 +
                .Label = "Local Dispatch Group"
 +
               
 +
                With .Buttons.Add(New rxButton)
 +
                    .Label = "Local Dispatch Button"
 +
                    .OnAction = m_customUI.make_delegate("LocalDispCallback")
 +
                End With
 +
               
 +
            End With
 +
           
 +
        End With
 +
       
 +
        .Refresh
 +
    End With
 +
   
 +
End Sub
 +
 +
' The callback stub
 +
' NOTE: Notice it is a public method of the rxCustomUI's dispatch object, which happens to
 +
'      be this class here
 +
Sub LocalDispCallback(ByVal control As DynamicRibbonX.IRibbonControl)
 +
    MsgBox "Called through local dispatch!"
 +
End Sub
 +
</syntaxhighlight>
 +
 +
See also: [[Creating an rxCustomUI object with local dispatch scope in VBA]]
  
 
=== C# ===
 
=== C# ===
−
<syntaxhighlight lang="csharp" line>
+
<syntaxhighlight lang="csharp" line highlight="21">
 +
class rxBackstageEditBox_delegates_tests
 +
{
 +
    private rxCustomUI _customUI;
 +
   
 +
    // ctor
 +
    public rxBackstageEditBox_delegates_tests()
 +
    {
 +
        _customUI = rxCustomUI.create("my_cs_context");
 +
        _customUI.clear();
 +
 
 +
        _customUI.backstage.tabs.add(new rxBackstageTab
 +
        {
 +
            label = "rxBackstageEditBox - DELEGATES TESTS"
 +
        })
 +
        .firstColumn.groups.add(new rxBackstageGroup
 +
        {
 +
            label = "rxBackstageEditBox test group"
 +
        })
 +
        .topItems.editBoxes.add(new rxBackstageEditBox
 +
        {
 +
            onChange = _customUI.make_delegate(new rxBackstageEditBoxDelegates.onChange(OnChange))
 +
        });
 +
 
 +
        _customUI.refresh();
 +
           
 +
    }
 +
 
 +
    // The callback stub
 +
    private void OnChange(IRibbonControl control, string text)
 +
    {
 +
        System.Diagnostics.Debug.WriteLine("OnChange() called...");
 +
        MessageBox.Show("Text change :[" + text + "]");
 +
    }
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
=== VB.NET ===
 
=== VB.NET ===
−
<syntaxhighlight lang="vb" line>
+
<syntaxhighlight lang="vb" line highlight="20">
 +
 
 +
    Public Sub New()
 +
        _customUI = rxCustomUI.create("my_vb_context")
 +
        With _customUI
 +
            .clear()
 +
            With .ribbon.tabs.add(New rxTab)
 +
                .label = "rxDropDownRegular - DELEGATES TESTS"
 +
                With .groups.add(New rxGroup)
 +
                    .label = "My Group"
 +
                   
 +
                    ' Add a new drop-down to the group
 +
                    With .dropDowns.add(New rxDropDownRegular)
 +
                       
 +
                        ' Add a few items and buttons to the drop-down
 +
                        .items.add(New rxItem).label = "DummyItem1"
 +
                        .items.add(New rxItem).label = "DummyItem2"
 +
                        .buttons.add(New rxButtonRegular).label = "DummyButton1"
 +
                        .buttons.add(New rxButtonRegular).label = "DummyButton2"
 +
 
 +
                        ' Register an 'onAction' callback
 +
                        .onAction = _customUI.make_delegate(New rxDropDownRegularDelegates.onAction(AddressOf OnAction))
 +
                    End With
 +
                End With
 +
            End With
 +
 
 +
            .refresh()
 +
        End With
 +
    End Sub
 +
   
 +
    ' The callback stub
 +
    Private Sub OnAction(control As LogismiX.Interop.DynamicRibbonX.IRibbonControl, ByRef itemID As String, itemIndex As Integer)
 +
        System.Diagnostics.Debug.Print("OnAction() called...")
 +
 
 +
        Dim sLabel As String = vbNullString
 +
 
 +
        Dim item As rxItem = _customUI.ribbonXControls.getItemIfExists(itemID)
 +
        If Not (item Is Nothing) Then
 +
            sLabel = item.label
 +
        End If
 +
 
 +
        MsgBox("Item with label=[" & IIf(Len(sLabel) > 0, sLabel, "[unknown]") & "] and index=[" & itemIndex & "] clicked.")
 +
    End Sub
 +
 
 +
End Class
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Latest revision as of 20:45, 19 October 2013

Description

Creates a new rxDelegate object associated with a callback function and owned by the rxCustomUI instance.

Parameters

rxCustomUI.make_delegate(string) -> rxDelegate

Parameter Name
Parameter Type
Default Value
Description
methodName string [none] The name of the target callback function
return rxDelegate [none] The newly created rxDelegate

rxCustomUI.make_delegate(Delegate) -> rxDelegate

Parameter Name
Parameter Type
Default Value
Description
callbackDelegate Delegate [none] An instance of a .NET delegate used to dispatch the callback
return rxDelegate [none] The newly created rxDelegate

Remarks

  1. (VBA-specific) If the rxCustomUI object has global dispatch scope, the target function needs to be a global member of a standard VBA module
  2. Otherwise the target function needs to be a public method of the object used as the rxCustomUI's dispatch object.
  3. (.NET-specific) By using the second method override, Native .NET delegates can be used to instantiate rxDelegate objects. There is a *Delegates class for every Ribbon Commander control in namespace LogismiX.DynamicRibbonX.Core that specifies the callback signature of every callback (see Examples), e.g. class rxButtonDelegates contains all delegates of rxButton.

Examples

VBA

Global dispatch

  1. Public Sub MakeDelegateTest()
  2.  
  3.     ' Create a new rxCustomUI with global dispatch scope
  4.     Dim myCustomUI As rxCustomUI
  5.     Set myCustomUI = rxCustomUI.Create("my_custom_context", , DispatchScope_global)
  6.  
  7.     With myCustomUI
  8.         ' Clear old state
  9.         .Clear
  10.  
  11.         ' Add new tab and label it 'My Tab'
  12.         With .ribbon.tabs.Add(New rxTab)
  13.             .Label = "My Tab"
  14.             ' Add new group and label it 'My Group'
  15.             With .groups.Add(New rxGroup)
  16.  
  17.                 ' Add a new button and label it 'Click Me!'
  18.                 Dim myButton As rxButton
  19.                 Set myButton = .Buttons.Add(New rxButton)
  20.  
  21.                 myButton.Label = "Click Me!"
  22.  
  23.                 ' Add a delegate that dispatches to a function with name 'MyCallbackFunc'
  24.                 myButton.OnAction = myCustomUI.make_delegate("MyCallbackFunc")
  25.  
  26.             End With
  27.  
  28.         End With
  29.  
  30.         'Render the UI
  31.         .Refresh
  32.  
  33.     End With
  34.  
  35. End Sub
  36.  
  37. ' The callback stub
  38. Public Sub MyCallbackFunc(ByVal control As DynamicRibbonX.IRibbonControl)
  39.     MsgBox "Button clicked!"
  40. End Sub

See also: Creating our first button in VBA, Creating an rxCustomUI object with global dispatch scope in VBA

Local dispatch

  1. '
  2. ' in class clsMyUI
  3. '
  4. Private m_customUI As rxCustomUI
  5.  
  6. Private Sub Class_Initialize()
  7.  
  8.     ' Instantiate a local dispatch rxCustomUI
  9.     Set m_customUI = rxCustomUI.Create("my_local_disp_ctxt", , DispatchScope_local)
  10.  
  11.     With m_customUI
  12.         .Clear
  13.  
  14.         ' IMPORTANT: We need to specify a dispatch object through which callbacks are dispatched
  15.         '            Here we have chosen to use the same class for the UI and the callbacks, which
  16.         '            is convenient but also means we need to use the *_weakRef version of the method
  17.         '            to avoid circular references.
  18.         Set .dispatchObject_weakRef = Me
  19.  
  20.         With .ribbon.tabs.Add(New rxTab)
  21.             .Label = "Local Dispatch Tab"
  22.             With .groups.Add(New rxGroup)
  23.                 .Label = "Local Dispatch Group"
  24.  
  25.                 With .Buttons.Add(New rxButton)
  26.                     .Label = "Local Dispatch Button"
  27.                     .OnAction = m_customUI.make_delegate("LocalDispCallback")
  28.                 End With
  29.  
  30.             End With
  31.  
  32.         End With
  33.  
  34.         .Refresh
  35.     End With
  36.  
  37. End Sub
  38.  
  39. ' The callback stub
  40. ' NOTE: Notice it is a public method of the rxCustomUI's dispatch object, which happens to
  41. '       be this class here
  42. Sub LocalDispCallback(ByVal control As DynamicRibbonX.IRibbonControl)
  43.     MsgBox "Called through local dispatch!"
  44. End Sub

See also: Creating an rxCustomUI object with local dispatch scope in VBA

C#

  1. class rxBackstageEditBox_delegates_tests
  2. {
  3.     private rxCustomUI _customUI;
  4.  
  5.     // ctor
  6.     public rxBackstageEditBox_delegates_tests()
  7.     {
  8.         _customUI = rxCustomUI.create("my_cs_context");
  9.         _customUI.clear();
  10.  
  11.         _customUI.backstage.tabs.add(new rxBackstageTab
  12.         {
  13.             label = "rxBackstageEditBox - DELEGATES TESTS"
  14.         })
  15.         .firstColumn.groups.add(new rxBackstageGroup
  16.         {
  17.             label = "rxBackstageEditBox test group"
  18.         })
  19.         .topItems.editBoxes.add(new rxBackstageEditBox
  20.         {
  21.             onChange = _customUI.make_delegate(new rxBackstageEditBoxDelegates.onChange(OnChange))
  22.         });
  23.  
  24.         _customUI.refresh();
  25.  
  26.     }
  27.  
  28.     // The callback stub
  29.     private void OnChange(IRibbonControl control, string text)
  30.     {
  31.         System.Diagnostics.Debug.WriteLine("OnChange() called...");
  32.         MessageBox.Show("Text change :[" + text + "]");
  33.     }
  34. }

VB.NET

  1.     Public Sub New()
  2.         _customUI = rxCustomUI.create("my_vb_context")
  3.         With _customUI
  4.             .clear()
  5.             With .ribbon.tabs.add(New rxTab)
  6.                 .label = "rxDropDownRegular - DELEGATES TESTS"
  7.                 With .groups.add(New rxGroup)
  8.                     .label = "My Group"
  9.  
  10.                     ' Add a new drop-down to the group
  11.                     With .dropDowns.add(New rxDropDownRegular)
  12.  
  13.                         ' Add a few items and buttons to the drop-down
  14.                         .items.add(New rxItem).label = "DummyItem1"
  15.                         .items.add(New rxItem).label = "DummyItem2"
  16.                         .buttons.add(New rxButtonRegular).label = "DummyButton1"
  17.                         .buttons.add(New rxButtonRegular).label = "DummyButton2"
  18.  
  19.                         ' Register an 'onAction' callback 
  20.                         .onAction = _customUI.make_delegate(New rxDropDownRegularDelegates.onAction(AddressOf OnAction))
  21.                     End With
  22.                 End With
  23.             End With
  24.  
  25.             .refresh()
  26.         End With
  27.     End Sub
  28.  
  29.     ' The callback stub
  30.     Private Sub OnAction(control As LogismiX.Interop.DynamicRibbonX.IRibbonControl, ByRef itemID As String, itemIndex As Integer)
  31.         System.Diagnostics.Debug.Print("OnAction() called...")
  32.  
  33.         Dim sLabel As String = vbNullString
  34.  
  35.         Dim item As rxItem = _customUI.ribbonXControls.getItemIfExists(itemID)
  36.         If Not (item Is Nothing) Then
  37.             sLabel = item.label
  38.         End If
  39.  
  40.         MsgBox("Item with label=[" & IIf(Len(sLabel) > 0, sLabel, "[unknown]") & "] and index=[" & itemIndex & "] clicked.")
  41.     End Sub
  42.  
  43. End Class

C++

  1.  
Retrieved from ‘https://documentation.ribboncommander.com/index.php?title=Method_make_delegate&oldid=2961’