Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions WIP.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,10 @@ Formatting conventions:
- Parameter lists use the deflist `term` + `: definition` indentation pattern (NOT the MS-style markdown table).
- Set `vba_attribution: true` in the frontmatter on any page derived from VBA-Docs; omit it on fully original content (e.g. VB package pages). The flag drives an extra line in the site footer.

#### Attribution policy

The attribution rule is **per-page**, determined by content provenance — not by package membership. A symbol existing in VBA is not sufficient to require the flag: the twinBASIC page must have been derived (verbatim or paraphrased) from a specific VBA-Docs source page. Many symbols that exist in VBA have no dedicated VBA-Docs page at all, and even where one exists the twinBASIC page may have been written independently. In particular, `VBA/HiddenModule`, `VBA/Compilation`, `VBA/TbExpressionService`, and twinBASIC-specific additions within VBA modules (`CType`, `If`, `CallByDispId`, `RaiseEventByName`, `ObjPtr`, `VarPtr`, `StrPtr`, ...) are twinBASIC-original and correctly omit `vba_attribution: true` regardless of their package location.

### Cross-section linking

Relative links resolve against the **rendered URL** (the page's `permalink:`), not the file path. Pages that share a URL folder can use bare names (`[Y](Y)`); crossing folders needs `../` to climb out.
Expand Down
2 changes: 1 addition & 1 deletion builder/template.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,7 @@ function renderSidebar(site) {
// fallback footer. The site doesn't override nav_footer_custom.html,
// so the upstream default applies verbatim.
` <footer class="site-footer">\n` +
` This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.\n` +
` This site uses <a href="https://github.com/just-the-docs/just-the-docs">Just the Docs</a>, a documentation theme originally for Jekyll.\n` +
` </footer>\n` +
` </div>`;
}
Expand Down
2 changes: 0 additions & 2 deletions docs/Features/Advanced/Static-Linking.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,5 +49,3 @@ Module MainModule

> [!NOTE]
> StdCall names will be mangled with argument sizes, e.g. `int myfunc(int x, short y);` would be `myfunc@6`. It therefore may be better to use `CDecl`.

A documentation page will be dedicated to more fully explaining this in the future; for now if you need help with it, visit the tB Discord or Discussions section of the GitHub repository and ask.
10 changes: 10 additions & 0 deletions docs/Features/Compiler-IDE/CodeLens.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,13 @@ The CodeLens feature allows running Subs and Functions, with no arguments and in
Methods eligible to run with CodeLens (when enabled), have a bar above them that you can click to run:

![image](../Images/351d0147-cad3-4e16-89e5-0a9e43496740.png)

### Example

A no-argument `Public Sub` in a module is eligible for CodeLens:

```tb
Public Sub RunTest()
Debug.Print "Hello from CodeLens"
End Sub
```
7 changes: 7 additions & 0 deletions docs/Features/Compiler-IDE/Debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,13 @@ New to the debugging experience is a trace logging feature that automatically cr

![image](../Images/4fc2bf99-2bec-4943-837d-21038d791574.png)

```tb
Public Sub ProcessOrder(ByVal orderId As Long)
Debug.TracePrint "ProcessOrder called, orderId=" & CStr(orderId)
' ... processing ...
End Sub
```

## Stale/Dangling Pointer Detection

Bugs result from using Strings and Variants after they have been freed. It may not be noticed immediately if the memory has not been overwritten, but it's sometimes hard to detect and can cause issues like a String displaying it's previous value or garbage. This debugging option detects use-after-free, and replaces the data with a special symbol indicating the problem.
Expand Down
12 changes: 12 additions & 0 deletions docs/Features/GUI-Components/Control-Properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,15 @@ permalink: /Features/GUI-Components/Control-Properties
## Timer Enhancements

`Timer.Interval` can now be set to any positive `Long` instead of being limited to 65,535.

## Example

```tb
TextBox1.TextHint = "Enter your name"
TextBox1.NumbersOnly = True

Label1.Angle = 45
Label1.LineSpacing = 30

Timer1.Interval = 120000 ' 2 minutes; not limited to 65,535 ms
```
14 changes: 14 additions & 0 deletions docs/Features/GUI-Components/UserControl.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,17 @@ These work with all child windows inside the UserControl, including ones created
## Access to Raw Message Data

You can access raw message data in the `PreKeyDown`/`PreKeyUp` event handlers with the new `PreKeyWParam`/`PreKeyLParam` and `PreKeyTargetHwnd` UserControl properties.

## Example

```tb
Private Sub UserControl_Initialize()
PreKeyEvents = True
End Sub

Private Sub UserControl_PreKeyDown(KeyCode As Integer, Shift As Integer)
If KeyCode = vbKeyTab Then
Debug.Print "Tab intercepted; lParam=" & CStr(PreKeyLParam)
End If
End Sub
```
14 changes: 14 additions & 0 deletions docs/Features/Language/Comments.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,17 @@ a comment until:
*/
```

### Example

```tb
' Single-line comment using the apostrophe

Sub Greet(ByVal name As String /* in */)
Debug.Print "Hello, " & name ' inline comment
/*
This block comment
spans multiple lines.
*/
End Sub
```

10 changes: 10 additions & 0 deletions docs/Features/Language/Handlers.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,16 @@ You can now separate the name of method from the class member it applies to.

For events on Forms, UserControls, and event-raising objects, you can define any method as the handler, rather than need to name it as `Object_Event()`, by following it with `Handles Object.Event`. For example, in a form, instead of `Private Sub Form_Load()` you could handle the `Load` event with `Private Sub OnLoad() Handles Form.Load`.

```tb
Private Sub OnLoad() Handles Form.Load
Caption = "Loaded"
End Sub

Private Sub OnClick() Handles Command1.Click
Debug.Print "clicked"
End Sub
```

## Implements for Interfaces

Similar to the above, for forms/UCs/classes that use `Implements`, you can use `Sub Bar() Implements IFoo.Bar`. Note that you can specify more than one implemented method; for more information, see the [Enhancements to Implements section](Interfaces-CoClasses).
Expand Down
10 changes: 10 additions & 0 deletions docs/Features/Language/Literals.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,13 @@ In addition to `&H` for hexadecimal literals and `&O` for octal notation, twinBA
## Digit Grouping

The `&H`, `&O`, and `&B` literals can all be grouped using an underscore, for example, grouping a `Long` by it's constituent binary byte groups: `&B10110101_10100011_10000011_01101110`, or grouping a `LongLong` as two `Long` groups: `&H01234567_89ABCDEF`.

## Example

```tb
Dim flags As Long = &B1010 ' 10 in decimal
Dim perms As Long = &O17 ' 15 in decimal
Dim colour As Long = &HFF ' 255 in decimal
Dim mask As Long = &B10110101_10100011 ' grouped binary bytes
Dim wide As LongLong = &H01234567_89ABCDEF ' grouped hex halves
```
12 changes: 12 additions & 0 deletions docs/Features/Language/Loop-Control.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,15 @@ The following new statements are available for controlling the procession of loo
- `Continue While` - Proceed to the next iteration (or end) of `While` loop.
- `Continue Do` - Proceed to the next iteration of `Do` loop.
- `Exit While` - Exit a `While` loop immediately.

## Example

```tb
Dim i As Long
For i = 1 To 10
If i Mod 2 = 0 Then Continue For ' skip even numbers
If i > 7 Then Exit For ' stop before reaching 8
Debug.Print i
Next
' prints: 1, 3, 5, 7
```
16 changes: 16 additions & 0 deletions docs/Features/Language/Operators.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,19 @@ These are the equivalent of `var = var (operand) (var2)`. So `i += 1` is the equ

The logical opposite of the [`Is`](../../tB/Core/Is) operator for testing object equivalence. For example, instead of `If (object Is Nothing) = False` you could now write `If object `[`IsNot`](../../tB/Core/IsNot)` Nothing Then`.

## Examples

```tb
Dim n As Long = &HFF
Dim shifted As Long = n << 4 ' result: &HFF0

n += 1 ' compound assignment: n = &H100
n <<= 2 ' left-shift assignment: n = &H400

Dim obj As Object = Nothing
If obj IsNot Nothing Then Debug.Print obj

Dim x As Long = -5
Debug.Print If(x >= 0, x, -x) ' short-circuit If(): prints 5
```

6 changes: 6 additions & 0 deletions docs/Features/Language/Type-Inference.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ Variables can now be declared `As Any` and their type will be inferred, similar

`Dim x As Any = 5&` would result in x being a `Long`.

```tb
Dim x As Any = 5& ' x is inferred as Long
Dim s As Any = "hello" ' s is inferred as String
Dim b As Any = True ' b is inferred as Boolean
```

## Limitations

This is only for the `Dim` statement; arguments cannot be `As Any` except in API declarations.
8 changes: 8 additions & 0 deletions docs/Features/Packages/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,12 @@ With TWINPACK packages you group common components together into their own names

Please be aware that TWINPACK files currently contain the full source code of your packaged components. It is planned that we will in future allow for creating binary (compiled) TWINPACK files for developers that hold an Ultimate edition licence of twinBASIC.

## Topics

- [Creating a TWINPACK Package](Creating-TWINPACK) -- packaging twinBASIC components into a distributable TWINPACK file.
- [Importing a Package from TWINSERV](Importing-TWINSERV) -- browsing and installing packages from the TWINSERV online repository.
- [Importing a Package from a TWINPACK File](Importing-TWINPACK) -- installing a package from a local TWINPACK file.
- [Linked Packages](Linked) -- storing a package in a shared location rather than embedding it in each project file.
- [Updating a Package](Updating) -- removing an outdated package and installing a newer version from TWINSERV.

[^1]: A service of TWINBASIC LTD offered to the user community.
2 changes: 1 addition & 1 deletion docs/Features/Project-Configuration/Compiler-Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ You can adjust the following parameters: Max Size Raw, Max Size Lookup, and Data

## Boolean Type Sanitization

Under the hood, a Boolean is a 2-byte type. With memory APIs, or when receiving these from outside code, it's possible to store values other than the ones representing `True` and `False`. This option validates Booleans from external sources, e.g. COM objects and APIs, to ensure only the two supported values are stored.
Internally, a Boolean is a 2-byte type. With memory APIs, or when receiving these from outside code, it's possible to store values other than the ones representing `True` and `False`. This option validates Booleans from external sources, e.g. COM objects and APIs, to ensure only the two supported values are stored.

## Additional Options

Expand Down
12 changes: 12 additions & 0 deletions docs/Features/Project-Configuration/Project-Types.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,18 @@ While it was possible to accomplish this via hacks previously, tB offers it as a

Standard DLLs in twinBASIC can still specify a startup point; each export will then check if this code has run yet, and if not, run it.

```tb
[DllExport]
Public Function Add(ByVal a As Long, ByVal b As Long) As Long
Add = a + b
End Function

[DllExport]
Public Function Multiply CDecl(ByVal a As Long, ByVal b As Long) As Long
Multiply = a * b
End Function
```

## Console Applications

This project type allows making a true console project rather than a GUI project. Helpfully, it will also add a default `Console` class for reading/writing console IO and provided debug console.
Expand Down
8 changes: 7 additions & 1 deletion docs/IDE/AddIns/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,13 @@ permalink: /tB/IDE/AddIns/

# Add Ins

To install addins in twinBASIC, just unzip and copy each architecture dll in the corresponding folder:
An addin is a Standard DLL that exports `tbCreateCompilerAddin` and returns an object implementing the [**AddIn**](../../Packages/tbIDE/AddIn) interface. Through the [**Host**](../../Packages/tbIDE/Host) object the IDE passes at startup, an addin can reach the toolbar, tool windows, debug console, current project, keyboard shortcuts, and themes. The [**tbIDE package**](../../Packages/tbIDE/) documents the full API.

The New Project dialog includes addin templates (samples 10 through 16), covering patterns from simple toolbar buttons to HTML DOM-backed tool windows. Community addins are listed on the [**Community**](Community) page.

twinBASIC supports two addin install locations. The IDE install directory is available to all user accounts on the machine but may require reinstallation after an IDE update. A per-user application data folder persists across IDE upgrades and requires no administrator rights.

To install an addin via the IDE install directory, unzip and copy each architecture DLL to the matching folder:

`\twinBASIC_IDE_BETA_xxx\addins\win32\`

Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Call Stack.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/CallStack
# Call Stack

![Call Stack](Images/CallStack.png "Call Stack")

The Call Stack pane lists the active chain of procedure calls at the current execution point during a debugging session, with the most recent call at the top. Clicking an entry in the list navigates the editor to that call site.
2 changes: 2 additions & 0 deletions docs/IDE/Debug Console.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ permalink: /tB/IDE/Project/DebugConsole

![Debug Console](Images/DebugConsole.png "Debug Console")

The Debug Console captures output from `Debug.Print` statements and other debug-layer messages written at runtime, displaying them in a scrollable log.

## ![](Images/DebugConsole_AutoScroll.png) Auto Scroll

## ![](Images/DebugConsole_Clear.png) Clear Debug Console
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Memory.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/Memory
# Memory

![Memory](Images/Memory.png "Memory")

The Memory pane displays the raw contents of process memory during a paused debugging session, with addresses in the left column and byte values on the right. It is useful for inspecting data structures at the byte level.
2 changes: 1 addition & 1 deletion docs/IDE/Menu/Add-Ins.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,6 @@ Once you open a project:

Clicking on this menu option shows

> 🛈 Sorry, this menu option has not been imlpemented yet
> 🛈 Sorry, this menu option has not been implemented yet

![Global Search - Popup](Images/GlobalSearch-Popup.png "Global Search - Popup")
2 changes: 1 addition & 1 deletion docs/IDE/Menu/Debug.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ permalink: /tB/IDE/Project/Menu/Debug
- Clear Watches
---
- Toggle Breakpoint <kbd>F9</kbd>
- Clear Al Breakpoints <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>F9</kbd>
- Clear All Breakpoints <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>F9</kbd>
---
- Set Next Statement (Jump To Line) <kbd>CTRL</kbd> + <kbd>F9</kbd>
---
Expand Down
4 changes: 0 additions & 4 deletions docs/IDE/Menu/File.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,3 @@ permalink: /tB/IDE/Project/Menu/File
- Clean
---
- Exit <kbd>ALT</kbd> + <kbd>F4</kbd>

> [!NOTE]
>
> TODO: Add each Menu item.
2 changes: 1 addition & 1 deletion docs/IDE/Menu/Format.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ permalink: /tB/IDE/Project/Menu/Format
- Vertical Spacing
---
- Center In Container (Horizontally)
- Center In Container (Horizontally)
- Center In Container (Vertically)
---
- Bring To Front
- Send To Back
Expand Down
4 changes: 0 additions & 4 deletions docs/IDE/Menu/Help.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,6 @@ permalink: /tB/IDE/Project/Menu/Help
---
- Compiler services TRACE mode: Disabled

> [!NOTE]
>
> TODO: Add each Help Menu item.

## About twinBASIC...

![About - Help Menu](Images/Menu_Help_About.png "About - Help Menu")
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Open Editors.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,5 @@ When a project isn't open this will be empty.
When a project is open it will list the files that are currently open in your [Editor](Editor)

![Open Editors](Images/OpenEditors_1.png "Open Editors")

Clicking a file in the list brings it into focus in the editor.
2 changes: 2 additions & 0 deletions docs/IDE/Outline.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ permalink: /tB/IDE/Project/Outline

# Outline

The Outline pane shows a structural overview of the declarations in the active source file---modules, classes, procedures, and properties.

When a project isn't open this will be empty.

![Outline](Images/Outline.png "Outline")
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Package Publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ permalink: /tB/IDE/Project/PackagePublishing

# Package Publishing

The Package Publishing pane manages the metadata for the current project when it is published as a twinBASIC package, including the package name, version, and description.

When a project isn't open this will be empty.

![Package Publishing](Images/PackagePublishing.png "Package Publishing")
Expand Down
4 changes: 0 additions & 4 deletions docs/IDE/Project Explorer.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,6 @@ When a Project is open contextual icons will appear.

Same as Right-Click

> [!NOTE]
>
> TODO: Add each Menu item.

## Right-Click - Add

![Right-Click Add](Images/RightClick-Add.png "Right-Click Add")
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/Properties
# Properties

![Properties](Images/Properties.png "Properties")

The Properties pane shows the properties of the control or object currently selected in the form designer. Property names appear in the left column with their current values on the right; clicking a value edits it in place.
2 changes: 2 additions & 0 deletions docs/IDE/Splash Screen.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/Splash
# Splash Screen

![Splash Screen](Images/Splash_Screen.png "Splash Screen")

The Splash Screen appears each time the IDE starts and displays the current twinBASIC version number, build date, and links to community resources. It closes automatically once the IDE finishes loading.
2 changes: 2 additions & 0 deletions docs/IDE/Status Bar.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ permalink: /tB/IDE/Project/StatusBar

![Status Bar](Images/StatusBar.png "Status Bar")

The Status Bar runs along the bottom of the IDE window and shows at-a-glance information about the health of backend services, the active licence tier, and quick-access links to community resources.

## Services

![Services Unavailable](Images/Services_Unavailable.png "Services Unavailable")
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Toolbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ permalink: /tB/IDE/Project/Toolbox

# Toolbox

The Toolbox lists the controls available for placement on forms and designers in the current project. Additional COM components can be added through the **+ More Components** button, which opens the COM References section of Project Settings.

See [Controls](../../Controls)

<!-- ![Toolbox](../Controls/Images/toolbox.png "Toolbox") -->
Expand Down
2 changes: 2 additions & 0 deletions docs/IDE/Variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/Variables
# Variables

![Variables](Images/Variables.png "Variables")

The Variables pane lists the variables in scope at the current execution point during debugging, showing each variable's name, type, and current value. Structured types---classes and user-defined types---can be expanded to inspect their individual members.
2 changes: 2 additions & 0 deletions docs/IDE/Webpage.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,5 @@ permalink: /tB/IDE/Project/Webpage
# Webpage

![Webpage](Images/Webpage.png "Webpage")

The Webpage pane embeds a web browser view inside the IDE. It is used to display online content---such as documentation or release notes---without opening an external browser.
6 changes: 6 additions & 0 deletions docs/IDE/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,9 @@ permalink: /tB/IDE
# The twinBASIC IDE

![IDE](Images/IDE.png "IDE")

The IDE consists of several fixed panes and tool windows. The [**Project Explorer**](IDE/Project/Explorer) shows the file tree of the open project; the [**Editor**](IDE/Project/Editor) is the main code and designer surface; the [**Properties**](IDE/Project/Properties) pane shows and edits properties for the selected item; the [**Toolbox**](IDE/Project/Toolbox) lists the controls available to drop onto a form.

The debug tool windows --- [**Call Stack**](IDE/Project/CallStack), [**Watches**](IDE/Project/Watches), [**Variables**](IDE/Project/Variables), [**Debug Console**](IDE/Project/DebugConsole), [**Diagnostics**](IDE/Project/Diagnostics), [**Outline**](IDE/Project/Outline), and [**Memory**](IDE/Project/Memory) --- open during a debug session.

The [**tbForm**](IDE/Project/Editor/Form) and [**tbReport**](IDE/Project/Editor/Report) designers open when a form or report file is selected in the Project Explorer. Third-party and community [**addins**](IDE/AddIns/) extend the IDE with additional commands and tool windows.
Loading