Difference between revisions of "A 'hello world' VBA program"

From Ribbon Commander Documentation
Jump to: navigation, search
(→‎Making our code more compact)
 
(18 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
__FORCETOC__
 
== Creating a tab ==
 
== Creating a tab ==
 
* Enter the code below in a standard VBA module
 
* Enter the code below in a standard VBA module
Line 14: Line 15:
 
     ' Create a new tab
 
     ' Create a new tab
 
     Dim myTab As rxTab
 
     Dim myTab As rxTab
−
     Set myTab = myRibbon.tabs.Add(New rxTab)
+
     Set myTab = New rxTab
−
       
+
 
      
 
      
 
     ' Give the new tab a label
 
     ' Give the new tab a label
 
     myTab.Label = "My First Tab"
 
     myTab.Label = "My First Tab"
 
      
 
      
 +
    ' Add the new tab to myRibbon's tabs
 +
    myRibbon.tabs.Add myTab
 +
       
 
      
 
      
 
     ' Render the UI
 
     ' Render the UI
Line 27: Line 30:
 
</syntaxhighlight>
 
</syntaxhighlight>
 
* Run the sub to create an empty tab labeled 'My First Tab'
 
* Run the sub to create an empty tab labeled 'My First Tab'
−
*: [[image: EmptyTab.png]]
+
*: [[image: EmptyTab.png|link=]]
  
 
== Code Analysis ==
 
== Code Analysis ==
−
<syntaxhighlight lang="vb">
+
<syntaxhighlight lang="vb" line start="3">
 +
' Get a reference to the default rxCustomUI instance
 
Dim myCustomUI As rxCustomUI
 
Dim myCustomUI As rxCustomUI
 
Set myCustomUI = rxCustomUI.defaultInstance
 
Set myCustomUI = rxCustomUI.defaultInstance
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
[[rxCustomUI]] is at the top of the object model hierarchy. Here, we are holding on to the default rxCustomUI instance for the current office application session.
+
[[rxCustomUI]] is at the top of the object model hierarchy. Here, we are holding on to the default rxCustomUI instance of the current session.
  
  
 +
<syntaxhighlight lang="vb" line start="7">
 +
' Get a reference to the rxRibbon object of our rxCustomUI instance
 +
Dim myRibbon As rxRibbon
 +
Set myRibbon = myCustomUI.ribbon
 +
</syntaxhighlight>
 +
 +
Each rxCustomUI object owns a unique [[rxRibbon]] object. Here, we are holding on to the rxRibbon object of myCustomUI
 +
 +
 +
<syntaxhighlight lang="vb" line start="11">
 +
' Create a new tab
 +
Dim myTab As rxTab
 +
Set myTab = New rxTab
 +
   
 +
' Give the new tab a label
 +
myTab.Label = "My First Tab"
 +
</syntaxhighlight>
 +
 +
Here we create a new [[rxTab]] object and give it a label
 +
 +
 +
<syntaxhighlight lang="vb" line start="18">
 +
' Add the new tab to myRibbon's tabs
 +
myRibbon.tabs.Add myTab
 +
</syntaxhighlight>
 +
 +
Each [[rxRibbon]] object has a collection of [[rxTab]] objects (accessible through its .tabs property). Here we add the tab we created above to our ribbon's tabs
 +
 +
 +
<syntaxhighlight lang="vb" line start="22">
 +
' Render the UI
 +
myCustomUI.Refresh
 +
</syntaxhighlight>
 +
 +
To ensure optimal performance, UI updates always take place in two steps:
 +
# Update the target [[rxCustomUI]] state, which we have done above
 +
# Render the updated UI, which we are doing here
 +
 +
== Remarks ==
 +
This sub will create a new empty tab every time it is run. We can prevent that from happening by adding a call to rxCustomUI.clear before we start updating its state, which resets the object's state (see [[#Making our code more compact]]).
 +
To explicitly reset the state of the default rxCustomUI, you can execute the lines below in the immediate window:
 
<syntaxhighlight lang="vb">
 
<syntaxhighlight lang="vb">
−
Dim i As Long
+
rxCustomUI.defaultInstance.clear
 +
rxCustomUI.defaultInstance.refresh
 +
</syntaxhighlight>
 +
 
 +
== Making our code more compact ==
 +
The Ribbon Commander API has been specifically designed to take advantage of the 'With blocks' feature of VBA. All .add() methods return the added object, so the code of this example can be rewritten like so:
 +
 
 +
<syntaxhighlight lang="vb" line>
 +
Public Sub CreateMyUI2()
 +
   
 +
    With rxCustomUI.defaultInstance
 +
        ' Clear old state
 +
        .Clear
 +
       
 +
        With .ribbon.tabs.Add(New rxTab)
 +
            .Label = "My First Tab"
 +
        End With
 +
       
 +
        ' Render the UI
 +
        .Refresh
 +
    End With
 +
   
 +
End Sub
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 20:39, 19 October 2013

Creating a tab

  • Enter the code below in a standard VBA module
  1. Public Sub CreateMyUI()
  2.  
  3.     ' Get a reference to the default rxCustomUI instance
  4.     Dim myCustomUI As rxCustomUI
  5.     Set myCustomUI = rxCustomUI.defaultInstance
  6.  
  7.     ' Get a reference to the rxRibbon object of our rxCustomUI instance
  8.     Dim myRibbon As rxRibbon
  9.     Set myRibbon = myCustomUI.ribbon
  10.  
  11.     ' Create a new tab
  12.     Dim myTab As rxTab
  13.     Set myTab = New rxTab
  14.  
  15.     ' Give the new tab a label
  16.     myTab.Label = "My First Tab"
  17.  
  18.     ' Add the new tab to myRibbon's tabs
  19.     myRibbon.tabs.Add myTab
  20.  
  21.  
  22.     ' Render the UI
  23.     myCustomUI.Refresh
  24.  
  25. End Sub
  • Run the sub to create an empty tab labeled 'My First Tab'
    EmptyTab.png

Code Analysis

  1. ' Get a reference to the default rxCustomUI instance
  2. Dim myCustomUI As rxCustomUI
  3. Set myCustomUI = rxCustomUI.defaultInstance

rxCustomUI is at the top of the object model hierarchy. Here, we are holding on to the default rxCustomUI instance of the current session. 


  1. ' Get a reference to the rxRibbon object of our rxCustomUI instance
  2. Dim myRibbon As rxRibbon
  3. Set myRibbon = myCustomUI.ribbon

Each rxCustomUI object owns a unique rxRibbon object. Here, we are holding on to the rxRibbon object of myCustomUI 


  1. ' Create a new tab
  2. Dim myTab As rxTab
  3. Set myTab = New rxTab
  4.  
  5. ' Give the new tab a label
  6. myTab.Label = "My First Tab"

Here we create a new rxTab object and give it a label 


  1. ' Add the new tab to myRibbon's tabs
  2. myRibbon.tabs.Add myTab

Each rxRibbon object has a collection of rxTab objects (accessible through its .tabs property). Here we add the tab we created above to our ribbon's tabs 


  1. ' Render the UI
  2. myCustomUI.Refresh

To ensure optimal performance, UI updates always take place in two steps:

  1. Update the target rxCustomUI state, which we have done above
  2. Render the updated UI, which we are doing here

Remarks

This sub will create a new empty tab every time it is run. We can prevent that from happening by adding a call to rxCustomUI.clear before we start updating its state, which resets the object's state (see #Making our code more compact). To explicitly reset the state of the default rxCustomUI, you can execute the lines below in the immediate window: 

rxCustomUI.defaultInstance.clear
rxCustomUI.defaultInstance.refresh

Making our code more compact

The Ribbon Commander API has been specifically designed to take advantage of the 'With blocks' feature of VBA. All .add() methods return the added object, so the code of this example can be rewritten like so: 

  1. Public Sub CreateMyUI2()
  2.  
  3.     With rxCustomUI.defaultInstance
  4.         ' Clear old state
  5.         .Clear
  6.  
  7.         With .ribbon.tabs.Add(New rxTab)
  8.             .Label = "My First Tab"
  9.         End With
  10.  
  11.         ' Render the UI
  12.         .Refresh
  13.     End With
  14.  
  15. End Sub
Retrieved from ‘https://documentation.ribboncommander.com/index.php?title=A_%27hello_world%27_VBA_program&oldid=2931’