Microsoft Office User Interfaces

Microsoft introduced a flexible and powerful user interface system in Office 97, and this interface has remained in use through Office 2003 (and a subset remains in use in later versions). The user interface consists of various command bars, which include menu bars and toolbars. Command bars can contain menus as well as buttons. Menus can contain submenus and buttons. Submenus can contain, well, you get the idea. This system of menus, toolbars, and buttons is easily customized through the user interface and via VBA.

Here is what our add-in’s menu customizations look like. This article shows how to create these customizations.

The Microsoft Office development team at Microsoft noticed some things about the command-bar-style interface, and about how users interacted with it. The interface was becoming complicated, with three or more levels of menus and submenus existing in some places. Each application ended up with its Tools menu, a kitchen junk drawer of commands that didn’t logically fit into the other menus. Users didn’t know what all the features were, or couldn’t find them, if they were buried more than a level deep, so they kept suggesting new features which already existed. Many users also didn’t know how to clean up their interfaces, so there were too many rows of docked toolbars and too many floating toolbars obstructing the workspace.

In response to the complicated nature of the command-bar-based interface and to the inability of some users to learn to use it as intended, the Microsoft Office team gutted the interface, replacing most toolbar implementations in favor of a new Ribbon in Office 2007. The ribbon is controlled using XML instead of VBA. Instead of toolbars which are visible all or most of the time, the ribbon has a set of different tabs. These tabs contain fewer buttons, and the buttons used more tend to be larger. The tabs become visible when the Office program thinks you might want to use them, and invisible when you actually do want to use them. No parts of the new interface can be undocked, so users who didn’t know how to click the close box of a floating toolbar now have clean interfaces, while users who like dispatching toolbars and palettes to areas on the screen where they are needed have to resort to extra mouse travel distances and excess mouse clicks. The ribbon-based interface is easy to customize using the RibbonX XML dialect and related VBA callbacks, but it is practically inaccessable through the user interface. Unless, of course, you count the QAT (Quick Access Toolbar), which is like a Classic toolbar on strong sedatives. Fortunately the ability of a user to customize their own interface was resuscitated for use in Office 2010.

This article will show how to construct a simple set of Classic Excel menu and toolbar customizations using VBA. The next article in the sequence will show simple XML code and VBA callbacks for use in New Excel.

Classic Excel User Interface Code

The object model for the Office command bar system is straightforward. The CommandBars collection contains menu bars, standard toolbars, and popup menus (context or right-click menus). There is a lot of documentation of this system on the internet. This article shows a set of simple, hard-coded routines, all that is necessary for this simple add-in. There are a number of examples of more elaborate and flexible routines that use tables in Excel workbooks to define all of the interface elements to be created. John Walkenbach describes Creating Custom Menus using his MenuMakr system. I started with his system, but like any good engineer, I tweaked it beyond all recognition to create the system I use in my own add-ins and in projects for my clients.

Here is the simple code in its entirety, copied out of its code module. Explanations for selected sections of the code follow the complete listing.

''========================================================================
'' Peltier Technical Services, Inc., Copyright © 2010. All rights reserved.
''========================================================================
Option Explicit

Const sMenuName As String = "&PTS Charts"
Const sToolbars As String = "Worksheet Menu Bar|Chart Menu Bar|PTS Charts"
Const sButton As String = "PT_Plotter"
Const sOnAction As String = "PT_Plotter_Dialog"

Sub Create_PTPlotter_Menu()
  Dim ctlpop As CommandBarPopup
  Dim ctlbtn As CommandBarButton
  Dim iMenu As Long
  Dim vMenu As Variant

  Delete_PTPlotter_Menu

  vMenu = Split(sToolbars, "|")

  For iMenu = LBound(vMenu) To UBound(vMenu)
    On Error Resume Next
    If Application.CommandBars(vMenu(iMenu)) Is Nothing Then
      With Application.CommandBars.Add(vMenu(iMenu), msoBarFloating)
        .Left = Application.Left + Application.Width / 4
        .Top = Application.Top + 144
        .Visible = True
      End With
    End If
    On Error GoTo 0

    With Application.CommandBars(vMenu(iMenu))
      On Error Resume Next
      If .Type = msoBarTypeMenuBar Then
        Set ctlpop = .Controls(sMenuName)
        On Error GoTo 0
        If ctlpop Is Nothing Then
          Set ctlpop = .Controls.Add(10, 1, , , True)
          With ctlpop
            .Caption = sMenuName
            .Visible = True
          End With
        End If
        Set ctlbtn = ctlpop.Controls.Add(1, 1, , , True)
      Else
        Set ctlbtn = .Controls.Add(1, 1, , , True)
        .Visible = True
      End If

      With ctlbtn
        .Caption = sButton
        .OnAction = "'" & ThisWorkbook.Name & "'!" & sOnAction
        .TooltipText = "Create chart from arbitrary data range"
        .FaceId = 422
        .Visible = True
      End With
      Set ctlpop = Nothing
    End With
  Next
End Sub

Sub Delete_PTPlotter_Menu()
  Dim ctlpop As CommandBarPopup
  Dim ctlbtn As CommandBarControl
  Dim iMenu As Long
  Dim vMenu As Variant

  On Error Resume Next
  vMenu = Split(sToolbars, "|")

  For iMenu = LBound(vMenu) To UBound(vMenu)
    With Application.CommandBars(vMenu(iMenu))
      If .Type = msoBarTypeMenuBar Then
        Set ctlpop = .Controls(sMenuName)
        Do
          Set ctlbtn = ctlpop.Controls(sButton)
          If ctlbtn Is Nothing Then Exit Do
          ctlbtn.Delete
          Set ctlbtn = Nothing
        Loop

        If ctlpop.Controls.Count = 0 Then
          ctlpop.Delete
        End If
      Else
        Do
          Set ctlbtn = .Controls(sButton)
          If ctlbtn Is Nothing Then Exit Do
          ctlbtn.Delete
          Set ctlbtn = Nothing
        Loop

        If .Controls.Count = 0 Then
          .Delete
        End If

      End If
    End With
  Next

End Sub

Explanations

The module starts by defining a few constants. The menu name sMenuName, “&PTS Charts” has an ampersand that tells Excel to use the next character (P) as an accelerator key, that is, to activate the menu when Alt plus the next character is pressed (Alt+P). This character will appear underlined in the menu name: “PTS Charts”.

sToolBars is a pipe-delimited string of command bars which will be customized. The remaining constants list the button caption and the name of the procedure to be run when the button is clicked.

Create_PTPlotter_Menu is the routine that adds our buttons to the Classic Excel interface. The first command in this routine is Delete_PTPlotter_Menu, which removes any existing buttons from this add-in which have somehow been orphaned due to a disorderly shutdown.

The pipe-delimited string is converted into an array of command bar names. The program loops through this array, looking for command bars with each name. If such a command bar is not found, then a new standard command bar is created using that name, other wise the program continues with the found command bar.

If the command bar is a menu bar, the program looks for a menu with the indicated name. If such a menu is not found on the command bar, a new menu is created, otherwise the existing menu is used. Then the button is placed on the menu. If the command bar is a regular toolbar, the button is placed directly on the toolbar.

The caption of the button is assigned, as is the name of the procedure to run when the button is clicked. The procedure name is prepended with the workbook name in single quotes, so Excel will not confuse our procedure with a procedure with the same name in another workbook.

The button is assigned its tooltip text, which appears when the cursor passes over the button.

Built-in button image number 422 is used for the button’s icon. Display FaceIDs is a simple utility that helps you browse Excel’s button images. Not described here is the means to assign a custom button image.

Finally the button is made visible, so users can find it.

Delete_PTPlotter_Menu goes through the command bars listed in the pipe-delimited string, looking for buttons with the name used by our add-in. This is done inside Do loops, in case multiple crashes left behind multiple identical buttons. If the last button of a menu or toolbar is deleted, the empty menu or toolbar is also deleted.

Our Menu and Toolbar

The menu and toolbar customizations produced by the code above are displayed below.

The menu is on the Worksheet Menu Bar; the menu on the Chart menu Bar is the same. The PTS Charts menu and the PTS Charts toolbar already existed, with a variety of my utilities displayed, and the PT_Plotter button is added at the end of the list.

Contents: How to Build an Excel Add-In

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

Create_LblLastPt_Menu

When you run the macro to make your chart the next time, you get no chart. Instead you get an ugly error message.

That’s frustrating. All you did was record and rerun a macro. You didn’t even change the code, so at least this once, you couldn’t have messed it up. And still it crashed.

Let’s examine the macro recorder code.

Sub RecordedMacro_MakeBubbleChart()
'
' RecordedMacro_MakeBubbleChart Macro
' Macro recorded 1/26/2010 by Jon Peltier
'

'
    Charts.Add
    ActiveChart.ChartType = xlBubble
    ActiveChart.SetSourceData Source:=Sheets("Sheet1").Range("A1:C7"), _
        PlotBy:=xlColumns
    ActiveChart.Location Where:=xlLocationAsObject, Name:="Sheet1"
End Sub

The macro recorder follow the order of the Excel 2003 chart wizard, putting the chart type before the chart source data. The steps given by the recorder work fine for most chart types, but a few chart types cannot be correctly assigned until the chart has been populated with sufficient data. In particular, code which creates stock charts and bubble charts will fail if you set the chart type before the chart is populated with data.

To make the code run properly without crashing, all you need to do is switch the SetSourceData and ChartType commands. The following code works fine.

Sub RecordedMacro_MakeBubbleChart()
'
' RecordedMacro_MakeBubbleChart Macro
' Macro recorded 1/26/2010 by Jon Peltier
'

'
    Charts.Add
    ActiveChart.SetSourceData Source:=Sheets("Sheet1").Range("A1:C7"), _
        PlotBy:=xlColumns
    ActiveChart.ChartType = xlBubble
    ActiveChart.Location Where:=xlLocationAsObject, Name:="Sheet1"
End Sub

This code isn’t particularly efficient, but at least it works. You can improve it following the suggestions in How To Fix a Recorded Macro.

This error has existed in Excel from the first modern version (Excel 97) through Excel 2003. Microsoft must have received inquiries about the problem, and they addressed it with a KB article, How to Use a Visual Basic Macro to Create a Bubble Chart., which propagated through versions 5/95, 97, 2000, 2002, and 2003. The author of the article didn’t think to rearrange the two VBA commands, so he wrote a long procedure that made an XY chart, and for markers, the chart used custom AutoShape circles sized according to the bubble values. It’s a nice procedure and a nice technique to know, but also a long voyage to go such a short distance.

When Microsoft rebuilt the charting infrastructure for Excel 2007, they changed some of the code produced by the macro recorder. Here is the Excel 2007 bubble chart macro:

Sub RecordedMacro_MakeBubbleChart()
'
' RecordedMacro_MakeBubbleChart Macro
' Macro recorded 1/26/2010 by Jon Peltier
'

'
  ActiveSheet.Shapes.AddChart.Select
  ActiveChart.SetSourceData Source:=Range("'Sheet1'!$A$1:$C$5")
  ActiveChart.ChartType = xlBubble
End Sub

Excel 2007’s macro recorder has been criticized because it didn’t capture any actions that affected the new shapes which comprise the chart. But in the simple macro above, we see that some improvements were made to Excel 2007’s macro recorder:

• In earlier versions of Excel, a separate chart sheet is made, then later inserted in the worksheet. In 2007, a chart is directly added to the worksheet’s Shapes collection. That’s more efficient.
• More important, the chart type is not set until after the chart is populated with data. The error in recorded macros no longer occurs.

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

In this installment of the Build an Excel Add-In series, I will show a VBA procedure that ties together all of the pieces that we’ve built so far. This master procedure is really a short list of the other procedures that do the individual tasks.

Here is the master procedure in its entirety. Below this, the individual pieces will be explained.

Sub PT_Plotter_Dialog()

  ' GET USER SPECIFICATIONS
  ' ' Using custom dialog
  ' ' Get data range and orientation
  ' ' Get header rows and columns
  ' ' Get chart type
  ' ' Get optional chart position and size

  Dim frmPlotSetup As FPlotSetup
  Dim rChartData As Range
  Dim Orientation As XlRowCol
  Dim iHeaderRows As Long
  Dim iHeaderCols As Long
  Dim ChtType As XlChartType
  Dim rPosition As Range
  Dim bCancel As Boolean
  Dim PT_Plot As Chart

  Set frmPlotSetup = New FPlotSetup
  With frmPlotSetup
    .Show

    bCancel = .Cancel
    If Not bCancel Then
      Set rChartData = .ChartDataRange
      Orientation = .DataOrientation
      iHeaderRows = .HeaderRows
      iHeaderCols = .HeaderColumns
      ChtType = .ChartType
      Set rPosition = .ChartPosition
    End If
  End With
  Set frmPlotSetup = Nothing

  If Not bCancel Then
    Application.ScreenUpdating = False

    ' make the chart
    Set PT_Plot = PT_Plotter_Chart(rChartData, Orientation, _
        iHeaderRows, iHeaderCols, ChtType, rPosition)

    ' clean up the chart
    Set PT_Plot = CleanUpChart(PT_Plot)

    Application.ScreenUpdating = True
  End If

ExitSub:

End Sub

After the declarations, the program calls the dialog to get the user’s settings.

  ' declare a new instance of the dialog class
  ' this may be overkill, but it's done this way in PED
  Set frmPlotSetup = New FPlotSetup
  With frmPlotSetup
    ' display the dialog
    .Show

    ' execution returns here when user dismisses dialog
    ' first see whether user canceled
    bCancel = .Cancel
    If Not bCancel Then
      ' if user did not cancel, we need the information
      Set rChartData = .ChartDataRange
      Orientation = .DataOrientation
      iHeaderRows = .HeaderRows
      iHeaderCols = .HeaderColumns
      ChtType = .ChartType
      Set rPosition = .ChartPosition
    End If
  End With
  ' we're done with the form, so destroy it
  Set frmPlotSetup = Nothing

Now that we’ve retrieved the user settings, it’s time to make the chart, then clean it up.

  ' skip the rest if the user has canceled
  If Not bCancel Then
    ' prevent seizures and speed execution
    Application.ScreenUpdating = False

    ' call the PT_Plotter_Chart function, pass in user info,
    ' function returns the chart
    Set PT_Plot = PT_Plotter_Chart(rChartData, Orientation, _
        iHeaderRows, iHeaderCols, ChtType, rPosition)

    ' call the CleanUpChart function to, uh, clean up the chart
    ' pass in the chart, and it is returned in cleaned state
    Set PT_Plot = CleanUpChart(PT_Plot)

    ' turn display updating back on
    Application.ScreenUpdating = True
  End If

In the next two articles, we’ll create the user interface for Classic Excel (menu and command bar elements in Excel 2000 through 2003) and for New Excel (ribbon elements in Excel 2007 and 2010). There is some clean up to do, including modifications to make the add-in work for both Classic and new Excel, and a trick to improve the chances of compatibility with as many users as possible. Finally I will cover deployment using Inno Setup, an awesome piece of customizable freeware for packaging up your add-in.

Contents: How to Build an Excel Add-In

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

In this installment of the Build an Excel Add-In series, I will show how to create a custom dialog using a VBA UserForm, a set of controls, and related code.

Insert UserForm

The first step in building a dialog is to insert a UserForm. In the Visual Basic Editor (VBE) select the project in the Project Explorer pane, then from the Insert menu, choose UserForm.

A new window is created, containing a blank UserForm.

The UserForm is listed in the Project Explorer, in the Forms folder of the VB Project.

A UserForm actually consists of two parts: the Designer window and the Code window. The code window contains all of the VBA procedures that make the dialog work. For example, in the code window you will find the code that responds to button clicks.

When the UserForm’s window is active, the Properties window can be used to edit the properties of the UserForm. For example, the name of the UserForm has been changed from UserForm1 (below left) to FPlotSetup (below right), and the caption has been changed from UserForm1 to PT Plotter.

- -

In addition to changing properties through the Properties window, the size of the dialog can be changed by dragging the white handles on the right and bottom edge of the UserForm.

Forms Controls

The blank UserForm shown above is transformed into the fully featured dialog shown below by adding and coding a set of controls. VBA offers a range of controls, and others can be used if additional capabilities are required. Care should be taken when using controls which are not built in, because of potential deployment complications.

The controls in this dialog are listed below, in top-down and left-to-right order:

• lblChartData
• refChartData
• fraOrientation
  • optByRow
  • optByColumn
• fraHeaders
  • txtHeaderRows
  • lblHeaderRows
  • txtHeaderColumns
  • lblHeaderColumns
• fraChartType
  • optChartTypeXY
  • optChartTypeLine
  • optChartTypeBar
  • optChartTypeColumn
• lblChartPosition
• refChartPosition
• lblChartPosition2
• lblCopyright
• btnOK
• btnCancel

I have used a simple naming convention:

Three letter prefixes identify the type of control: lbl for label, ref for RefEdit, fra for frame, opt for option button, txt for text boxes, btn for command buttons (some developers use cmd for command button, but I think btn is more descriptive)). Not used in this dialog are chk for check box, mpg for multipage, lst for list box, cbo for combo box, scr for scroll bar, spn for spin button, img for image.

The purpose of each control is encoded into its name. For example, optChartTypeXY is for choosing the XY Chart Type option, refChartData is the RefEdit used to select the chart data, etc.

Controls Toolbox

When a UserForm is the active window, the Controls Toolbox appears. This is a toolbar-like window that contains VBA controls as well as other controls that you may have added.

To add a control to the dialog, click on its icon in the Controls Toolbox. When the cursor is moved over the UserForm, it changes to a cross hair and the selected icon is shown below the icon to remind you what control you’re adding. Click and drag to draw a rectangle as large as the control you are adding.

When you release the mouse, the control appears, highlighted with white resizing handles.

After a control is added, its name and other properties can be set in the Property window, just as the name and caption of the UserForm itself were set.

Labels and Text Boxes

Labels simply contain text that guides the user through the dialog. The user cannot change the caption of a label, but the caption can be controlled by code in response to certain conditions.

Text boxes allow a user to specify values which can be represented as text. These values may be numerical, but it is up to the programmer to deal with number formats of entered and displayed numbers. In our dialog, text boxes are used to specify the number of header rows and columns in the chart source data.

Frames

Frames are used to give some order to the dialog, grouping together related controls. Our dialog has three frames, containing controls for selection of data orientation, header rows and columns, and chart type.

Option Buttons and Checkboxes

Option buttons are used to let a user select from among several options. All option buttons within a frame or with the same GroupName property are grouped together, such that only one can be true (selected) at once, and changing one to true automatically changes the others in its group to false. In this frame, only the XY option is selected.

When the Line option is selected, the XY option is unselected.

Check boxes are used to let a user set a true (checked) or false (unchecked) value. In the absence of event code in the UserForm, check box values are independent of each other.

List Boxes and Combo Boxes

List boxes and combo boxes allow the user to select one or more items from a list. A list box is more user friendly because it shows the whole list (or at least a subset of the list) while the combo box only shows the selected item, unless the user clicks to expand the list.

Command Buttons

Command Buttons allow a user to initiate an action, in our case, approving or canceling the session with the dialog. Clicking the button runs code that carries out the user’s command.

RefEdit Controls

RefEdit controls allow the user to select a range of cells with the mouse. While the user is selecting cells, the UserForm shrinks to the size of the RefEdit plus the title bar. The address of the selected range appears in the RefEdit and updates as the mouse is dragged, and the size of the selected range is displayed next to the cursor.

When the mouse is released, the UserForm returns to its original size, and the address remains in the RefEdit.

Read more about the RefEdit control in Using RefEdit Controls in Excel Dialogs.

Adding Code

There is a simple way to add code to the UserForm. Double click on a control, and the UserForm’s code window opens. An empty event procedure for the default method (action) of the control is added to the code window. For example, double clicking on the OK button adds the btnOK_Click event procedure stub to the code.

You enter the code you want to run on the OK button click event into this procedure stub. The following shows a call to a function that validates the user’s selections. If selections are valid, the code hides the form, sending execution back to the procedure that showed the UserForm. If selections are invalid, the user sees a message and decides whether to continue or bail out.

Notice the two dropdowns at the top of the code window. The selected control, btnOK, is shown in the left dropdown, and the Click event is shown in the right dropdown. You can use these dropdowns to select any event that’s available for any control. It’s a good idea to use these dropdowns to define your procedures, because some events include arguments, and the dropdowns will always get the arguments correct.

For example, the KeyDown event of a text box control includes the KeyCode (the ASCII code of the key that was pressed) and the Shift (whether Shift, Alt, and/or Ctrl were down when the key was pressed) arguments. When the procedure runs, Excel passes these values into the procedure, so the code knows which key was pressed, under which shift state.

The UserForm code module can contain event procedures, as well as functions and subs that can be called by these event procedures. For example, the Validated function called by the btnOK_Click event is also found in the UserForm’s code. Procedures in the UserForm can also call procedures in other modules.

The Code Behind the Dialog

The complete listing of the Userform’s code is presented below.

The UserForm_Initialize event loads the selected range address into the RefEdit.

The Validated function checks the RefEdit for a valid range and the header text boxes for valid numbers of header rows and columns.

The various property procedures are used called by the main routine to extract information from the UserForm. I wrote about this technique in Property Procedures – Passing Information to and from Forms.

The mbCancel variable is True if the Cancel button is clicked. The Cancel property checks this variable and tells the main routine if the user canceled the dialog.

Option Explicit

Private mbCancel As Boolean

Private Sub btnCancel_Click()
  mbCancel = True
  Me.Hide
End Sub

Private Sub btnOK_Click()
  Dim sMessage As String
  Dim lResponse As VbMsgBoxResult

  If Validated(sMessage) Then
    mbCancel = False
    Me.Hide
  Else
    lResponse = MsgBox(sMessage, vbRetryCancel, "Invalid Information")
    If lResponse = vbCancel Then
      btnCancel_Click
    End If
  End If
End Sub

Public Property Get Cancel() As Boolean
  Cancel = mbCancel
End Property

Public Property Get DataOrientation() As XlRowCol
  Select Case True
    Case Me.optByColumn.Value
      DataOrientation = xlColumns
    Case Me.optByRow.Value
      DataOrientation = xlRows
  End Select
End Property

Public Property Get HeaderRows() As Long
  HeaderRows = Val(Me.txtHeaderRows.Text)
End Property

Public Property Get HeaderColumns() As Long
  HeaderColumns = Val(Me.txtHeaderColumns.Text)
End Property

Public Property Get ChartType() As XlChartType
  Select Case True
    Case Me.optChartTypeXY.Value
      ChartType = xlXYScatterLines
    Case Me.optChartTypeLine.Value
      ChartType = xlLineMarkers
    Case Me.optChartTypeBar.Value
      ChartType = xlBarClustered
    Case Me.optChartTypeColumn.Value
      ChartType = xlColumnClustered
  End Select
End Property

Public Property Get ChartDataRange() As Range
  Set ChartDataRange = Range(Me.refChartData.Text)
End Property

Public Property Get ChartPosition() As Range
  On Error Resume Next
  Set ChartPosition = Range(Me.refChartPosition.Text)
  On Error GoTo 0
End Property

Private Function Validated(sMsg As String) As Boolean

  ' Minimalist input validation

  Dim rTest As Range
  Dim iTest As Long

  Validated = True

  On Error Resume Next
  Set rTest = Range(Me.refChartData.Text)
  On Error GoTo 0
  If rTest Is Nothing Then
    Validated = False
    sMsg = "Invalid data range selected."
    GoTo ExitFunction
  End If

  iTest = Me.HeaderRows
  If iTest >= rTest.Rows.Count Then
    Validated = False
    sMsg = "Too many header rows specified."
    GoTo ExitFunction
  End If
  iTest = Me.HeaderColumns
  If iTest >= rTest.Columns.Count Then
    Validated = False
    If Len(sMsg) > 0 Then sMsg = sMsg & vbNewLine
    sMsg = sMsg & "Too many header columns specified."
    GoTo ExitFunction
  End If

ExitFunction:

End Function

Private Sub UserForm_Initialize()

  ' Define current range for RefEdit, if applicable

  Dim sAddress As String
  If TypeName(Selection) = "Range" Then
    If Selection.Cells.Count = 1 Then
      sAddress = Selection.CurrentRegion.Address(External:=True)
    Else
      sAddress = Selection.Address(External:=True)
    End If
    sAddress = Mid$(sAddress, InStr(sAddress, "]") + 1)
    If InStr(sAddress, "'") > 0 Then
      sAddress = "'" & sAddress
    End If
    Me.refChartData.Text = sAddress
  End If
End Sub

Private Sub UserForm_QueryClose(Cancel As Integer, CloseMode As Integer)
  If CloseMode = vbFormControlMenu Then
    Cancel = True
    btnCancel_Click
  End If
End Sub

In the next article of the series, Build an Excel Add-In 5 – Tie the Code Together, we will develop code to call this dialog, extract the user selections, and produce a chart using these settings.

Contents: How to Build an Excel Add-In

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

RefEdit controls allow the user to select a range of cells with the mouse. While the user is selecting cells, the parent UserForm shrinks to the size of the RefEdit plus the title bar. The address of the selected range appears in the RefEdit and updates as the mouse is dragged, and the size of the selected range is displayed next to the cursor.

When the mouse is released, the UserForm returns to its original size, and the address remains in the RefEdit. When the RefEdit has focus, the indicated range is highlighted with the “marching ants” border.

The RefEdit actually contains a string variable, not a range. This allows the user to edit the address in the RefEdit, and in fact, the user can enter any text as if the RefEdit is a text box. This also allows the programmer to insert the address of a range (usually the current selection) into the RefEdit when loading the UserForm.

The Error Bar Utility that I introduced in Error Bars in Excel 2007 Charts makes use of this dual entry behavior, allowing a user to enter a constant or a range of cells for the error bar values.

RefEdit Irregularities

The RefEdit control has some strange and wonderful idiosyncrasies which must be considered when designing a dialog. There are (at least) four issues that are important to keep in mind.

RefEdits must be placed directly on the UserForm itself. If you put a RefEdit in a frame or on a multipage, strange things will happen, including bizarre Excel crashes.

RefEdits must not be used on modeless forms. RefEdits on modeless forms will result in bizarre Excel crashes.

RefEdit event procedures should be avoided. RefEdit events do not behave reliably, and they may result in VBA errors which are difficult to debug.

References to RefEdits must be removed. When a UserForm is added to a VB project, Excel adds a reference to the Microsoft Forms 2.0 Object Library. This reference is required for proper operation of the UserForms in your project. To see what references your project has, select the project in the Project Explorer, then select References from the Tools menu.

When a RefEdit is added to a UserForm, Excel sometimes adds a reference to the Ref Edit Control. This was fine in earlier versions of Excel, but there appear to be incompatibilities in recent versions of the RefEdit library. These problems often are associated with an Unspecified but Painfully Frustrating Error.

To reduce the risk of RefEdit-related issues, you should uncheck the box in front of Ref Edit Control in the References dialog. Otherwise, there may be problems loading the add-in on another user’s machine, including the removal of RefEdits from the dialogs and other bizarre behavior.

It is also helpful to process the workbook or add-in’s code through an earlier version of Excel. I use a VM with Office 2000 installed on it for this purpose. Open Excel 2000, open the workbook or add-in, run Rob Bovey’s free Code Cleaner application, then compile the code and save the file.

It may also be necessary to remove RefEdit.exd files from a user’s computer if problems occur and unchecking the reference doesn’t fix them. these exd files are temporary files that contain instructions Excel uses to build RefEdits, and the exd may conflict with the RefEdits in the workbook. If this doesn’t work, the next step is to run Detect and Repair on Excel, then reinstall Office, then sacrifice the computer at the next full moon.

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

In this post I present an example of another modular function. I say “modular” because the function is not integrated into any other code, and thus can be called from any procedure that needs its functionality.

One big advantage of modular functions like this is that they can be called from many other procedures, and each time they execute the same way. If I want to make an adjustment to the function, I can make the change in one place, and the change is reflected every time it is run.

Another advantage of such modular functions is that they can be copied from one project and pasted into another, and you don’t have to carry out extensive testing to make sure that it works. A quick run through the code is usually sufficient to ensure proper execution.

The New Function

This rudimentary function is still a very useful one. It takes a chart as its sole argument, applies some formatting to the chart, then returns the chart as its value.

Given a chart variable called TheChart, the function is called like this:

Set TheChart = CleanUpChart(TheChart)

The function removes the borders on the chart area, plot area, and legend. It applies a uniform, non-auto-scaling font to all text elements. It removes borders on bar and column chart series and changes the gap spacing to 100%. It also widens the plot area to redue the wasted white space around the chart.

Here is the function in all of its glory. Feel free to adapt it to your own needs, using your own preferred formatting.

An alternate version of this function may convert 3D charts to their 2D equivalents, for example.

Function CleanUpChart(cht As Chart) As Chart

  ' PRETTIFY THIS CHART
  ' ' chart area: remove border, fix font size, disable font autoscaling
  ' ' legend: remove border, resize, reposition
  ' ' plot area: remove border and fill, maximize size, minimize margins
  ' ' gridlines: remove

  Dim dLgndWidth As Double
  Dim iLgndEntry As Long
  Dim iAxType As XlAxisType
  Dim iAxGroup As XlAxisGroup
  Dim iSrs As Long
  Dim bScreenUpdating As Boolean

  bScreenUpdating = Application.ScreenUpdating
  Application.ScreenUpdating = False

  With cht
    With .ChartArea
      .Border.LineStyle = xlNone
      .AutoScaleFont = False
      .Font.Size = 8
    End With
    With .Legend
      .Border.LineStyle = xlNone
      .Left = 0
      .Width = cht.ChartArea.Width
      dLgndWidth = .LegendEntries(1).Width
      For iLgndEntry = 2 To .LegendEntries.Count
        If dLgndWidth < .LegendEntries(iLgndEntry).Width Then
          dLgndWidth = .LegendEntries(iLgndEntry).Width
        End If
      Next
      .Width = dLgndWidth
      .Left = cht.ChartArea.Width
    End With
    With .PlotArea
      .Border.LineStyle = xlNone
      .Interior.ColorIndex = xlNone
      .Top = 0
      .Left = 0
      .Height = cht.ChartArea.Height
      .Width = cht.Legend.Left - 2
    End With
    For iAxGroup = xlPrimary To xlSecondary
      For iAxType = xlCategory To xlValue
        If .HasAxis(iAxType, iAxGroup) Then
          If .Axes(iAxType, iAxGroup).HasMajorGridlines Then
            .Axes(iAxType, iAxGroup).MajorGridlines.Delete
          End If
          If .Axes(iAxType, iAxGroup).HasMinorGridlines Then
            .Axes(iAxType, iAxGroup).MinorGridlines.Delete
          End If
        End If
      Next
    Next
    If .ChartType = xlColumnClustered Or .ChartType = xlBarClustered Then
      .ChartGroups(1).GapWidth = 100
      For iSrs = 1 To .SeriesCollection.Count
        .SeriesCollection(iSrs).Border.LineStyle = xlNone
      Next
    End If

  End With

  Set CleanUpChart = cht

  Application.ScreenUpdating = bScreenUpdating

End Function

Contents: How to Build an Excel Add-In

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

The VBA procedure in Build an Excel Add-In 1 – Basic Routine is a subroutine which creates a chart using a number of built-in (hard-coded) options. In this post I will show how to make this subroutine into a modular function, which allows a calling procedure to pass these options into the procedure. This adds the flexibility that allows the function to create a variety of charts based on different options. In a future installment of this series I will build a dialog (a VBA UserForm) which allows a user to select these options.

Modular Function

The first step in the transformation is to turn the subroutine in the previous step:

Sub PT_Plot() 

into a function with parameters for the various options:

Function PT_Plotter_Chart(DataRange As Range, DataOrientation As XlRowCol, _
    HeaderRows As Long, HeaderColumns As Long, ChartType As XlChartType, _
    Optional PositionRange As Range) As Chart

The parameters passed into this function are:

DataRange: a Range object containing the chart's source data
DataOrientation: whether series are specified by xlColumns or xlRows
HeaderRows: number of header rows in the data range (series names or category values)
HeaderColumns: number of header columns in the data range (series names or category values)
ChartType: type of chart to create (XY, Line, Area, Column, Bar)
PositionRange (optional): range of cells that chart object will cover 

The result of the function is a reference to the chart created in the function.

The calling procedure has defined the values of these parameters, and our function has to adjust its execution to account for these values.

Chart Source Data Range

In the original sub, if the selection is not a range, execution exits the procedure. Otherwise the selected range becomes the source data range:

  If TypeName(Selection) <> "Range" Then
    MsgBox "Select a range and try again.", vbOKOnly, "No Range Selected"
    GoTo ExitProcedure
  End If
  Set rData = Selection

In the new function, DataRange As Range is passed into the function.

Header Rows and Columns, and Data Orientation

The original sub assumes that there is one header row and one header column. The range containing the series values is offset one row down and one column right of the source data range, and reduced in size by one row and one column. In addition, it assumes that series are defined by columns, so the series names are defined as the top row, the category values as the left column, and the number of series as the number of columns in the series values range.

  With rData
    Set rValues = .Offset(1, 1).Resize(.Rows.Count - 1, .Columns.Count - 1)
    nSrs = .Columns.Count - 1
    Set rNames = .Offset(, 1).Resize(1, nSrs)
    Set rCats = .Offset(1).Resize(.Rows.Count - 1, 1)
  End With

The new function adjusts the position and size of the range containing the series values by the number of header rows and columns it is passed. The data orientation helps to define the number of series, the series names, and the category values.

  With DataRange
    Set rValues = .Offset(HeaderRows, HeaderColumns) _
        .Resize(.Rows.Count - HeaderRows, .Columns.Count - HeaderColumns)
    Select Case DataOrientation
      Case xlColumns
        nSrs = .Columns.Count - HeaderColumns
        Set rNames = .Offset(, HeaderColumns).Resize(HeaderRows, nSrs)
        Set rCats = .Offset(HeaderRows) _
            .Resize(.Rows.Count - HeaderRows, HeaderColumns)
      Case xlRows
        nSrs = .Rows.Count - HeaderRows
        Set rNames = .Offset(HeaderRows).Resize(nSrs, HeaderColumns)
        Set rCats = .Offset(, HeaderColumns) _
            .Resize(HeaderRows, .Columns.Count - HeaderColumns)
    End Select
  End With 

Series are added to the chart as columns or as rows, based on the data orientation:

  For iSrs = 1 To nSrs
    Set Srs = cht.SeriesCollection.NewSeries
    With Srs
      Select Case DataOrientation
        Case xlColumns
          .Values = rValues.Columns(iSrs)
          .XValues = rCats
          .Name = "=" & rNames.Columns(iSrs).Address(ReferenceStyle:=xlR1C1, External:=True)
        Case xlRows
          .Values = rValues.Rows(iSrs)
          .XValues = rCats
          .Name = "=" & rNames.Rows(iSrs).Address(ReferenceStyle:=xlR1C1, External:=True)
      End Select
    End With
  Next 

Chart Type

The original sub does not specify a chart type, so it creates a chart of the default type. If the user has not specified their own default, then the Excel default chart type, 2D clustered column, is used.

The new function applies the specified chart type to the finished chart:

  cht.ChartType = ChartType 

Chart Position

The original sub mimics the Excel 2003 default chart object position, which is half the size of the active window, centered within the active window.

  Set rScroll = ActiveSheet.Cells(ActiveWindow.ScrollRow, ActiveWindow.ScrollColumn)
  With ActiveWindow
    dWidth = .UsableWidth / 2
    dHeight = .UsableHeight / 2
    dLeft = rScroll.Left + dWidth / 2
    dTop = rScroll.Top + dHeight / 2
  End With

If it is passed a range defining the chart position, the new function covers this range with the chart object.

    With PositionRange
      dLeft = .Left
      dTop = .Top
      dWidth = .Width
      dHeight = .Height
    End With

Otherwise, the function mimics the Excel 2003 default chart object position, using the largest pane instead of the entire active window. If the chart will be smaller than a minimum defined size, this defined minimum will be used rather than half the size of the largest pane.

    With ActiveWindow
      dWidth = .UsableWidth / 2
      dHeight = .UsableHeight / 2
      If .SplitColumn > 0 Then
        If ActiveSheet.Range("A1").Resize(, .SplitColumn).Width > dWidth Then
          dWidth = ActiveSheet.Range("A1").Resize(, .SplitColumn).Width / 2
          If dWidth < 200 Then dWidth = 200
          dLeft = ActiveSheet.Columns(.Panes(1).ScrollColumn).Left + dWidth / 2
        Else
          dWidth = dWidth - ActiveSheet.Range("A1").Resize(, .SplitColumn).Width / 2
          If dWidth < 200 Then dWidth = 200
          dLeft = ActiveSheet.Columns(.Panes(.Panes.Count).ScrollColumn).Left + dWidth / 2
        End If
      Else
        If dWidth < 200 Then dWidth = 200
        dLeft = ActiveSheet.Columns(.Panes(1).ScrollColumn).Left + dWidth / 2
      End If
      If dLeft < 40 Then dLeft = 40
      If .SplitRow > 0 Then
        If ActiveSheet.Range("A1").Resize(.SplitRow).Height > dHeight Then
          dHeight = ActiveSheet.Range("A1").Resize(.SplitRow).Height / 2
          If dHeight < 125 Then dHeight = 125
          dTop = ActiveSheet.Rows(.Panes(1).ScrollRow).Top + dHeight / 2
        Else
          dHeight = dHeight - ActiveSheet.Range("A1").Resize(.SplitRow).Height / 2
          If dHeight < 125 Then dHeight = 125
          dTop = ActiveSheet.Rows(.Panes(.Panes.Count).ScrollRow).Top + dHeight / 2
        End If
      Else
        If dHeight < 125 Then dHeight = 125
        dTop = ActiveSheet.Rows(.Panes(.Panes.Count).ScrollRow).Top + dHeight / 2
      End If
    If dTop < 25 Then dTop = 25
    End With

This set of calculations based on the splitting of the window into multiple panes is too complicated for this post, but it may be covered in a future post.

Returned Value

The function returns the chart that is created in the function:

  Set PT_Plotter_Chart = cht

Entire Code of New Function

The following is the listing of the updated procedure:

Function PT_Plotter_Chart(DataRange As Range, DataOrientation As XlRowCol, _
    HeaderRows As Long, HeaderColumns As Long, ChartType As XlChartType, _
    Optional PositionRange As Range) As Chart

  ' CREATE AND POPULATE A CHART
  ' ' Start with defined data range
  ' ' Put chart in specified (or default) position
  ' ' Use specified chart type
  ' ' Plot by row or column as specified
  ' ' Use specified rows/columns for category values
  ' ' Use specified columns/rows for series names
  ' ' Use position range (if specified) for position of chart object
  ' ' Otherwise center chart object in largest pane of active window

  Dim ChtOb As ChartObject
  Dim cht As Chart
  Dim wsPosition As Worksheet
  Dim dLeft As Double, dTop As Double, dWidth As Double, dHeight As Double
  Dim rActive As Range
  Dim rScroll As Range
  Dim rCats As Range
  Dim rNames As Range
  Dim rValues As Range
  Dim iSrs As Long, nSrs As Long
  Dim Srs As Series
  Dim bScreenUpdating As Boolean

  bScreenUpdating = Application.ScreenUpdating
  Application.ScreenUpdating = False

  If TypeName(Selection) = "Range" Then
    Set rActive = ActiveCell
    Set rScroll = ActiveSheet.Cells(ActiveWindow.ScrollRow, ActiveWindow.ScrollColumn)
  End If
  If PositionRange Is Nothing Then
    ' Position unspecified
    ' Define using 2003 configuration
    ' Put into largest pane (whole window if unsplit)
    ' Half the pane's width and height, centered in pane
    With ActiveWindow
      dWidth = .UsableWidth / 2
      dHeight = .UsableHeight / 2

      If .SplitColumn > 0 Then
        If ActiveSheet.Range("A1").Resize(, .SplitColumn).Width > dWidth Then
          dWidth = ActiveSheet.Range("A1").Resize(, .SplitColumn).Width / 2
          If dWidth < 200 Then dWidth = 200
          dLeft = ActiveSheet.Columns(.Panes(1).ScrollColumn).Left + dWidth / 2
        Else
          dWidth = dWidth - ActiveSheet.Range("A1").Resize(, .SplitColumn).Width / 2
          If dWidth < 200 Then dWidth = 200
          dLeft = ActiveSheet.Columns(.Panes(.Panes.Count).ScrollColumn).Left + dWidth / 2
        End If
      Else
        If dWidth < 200 Then dWidth = 200
        dLeft = ActiveSheet.Columns(.Panes(1).ScrollColumn).Left + dWidth / 2
      End If
      If dLeft < 40 Then dLeft = 40

      If .SplitRow > 0 Then
        If ActiveSheet.Range("A1").Resize(.SplitRow).Height > dHeight Then
          dHeight = ActiveSheet.Range("A1").Resize(.SplitRow).Height / 2
          If dHeight < 125 Then dHeight = 125
          dTop = ActiveSheet.Rows(.Panes(1).ScrollRow).Top + dHeight / 2
        Else
          dHeight = dHeight - ActiveSheet.Range("A1").Resize(.SplitRow).Height / 2
          If dHeight < 125 Then dHeight = 125
          dTop = ActiveSheet.Rows(.Panes(.Panes.Count).ScrollRow).Top + dHeight / 2
        End If
      Else
        If dHeight < 125 Then dHeight = 125
        dTop = ActiveSheet.Rows(.Panes(.Panes.Count).ScrollRow).Top + dHeight / 2
      End If
      If dTop < 25 Then dTop = 25

    End With
    Set wsPosition = ActiveSheet
  Else
    ' Position specified
    With PositionRange
      dLeft = .Left
      dTop = .Top
      dWidth = .Width
      dHeight = .Height
      Set wsPosition = .Parent
    End With
  End If

  With DataRange
    Set rValues = .Offset(HeaderRows, HeaderColumns) _
        .Resize(.Rows.Count - HeaderRows, .Columns.Count - HeaderColumns)
    Select Case DataOrientation
      Case xlColumns
        nSrs = .Columns.Count - HeaderColumns
        Set rNames = .Offset(, HeaderColumns).Resize(HeaderRows, nSrs)
        Set rCats = .Offset(HeaderRows) _
            .Resize(.Rows.Count - HeaderRows, HeaderColumns)
      Case xlRows
        nSrs = .Rows.Count - HeaderRows
        Set rNames = .Offset(HeaderRows).Resize(nSrs, HeaderColumns)
        Set rCats = .Offset(, HeaderColumns) _
            .Resize(HeaderRows, .Columns.Count - HeaderColumns)
    End Select
  End With

  ' NEED ACTIVE CELL NOT IN PIVOT TABLE WHEN CREATING CHART
  If Not rActive Is Nothing Then
    ActiveSheet.Columns(1).Cells(ActiveSheet.Rows.Count).Select
  End If

  Set cht = wsPosition.ChartObjects.Add(dLeft, dTop, dWidth, dHeight).Chart
  ' probably blank, but remove all series just in case
  For iSrs = cht.SeriesCollection.Count To 1 Step -1
    cht.SeriesCollection.Count(iSrs).Delete
  Next

  ' add series from data range
  For iSrs = 1 To nSrs
    Set Srs = cht.SeriesCollection.NewSeries
    With Srs
      Select Case DataOrientation
        Case xlColumns
          .Values = rValues.Columns(iSrs)
          .XValues = rCats
          .Name = "=" & rNames.Columns(iSrs).Address(ReferenceStyle:=xlR1C1, External:=True)
        Case xlRows
          .Values = rValues.Rows(iSrs)
          .XValues = rCats
          .Name = "=" & rNames.Rows(iSrs).Address(ReferenceStyle:=xlR1C1, External:=True)
      End Select
    End With
  Next
  cht.ChartType = ChartType

  Set PT_Plotter_Chart = cht

  ' restore original window configuration
  ActiveWindow.ScrollRow = rScroll.Row
  ActiveWindow.ScrollColumn = rScroll.Column
  If Not rActive Is Nothing Then
    DataRange.Select
    rActive.Activate
  End If

  Application.ScreenUpdating = bScreenUpdating

End Function

Contents: How to Build an Excel Add-In

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

In a recent project I had to make a number of regular charts from pivot tables, and I finally got tired of the long, slow, tedious manual process. I put together some VBA code and built myself an add-in so I would always have this functionality on hand. The add-in is also handy as a Chart Wizard replacement for Excel 2007, which lost the Wizard in the User Interface Wars.

I thought it would be nice to post this add-in on my blog, for all of you faithful readers. I frequently share such routines, and judging from comments and emails, they are pretty popular. Then I remembered that whole teach-a-man-to-fish thing, and decided it would be a great series of posts if I described the whole process of developing an Excel add-in.

Here is the table of contents for this series.

• Build an Excel Add-In 1 – Basic Routine
• Build an Excel Add-In 2 – Enhanced Functionality
• Build an Excel Add-In 3 – Auxiliary Modular Functions
• Build an Excel Add-In 4 – Create the Dialog
• Build an Excel Add-In 5 – Tie the Code Together
• Build an Excel Add-In 6 – Interface for 2003
• Build an Excel Add-In 7 – Interface for 2007
• Build an Excel Add-In 8 – Last Steps
• Build an Excel Add-In 9 – Deployment

And now, on to the first topic of the series:

Build an Excel Add-In 1 – Basic Routine

The steps in the manual procedure involve selecting a cell which is blank and not part of the pivot table, inserting a blank chart, and adding one series per column (or row) of the pivot table, using the first column as categories and the first row as series names.

The VBA procedure will use the selected range as the chart data source. It will assume that the series are in columns, that categories are in the first column, and that series names are in the first row. It will create the default chart type (clustered column if you’ve never reassigned your default), positioned according to the defaults in “Classic” Excel, that is, Excel 2003 and earlier. This default positioning creates a chart roughly half the size dimensions of the active window, roughly centered in the visible region of the active window.

Here is the whole VBA routine:

Sub PT_Plot()

  ' CREATE AND POPULATE A CHART
  ' ' Start with selected data range
  ' ' Add chart object
  ' ' Use default chart type
  ' ' Plot by column
  ' ' First column for category values
  ' ' First row for series names

  Dim ChtOb As ChartObject
  Dim cht As Chart
  Dim dLeft As Double, dTop As Double, dWidth As Double, dHeight As Double
  Dim rScroll As Range
  Dim rData As Range
  Dim rCats As Range
  Dim rNames As Range
  Dim rValues As Range
  Dim iSrs As Long, nSrs As Long
  Dim Srs As Series
  Dim shp As Shape

  Application.ScreenUpdating = False

  If TypeName(Selection) <> "Range" Then
    MsgBox "Select a range and try again.", vbOKOnly, "No Range Selected"
    GoTo ExitProcedure
  End If

  Set rData = Selection

  ' determine chart object size:
  ' ' half of window height and width, centered in window
  Set rScroll = ActiveSheet.Cells _
      (ActiveWindow.ScrollRow, ActiveWindow.ScrollColumn)
  With ActiveWindow
    dWidth = .UsableWidth / 2
    dHeight = .UsableHeight / 2
    dLeft = rScroll.Left + dWidth / 2
    dTop = rScroll.Top + dHeight / 2
  End With

  With rData
    Set rValues = .Offset(1, 1).Resize(.Rows.Count - 1, .Columns.Count - 1)
    nSrs = .Columns.Count - 1
    Set rNames = .Offset(, 1).Resize(1, nSrs)
    Set rCats = .Offset(1).Resize(.Rows.Count - 1, 1)
  End With

  ' NEED ACTIVE CELL NOT IN PIVOT TABLE WHEN CREATING CHART
  ActiveSheet.Columns(1).Cells(ActiveSheet.Rows.Count).Select

  Set cht = ActiveSheet.ChartObjects.Add(dLeft, dTop, dWidth, dHeight).Chart
  ' probably blank, but remove all series just in case
  For iSrs = cht.SeriesCollection.Count To 1 Step -1
    cht.SeriesCollection.Count(iSrs).Delete
  Next

  ' add series from data range
  For iSrs = 1 To nSrs
    Set Srs = cht.SeriesCollection.NewSeries
    With Srs
      .Values = rValues.Columns(iSrs)
      .XValues = rCats
      .Name = "=" & rNames.Columns(iSrs).Address(ReferenceStyle:=xlR1C1, External:=True)
    End With
  Next

  ' restore original window configuration
  ActiveWindow.ScrollRow = rScroll.Row
  ActiveWindow.ScrollColumn = rScroll.Column
  rData.Select 

ExitProcedure:

  Application.ScreenUpdating = True 

End Sub 

The way to use this program is to select your data, including a header row and header column, and run the procedure. The data below comes from a very simple pivot table.

The easiest way to run the program is to press Alt-F8, select the PT_Plot macro from the list of available macros, and press Enter.

You can also see PT_Plotter_Dialog in the list. This is the routine which will eventually be called from the menu or ribbon in the add-in. You’ll have to be patient as it will be refined over the next few installments.

The output of the program is a chart object half the size of the active window, centered in the window. It is the default clustered column type, with default formatting.

Coming Attractions

In Build an Excel Add-In 2 – Enhanced Functionality, this sub will be converted to a function. Various arguments, such as chart source data range, data series orientation, number of header row(s) and column(s), chart type, and optionally the position of chart, will be passed into the function. The function will return an object representing the chart it has constructed.

Build an Excel Add-In 3 – Auxiliary Modular Functions will demonstrate how to incorporate additional functionality in the form of additional functions, which can be shared among any of your procedures. The particular function will be a routine that takes the chart as an argument, applies some “nice” formatting, and returns the cleaned up chart.

We will add a user interface in Build an Excel Add-In 4 – Create the Dialog that will allow the user to easily select the arguments that are passed into the function we developed in installment 2. The PT_Plotter_Dialog will incorporate the use of this dialog, then call the function to create the chart. At this point, the features of the add-in are complete.

Build an Excel Add-In 5 – Tie the Code Together will merge the function that creates the chart, the auxiliary function that formats the chart, and the dialog and the code that interacts with the dialog.

The add-in still needs to make itself visible in the Excel application. This will be done using a custom menu and button in Build an Excel Add-In 6 – Interface for 2003 and using a custom ribbon tab and button in Build an Excel Add-In 7 – Interface for 2007.

Build an Excel Add-In 8 – Last Steps describes some final tasks to ensure your add-in will work properly on a wide range of version combinations of Windows and Excel. Build an Excel Add-In 9 – Deployment will talk about issues you may encounter while deploying your add-in to other users.

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

Not being able to leave anything alone, I made some changes to how the procedure worked. The original put its list of procedures into a dialog, and when the dialog was closed, the list evaporated. I changed the output so that the list is dumped into a new worksheet inserted just for this purpose.

I broadened the scope of the procedure, so that it lists all procedures in all VB projects, not just the active one. The first two rows of the output sheet contain the names of the parent workbook and of the project.

If the project is protected, you’ll get an error if you try to look inside, so my code bypasses the error and notes that the project is protected. My code also notes when there isn’t any code in a project.

I also didn’t find the original variable names useful, so I used some which were more descriptive, to me at least.

Here’s my modified procedure, for what it’s worth.

'' Based on:
'' Displaying a List of All VBA Procedures in an Excel 2007 Workbook
''     from the Ribbon (June 2009)
'' by Frank Rice, Microsoft Corporation
'' http://msdn.microsoft.com/en-us/library/dd890502(office.11).aspx#

'' set a reference to the Microsoft Visual Basic for Applications Extensibility 5.3 Library

Sub GetProcedures()
  ' Declare variables to access the Excel workbook.
  Dim app As Excel.Application
  Dim wb As Excel.Workbook
  Dim wsOutput As Excel.Worksheet
  Dim sOutput() As String
  Dim sFileName As String

  ' Declare variables to access the macros in the workbook.
  Dim vbProj As VBIDE.VBProject
  Dim vbComp As VBIDE.VBComponent
  Dim vbMod As VBIDE.CodeModule

  ' Declare other miscellaneous variables.
  Dim iRow As Long
  Dim iCol As Long
  Dim iLine As Integer
  Dim sProcName As String
  Dim pk As vbext_ProcKind

  Set app = Excel.Application

  ' create new workbook for output
  Set wsOutput = app.Workbooks.Add.Worksheets(1)

  'For Each wb In app.Workbooks
  For Each vbProj In app.VBE.VBProjects

    ' Get the project details in the workbook.
    On Error Resume Next
    sFileName = vbProj.Filename
    If Err.Number <> 0 Then sFileName = "file not saved"
    On Error GoTo 0

    ' initialize output array
    ReDim sOutput(1 To 2)
    sOutput(1) = sFileName
    sOutput(2) = vbProj.Name
    iRow = 0

    ' check for protected project
    On Error Resume Next
    Set vbComp = vbProj.VBComponents(1)
    On Error GoTo 0

    If Not vbComp Is Nothing Then
      ' Iterate through each component in the project.
      For Each vbComp In vbProj.VBComponents

        ' Find the code module for the project.
        Set vbMod = vbComp.CodeModule

        ' Scan through the code module, looking for procedures.
        iLine = 1
        Do While iLine < vbMod.CountOfLines
          sProcName = vbMod.ProcOfLine(iLine, pk)
          If sProcName <> "" Then
            iRow = iRow + 1
            ReDim Preserve sOutput(1 To 2 + iRow)
            sOutput(2 + iRow) = vbComp.Name & ": " & sProcName
            iLine = iLine + vbMod.ProcCountLines(sProcName, pk)
          Else
            ' This line has no procedure, so go to the next line.
            iLine = iLine + 1
          End If
        Loop

        ' clean up
        Set vbMod = Nothing
        Set vbComp = Nothing

      Next
    Else
      ReDim Preserve sOutput(1 To 3)
      sOutput(3) = "Project protected"
    End If

    If UBound(sOutput) = 2 Then
      ReDim Preserve sOutput(1 To 3)
      sOutput(3) = "No code in project"
    End If

    ' define output location and dump output
    If Len(wsOutput.Range("A1").Value) = 0 Then
      iCol = 1
    Else
      iCol = wsOutput.Cells(1, wsOutput.Columns.Count).End(xlToLeft).Column + 1
    End If
    wsOutput.Cells(1, iCol).Resize(UBound(sOutput) + 1 - LBound(sOutput)).Value = _
        WorksheetFunction.Transpose(sOutput)

    ' clean up
    Set vbProj = Nothing
  Next

  ' clean up
  wsOutput.UsedRange.Columns.AutoFit
End Sub
 

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.
 

This functionality is even better if the user is given the opportunity to specify a path and file name.  You can simply pop up Excel’s own Save As dialog:

Application.Dialogs(xlDialogSaveAs).Show sFileName

This approach is fine for simple applications, but it saves the file before execution returns to the calling procedure. This may not be what you want to do with the file and file name.

Excel’s VBA object model has a more flexible approach. The GetSaveAsFilename method opens a Save As dialog and gives the user control over directory and file name. GetSaveAsFilename does not save the file, but only retrieves the combined path and file name and returns it to the executing procedure for further use. If the user cancels, the function returns the string “False” instead of a filename.

Below is an implementation of GetSaveAsFilename that I’ve wrapped in a function called GSAFN. The function  takes a file name and path, which are used as the defaults in the Save As dialog.  If the file name entered by the user matches an existing file name, it asks the user what to do: overwrite the existing file, enter another file name, or cancel the save operation. If the user cancels the save, GSAFN returns a zero length string.

Function GSAFN(sFileName As String, sPathName As String) As String
  Dim sFullName As String
  Dim sPrompt As String
  Dim sCurDir As String
  Dim iOverwrite As Long

  If ActiveWorkbook Is Nothing Then GoTo ExitSub

  ' save current directory, restore it later
  sCurDir = CurDir

  ' switch to desired directory
  If Len(sPathName) > 0 Then
    ChDrive sPathName
    ChDir sPathName
  End If

  ' loop until unique name is entered
  Do
    sFullName = Application.GetSaveAsFilename(sFileName, _
        "Excel Files (*.xls),*.xls", , _
        "Browse to a folder and enter a file name")

    If Len(sFullName) = 0 Then GoTo ExitSub
    If sFullName = "False" Then GoTo ExitSub

    ' if name is unique, exit loop and save file
    If Not FileExists(sFullName) Then Exit Do

    ' tell user that the filename is in use

    ' parse filename
    sFileName = FullNameToFileName(sFullName)
    sPathName = FullNameToPath(sFullName)

    ' construct message
    sPrompt = "A file named '" & sFileName & "' already exists in '" _
        & sPathName & "'"
    sPrompt = sPrompt & vbNewLine & vbNewLine & _
        "Do you want to overwrite the existing file?"

    ' ask user what to do
    iOverwrite = MsgBox(sPrompt, vbYesNoCancel + vbQuestion, _
        "Image File Exists")

    Select Case iOverwrite
      Case vbYes
        ' overwrite existing file
        Exit Do
      Case vbNo
        ' do nothing, loop again to get new filename
      Case vbCancel
        ' bail out
        GoTo ExitSub
    End Select
  Loop

  ' finally, save the file using filename from above
  Application.DisplayAlerts = False
  ActiveWorkbook.SaveAs sFullName
  Application.DisplayAlerts = True

  GSAFN = sFullName

ExitSub:
  ' restore previous current directory
  ChDrive sCurDir
  ChDir sCurDir

End Function

The following procedures are used in the main procedure above. The FileExists function is more flexible than simply using Dir, because using it does not reset the initial file spec used in Dir. The FullNameToFileName and FullNameToPath functions parse the combined path and file name into a separate path and file name, making the GSAFN function work more easily. They were originally written for Excel 97, before VBA had the RevInStr string function; don’t laugh at the antiquated syntax, because they still work just fine.

Function FileExists(ByVal FileSpec As String) As Boolean
  ' Karl Peterson, Former MS VB6 MVP
  Dim Attr As Long
  ' Guard against bad FileSpec by ignoring errors
  ' retrieving its attributes.
  On Error Resume Next
  Attr = GetAttr(FileSpec)
  If Err.Number = 0 Then
    ' No error, so something was found.
    ' If Directory attribute set, then not a file.
    FileExists = Not ((Attr And vbDirectory) = vbDirectory)
  End If
End Function

Function FullNameToFileName(sFullName As String) As String
  Dim k As Integer
  Dim sTest As String
  If InStr(1, sFullName, "[") > 0 Then
    k = InStr(1, sFullName, "[")
    sTest = Mid(sFullName, k + 1, InStr(1, sFullName, "]") - k - 1)
  Else
    For k = Len(sFullName) To 1 Step -1
      If Mid(sFullName, k, 1) = "\" Then Exit For
    Next k
    sTest = Mid(sFullName, k + 1, Len(sFullName) - k)
  End If
  FullNameToFileName = sTest
End Function

Function FullNameToPath(sFullName As String) As String
  ''' does not include trailing backslash
  Dim k As Integer
  For k = Len(sFullName) To 1 Step -1
    If Mid(sFullName, k, 1) = "\" Then Exit For
  Next k
  If k < 1 Then
    FullNameToPath = ""
  Else
    FullNameToPath = Mid(sFullName, 1, k - 1)
  End If
End Function

GSAFN is called as follows:

Sub TestGSAFN()
  Dim sFile As String
  sFile = GSAFN("testfile.xls", "C:\Temp")
  If Len(sFile) > 0 Then
    MsgBox "File successfully saved"
  Else
    MsgBox "File was not saved"
  End If
End Sub

GSAFN and the supporting functions are so helpful that I include them in a general Tools module which I drop into each new project I develop.

Peltier Technical Services, Inc., Copyright © 2010.
 
Licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.