Skip to content

Commit f8e122c

Browse files
KubaOKubaO
committed
TBMANLIB_Dialog: a contributed section of 32 pages (cDialog and its 30 members), with its snapshot, sample template and book chapter; what its dialogs do comes from a probe kept in test/package-probes/, which operates them in an exe on a private desktop
1 parent 0892a1e commit f8e122c

44 files changed

Lines changed: 3516 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎WIP.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ sibling. History goes nowhere: git keeps it.
3333

3434
Reference documentation is **complete** for all thirteen packages: VBA, VBRUN, VB, WebView2, Assert, CustomControls, CEF, WinEventLogLib, WinNamedPipesLib, WinServicesLib, tbIDE, WinNativeCommonCtls and AppGlobalClassObject. It is adapted from primary sources: Microsoft VBA-Docs (CC-BY-4.0) for the runtime library, `.twin` source for the twinBASIC-specific packages. The CEF and WebView2 packages also carry a tutorial set.
3535

36-
Thirteen **contributed** packages from TWINSERV have sections under `docs/Reference/Contributed/`: FileProps, Fmt, OLEGuids, WinReg, TwinTimerPackage, TBMANLIB_ListBoxHScroll, TBMANLIB_RES, tbProjPacker, tbRegExp and VBA_JSON complete; AutoCompleteLib, BigNumberLib and VBComDlg their main class only. Fmt documents its test code (`HelloWorldClass`, `HelloWorldModule`, `Pootle`) in one paragraph of its landing page, which `exclude_from_docs` names. tbRegExp's `exclude_from_docs` names its private engine module, `StaticRegex`, and tbProjPacker's its helper modules, `modPackUnpack` and `modWin32`: the indexer counts a Public Enum as public even inside a Private Module, because a built-in package's are reached through its library symbol written with an asterisk (`*WinNativeCommonCtls`, as `ImlDrawConstants` says). By its bare name no such enum is reachable, in a built-in or a contributed package (TB5079 on BETA 1005). OLEGuids documents each interface's methods on the interface's page. tbRegExp is the first section drafted by the doc-draft workflow ([WIP.Indexer.md](WIP.Indexer.md#draft-and-the-doc-draft-workflow)), then reviewed against the sources, the package's README and VBScript's own **RegExp** under `cscript`. Each published one has a chapter in the book's Packages part. **BigNumberLib and WinReg are not published**: their packages do not compile on BETA 1005, so their pages are kept but excluded in `_config.yml`'s `exclude:` (owner, 2026-10-11), whose comment says how to bring one back.
36+
Fourteen **contributed** packages from TWINSERV have sections under `docs/Reference/Contributed/`: FileProps, Fmt, OLEGuids, WinReg, TwinTimerPackage, TBMANLIB_Dialog, TBMANLIB_ListBoxHScroll, TBMANLIB_RES, tbProjPacker, tbRegExp and VBA_JSON complete; AutoCompleteLib, BigNumberLib and VBComDlg their main class only. Fmt documents its test code (`HelloWorldClass`, `HelloWorldModule`, `Pootle`) in one paragraph of its landing page, which `exclude_from_docs` names. tbRegExp's `exclude_from_docs` names its private engine module, `StaticRegex`, and tbProjPacker's its helper modules, `modPackUnpack` and `modWin32`: the indexer counts a Public Enum as public even inside a Private Module, because a built-in package's are reached through its library symbol written with an asterisk (`*WinNativeCommonCtls`, as `ImlDrawConstants` says). By its bare name no such enum is reachable, in a built-in or a contributed package (TB5079 on BETA 1005). OLEGuids documents each interface's methods on the interface's page. What TBMANLIB_Dialog's pages say its dialogs do comes from `test/package-probes/TBMANLIB_Dialog/`, which operates them in a built exe on a private desktop; run it again when the package's version changes. tbRegExp is the first section drafted by the doc-draft workflow ([WIP.Indexer.md](WIP.Indexer.md#draft-and-the-doc-draft-workflow)), then reviewed against the sources, the package's README and VBScript's own **RegExp** under `cscript`. Each published one has a chapter in the book's Packages part. **BigNumberLib and WinReg are not published**: their packages do not compile on BETA 1005, so their pages are kept but excluded in `_config.yml`'s `exclude:` (owner, 2026-10-11), whose comment says how to bring one back.
3737

3838
The rest of this file is the maintenance guide for updating existing pages or adding new ones: package surface notes, page conventions, and the integrity check.
3939

‎builder/page-baseline.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"src": "docs",
3-
"pages": 1099,
3+
"pages": 1131,
44
"staticFiles": 794
55
}

‎docs/Reference/Contributed.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Each package is versioned apart from twinBASIC, and its section says which versi
1616
- [**FileProps**](FileProps/) -- the Windows shell properties of a file, read and written
1717
- [**Fmt**](Fmt/) -- **StringFormat**, a string built from a format string and values, in the style of C#'s **String.Format**
1818
- [**OLEGuids**](OLEGuids/) -- OLE and COM interfaces and structures in twinBASIC source, in place of `OLEGuids.tlb`
19+
- [**TBMANLIB_Dialog**](TBMANLIB_Dialog/) -- the **cDialog** class: the Open, Save and folder dialogs, with file filters and path helpers
1920
- [**TBMANLIB_ListBoxHScroll**](TBMANLIB_ListBoxHScroll/) -- a horizontal scroll bar for a **ListBox**
2021
- [**TBMANLIB_RES**](TBMANLIB_RES/) -- resources embedded in an executable, as bytes, strings, hex, Base64 or pictures
2122
- [**tbProjPacker**](tbProjPacker/) -- a `.twinproj` or `.twinpack` file unpacked into a folder of source files, and packed again

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/AddFilter.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: AddFilter
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/AddFilter
5+
has_toc: false
6+
---
7+
8+
# AddFilter
9+
{: .no_toc }
10+
11+
Appends a description and a pattern to the [**Filter**](Filter) of the Open and Save As dialogs.
12+
13+
Syntax: *object*.**AddFilter** ( *strDescription*, *strExtension* )
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
*strDescription*
19+
: *required* A **String**, the text that the dialog shows for the pair, such as `Text Files (*.txt)`.
20+
21+
*strExtension*
22+
: *required* A **String**, the pattern that selects the files, such as `*.txt`. Several patterns are separated by semicolons: `*.jpg;*.jpeg`.
23+
24+
## Remarks
25+
26+
**AddFilter** appends `description|pattern` to the text of **Filter**, with a `|` in front of it when **Filter** is not empty. The first pair added is the one that the dialog selects when it opens.
27+
28+
A filter with one pair gives a file-type list with one item. Despite its name, *strExtension* is a pattern, and the class uses the text as it is: it adds no `*.` in front. Write the pattern in the form that the Windows documentation of `OPENFILENAME` gives, such as `*.txt`.
29+
30+
The class does not check the arguments. A `|` in either one adds an element, so the later elements are no longer paired correctly.
31+
32+
## Example
33+
34+
```tb check_build check_run
35+
Dim dlg As New cDialog
36+
dlg.AddFilter "Text Files (*.txt)", "*.txt"
37+
dlg.AddFilter "Pictures", "*.png;*.jpg"
38+
Debug.Print dlg.Filter ' Text Files (*.txt)|*.txt|Pictures|*.png;*.jpg
39+
```
40+
41+
A `|` in a description makes three elements out of two:
42+
43+
```tb check_build check_run
44+
Dim dlg As New cDialog
45+
dlg.AddFilter "Text|Notes", "*.txt"
46+
Debug.Print UBound(Split(dlg.Filter, "|")) + 1 ' 3
47+
```
48+
49+
## See Also
50+
51+
- [Filter](Filter) property -- the whole list as one string
52+
- [ClearFilter](ClearFilter) method -- empties the filter
53+
- [SetCommonFilters](SetCommonFilters) method -- replaces the filter with a ready-made list
54+
- [ShowOpen](ShowOpen) method -- shows the Open dialog
55+
- [cDialog](.) class -- overview

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/ClearFilter.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
title: ClearFilter
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ClearFilter
5+
has_toc: false
6+
---
7+
8+
# ClearFilter
9+
{: .no_toc }
10+
11+
Empties the [**Filter**](Filter) of the Open and Save As dialogs.
12+
13+
Syntax: *object*.**ClearFilter**
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
## Remarks
19+
20+
**ClearFilter** sets **Filter** to an empty string, as `dlg.Filter = ""` does. The four `Set...Filters` methods call it first, so each of them replaces the filter.
21+
22+
## Example
23+
24+
```tb check_build check_run
25+
Dim dlg As New cDialog
26+
dlg.AddFilter "Text Files (*.txt)", "*.txt"
27+
Debug.Print Len(dlg.Filter) > 0 ' True
28+
29+
dlg.ClearFilter
30+
Debug.Print Len(dlg.Filter) ' 0
31+
```
32+
33+
## See Also
34+
35+
- [Filter](Filter) property -- the whole list as one string
36+
- [AddFilter](AddFilter) method -- appends a pair
37+
- [Reset](Reset) method -- clears the filter along with every other property
38+
- [cDialog](.) class -- overview

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/CreatePrompt.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: CreatePrompt
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/CreatePrompt
5+
has_toc: false
6+
---
7+
8+
# CreatePrompt
9+
{: .no_toc }
10+
11+
Returns or sets whether the Open dialog asks permission before it accepts the name of a file that does not exist.
12+
13+
Syntax: *object*.**CreatePrompt** [ = *boolean* ]
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
*boolean*
19+
: A **Boolean**. **True** sets `OFN_CREATEPROMPT`. The default is **False**.
20+
21+
## Remarks
22+
23+
Only [**ShowOpen**](ShowOpen) uses the property. [**ShowSave**](ShowSave) never sets `OFN_CREATEPROMPT`, and [**ShowBrowseForFolder**](ShowBrowseForFolder) ignores the property.
24+
25+
When the user types the name of a file that does not exist, such as `nosuch.txt`, the box *This file doesn't exist. Create the file?* appears, with the buttons *Yes* and *No*. *Yes* closes the dialog and returns the path. *No* leaves the dialog open. This happens whether [**FileMustExist**](FileMustExist) is **True** or **False**, so the question takes the place of the *File not found* box that **FileMustExist** shows.
26+
27+
The file is not created: neither the dialog nor the class creates it, and the program has to do so.
28+
29+
## Example
30+
31+
```tb check_build check_run
32+
Dim dlg As New cDialog
33+
Debug.Print dlg.CreatePrompt ' False
34+
35+
dlg.CreatePrompt = True
36+
Debug.Print dlg.CreatePrompt ' True
37+
```
38+
39+
This example lets the user name a new file in the Open dialog and creates it when the user agrees.
40+
41+
```tb check_build
42+
Dim dlg As New cDialog
43+
Dim path As String
44+
45+
dlg.CreatePrompt = True
46+
path = dlg.ShowOpen()
47+
If Len(path) > 0 Then
48+
If Len(Dir$(path)) = 0 Then
49+
Open path For Output As #1
50+
Close #1
51+
End If
52+
End If
53+
```
54+
55+
## See Also
56+
57+
- [FileMustExist](FileMustExist) property -- lets only names of existing files through
58+
- [ShowOpen](ShowOpen) method -- shows the Open dialog
59+
- [cDialog](.) class -- overview

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/DefaultExt.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: DefaultExt
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DefaultExt
5+
has_toc: false
6+
---
7+
8+
# DefaultExt
9+
{: .no_toc }
10+
11+
Returns or sets the extension that Windows adds to a file name that the user types without one.
12+
13+
Syntax: *object*.**DefaultExt** [ = *string* ]
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
*string*
19+
: A **String**, an extension written without a period, such as `txt`. The default is an empty string.
20+
21+
## Remarks
22+
23+
[**ShowOpen**](ShowOpen) and [**ShowSave**](ShowSave) pass the text as the `lpstrDefExt` member of `OPENFILENAME`. [**ShowBrowseForFolder**](ShowBrowseForFolder) ignores it.
24+
25+
Windows appends the extension to a name that the user types without one. Write the extension without a period. The class does not change the text, and does not take an extension from the selected pair of [**Filter**](Filter).
26+
27+
In the Save As dialog, with the user typing `out`:
28+
29+
| **DefaultExt** | **ShowSave** returns |
30+
|---|---|
31+
| `txt` | `<dir>\out.txt` |
32+
| `.txt` | `<dir>\out..txt` |
33+
| An empty string | `<dir>\out` |
34+
35+
`<dir>` is the folder of the dialog. A period in **DefaultExt** is kept, and gives a name with two periods. An empty **DefaultExt** appends nothing.
36+
37+
## Example
38+
39+
```tb check_build check_run
40+
Dim dlg As New cDialog
41+
Debug.Print "[" & dlg.DefaultExt & "]" ' []
42+
43+
dlg.DefaultExt = "txt"
44+
Debug.Print dlg.DefaultExt ' txt
45+
```
46+
47+
This example shows the Save As dialog and adds `.txt` to a name typed without an extension.
48+
49+
```tb check_build
50+
Dim dlg As New cDialog
51+
dlg.DefaultExt = "txt"
52+
dlg.SetCommonFilters
53+
Debug.Print dlg.ShowSave()
54+
```
55+
56+
## See Also
57+
58+
- [Filter](Filter) property -- the file-type list, which does not set the extension
59+
- [ShowSave](ShowSave) method -- shows the Save As dialog
60+
- [ShowOpen](ShowOpen) method -- shows the Open dialog
61+
- [cDialog](.) class -- overview

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/DialogTitle.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: DialogTitle
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DialogTitle
5+
has_toc: false
6+
---
7+
8+
# DialogTitle
9+
{: .no_toc }
10+
11+
Returns or sets the text that the dialogs show as their title, or in the folder dialog as an instruction above the tree of folders.
12+
13+
Syntax: *object*.**DialogTitle** [ = *string* ]
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
*string*
19+
: A **String**. The default is an empty string.
20+
21+
## Remarks
22+
23+
[**ShowOpen**](ShowOpen) and [**ShowSave**](ShowSave) pass the text as the `lpstrTitle` member of `OPENFILENAME`, the text of the title bar. With an empty **DialogTitle** the Open dialog is titled *Open* and the Save As dialog *Save As*. A text that is set replaces the title.
24+
25+
[**ShowBrowseForFolder**](ShowBrowseForFolder) passes the text as the `lpszTitle` member of `BROWSEINFO`. The title bar of that dialog always reads *Browse For Folder* (*Browse for Folder* when [**NewDialogStyle**](NewDialogStyle) is **False**), and **DialogTitle** is shown as a line of text above the tree of folders, as an instruction to the user. With an empty **DialogTitle** there is no text there.
26+
27+
## Example
28+
29+
This example reads the starting value and sets a title.
30+
31+
```tb check_build check_run
32+
Dim dlg As New cDialog
33+
Debug.Print "[" & dlg.DialogTitle & "]" ' []
34+
35+
dlg.DialogTitle = "Choose the log file"
36+
Debug.Print dlg.DialogTitle ' Choose the log file
37+
```
38+
39+
This example shows the Open dialog with that title.
40+
41+
```tb check_build
42+
Dim dlg As New cDialog
43+
dlg.DialogTitle = "Choose the log file"
44+
Debug.Print dlg.ShowOpen()
45+
```
46+
47+
## See Also
48+
49+
- [ShowOpen](ShowOpen) method -- shows the Open dialog
50+
- [ShowSave](ShowSave) method -- shows the Save As dialog
51+
- [ShowBrowseForFolder](ShowBrowseForFolder) method -- shows the Browse For Folder dialog
52+
- [cDialog](.) class -- overview

‎docs/Reference/Contributed/TBMANLIB_Dialog/cDialog/FileMustExist.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
title: FileMustExist
3+
parent: cDialog
4+
permalink: /tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileMustExist
5+
has_toc: false
6+
---
7+
8+
# FileMustExist
9+
{: .no_toc }
10+
11+
Returns or sets whether the Open dialog lets the user choose only the name of a file that exists.
12+
13+
Syntax: *object*.**FileMustExist** [ = *boolean* ]
14+
15+
*object*
16+
: *required* An object expression that evaluates to a **cDialog**.
17+
18+
*boolean*
19+
: A **Boolean**. **True** sets `OFN_FILEMUSTEXIST`. The default is **True**.
20+
21+
## Remarks
22+
23+
Only [**ShowOpen**](ShowOpen) uses the property. [**ShowSave**](ShowSave) never sets `OFN_FILEMUSTEXIST`, and Windows documents the flag for Open dialogs only, so **FileMustExist** has no effect on a Save As dialog. [**ShowBrowseForFolder**](ShowBrowseForFolder) ignores it too.
24+
25+
With **True**, a name that the user types and that does not exist, such as `nosuch.txt`, makes Windows show the box *File not found. Check the file name and try again.*, and the Open dialog stays open. Windows documents that the flag also applies `OFN_PATHMUSTEXIST`. With **False**, **ShowOpen** returns the path of a file that does not exist, and does not create the file, so the caller has to be ready to meet a missing file.
26+
27+
With [**CreatePrompt**](CreatePrompt) **True**, the question of that property is asked in place of the box, whether **FileMustExist** is **True** or **False**.
28+
29+
## Example
30+
31+
```tb check_build check_run
32+
Dim dlg As New cDialog
33+
Debug.Print dlg.FileMustExist ' True
34+
35+
dlg.FileMustExist = False
36+
Debug.Print dlg.FileMustExist ' False
37+
```
38+
39+
This example lets the Open dialog return a name that does not exist, and creates the file when it is missing.
40+
41+
```tb check_build
42+
Dim dlg As New cDialog
43+
Dim path As String
44+
45+
dlg.FileMustExist = False
46+
path = dlg.ShowOpen()
47+
If Len(path) > 0 Then
48+
If Len(Dir$(path)) = 0 Then
49+
Open path For Output As #1
50+
Close #1
51+
End If
52+
End If
53+
```
54+
55+
## See Also
56+
57+
- [PathMustExist](PathMustExist) property -- the check on the folder of the name
58+
- [CreatePrompt](CreatePrompt) property -- asks before a name that does not exist is accepted
59+
- [ShowOpen](ShowOpen) method -- shows the Open dialog
60+
- [cDialog](.) class -- overview

0 commit comments

Comments
 (0)