Difference between revisions of "Creating our first button in VBA"

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Adding a handler for the button's onAction delegate)
(→‎Complete Example Code)
 
(2 intermediate revisions by the same user not shown)
Line 102: Line 102:
 
*# Right-click inside the callback name string ("MyCallback" here)
 
*# Right-click inside the callback name string ("MyCallback" here)
 
*# Follow the path 'Ribbon Commander'->'Insert Delegate Stubs'->'Insert [rxButton.onAction] stub':
 
*# Follow the path 'Ribbon Commander'->'Insert Delegate Stubs'->'Insert [rxButton.onAction] stub':
−
*#: [[image: InsertDelegateStub.png|link=]]
+
*#: [[image: InsertDelegateStub_ILYDA_UK.PNG|link=]]
 
*# This will insert an empty stub right below the current function:
 
*# This will insert an empty stub right below the current function:
  
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
−
Sub MyCallback(ByVal control As DynamicRibbonX.IRibbonControl)
+
Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
 
     Err.Raise &H80004001, , "Not implemented"
 
     Err.Raise &H80004001, , "Not implemented"
 
End Sub
 
End Sub
Line 113: Line 113:
 
* The delegate stub currently raises and error. Update it to display a message box instead:
 
* The delegate stub currently raises and error. Update it to display a message box instead:
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
−
Sub MyCallback(ByVal control As DynamicRibbonX.IRibbonControl)
+
Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
 
     MsgBox "Hello, world!"
 
     MsgBox "Hello, world!"
 
End Sub
 
End Sub
Line 132: Line 132:
 
[[rxButton]] has a number of [[rxButton#Delegates|delegate properties]] which allow you to hook up callbacks to events of the control. One of them is onAction which is called when the button is clicked.
 
[[rxButton]] has a number of [[rxButton#Delegates|delegate properties]] which allow you to hook up callbacks to events of the control. One of them is onAction which is called when the button is clicked.
  
−
In the Dynamic RibbonX framework, delegates are of type [[rxDelegate]] and are always associated with (and [[Method create|created]] via) a unique [[rxCustomUI]] instance.
+
In the Ribbon Commander Framework, delegates are of type [[rxDelegate]] and are always associated with (and [[Method create|created]] via) a unique [[rxCustomUI]] instance.
  
 
Here, we create a new [[rxDelegate]] object for a VBA function named 'MyCallback' through our rxCustomUI's [[Method make_delegate | make_delegate]] method and connect the new object with our button (through its onAction property)
 
Here, we create a new [[rxDelegate]] object for a VBA function named 'MyCallback' through our rxCustomUI's [[Method make_delegate | make_delegate]] method and connect the new object with our button (through its onAction property)
Line 189: Line 189:
  
  
−
Sub MyCallback(ByVal control As DynamicRibbonX.IRibbonControl)
+
Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
 
     MsgBox "Hello, world!"
 
     MsgBox "Hello, world!"
 
End Sub
 
End Sub
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 11:04, 12 January 2015

Prerequisites

We recommend you go though A 'hello world' VBA program before going into this example.

Creating a button

  • Enter the code below in a standard VBA module
  1. Public Sub CreateMyUI3()
  2.  
  3.     Dim myCustomUI As rxCustomUI
  4.     Set myCustomUI = rxCustomUI.defaultInstance
  5.  
  6.     With myCustomUI
  7.         ' Clear old state
  8.         .Clear
  9.  
  10.         ' Add a new tab
  11.         With .ribbon.tabs.Add(New rxTab)
  12.             .Label = "My First Tab"
  13.             ' Add a new group to our tab
  14.             With .groups.Add(New rxGroup)
  15.                 .Label = "My Group"
  16.  
  17.                 ' Add a new button to our group
  18.                 With .Buttons.Add(New rxButton)
  19.                     .Label = "My Button"
  20.                 End With
  21.  
  22.             End With
  23.         End With
  24.  
  25.         ' Render the UI
  26.         .Refresh
  27.     End With
  28.  
  29. End Sub
  • Run the sub to create a button labeled 'My Button' (which belongs to a group labeled 'My Group' which, in turn' belongs to a tab labeled 'My Tab')
    FirstButton.png

Code Analysis I

  1. ' Add a new group to our tab
  2. With .groups.Add(New rxGroup)
  3.     .Label = "My Group"
  4.     '...
  5. End With

Each rxTab object has a collection of rxGroup objects (accessible through its groups property). Here we add a new group to our tab's groups and label it 'My Group' 


  1. ' Add a new button to our group
  2. With .Buttons.Add(New rxButton)
  3.     .Label = "My Button"                    
  4. End With

Each rxGroup object has a collection of rxButton objects (accesible through its buttons property). Here we add a new button to our group's buttons and label it 'My Button'

Adding a handler for the button's onAction delegate

At the moment the new button isn't of much use as it does nothing when clicked. In this section we will hook up to the control's onAction delegate.

  • Update the sub as follows
  1. Public Sub CreateMyUI3()
  2.  
  3.     Dim myCustomUI As rxCustomUI
  4.     Set myCustomUI = rxCustomUI.defaultInstance
  5.  
  6.     With myCustomUI
  7.         ' Clear old state
  8.         .Clear
  9.  
  10.         ' Add a new tab
  11.         With .ribbon.tabs.Add(New rxTab)
  12.             .Label = "My First Tab"
  13.             ' Add a new group to our tab
  14.             With .groups.Add(New rxGroup)
  15.                 .Label = "My Group"
  16.  
  17.                 ' Add a new button to our group
  18.                 With .Buttons.Add(New rxButton)
  19.                     .Label = "My Button"
  20.                     ' Hook up the control's onAction delegate
  21.                     .onAction = myCustomUI.make_delegate("MyCallback")
  22.                 End With
  23.  
  24.             End With
  25.         End With
  26.  
  27.         ' Render the UI
  28.         .Refresh
  29.     End With
  30.  
  31. End Sub
  • We have now hooked up the control's onAction delegate with a function called MyCallback, which we haven't yet provided.
  • We can now either manually provide a delegate stub function with the correct name and signature, or make use of the Ribbon Commander VBA tools to insert it automatically:
    1. Right-click inside the callback name string ("MyCallback" here)
    2. Follow the path 'Ribbon Commander'->'Insert Delegate Stubs'->'Insert [rxButton.onAction] stub':
      InsertDelegateStub ILYDA UK.PNG
    3. This will insert an empty stub right below the current function:
Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
    Err.Raise &H80004001, , "Not implemented"
End Sub
  • Run the updated sub (CreateMyUI3).
  • The delegate stub currently raises and error. Update it to display a message box instead:
Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
    MsgBox "Hello, world!"
End Sub
  • If everything has gone according to plan, clicking the button will now display:
    HelloWorldMsgBoxVBA.png

Code Analysis II

  1. ' Add a new button to our group
  2. With .Buttons.Add(New rxButton)
  3.     .Label = "My Button"
  4.     ' Hook up the control's onAction delegate
  5.     .onAction = myCustomUI.make_delegate("MyCallback")
  6. End With

rxButton has a number of delegate properties which allow you to hook up callbacks to events of the control. One of them is onAction which is called when the button is clicked.

In the Ribbon Commander Framework, delegates are of type rxDelegate and are always associated with (and created via) a unique rxCustomUI instance.

Here, we create a new rxDelegate object for a VBA function named 'MyCallback' through our rxCustomUI's make_delegate method and connect the new object with our button (through its onAction property)

We can also write the snippet in a more verbose way: 

' Add a new button to our group
With .Buttons.Add(New rxButton)
    .Label = "My Button"
 
    ' Create a new delegate for VBA function 'MyCallback'
    Dim myDelegate As rxDelegate
    Set myDelegate = myCustomUI.make_delegate("MyCallback")
 
    ' Hook up the control's onAction delegate
    .OnAction = myDelegate
End With

Remarks

Complete Example Code

  1. Public Sub CreateMyUI3()
  2.  
  3.     Dim myCustomUI As rxCustomUI
  4.     Set myCustomUI = rxCustomUI.defaultInstance
  5.  
  6.     With myCustomUI
  7.         ' Clear old state
  8.         .Clear
  9.  
  10.         ' Add a new tab
  11.         With .ribbon.tabs.Add(New rxTab)
  12.             .Label = "My First Tab"
  13.             ' Add a new group to our tab
  14.             With .groups.Add(New rxGroup)
  15.                 .Label = "My Group"
  16.  
  17.                 ' Add a new button to our group
  18.                 With .Buttons.Add(New rxButton)
  19.                     .Label = "My Button"
  20.  
  21.                     ' Hook up the control's onAction delegate
  22.                     .OnAction = myCustomUI.make_delegate("MyCallback")
  23.                 End With
  24.  
  25.             End With
  26.         End With
  27.  
  28.         ' Render the UI
  29.         .Refresh
  30.     End With
  31.  
  32. End Sub
  33.  
  34.  
  35. Sub MyCallback(ByVal control As RibbonCommander.IRibbonControl)
  36.     MsgBox "Hello, world!"
  37. End Sub
Retrieved from ‘https://documentation.ribboncommander.com/index.php?title=Creating_our_first_button_in_VBA&oldid=4161’