Skip to content

navigation.md

Latest commit

 

History

History
447 lines (315 loc) · 9.47 KB

navigation.md

File metadata and controls

447 lines (315 loc) · 9.47 KB

Navigation Features

← Back to Documentation Home

Master code navigation with F12, Ctrl+F12, and hover tooltips.

Overview

The Clarion Extension provides three powerful ways to navigate your code:

  • Go to Definition (F12) - Find where something is declared
  • Go to Implementation (Ctrl+F12) - See the actual code
  • Hover Tooltips - Preview without leaving your current file

All navigation features are scope-aware and work across files in your solution.

Go to Definition (F12)

What it does: Jumps to where a symbol is declared or defined.

Supported Symbols

Procedures

  • Click on any procedure call
  • Press F12
  • Jump to:
    • MAP declaration (if it's a mapped procedure)
    • PROCEDURE line (if it's a local procedure)

Example:

  MyProcedure()  ! ← F12 here jumps to MAP or PROCEDURE declaration

Variables

  • Click on any variable
  • Press F12
  • Jump to its declaration in the DATA section or parameter list

Scope-aware: Correctly prioritizes local variables over globals with the same name.

Example:

MyProc PROCEDURE
MyVar    LONG  ! ← F12 on MyVar usage jumps here
CODE
  MyVar = 10   ! ← F12 here

Include Files

  • Click on the filename in an INCLUDE statement
  • Press F12
  • The included file opens

Example:

  INCLUDE('MyFile.inc')  ! ← F12 opens MyFile.inc

Bonus - SECTION support:

  INCLUDE('MyFile.inc', 'MySection')  ! ← F12 jumps to MySection CODE

Modules & Members

  • Click on MODULE attribute in CLASS declaration
  • Press F12
  • Opens the .clw implementation file

Example:

MyClass CLASS,MODULE('MyClass.clw')  ! ← F12 opens MyClass.clw

Reverse lookup: From MEMBER file back to parent MODULE:

  • Press F12 on MEMBER('MyClass') to jump back to CLASS declaration

Methods

  • Click on method name (in call or declaration)
  • Press F12
  • Jump to method declaration in CLASS

Method overload support: Resolves to the correct overload based on parameters.

Example:

  MyObj.MyMethod('test')  ! ← F12 jumps to correct MyMethod(STRING) declaration

Class Members

  • Click on a class member access (e.g., MyObj.Property)
  • Press F12
  • Jump to the member declaration in the CLASS

Group Prefix Variables

  • Works with prefixed variable access
  • Handles both . and : syntax

Example:

MyGroup GROUP,PRE(Grp)
Field     LONG
        END

CODE
  Grp:Field = 10    ! ← F12 jumps to Field declaration
  MyGroup.Field = 5 ! ← F12 also works here

Go to Implementation (Ctrl+F12)

What it does: Jumps to the actual implementation/code (not just the declaration).

Supported Symbols

MAP Declarations → Procedure Implementation

  • Click on a procedure in a MAP
  • Press Ctrl+F12
  • Jump to the PROCEDURE implementation

Example:

MAP
  MyProc()  ! ← Ctrl+F12 here
END

! ... later in file or another file ...

MyProc PROCEDURE  ! ← Jumps here
CODE
  ! Implementation

Procedure Calls → Implementation

  • Click on any procedure call
  • Press Ctrl+F12
  • Jump to the PROCEDURE implementation (not MAP)

Example:

  MyProc()  ! ← Ctrl+F12 jumps to PROCEDURE implementation

Method Declarations → Implementation

  • Click on method name in CLASS declaration
  • Press Ctrl+F12
  • Jump to method implementation in MODULE file

Example:

! In MyClass.inc:
MyClass CLASS,MODULE('MyClass.clw')
MyMethod  PROCEDURE()  ! ← Ctrl+F12 here
        END

! Jumps to MyClass.clw:
MyClass.MyMethod PROCEDURE
CODE
  ! Implementation

MODULE → Source File

  • Click on MODULE statement
  • Press Ctrl+F12
  • Opens the source file

Example:

MAP
  MODULE('MyLib.dll')
    MyFunc(), NAME('_MyFunc')  ! ← Ctrl+F12 finds MyLib source
  END
END

Cross-project support: Automatically finds source files for DLLs/LIBs across your solution.

Hover Tooltips

What it does: Shows documentation, signatures, and previews without leaving your current file.

Hover Over Procedures

Shows:

  • MAP declaration
  • Implementation preview (first 10 lines)
  • File location

Example: Hover over a procedure call to see both its declaration and implementation context.

Hover Over Variables

Shows:

  • Variable type and declaration
  • Scope (global, procedure-local, routine-local)
  • File location

Example:

MyVar  STRING(100)  ! Hover here

Shows:
---
Local procedure variable: MyVar
Type: STRING(100)
File: MyApp.clw (Line 45)
---

Hover Over Built-in Functions

Shows:

  • Function signature
  • Parameter descriptions
  • Return type
  • Usage examples

Example: Hover over SUB to see:

SUB(string, start, <length>)

Returns a substring from a string.

Parameters:
  string - Source string
  start  - Starting position (1-based)
  length - Number of characters (optional)

Returns: STRING

Hover Over Includes

Shows:

  • File preview (first 20 lines)
  • Full file path

SECTION support: If INCLUDE specifies a SECTION, shows only that section content.

Example:

INCLUDE('MyFile.inc', 'MySection')  ! Hover shows MySection content

Hover Over Methods

Shows:

  • Method signature
  • Parameter types
  • Implementation preview
  • File location

Overload support: Shows all overloaded versions if multiple exist.

CodeLens — Inline Reference Counts

A N references count appears above every procedure and CLASS declaration.

  • Shows how many times the symbol is referenced across the solution
  • Click the lens to open the References panel with all locations
  • Dead code (0 references) is immediately visible
  • Requires solution to be open for cross-file counts

Find All References (Shift+F12)

  • Press Shift+F12 on any symbol to find all usages
  • Scope-aware: searches across all project files in the solution
  • Works for procedures, classes, variables, methods, type names in declarations
  • Results grouped by file with line previews

Rename Symbol (F2)

  • Press F2 on any user-defined symbol to rename it across the whole workspace
  • Scope-aware: only renames symbols in the correct scope
  • Protects library/read-only .inc files from modification
  • Validates cursor position before opening the rename dialog

Document Highlight

  • Click on a symbol to highlight all its occurrences in the current file
  • Useful for quickly seeing all uses without opening the References panel

INTERFACE Support

  • Hover, F12, Ctrl+F12, and Find All References work on interface methods
  • Supports IMPLEMENTS() declarations
  • Resolves 3-part Class.Interface.Method implementations
  • Navigate from interface method declaration to all class implementations

LIKE(TypeName) Chain Navigation

  • SELF.OrigWin.Maximized where OrigWin is declared LIKE(WindowPositionGroup) navigates correctly to the Maximized field in the GROUP
  • Colon-qualified names such as LIKE(PYA:RECORD) are also supported

Navigation Tips

Breadcrumb Navigation

  • Use the breadcrumb trail at the top of the editor
  • Click to jump to different parts of your code structure

Go Back / Go Forward

  • After using F12, press Alt+← to go back
  • Press Alt+→ to go forward
  • Navigate your jump history easily

Peek Definition (Alt+F12)

  • Shows definition in a popup without leaving your current location
  • Great for quick lookups

Symbol Search (Ctrl+T)

  • Search for any symbol across your solution
  • Type the name and jump to it

Scope-Aware Navigation

The extension understands Clarion scope rules:

Variable Scope Priority

  1. Procedure-local variables (current procedure DATA section)
  2. Routine-local variables (routine DATA section)
  3. Module-local variables (MODULE's DATA section)
  4. Global variables (file-level DATA section)

Example:

MyVar  LONG  ! Global

MyProc PROCEDURE
MyVar    STRING(10)  ! Local (shadows global)
CODE
  MyVar = 'test'  ! ← F12 goes to local STRING, not global LONG

Routine Variable Access

Variables in routines are accessible from the parent procedure.

Example:

MyProc PROCEDURE
CODE
  DO MyRoutine
  RETURN

MyRoutine ROUTINE
MyVar     LONG
  MyVar = 10  ! ← F12 finds MyVar in this routine

Performance

Blazing Fast: All navigation features use optimized caching and indexing.

  • MAP resolution: Direct lookup, no scanning hundreds of files
  • Parent scope lookups: O(1) operations with parent index
  • Cross-file resolution: Efficient file-based caching

Even in large codebases (1000+ files), navigation is instant.

Troubleshooting

F12 Not Working

Check:

  1. Solution opened correctly (folder containing .sln)
  2. Symbol is within solution scope
  3. File is not excluded/ignored

Navigation Goes to Wrong Place

Possible causes:

  1. Multiple declarations with same name (check scope)
  2. Redirection files not configured correctly
  3. Include paths not resolving

Solution:

  • Use hover tooltip to verify you're on the correct symbol
  • Check .clarion.properties redirection settings

Cross-File Navigation Not Working

Check:

  1. All files are part of the solution
  2. Include paths are correct
  3. Redirection files are configured

Related Features