Table of Contents

RDC01005: Hosted document code

Severity: Error  ·  Family: RDC (Rubberduck Core analyzers)  ·  Raised by: HostedDocumentCodeAnalyzer

A module is the code of a host application's document - an Excel worksheet or workbook, a Word document, an Access form or report - and RD-VBA does not host documents. The module's code never runs, and the document's name means nothing elsewhere in the project. The code is to move into a class that holds the document in a variable, from an application the program automates.

Why RD-VBA is not hosted

In Microsoft Office, VBA runs inside the application. The project is saved inside the document, and a document module belongs to the application: Excel makes Sheet1 the moment the workbook opens, calls Worksheet_Change when a cell changes, and makes the name Sheet1 mean the sheet everywhere in the project.

RD-VBA runs VBA outside of any application. A project is a folder of source files, and an application is something the program automates from the outside, as any other program can. That makes the code portable: it runs with no Office installed, it is tested without opening a workbook, and it is versioned as text. It also means that there is no application around the code to make Sheet1, to call its event handlers, or to answer Me.Range. RD-VBA never starts or attaches to Excel on a document module's behalf: an Excel process starts only when the program creates one.

A project exported from Office keeps its document modules - legacy Rubberduck exported them as .doccls files - and the project file says what each one is (Super, RD-VBAL §2.2.3.3). RD-VBA reads them for what they are, so that the code binds and reads correctly in the editor: Me is valid, and Range is Excel.Worksheet.Range. It reports them so the code can be moved.

How it is raised

Situation Where
A document module of a host RD-VBA knows, whose code presumes the host: it names a member of the host's class through Me (Me.Range, or .Range in a With Me block) or by its name alone (an unqualified Cells), or it has a procedure named as a handler of the host's events (Worksheet_Change), which nothing raises. Once, at the module's first line. Its related information lists each of those places. A document module with none of them is not reported: an empty ThisWorkbook or Sheet1, or code that holds a sheet of an application it automates (ws.Range, With ws), presumes nothing of a host.
A name of a document module, written in another module (GameSheet.Reset, ThisWorkbook.Save). At the name, in place of Variable not defined: in Office, the application makes the name the document. Here it stands for nothing.

Moving the code

Before: the code of the worksheet GameSheet, as Office runs it.

'@Folder("Battleship.View")
Option Explicit

Private Sub Worksheet_Change(ByVal Target As Range)
    If Not Intersect(Target, Me.Range("Grid")) Is Nothing Then
        Debug.Print "Played: " & Target.Address
    End If
End Sub

After: a class module that holds the worksheet in a WithEvents variable of Excel.Worksheet. The handler is named for the variable, not for the document.

'@Folder("Battleship.View")
Option Explicit

Private WithEvents AutomationSheet As Excel.Worksheet

Public Sub Attach(ByVal sheet As Excel.Worksheet)
    Set AutomationSheet = sheet
End Sub

Private Sub AutomationSheet_Change(ByVal Target As Excel.Range)
    If Not AutomationSheet.Application.Intersect(Target, AutomationSheet.Range("Grid")) Is Nothing Then
        Debug.Print "Played: " & Target.Address
    End If
End Sub

The program creates the application, opens or makes the workbook, and attaches the sheet. Where the code wrote Me.Range, or an unqualified Range, it writes AutomationSheet.Range. Where another module wrote GameSheet.Reset, it calls the class's method on the object the program made.

Public Sub Main()
    Dim app As Excel.Application
    Set app = New Excel.Application
    app.Visible = True

    Dim book As Excel.Workbook
    Set book = app.Workbooks.Open("C:\Games\Battleship.xlsx")

    Dim view As GameSheetView
    Set view = New GameSheetView
    view.Attach book.Worksheets("GameSheet")
End Sub

The project references the Excel library for Excel.Worksheet to be a type (References of the .rdproj). Its events reach the handler as any automation object's do: RD-VBA routes them to the procedures of the WithEvents variables that hold the object.

Notes

See also


ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca