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
- A document module of a host RD-VBA does not know is RDC01006 Unsupported document module, and one whose library the project does not reference is RDC01007 Host library not referenced.
Newof a document module is a compile error, Invalid use of New keyword, as it is in Office: only the host makes its documents.- An
Implementsdirective in a document module is RDC11024 Implements in a document module.
See also
- RD-VBAL §2.2.3.3 RDCoreModule
- RD-VBAL §2.6.4 Rubberduck Core Diagnostics
- RD-VBAL §5.3.1.8 Event Handler Declarations
ACCUEIL • HOME | ℹ️ BIENVENUE • WELCOME | 🧩 BÂTISSONS • BUILD | RD-VBAL | SDK | 🌐 rubberduckvba.ca