From 7b09bc84289cfdf637d625f80c513ed03b59f9f3 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 11 Oct 2026 19:15:22 +0200 Subject: [PATCH 01/15] KeyCompareMode: the default is vbTextCompare, as the text said and the sample did not; a different mode is refused with error 5 once a keyed item is in, not rehashed --- .../Default/VBA/Collection/KeyCompareMode.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/Reference/Default/VBA/Collection/KeyCompareMode.md b/docs/Reference/Default/VBA/Collection/KeyCompareMode.md index edd7a69f1..078f7f676 100644 --- a/docs/Reference/Default/VBA/Collection/KeyCompareMode.md +++ b/docs/Reference/Default/VBA/Collection/KeyCompareMode.md @@ -30,21 +30,23 @@ The *compare* argument settings are: > > **KeyCompareMode** is a twinBASIC extension; the classic VBA **Collection** object always uses case-insensitive comparison and does not expose this property. -The default comparison mode is **vbTextCompare**. Changing the comparison mode rehashes the existing keys, so for large collections it is most efficient to set **KeyCompareMode** before adding items. +The default comparison mode is **vbTextCompare**, whatever the module's **Option Compare** setting, so a new **Collection** matches keys as VBA's does. + +The mode can be changed only while the collection holds no item added with a key. Once one has been added, setting a different mode raises run-time error 5, *Can't change KeyCompareMode once keyed items have been added to the collection*, and the mode stays as it was. Items added without a key do not prevent the change, and neither do keyed items that have since been removed. Setting the mode the collection already has raises no error. A *compare* value other than **vbBinaryCompare** or **vbTextCompare** raises run-time error 5, *Invalid procedure call or argument*. ### Example ```tb check_build Dim col As New Collection -' Default mode is binary (case-sensitive). -col.Add "first", Key:="A" -col.Add "second", Key:="a" ' Distinct from "A" — succeeds. +' The default mode is text: "A" and "a" are the same key. +col.Add "first", Key:="A" +' col.Add "second", Key:="a" ' Would raise error 457: the key is already in use. Dim col2 As New Collection -col2.KeyCompareMode = vbTextCompare +col2.KeyCompareMode = vbBinaryCompare ' Before any item is added with a key. col2.Add "first", Key:="A" -' col2.Add "second", Key:="a" ' Would raise an error — same key as "A". +col2.Add "second", Key:="a" ' A different key from "A", so it succeeds. ``` ### See Also From 05796fa2d10dde2ebb2d539176f59d2ecb3c85d2 Mon Sep 17 00:00:00 2001 From: Kuba Sunderland-Ober Date: Sun, 11 Oct 2026 18:59:13 +0200 Subject: [PATCH 02/15] Contributed packages: nine sections under /tB/Packages/Contributed/, checked against their TWINSERV sources, with their snapshots; left out of the book --- builder/page-baseline.json | 2 +- docs/Reference/Contributed.md | 23 + .../AutoCompleteLib/AutoComplete.md | 178 ++ .../Contributed/AutoCompleteLib/index.md | 16 + .../Contributed/BigNumberLib/BigNumber.md | 413 +++++ .../Contributed/BigNumberLib/index.md | 16 + .../Example/DisplayInDebugConsole.md | 39 + .../Contributed/FileProps/Example/index.md | 49 + .../FileProps/FileProperties/Count.md | 33 + .../FileProps/FileProperties/FilePath.md | 36 + .../FileProps/FileProperties/Item.md | 49 + .../FileProps/FileProperties/VCOMObject.md | 30 + .../FileProps/FileProperties/index.md | 108 ++ .../Contributed/FileProps/FileProperty/ID.md | 43 + .../FileProps/FileProperty/Name.md | 47 + .../FileProps/FileProperty/NameDesc.md | 27 + .../FileProps/FileProperty/VCOMObject.md | 32 + .../FileProps/FileProperty/Value.md | 64 + .../FileProps/FileProperty/ValueDesc.md | 41 + .../FileProps/FileProperty/index.md | 117 ++ .../FilePropertyExplorer/BrowseAndOpenFile.md | 48 + .../FilePropertyExplorer/OpenFile.md | 51 + .../FileProps/FilePropertyExplorer/index.md | 121 ++ docs/Reference/Contributed/FileProps/index.md | 35 + .../cListboxHScroll/Show.md | 53 + .../cListboxHScroll/UnShow.md | 44 + .../cListboxHScroll/index.md | 99 + .../TBMANLIB_ListBoxHScroll/index.md | 21 + .../Contributed/TBMANLIB_RES/Base64Prefix.md | 32 + .../Contributed/TBMANLIB_RES/TBMAN.md | 41 + .../Contributed/TBMANLIB_RES/cRes/Read.md | 52 + .../TBMANLIB_RES/cRes/ReturnBase64.md | 66 + .../TBMANLIB_RES/cRes/ReturnBytes.md | 46 + .../TBMANLIB_RES/cRes/ReturnHex.md | 50 + .../TBMANLIB_RES/cRes/ReturnPicture.md | 35 + .../TBMANLIB_RES/cRes/ReturnString.md | 40 + .../Contributed/TBMANLIB_RES/cRes/index.md | 167 ++ .../Contributed/TBMANLIB_RES/index.md | 32 + .../TwinTimerPackage/TwinTimer/Enabled.md | 62 + .../TwinTimerPackage/TwinTimer/Interval.md | 59 + .../TwinTimerPackage/TwinTimer/Timer.md | 49 + .../TwinTimerPackage/TwinTimer/index.md | 114 ++ .../Contributed/TwinTimerPackage/index.md | 22 + .../Contributed/VBA_JSON/Dictionary/Item.md | 78 + .../Contributed/VBA_JSON/Dictionary/Keys.md | 40 + .../Contributed/VBA_JSON/Dictionary/index.md | 129 ++ .../VBA_JSON/JsonConverter/ConvertToIso.md | 55 + .../VBA_JSON/JsonConverter/ConvertToJson.md | 101 + .../VBA_JSON/JsonConverter/ConvertToUtc.md | 48 + .../VBA_JSON/JsonConverter/ParseIso.md | 62 + .../VBA_JSON/JsonConverter/ParseJson.md | 58 + .../VBA_JSON/JsonConverter/ParseUtc.md | 48 + .../VBA_JSON/JsonConverter/index.md | 182 ++ docs/Reference/Contributed/VBA_JSON/index.md | 31 + .../Contributed/VBComDlg/CommonDialog.md | 792 ++++++++ docs/Reference/Contributed/VBComDlg/index.md | 16 + .../WinReg/RegCls/ConvertValueToString.md | 92 + .../Contributed/WinReg/RegCls/CreateKey.md | 49 + .../Contributed/WinReg/RegCls/DeleteKey.md | 44 + .../Contributed/WinReg/RegCls/DeleteKeyEx.md | 53 + .../Contributed/WinReg/RegCls/DeleteValue.md | 55 + .../Contributed/WinReg/RegCls/EnumValues.md | 61 + .../WinReg/RegCls/GetRegistryValueType.md | 56 + .../Contributed/WinReg/RegCls/KeyExists.md | 46 + .../Contributed/WinReg/RegCls/ReadDWORD.md | 54 + .../Contributed/WinReg/RegCls/ReadString.md | 69 + .../Contributed/WinReg/RegCls/ValueExists.md | 51 + .../Contributed/WinReg/RegCls/WriteDWORD.md | 61 + .../Contributed/WinReg/RegCls/WriteString.md | 53 + .../Contributed/WinReg/RegCls/index.md | 342 ++++ docs/Reference/Contributed/WinReg/index.md | 32 + docs/Reference/Packages.md | 1 + docs/_book.yml | 3 + .../contributed/AutoCompleteLib/api.json | 222 +++ .../contributed/BigNumberLib/api.json | 336 ++++ .../snapshots/contributed/FileProps/api.json | 128 ++ .../TBMANLIB_ListBoxHScroll/api.json | 127 ++ .../contributed/TBMANLIB_RES/api.json | 59 + .../contributed/TwinTimerPackage/api.json | 37 + .../snapshots/contributed/VBA_JSON/api.json | 149 ++ .../snapshots/contributed/VBComDlg/api.json | 1624 +++++++++++++++++ indexer/snapshots/contributed/WinReg/api.json | 33 + 82 files changed, 8178 insertions(+), 1 deletion(-) create mode 100644 docs/Reference/Contributed.md create mode 100644 docs/Reference/Contributed/AutoCompleteLib/AutoComplete.md create mode 100644 docs/Reference/Contributed/AutoCompleteLib/index.md create mode 100644 docs/Reference/Contributed/BigNumberLib/BigNumber.md create mode 100644 docs/Reference/Contributed/BigNumberLib/index.md create mode 100644 docs/Reference/Contributed/FileProps/Example/DisplayInDebugConsole.md create mode 100644 docs/Reference/Contributed/FileProps/Example/index.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperties/Count.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperties/FilePath.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperties/Item.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperties/VCOMObject.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperties/index.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/ID.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/Name.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/NameDesc.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/VCOMObject.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/Value.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/ValueDesc.md create mode 100644 docs/Reference/Contributed/FileProps/FileProperty/index.md create mode 100644 docs/Reference/Contributed/FileProps/FilePropertyExplorer/BrowseAndOpenFile.md create mode 100644 docs/Reference/Contributed/FileProps/FilePropertyExplorer/OpenFile.md create mode 100644 docs/Reference/Contributed/FileProps/FilePropertyExplorer/index.md create mode 100644 docs/Reference/Contributed/FileProps/index.md create mode 100644 docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/Show.md create mode 100644 docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/UnShow.md create mode 100644 docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/index.md create mode 100644 docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/index.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/Base64Prefix.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/TBMAN.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/Read.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnBase64.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnBytes.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnHex.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnPicture.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnString.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/cRes/index.md create mode 100644 docs/Reference/Contributed/TBMANLIB_RES/index.md create mode 100644 docs/Reference/Contributed/TwinTimerPackage/TwinTimer/Enabled.md create mode 100644 docs/Reference/Contributed/TwinTimerPackage/TwinTimer/Interval.md create mode 100644 docs/Reference/Contributed/TwinTimerPackage/TwinTimer/Timer.md create mode 100644 docs/Reference/Contributed/TwinTimerPackage/TwinTimer/index.md create mode 100644 docs/Reference/Contributed/TwinTimerPackage/index.md create mode 100644 docs/Reference/Contributed/VBA_JSON/Dictionary/Item.md create mode 100644 docs/Reference/Contributed/VBA_JSON/Dictionary/Keys.md create mode 100644 docs/Reference/Contributed/VBA_JSON/Dictionary/index.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ConvertToIso.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ConvertToJson.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ConvertToUtc.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ParseIso.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ParseJson.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/ParseUtc.md create mode 100644 docs/Reference/Contributed/VBA_JSON/JsonConverter/index.md create mode 100644 docs/Reference/Contributed/VBA_JSON/index.md create mode 100644 docs/Reference/Contributed/VBComDlg/CommonDialog.md create mode 100644 docs/Reference/Contributed/VBComDlg/index.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/ConvertValueToString.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/CreateKey.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/DeleteKey.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/DeleteKeyEx.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/DeleteValue.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/EnumValues.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/GetRegistryValueType.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/KeyExists.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/ReadDWORD.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/ReadString.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/ValueExists.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/WriteDWORD.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/WriteString.md create mode 100644 docs/Reference/Contributed/WinReg/RegCls/index.md create mode 100644 docs/Reference/Contributed/WinReg/index.md create mode 100644 indexer/snapshots/contributed/AutoCompleteLib/api.json create mode 100644 indexer/snapshots/contributed/BigNumberLib/api.json create mode 100644 indexer/snapshots/contributed/FileProps/api.json create mode 100644 indexer/snapshots/contributed/TBMANLIB_ListBoxHScroll/api.json create mode 100644 indexer/snapshots/contributed/TBMANLIB_RES/api.json create mode 100644 indexer/snapshots/contributed/TwinTimerPackage/api.json create mode 100644 indexer/snapshots/contributed/VBA_JSON/api.json create mode 100644 indexer/snapshots/contributed/VBComDlg/api.json create mode 100644 indexer/snapshots/contributed/WinReg/api.json diff --git a/builder/page-baseline.json b/builder/page-baseline.json index fcbd962c5..f066c3e96 100644 --- a/builder/page-baseline.json +++ b/builder/page-baseline.json @@ -1,5 +1,5 @@ { "src": "docs", - "pages": 935, + "pages": 1005, "staticFiles": 794 } diff --git a/docs/Reference/Contributed.md b/docs/Reference/Contributed.md new file mode 100644 index 000000000..865febee8 --- /dev/null +++ b/docs/Reference/Contributed.md @@ -0,0 +1,23 @@ +--- +title: Contributed Packages +parent: Packages +nav_order: 3 +permalink: /tB/Packages/Contributed/ +has_toc: false +--- + +# Contributed Packages + +Community-authored packages published through TWINSERV, the twinBASIC package registry. To use a contributed package, add it to Project → References (Ctrl-T) → Available Packages. + +Each package is versioned apart from twinBASIC, and its section says which version it documents. + +- [**AutoCompleteLib**](AutoCompleteLib/) -- Windows shell auto-complete for text-input controls +- [**BigNumberLib**](BigNumberLib/) -- arbitrary-precision signed integer arithmetic +- [**FileProps**](FileProps/) -- the Windows shell properties of a file, read and written +- [**TBMANLIB_ListBoxHScroll**](TBMANLIB_ListBoxHScroll/) -- a horizontal scroll bar for a **ListBox** +- [**TBMANLIB_RES**](TBMANLIB_RES/) -- resources embedded in an executable, as bytes, strings, hex, Base64 or pictures +- [**TwinTimerPackage**](TwinTimerPackage/) -- a Win32 timer class that reports the elapsed time +- [**VBA_JSON**](VBA_JSON/) -- JSON parsing and serialization, with UTC and ISO 8601 date conversion +- [**VBComDlg**](VBComDlg/) -- the **CommonDialog** class, for the Windows common dialogs +- [**WinReg**](WinReg/) -- reading, writing, deleting and enumerating registry keys and values diff --git a/docs/Reference/Contributed/AutoCompleteLib/AutoComplete.md b/docs/Reference/Contributed/AutoCompleteLib/AutoComplete.md new file mode 100644 index 000000000..c0ba2d90d --- /dev/null +++ b/docs/Reference/Contributed/AutoCompleteLib/AutoComplete.md @@ -0,0 +1,178 @@ +--- +title: AutoComplete +parent: AutoCompleteLib Package +permalink: /tB/Packages/Contributed/AutoCompleteLib/AutoComplete +has_toc: false +--- + +# AutoComplete class +{: .no_toc } + +A class that attaches Windows shell auto-complete behaviour to a text-input control's window handle. + +**AutoComplete** wraps the `IAutoComplete2` COM interface. After calling [**Init**](#init) with the window handle of an edit box and a source type, the Windows shell begins offering suggestions as the user types. The source can be the shell history, the file system, the most-recently-used list, all three combined, or a custom string array supplied through [**CustomSource**](#customsource). + +```tb +Private m_AC As AutoComplete + +Private Sub Form_Load() + Set m_AC = New AutoComplete + m_AC.Init Text1.hWnd, AutoCompleteSourceHistory + m_AC.Options = AutoCompleteOptionSuggestAppend +End Sub +``` + +* TOC +{:toc} + +## Properties + +### CustomSource +{: .no_toc } + +Returns or sets a one-dimensional **String** array used as the suggestion list when [**Init**](#init) is called with **AutoCompleteSourceCustomSource**. + +Syntax: *object*.**CustomSource** [ = *StringArray* ] + +*StringArray* +: A one-dimensional **Variant** holding a **String** array. Empty strings and non-string elements are silently ignored. Assigning **Empty** clears the list. A two-or-more-dimensional array raises run-time error 5 ("Array must be single dimensioned"). An unallocated array raises run-time error 91. Any other value that is not an array raises run-time error 380. + +The getter returns the filtered array currently stored in the object. Assigning a new value replaces the previous list in full; there is no way to append individual entries. + +### FileSystemOptions +{: .no_toc } + +Returns or sets the file-system objects enumerated when the source is **AutoCompleteSourceFileSystem** or **AutoCompleteSourceAll**. + +Syntax: *object*.**FileSystemOptions** [ = *value* ] + +*value* +: One or more **AutoCompleteFileSystemOptionConstants** values combined with `Or`. + +| Constant | Value | Description | +|----------|-------|-------------| +| **AutoCompleteFileSystemOptionNone** | 0 | No specific file-system objects. | +| **AutoCompleteFileSystemOptionCurrentDir** | 1 | The current directory. | +| **AutoCompleteFileSystemOptionMyComputer** | 2 | Objects under *My Computer*. | +| **AutoCompleteFileSystemOptionDesktop** | 4 | Desktop objects. | +| **AutoCompleteFileSystemOptionFavorites** | 8 | Favorites folder contents. | +| **AutoCompleteFileSystemOptionFileSysOnly** | 16 | File-system items only (no virtual shell folders). | +| **AutoCompleteFileSystemOptionFileSysDirs** | 32 | Directories only. | + +### Options +{: .no_toc } + +Returns or sets flags that control how the completion works. + +Syntax: *object*.**Options** [ = *value* ] + +*value* +: One or more **AutoCompleteOptionConstants** values combined with `Or`. + +| Constant | Value | Description | +|----------|-------|-------------| +| **AutoCompleteOptionNone** | &H0 | No special behaviour. | +| **AutoCompleteOptionAppend** | &H2 | Appends the best match to the typed text inline. | +| **AutoCompleteOptionSuggest** | &H1 | Shows a drop-down list of suggestions. | +| **AutoCompleteOptionSuggestAppend** | &H3 | Both **AutoCompleteOptionSuggest** and **AutoCompleteOptionAppend**. | +| **AutoCompleteOptionSearch** | &H4 | Adds a search item at the bottom of the drop-down list. | +| **AutoCompleteOptionFilterPrefixes** | &H8 | Does not match common prefixes such as `www.` and `http://`. | +| **AutoCompleteOptionUseTab** | &H10 | Selects the highlighted suggestion when the user presses **Tab**. | +| **AutoCompleteOptionUpDownKeyDropsList** | &H20 | Opens the drop-down list when the user presses the **Up** or **Down** arrow key. | + +## Methods + +### Disable +{: .no_toc } + +Disables auto-complete without destroying the object. + +Syntax: *object*.**Disable** + +Auto-complete stops offering suggestions. Call [**Enable**](#enable) to turn it back on without calling [**Init**](#init) again. + +### DroppedDown +{: .no_toc } + +Returns whether the suggestion drop-down list is currently visible. + +Syntax: *object*.**DroppedDown** ( ) **As Boolean** + +Returns **True** when the drop-down is open, **False** otherwise. The return value is **False** if the `IAutoCompleteDropDown` interface cannot be obtained. + +### Enable +{: .no_toc } + +Re-enables auto-complete after a call to [**Disable**](#disable). + +Syntax: *object*.**Enable** + +### Init +{: .no_toc } + +Attaches auto-complete to a text-input control. + +Syntax: *object*.**Init** *hWndEdit*, *Source* + +*hWndEdit* +: *required* A **LongPtr** (32-bit: **Long**) containing the window handle of the edit control that should receive suggestions. + +*Source* +: *required* An **AutoCompleteSourceConstants** value identifying where suggestions come from. + +| Constant | Value | Description | +|----------|-------|-------------| +| **AutoCompleteSourceNone** | 0 | Not valid; passing this value raises run-time error 380. | +| **AutoCompleteSourceHistory** | 1 | The shell history list (the `ACLHistory` shell object). | +| **AutoCompleteSourceFileSystem** | 2 | File-system paths, filtered by [**FileSystemOptions**](#filesystemoptions). | +| **AutoCompleteSourceMRU** | 3 | The shell most-recently-used list. | +| **AutoCompleteSourceAll** | 4 | History, file system, and MRU combined through an `IObjMgr`. | +| **AutoCompleteSourceCustomSource** | 5 | The one-dimensional string array set through [**CustomSource**](#customsource). | + +The target control must exist when **Init** is called, and **Init** is called before the user starts typing. Calling **Init** with **AutoCompleteSourceNone**, or with any other value outside the table, raises run-time error 380 (Invalid property value). If the internal `IAutoComplete2` object could not be created when the **AutoComplete** object was created, **Init** exits silently. + +### Refresh +{: .no_toc } + +Forces the drop-down list to rebuild its suggestions from the current source. + +Syntax: *object*.**Refresh** + +Calls `IAutoCompleteDropDown.ResetEnumerator` on the underlying COM object. Use this after modifying [**CustomSource**](#customsource) while the list is open, or whenever the suggestion set changes at run time. + +## Example + +This example attaches file-system auto-complete to a text box and restricts suggestions to directories. + +```tb +Private m_AC As AutoComplete + +Private Sub Form_Load() + Set m_AC = New AutoComplete + m_AC.FileSystemOptions = AutoCompleteFileSystemOptionFileSysDirs + m_AC.Options = AutoCompleteOptionSuggestAppend + m_AC.Init Text1.hWnd, AutoCompleteSourceFileSystem +End Sub +``` + +This example supplies a fixed custom list. + +```tb +Private m_AC As AutoComplete + +Private Sub Form_Load() + Set m_AC = New AutoComplete + m_AC.CustomSource = Array("Apple", "Apricot", "Avocado", "Banana", "Blueberry") + m_AC.Options = AutoCompleteOptionSuggest + m_AC.Init Text1.hWnd, AutoCompleteSourceCustomSource +End Sub + +Private Sub btnRefresh_Click() + m_AC.CustomSource = Array("Cherry", "Clementine", "Coconut") + m_AC.Refresh +End Sub +``` + +## See Also + +- [AutoCompleteLib](.) package -- overview diff --git a/docs/Reference/Contributed/AutoCompleteLib/index.md b/docs/Reference/Contributed/AutoCompleteLib/index.md new file mode 100644 index 000000000..d9d223bf3 --- /dev/null +++ b/docs/Reference/Contributed/AutoCompleteLib/index.md @@ -0,0 +1,16 @@ +--- +title: AutoCompleteLib Package +parent: Contributed Packages +has_toc: false +indexed_from: 1.0.0.0 +permalink: /tB/Packages/Contributed/AutoCompleteLib/ +--- + +# AutoCompleteLib Package +{: .no_toc } + +The **AutoCompleteLib** contributed package provides Windows shell auto-complete behavior for text-input controls. The package references the **AutoCompleteGuids** package, which holds the GUID and interface definitions the class uses. + +## Classes + +- [AutoComplete](AutoComplete) -- attaches Windows shell auto-complete behaviour to a text-input control's window handle. diff --git a/docs/Reference/Contributed/BigNumberLib/BigNumber.md b/docs/Reference/Contributed/BigNumberLib/BigNumber.md new file mode 100644 index 000000000..3c3ad9750 --- /dev/null +++ b/docs/Reference/Contributed/BigNumberLib/BigNumber.md @@ -0,0 +1,413 @@ +--- +title: BigNumber +parent: BigNumberLib Package +permalink: /tB/Packages/Contributed/BigNumberLib/BigNumber +has_toc: false +--- + +# BigNumber class +{: .no_toc } + +A **BigNumber** represents an arbitrary-precision signed integer backed by the TomsFastMath (libtfm) C library, supporting numbers up to 4096 bits. A multiplication accepts operands of up to 2048 bits each. The default property is [**ValueString**](#valuestring). + +```tb +Dim a As New BigNumber +Dim b As New BigNumber +Dim result As New BigNumber + +a.ValueString = "123456789012345678901234567890" +b.ValueString = "987654321098765432109876543210" +result.AssignAddition a, b +Debug.Print result.ValueString +``` + +> [!NOTE] +> This class requires twinBASIC BETA 434 or newer. Overflow errors are not trapped. String-to-value conversions silently stop at the first invalid character --- for example, setting `ValueHex = "ABC123he"` stores `&HABC123` without raising an error. + +* TOC +{:toc} + +## Properties + +### ValueString +{: .no_toc } + +Returns or sets the value as a decimal string representation. **Default property.** + +Syntax: *object*.**ValueString** [ = *value* ] + +*value* +: A **String** containing a decimal integer, optionally preceded by a minus sign. Conversion stops at the first character that is not a valid decimal digit. + +The getter returns the decimal digits, preceded by a minus sign for a negative value. + +### ValueHex +{: .no_toc } + +Returns or sets the value as a hexadecimal string representation. + +Syntax: *object*.**ValueHex** [ = *value* ] + +*value* +: A **String** containing a hexadecimal integer (digits `0`--`9` and `A`--`F`, case-insensitive), optionally preceded by a minus sign. Conversion stops at the first character that is not a valid hex digit. + +The getter returns upper-case digits without leading zeros, preceded by a minus sign for a negative value. + +### ValueOctal +{: .no_toc } + +Returns or sets the value as an octal string representation. + +Syntax: *object*.**ValueOctal** [ = *value* ] + +*value* +: A **String** containing an octal integer (digits `0`--`7`), optionally preceded by a minus sign. Conversion stops at the first character that is not a valid octal digit. + +The getter returns the digits without leading zeros, preceded by a minus sign for a negative value. + +### ValueBinary +{: .no_toc } + +Returns or sets the value as a binary string representation. + +Syntax: *object*.**ValueBinary** [ = *value* ] + +*value* +: A **String** containing a binary integer (digits `0` and `1`), optionally preceded by a minus sign. Conversion stops at the first character that is not `0` or `1`. + +The getter returns the digits without leading zeros, preceded by a minus sign for a negative value. + +### IsNegative +{: .no_toc } + +Returns or sets whether the value is negative. + +Syntax: *object*.**IsNegative** [ = *value* ] + +*value* +: A **Boolean**. Setting **True** marks the number as negative; setting **False** marks it as positive. + +## Methods + +### AssignAddition +{: .no_toc } + +Sets this instance to `a + b`. + +Syntax: *object*.**AssignAddition** *a*, *b* + +*a* +: *required* A **BigNumber** holding the first operand. + +*b* +: *required* A **BigNumber** holding the second operand. + +### AssignSubtraction +{: .no_toc } + +Sets this instance to `a - b`. + +Syntax: *object*.**AssignSubtraction** *a*, *b* + +*a* +: *required* A **BigNumber** holding the minuend. + +*b* +: *required* A **BigNumber** holding the subtrahend. + +### AssignMultiplication +{: .no_toc } + +Sets this instance to `a * b`. + +Syntax: *object*.**AssignMultiplication** *a*, *b* + +*a* +: *required* A **BigNumber** holding the first factor. + +*b* +: *required* A **BigNumber** holding the second factor. + +### AssignDivision +{: .no_toc } + +Sets this instance to the integer quotient `a \ b`, truncated toward zero. Raises run-time error 5 if *b* is zero. + +Syntax: *object*.**AssignDivision** *a*, *b* + +*a* +: *required* A **BigNumber** holding the dividend. + +*b* +: *required* A **BigNumber** holding the divisor. Must not be zero. + +### AssignModulus +{: .no_toc } + +Sets this instance to `a Mod b`. The result is zero or has the sign of *b*, so `-7 Mod 2` is 1 and `7 Mod -2` is -1. Raises run-time error 5 if *b* is zero. + +Syntax: *object*.**AssignModulus** *a*, *b* + +*a* +: *required* A **BigNumber** holding the dividend. + +*b* +: *required* A **BigNumber** holding the divisor. Must not be zero. + +### AssignSquared +{: .no_toc } + +Sets this instance to `a * a` (the square of *a*). + +Syntax: *object*.**AssignSquared** *a* + +*a* +: *required* A **BigNumber** holding the value to square. + +### AssignAdditionModulus +{: .no_toc } + +Sets this instance to `(a + b) Mod mod_c`. + +Syntax: *object*.**AssignAdditionModulus** *a*, *b*, *mod_c* + +*a* +: *required* A **BigNumber** holding the first addend. + +*b* +: *required* A **BigNumber** holding the second addend. + +*mod_c* +: *required* A **BigNumber** holding the modulus. + +### AssignSubtractionModulus +{: .no_toc } + +Sets this instance to `(a - b) Mod mod_c`. + +Syntax: *object*.**AssignSubtractionModulus** *a*, *b*, *mod_c* + +*a* +: *required* A **BigNumber** holding the minuend. + +*b* +: *required* A **BigNumber** holding the subtrahend. + +*mod_c* +: *required* A **BigNumber** holding the modulus. + +### AssignMultiplicationModulus +{: .no_toc } + +Sets this instance to `(a * b) Mod mod_c`. + +Syntax: *object*.**AssignMultiplicationModulus** *a*, *b*, *mod_c* + +*a* +: *required* A **BigNumber** holding the first factor. + +*b* +: *required* A **BigNumber** holding the second factor. + +*mod_c* +: *required* A **BigNumber** holding the modulus. + +### AssignSquaredModulus +{: .no_toc } + +Sets this instance to `(a * a) Mod mod_b`. + +Syntax: *object*.**AssignSquaredModulus** *a*, *mod_b* + +*a* +: *required* A **BigNumber** holding the value to square. + +*mod_b* +: *required* A **BigNumber** holding the modulus. + +### AssignModularMultiplicativeInverse +{: .no_toc } + +Sets this instance to the modular multiplicative inverse of *a* modulo *mod_b* --- the value *x* such that `(a * x) Mod mod_b = 1`. Raises run-time error 5 if the inverse does not exist. + +Syntax: *object*.**AssignModularMultiplicativeInverse** *a*, *mod_b* + +*a* +: *required* A **BigNumber** holding the value to invert. + +*mod_b* +: *required* A **BigNumber** holding the modulus. + +### AssignGreatestCommonDivisor +{: .no_toc } + +Sets this instance to the greatest common divisor of *a* and *b*. The signs of *a* and *b* are ignored; the result is always non-negative. + +Syntax: *object*.**AssignGreatestCommonDivisor** *a*, *b* + +*a* +: *required* A **BigNumber** holding the first value. + +*b* +: *required* A **BigNumber** holding the second value. + +### AssignLeastCommonMultiple +{: .no_toc } + +Sets this instance to the least common multiple of *a* and *b*. The signs of *a* and *b* are ignored. + +Syntax: *object*.**AssignLeastCommonMultiple** *a*, *b* + +*a* +: *required* A **BigNumber** holding the first value. + +*b* +: *required* A **BigNumber** holding the second value. + +### AssignShiftRight +{: .no_toc } + +Sets this instance to *a* right-shifted by *shiftAmount_b* bits (equivalent to integer division by 2^*shiftAmount_b*, truncated toward zero, so shifting -1 right by any positive amount gives 0). + +Syntax: *object*.**AssignShiftRight** *a*, *shiftAmount_b* + +*a* +: *required* A **BigNumber** holding the value to shift. + +*shiftAmount_b* +: *required* A **Long** specifying the number of bit positions to shift right. + +### AssignShiftLeft +{: .no_toc } + +Sets this instance to *a* left-shifted by *shiftAmount_b* bits (equivalent to multiplication by 2^*shiftAmount_b*). + +Syntax: *object*.**AssignShiftLeft** *a*, *shiftAmount_b* + +*a* +: *required* A **BigNumber** holding the value to shift. + +*shiftAmount_b* +: *required* A **Long** specifying the number of bit positions to shift left. + +### AssignNegation +{: .no_toc } + +Sets this instance to the arithmetic negation of *a* (`-a`). + +Syntax: *object*.**AssignNegation** *a* + +*a* +: *required* A **BigNumber** holding the value to negate. + +**AssignNegation** is declared as a **Function** returning **Boolean**, but the return value is never set and is always **False**. + +### AssignAbsolute +{: .no_toc } + +Sets this instance to the absolute value of *a*. + +Syntax: *object*.**AssignAbsolute** *a* + +*a* +: *required* A **BigNumber** holding the value whose absolute value is taken. + +**AssignAbsolute** is declared as a **Function** returning **Boolean**, but the return value is never set and is always **False**. + +### AssignFromLong +{: .no_toc } + +Sets this instance to a value from a native **Long** integer. + +Syntax: *object*.**AssignFromLong** *a* + +*a* +: *required* A **Long** holding the value to assign. Negative values (including `&H80000000`) are handled correctly. + +### HandleError +{: .no_toc } + +Examines the last status code the class stored from the library and raises run-time error 5 if it is a failure. The error description is "invalid operation" or "out of memory". + +Syntax: *object*.**HandleError** + +The string-conversion properties, **AssignDivision**, **AssignModulus**, the four modular-arithmetic methods (**AssignAdditionModulus**, **AssignSubtractionModulus**, **AssignMultiplicationModulus**, **AssignSquaredModulus**) and **AssignModularMultiplicativeInverse** store the library's status and call **HandleError** themselves. The other methods do not store a status. The stored status stays in place until one of those members runs again, so calling **HandleError** later raises the error again. + +## Comparison functions + +### IsEqualTo +{: .no_toc } + +Returns **True** if this instance equals *b*. + +Syntax: *object*.**IsEqualTo**( *b* ) + +*b* +: *required* A **BigNumber** to compare against. + +### IsLessThan +{: .no_toc } + +Returns **True** if this instance is less than *b*. + +Syntax: *object*.**IsLessThan**( *b* ) + +*b* +: *required* A **BigNumber** to compare against. + +### IsLessThanOrEqualTo +{: .no_toc } + +Returns **True** if this instance is less than or equal to *b*. + +Syntax: *object*.**IsLessThanOrEqualTo**( *b* ) + +*b* +: *required* A **BigNumber** to compare against. + +### IsGreaterThan +{: .no_toc } + +Returns **True** if this instance is greater than *b*. + +Syntax: *object*.**IsGreaterThan**( *b* ) + +*b* +: *required* A **BigNumber** to compare against. + +### IsGreaterThanOrEqualTo +{: .no_toc } + +Returns **True** if this instance is greater than or equal to *b*. + +Syntax: *object*.**IsGreaterThanOrEqualTo**( *b* ) + +*b* +: *required* A **BigNumber** to compare against. + +## Example + +This example computes the factorial of 50 using **BigNumber** arithmetic. + +```tb +Public Function Factorial50() As String + Dim result As New BigNumber + Dim factor As New BigNumber + Dim temp As New BigNumber + + result.AssignFromLong 1 + + Dim i As Long + For i = 2 To 50 + factor.AssignFromLong i + temp.AssignMultiplication result, factor + result.ValueString = temp.ValueString ' copy temp into result + Next i + + Factorial50 = result.ValueString +End Function +``` + +## See Also + +- [BigNumberLib](.) package -- overview diff --git a/docs/Reference/Contributed/BigNumberLib/index.md b/docs/Reference/Contributed/BigNumberLib/index.md new file mode 100644 index 000000000..1fb3a58fe --- /dev/null +++ b/docs/Reference/Contributed/BigNumberLib/index.md @@ -0,0 +1,16 @@ +--- +title: BigNumberLib Package +parent: Contributed Packages +has_toc: false +indexed_from: 0.0.0.0 +permalink: /tB/Packages/Contributed/BigNumberLib/ +--- + +# BigNumberLib Package +{: .no_toc } + +The **BigNumberLib** contributed package provides arbitrary-precision signed integer arithmetic for twinBASIC. + +## Classes + +- [BigNumber](BigNumber) -- arbitrary-precision signed integer backed by the TomsFastMath (libtfm) C library, supporting numbers up to 4096 bits. diff --git a/docs/Reference/Contributed/FileProps/Example/DisplayInDebugConsole.md b/docs/Reference/Contributed/FileProps/Example/DisplayInDebugConsole.md new file mode 100644 index 000000000..3d8c79928 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/Example/DisplayInDebugConsole.md @@ -0,0 +1,39 @@ +--- +title: DisplayInDebugConsole +parent: Example +permalink: /tB/Packages/Contributed/FileProps/Example/DisplayInDebugConsole +has_toc: false +--- +# DisplayInDebugConsole +{: .no_toc } + +Opens a file and prints all its shell properties to the Debug console. + +Syntax: **DisplayInDebugConsole** [ *FilePath* ] + +*FilePath* +: *optional* A **String** containing the full path of the file whose shell properties are printed. If omitted or empty, a file dialog is displayed so the user can choose a file. + +The procedure opens the specified file through **FilePropertyExplorer** and iterates over every property in the returned **FileProperties** collection, printing the system property name and its localized value to the Debug console with `Debug.Print`. + +When *FilePath* is omitted or empty, **FilePropertyExplorer.BrowseAndOpenFile** is called instead of **FilePropertyExplorer.OpenFile**, which displays a file dialog. + +### Example + +This example prints the shell properties of a specific file by passing a path, then repeats the call without a path to let the user choose a file interactively. + +```tb +' Print properties for a known file. +DisplayInDebugConsole "C:\Windows\notepad.exe" + +' Print properties for a file chosen via dialog. +DisplayInDebugConsole +``` + +### See Also + +- [Example](.) module +- [FilePropertyExplorer](../FilePropertyExplorer/) class +- [BrowseAndOpenFile](../FilePropertyExplorer/BrowseAndOpenFile) method +- [OpenFile](../FilePropertyExplorer/OpenFile) method +- [FileProperties](../FileProperties/) class diff --git a/docs/Reference/Contributed/FileProps/Example/index.md b/docs/Reference/Contributed/FileProps/Example/index.md new file mode 100644 index 000000000..c5e3b21b3 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/Example/index.md @@ -0,0 +1,49 @@ +--- +title: Example +parent: FileProps Package +permalink: /tB/Packages/Contributed/FileProps/Example/ +has_toc: false +--- + +# Example module +{: .no_toc } + +A demonstration module that prints all Windows shell file properties for a chosen file to the Debug console. + +## Members + +### DisplayInDebugConsole + +Opens a file and prints each of its shell properties -- name and localized value -- to the Debug console. + +Syntax: **DisplayInDebugConsole** [ *FilePath* ] + +*FilePath* +: *optional* A **String** holding the full path of the file to inspect. If omitted or empty, a file dialog is displayed so the user can choose the file interactively. + +**DisplayInDebugConsole** calls [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile) when *FilePath* is not empty, or [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile) otherwise. Each property in the returned [**FileProperties**](../FileProperties/) collection is printed on its own line: the system name (**FileProperty.Name**), then the localized value string (**FileProperty.ValueDesc**), positioned further right with `Tab(80)`. + +## Example + +This example prints all shell properties of a specific file to the Debug console by supplying a path directly. + +```tb +Sub Main() + Example.DisplayInDebugConsole "C:\Users\Public\Pictures\Sample.jpg" +End Sub +``` + +To use the interactive file-open dialog instead, call the procedure without an argument: + +```tb +Sub Main() + Example.DisplayInDebugConsole +End Sub +``` + +## See Also + +- [FilePropertyExplorer](../FilePropertyExplorer/) class -- opens a file and returns its shell properties +- [FileProperties](../FileProperties/) class -- read-only collection of shell properties for a file +- [FileProperty](../FileProperty/) class -- one shell property entry with name, ID, and value +- [FileProps package](../) -- overview of all classes and modules diff --git a/docs/Reference/Contributed/FileProps/FileProperties/Count.md b/docs/Reference/Contributed/FileProps/FileProperties/Count.md new file mode 100644 index 000000000..7126c7439 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperties/Count.md @@ -0,0 +1,33 @@ +--- +title: Count +parent: FileProperties +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperties/Count +--- +# Count +{: .no_toc } + +Returns the number of properties in the collection. + +Syntax: *object*.**Count** + +*object* +: *required* An object expression that evaluates to a **FileProperties** object. + +**Count** returns a **Long** equal to the total number of shell properties available for the file. Valid index values for [**Item**](Item) range from `0` to `Count - 1`. + +### Example + +This example opens a file and prints the total number of shell properties it exposes. + +```tb +Dim props As FileProperties +Set props = FilePropertyExplorer.OpenFile("C:\example.mp3") +Debug.Print "Property count: " & props.Count +``` + +### See Also + +- [Item](Item) property +- [FilePath](FilePath) property +- [FileProperties](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperties/FilePath.md b/docs/Reference/Contributed/FileProps/FileProperties/FilePath.md new file mode 100644 index 000000000..ef23034a0 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperties/FilePath.md @@ -0,0 +1,36 @@ +--- +title: FilePath +parent: FileProperties +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperties/FilePath +--- +# FilePath +{: .no_toc } + +Returns a **String** containing the full file path of the file that was opened. Read-only. + +Syntax: *object*.**FilePath** + +*object* +: *required* An object expression that evaluates to a **FileProperties** object. + +The value is the full path of the file that was passed to [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile) or selected through [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile) when the **FileProperties** collection was created. + +### Example + +This example opens a file and prints its path and property count to the Debug console. + +```tb +Dim fp As FileProperties +Set fp = FilePropertyExplorer.OpenFile("C:\Users\Public\sample.mp3") +Debug.Print "File: " & fp.FilePath +Debug.Print "Properties: " & fp.Count +``` + +### See Also + +- [FileProperties](.) class +- [Count](Count) property +- [Item](Item) property +- [OpenFile](../FilePropertyExplorer/OpenFile) method +- [BrowseAndOpenFile](../FilePropertyExplorer/BrowseAndOpenFile) method diff --git a/docs/Reference/Contributed/FileProps/FileProperties/Item.md b/docs/Reference/Contributed/FileProps/FileProperties/Item.md new file mode 100644 index 000000000..afaf13699 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperties/Item.md @@ -0,0 +1,49 @@ +--- +title: Item +parent: FileProperties +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperties/Item +--- +# Item +{: .no_toc } + +Returns the **FileProperty** object at the given index, name, or ID in the collection. + +Syntax: *object*.**Item**(*IndexOrNameOrID*) + +*object* +: *required* An object expression that evaluates to a **FileProperties** object. + +*IndexOrNameOrID* +: *required* A **Variant** identifying the property to retrieve. Pass an integer index (zero-based, from `0` to `Count - 1`), a **String** matching **FileProperty.Name**, or a **String** matching **FileProperty.ID**. + +**Item** forwards the call to the underlying Virtual-COM object. Passing an integer retrieves the property at that position in the collection. Passing a string retrieves the property whose **FileProperty.Name** (the system identity name, such as `"System.Audio.EncodingBitrate"`) or **FileProperty.ID** (the unique identifier of the shell property) equals that string. + +### Example + +This example opens a file, iterates the properties by index, and also retrieves one property by name. + +```tb +Dim fp As FileProperties +Set fp = FilePropertyExplorer.OpenFile("C:\Music\track.mp3") + +' Iterate all properties by index. +Dim i As Long +For i = 0 To fp.Count - 1 + Dim prop As FileProperty + Set prop = fp.Item(i) + Debug.Print prop.NameDesc & ": " & prop.ValueDesc +Next i + +' Retrieve a specific property by system name. +Dim bitrate As FileProperty +Set bitrate = fp.Item("System.Audio.EncodingBitrate") +Debug.Print "Bitrate: " & bitrate.ValueDesc +``` + +### See Also + +- [FileProperties](.) class +- [Count](Count) property +- [FilePath](FilePath) property +- [FileProperty](../FileProperty/) class diff --git a/docs/Reference/Contributed/FileProps/FileProperties/VCOMObject.md b/docs/Reference/Contributed/FileProps/FileProperties/VCOMObject.md new file mode 100644 index 000000000..0096e09d5 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperties/VCOMObject.md @@ -0,0 +1,30 @@ +--- +title: VCOMObject +parent: FileProperties +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperties/VCOMObject +--- +# VCOMObject +{: .no_toc } + +Holds the native-code COM object created internally by the Virtual-COM library. For internal use only. + +> [!WARNING] +> +> **VCOMObject** is an internal implementation detail of the FileProps Virtual-COM loader, and the package marks it as for internal use only. Do not use it in application code. + +Syntax: *object*.**VCOMObject** + +*object* +: *required* An object expression that evaluates to a **FileProperties** object. + +The **FileProps** package is a Virtual-COM library. It creates native-code COM objects in memory without a separate DLL. **VCOMObject** is the raw **Object** reference to that in-memory COM object; the **FileProperties** class delegates all its property implementations (**Count**, **FilePath**, **Item**) to it. The field has the member ID -4 (`VB_VarUserMemId = -4`), the ID COM reserves for the enumerator of a collection, so it is the member that `For Each` uses to enumerate a **FileProperties** collection. + +This field has no documented interface and no stable contract outside the library. Use **Count**, **FilePath**, and **Item** to access file properties. + +### See Also + +- [FileProperties](.) class +- [Count](Count) property +- [FilePath](FilePath) property +- [Item](Item) property diff --git a/docs/Reference/Contributed/FileProps/FileProperties/index.md b/docs/Reference/Contributed/FileProps/FileProperties/index.md new file mode 100644 index 000000000..daed47468 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperties/index.md @@ -0,0 +1,108 @@ +--- +title: FileProperties +parent: FileProps Package +permalink: /tB/Packages/Contributed/FileProps/FileProperties/ +has_toc: false +--- + +# FileProperties class +{: .no_toc } + +A read-only collection of Windows shell properties for a single file, returned by **FilePropertyExplorer**. + +**FileProperties** is a Virtual-COM object that provides indexed access to the detailed file properties the operating system exposes for the opened file, commonly called shell property handlers. Each entry in the collection is a [**FileProperty**](../FileProperty/) object with the system name, localized name, unique property ID, and current value of one shell property. Common examples include the duration of an audio file such as an MP3 and the EXIF properties of a JPEG image. + +Instances are not constructed directly. Call [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile) or [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile) to obtain a **FileProperties** collection. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Music\track.mp3") + +Dim i As Long +For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " = " & Prop.ValueDesc +Next i +``` + +* TOC +{:toc} + +## Properties + +### Count +{: .no_toc } + +Returns the number of shell properties in the collection. **Long**. Read-only. + +Syntax: *object*.**Count** + +The count is the number of properties the shell exposes for the opened file. Different file types expose different property sets. + +### FilePath +{: .no_toc } + +Returns the full file path of the file that was opened. **String**. Read-only. + +Syntax: *object*.**FilePath** + +The value is the full path of the file passed to [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile). When a collection is obtained through [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile), it is the path of the file the user selected in the dialog. + +### Item +{: .no_toc } + +Returns the [**FileProperty**](../FileProperty/) object at the given position, name, or ID in the collection. + +Syntax: *object*.**Item** ( *IndexOrNameOrID* ) **As FileProperty** + +*IndexOrNameOrID* +: *required* A **Variant** that identifies the property to retrieve. Accepted forms: + - An integer index from `0` to `Count - 1`. + - A **String** matching [**FileProperty.Name**](../FileProperty/Name) (the system identity name, e.g. `"System.Media.Duration"`). + - A **String** matching [**FileProperty.ID**](../FileProperty/ID) (the unique property identifier). + +```tb +' By zero-based index: +Dim Prop As FileProperty +Set Prop = Props.Item(0) + +' By system name: +Set Prop = Props.Item("System.Media.Duration") +``` + +### VCOMObject +{: .no_toc } + +Holds the native-code COM object created internally by the Virtual-COM library. **Object**. For internal use only. + +> [!WARNING] +> Do not read, assign, or pass **VCOMObject** to any function. The package marks it as for internal use only, and **Count**, **FilePath** and **Item** forward their calls to it. + +## Example + +This example opens the file at the given path and prints its path, its property count and all its shell properties to the Debug console. + +```tb +Sub PrintShellProps(FilePath As String) + Dim Props As FileProperties + Set Props = FilePropertyExplorer.OpenFile(FilePath) + + Debug.Print "File: " & Props.FilePath + Debug.Print "Properties: " & Props.Count + + Dim i As Long + For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " (" & Prop.Name & ")" & " = " & Prop.ValueDesc + Next i +End Sub +``` + +## See Also + +- [FilePropertyExplorer](../FilePropertyExplorer/) class -- the predeclared factory that opens a file and returns a **FileProperties** collection +- [FileProperty](../FileProperty/) class -- one shell property in the collection +- [FilePropertyExplorer.OpenFile](../FilePropertyExplorer/OpenFile) -- opens a file by path and returns a **FileProperties** collection +- [FilePropertyExplorer.BrowseAndOpenFile](../FilePropertyExplorer/BrowseAndOpenFile) -- displays a file-open dialog and returns a **FileProperties** collection diff --git a/docs/Reference/Contributed/FileProps/FileProperty/ID.md b/docs/Reference/Contributed/FileProps/FileProperty/ID.md new file mode 100644 index 000000000..4534b8de5 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/ID.md @@ -0,0 +1,43 @@ +--- +title: ID +parent: FileProperty +permalink: /tB/Packages/Contributed/FileProps/FileProperty/ID +has_toc: false +--- +# ID +{: .no_toc } + +Returns a unique identifier string for the shell property. + +Syntax: *object*.**ID** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +The **ID** property returns a **String** that is a unique identity for the property and can always be used to refer to it. It consists of a GUID identifying the property schema, followed by an integer identifying the property's index within that schema. + +Unlike [**Name**](Name), which is a dotted system name such as `System.ItemFolderNameDisplay`, the **ID** string is made of the schema GUID and the index. + +### Example + +This example opens a file and prints the ID and name of each shell property to the Debug console. + +```tb +Dim props As FileProperties +Set props = FilePropertyExplorer.OpenFile("C:\example\photo.jpg") + +Dim i As Long +For i = 0 To props.Count - 1 + Dim prop As FileProperty + Set prop = props.Item(i) + Debug.Print prop.ID & " -> " & prop.Name +Next i +``` + +### See Also + +- [Name](Name) property +- [NameDesc](NameDesc) property +- [Value](Value) property +- [ValueDesc](ValueDesc) property +- [FileProperty](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperty/Name.md b/docs/Reference/Contributed/FileProps/FileProperty/Name.md new file mode 100644 index 000000000..9f992587c --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/Name.md @@ -0,0 +1,47 @@ +--- +title: Name +parent: FileProperty +permalink: /tB/Packages/Contributed/FileProps/FileProperty/Name +has_toc: false +--- +# Name +{: .no_toc } + +Returns the system identity name of the Windows shell property. + +Syntax: *object*.**Name** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +Returns a **String** containing the system identity name of the property, such as `"System.ItemFolderNameDisplay"`. This name is safe to use as an identity field even on non-English systems. + +### Remarks + +**Name** differs from [**NameDesc**](NameDesc), which returns a localized version of the name that is not always available. When storing or comparing property identifiers across locale boundaries, use **Name** rather than **NameDesc**. + +For an alternative unique identifier that includes the property schema GUID and index, see [**ID**](ID). + +### Example + +This example iterates over all shell properties for a file and prints the system name and value of each one to the Debug console. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Example\photo.jpg") + +Dim i As Long +For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.Name & " = " & Prop.ValueDesc +Next i +``` + +### See Also + +- [NameDesc](NameDesc) property -- returns the localized display name of the property +- [ID](ID) property -- returns the schema GUID and index as a unique identifier +- [Value](Value) property -- returns or sets the current value of the shell property as a Variant +- [ValueDesc](ValueDesc) property -- returns the current value as a localized string +- [FileProperty](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperty/NameDesc.md b/docs/Reference/Contributed/FileProps/FileProperty/NameDesc.md new file mode 100644 index 000000000..e8ff10879 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/NameDesc.md @@ -0,0 +1,27 @@ +--- +title: NameDesc +parent: FileProperty +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperty/NameDesc +--- +# NameDesc +{: .no_toc } + +Returns the localized name of the shell property, when one is available. + +Syntax: *object*.**NameDesc** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +Returns a **String** containing a localized version of the property's name. This name is suitable for display to the user. + +The localized name is not always available. Use [**Name**](Name) instead when a locale-independent identifier is needed --- for example, when storing or comparing property names across systems. + +### See Also + +- [Name](Name) property +- [ID](ID) property +- [Value](Value) property +- [ValueDesc](ValueDesc) property +- [FileProperty](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperty/VCOMObject.md b/docs/Reference/Contributed/FileProps/FileProperty/VCOMObject.md new file mode 100644 index 000000000..5fb32ee3e --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/VCOMObject.md @@ -0,0 +1,32 @@ +--- +title: VCOMObject +parent: FileProperty +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperty/VCOMObject +--- +# VCOMObject +{: .no_toc } + +Holds the native-code COM object created internally by the Virtual-COM library. For internal use only. + +> [!WARNING] +> +> **VCOMObject** is an internal implementation detail of the FileProps Virtual-COM loader, and the package marks it as for internal use only. Do not use it in application code. + +Syntax: *object*.**VCOMObject** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +The **FileProps** package is a Virtual-COM library. It creates native-code COM objects in memory without a separate DLL. **VCOMObject** is the raw **Object** reference to that in-memory COM object; the **FileProperty** class delegates all its property implementations (**Value**, **ValueDesc**, **NameDesc**, **Name**, **ID**) to it. + +This field has no documented interface and no stable contract outside the library. Use **Value**, **ValueDesc**, **NameDesc**, **Name**, and **ID** to access shell property data. + +### See Also + +- [FileProperty](.) class +- [Value](Value) property +- [ValueDesc](ValueDesc) property +- [Name](Name) property +- [NameDesc](NameDesc) property +- [ID](ID) property diff --git a/docs/Reference/Contributed/FileProps/FileProperty/Value.md b/docs/Reference/Contributed/FileProps/FileProperty/Value.md new file mode 100644 index 000000000..93a37d177 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/Value.md @@ -0,0 +1,64 @@ +--- +title: Value +parent: FileProperty +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FileProperty/Value +--- +# Value +{: .no_toc } + +Returns or sets the current value of the Windows shell property as a **Variant**. + +## Get + +Returns a **Variant** containing the current value of the shell property. + +Syntax: *object*.**Value** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +The type of the returned value depends on the property. A multi-value property can return an array. + +To obtain a localized string representation of the same data, use [**ValueDesc**](ValueDesc) instead. + +## Let + +Sets the current value of the shell property. + +Syntax: *object*.**Value** **=** *value* + +*value* +: A **Variant** containing the new value for the property. + +> [!IMPORTANT] +> +> Write support requires Windows Vista or newer. Assigning a property that is not writable raises a *Permission denied* error. + +### Remarks + +Not all shell properties are writable. To assign **Value**, open the file with write support enabled by passing **True** as the *WriteSupport* argument of [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile) or [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile). + +### Example + +This example opens a file, reads the **System.Title** property, then updates it. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Documents\Report.docx", True) + +Dim Prop As FileProperty +Set Prop = Props.Item("System.Title") + +Debug.Print "Current title: " & Prop.Value + +Prop.Value = "Annual Report 2025" +Debug.Print "Updated title: " & Prop.Value +``` + +### See Also + +- [ValueDesc](ValueDesc) property +- [Name](Name) property +- [ID](ID) property +- [FileProperty](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperty/ValueDesc.md b/docs/Reference/Contributed/FileProps/FileProperty/ValueDesc.md new file mode 100644 index 000000000..295f927a1 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/ValueDesc.md @@ -0,0 +1,41 @@ +--- +title: ValueDesc +parent: FileProperty +permalink: /tB/Packages/Contributed/FileProps/FileProperty/ValueDesc +has_toc: false +--- +# ValueDesc +{: .no_toc } + +Returns the current value of the shell property as a localized string. Read-only. + +Syntax: *object*.**ValueDesc** + +*object* +: *required* An object expression that evaluates to a **FileProperty** object. + +**ValueDesc** returns a **String** containing the property value in localized form, suitable for display. For multi-value properties, all values are combined into a single string; no array handling is required. + +To retrieve the value as a **Variant** (which can be an array for multi-value properties), use the [**Value**](Value) property instead. + +### Example + +This example opens a file and prints the localized value of each shell property to the Debug console. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Music\track.mp3") + +Dim Prop As FileProperty +For Each Prop In Props + Debug.Print Prop.Name & " = " & Prop.ValueDesc +Next Prop +``` + +### See Also + +- [Value](Value) property +- [Name](Name) property +- [NameDesc](NameDesc) property +- [ID](ID) property +- [FileProperty](.) class diff --git a/docs/Reference/Contributed/FileProps/FileProperty/index.md b/docs/Reference/Contributed/FileProps/FileProperty/index.md new file mode 100644 index 000000000..33446b11d --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FileProperty/index.md @@ -0,0 +1,117 @@ +--- +title: FileProperty +parent: FileProps Package +permalink: /tB/Packages/Contributed/FileProps/FileProperty/ +has_toc: false +--- + +# FileProperty class +{: .no_toc } + +A **FileProperty** represents one Windows shell property attached to a file --- its system name, localized name, unique ID, and current value. + +**FileProperty** objects are not created directly. They are returned as items from the [**FileProperties**](../FileProperties/) collection, which is obtained by calling [**FilePropertyExplorer.OpenFile**](../FilePropertyExplorer/OpenFile) or [**FilePropertyExplorer.BrowseAndOpenFile**](../FilePropertyExplorer/BrowseAndOpenFile). + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Photos\image.jpg") + +Dim Prop As FileProperty +Set Prop = Props.Item(1) + +Debug.Print Prop.Name ' e.g. "System.ItemFolderNameDisplay" +Debug.Print Prop.ValueDesc ' e.g. "Photos" +``` + +* TOC +{:toc} + +## Properties + +### ID +{: .no_toc } + +A unique identifier string for the shell property. + +Syntax: *object*.**ID** **As String** (read-only) + +The identifier consists of a GUID identifying the property schema, followed by an integer identifying the property index within that schema. It can always be used to refer to a specific property unambiguously. + +### Name +{: .no_toc } + +The system identity name of the property. + +Syntax: *object*.**Name** **As String** (read-only) + +Returns a system name such as `"System.ItemFolderNameDisplay"`. This name is safe to use as an identity field even on non-English systems. For the localized name, use [**NameDesc**](#namedesc). + +### NameDesc +{: .no_toc } + +The localized name of the property. + +Syntax: *object*.**NameDesc** **As String** (read-only) + +Returns a localized version of the name. It is not always available. Use [**Name**](#name) for a locale-independent identifier. + +### Value +{: .no_toc } + +The current value of the shell property as a **Variant**. + +Syntax: *object*.**Value** [ **=** *value* ] + +Reading this property returns the value of the property as exposed by the operating system. The type of the returned **Variant** depends on the property. A multi-value property can return an array. + +Assigning a value writes the property. Write support requires Windows Vista or newer. Assigning a property that is not writable raises a *Permission denied* error. + +> [!NOTE] +> Multi-value properties can return a **Variant** array. Check `IsArray(Prop.Value)` before using the result as a scalar. + +For a string representation of the value in localized form, use [**ValueDesc**](#valuedesc). + +### ValueDesc +{: .no_toc } + +The current value of the property as a localized string. + +Syntax: *object*.**ValueDesc** **As String** (read-only) + +Returns the property value in localized form, combined into a single string. Multi-value properties that can return an array from [**Value**](#value) are already combined into one string here. + +Use this property when displaying values to an end user. Use [**Value**](#value) when the typed value is needed for computation or comparison. + +### VCOMObject +{: .no_toc } + +Holds the native-code COM object created internally by the Virtual-COM library. + +Syntax: *object*.**VCOMObject** **As Object** + +> [!WARNING] +> This member is for internal use only. Do not read or assign **VCOMObject** from application code. All public members of **FileProperty** forward their calls to it. + +## Example + +This example opens a file and prints the system name, localized description, and value for each shell property. + +```tb +Sub PrintFileProperties(ByVal FilePath As String) + Dim Props As FileProperties + Set Props = FilePropertyExplorer.OpenFile(FilePath) + + Dim i As Long + For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.Name & " (" & Prop.NameDesc & "): " & Prop.ValueDesc + Next i +End Sub +``` + +## See Also + +- [FileProperties](../FileProperties/) class -- the collection that contains **FileProperty** objects +- [FilePropertyExplorer](../FilePropertyExplorer/) class -- the factory that opens a file and returns a **FileProperties** collection +- [FileProps Package](../) package -- overview and usage diff --git a/docs/Reference/Contributed/FileProps/FilePropertyExplorer/BrowseAndOpenFile.md b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/BrowseAndOpenFile.md new file mode 100644 index 000000000..81af18dbc --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/BrowseAndOpenFile.md @@ -0,0 +1,48 @@ +--- +title: BrowseAndOpenFile +parent: FilePropertyExplorer +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FilePropertyExplorer/BrowseAndOpenFile +--- +# BrowseAndOpenFile +{: .no_toc } + +Displays a file-open dialog and returns a **FileProperties** collection for the file the user selects. + +Syntax: *object*.**BrowseAndOpenFile** [ (*WriteSupport*) ] + +*object* +: *required* An object expression that evaluates to a **FilePropertyExplorer** object. The predeclared default instance is available as `FilePropertyExplorer`. + +*WriteSupport* +: *optional* A **Boolean** that controls whether the returned **FileProperties** collection is opened with write support for property values. **False** (default) opens it without write support. Pass **True** to allow setting [**FileProperty.Value**](../FileProperty/Value). Write support requires Windows Vista or newer. + +**BrowseAndOpenFile** opens a file dialog for the user to select a file, and returns a [**FileProperties**](../FileProperties/) collection for the selected file, as [**OpenFile**](OpenFile) does for a path. The returned collection contains the [**FileProperty**](../FileProperty/) entries for the properties the operating system exposes for the selected file. + +### Example + +This example uses **BrowseAndOpenFile** to let the user pick a file and then prints all its shell properties to the Debug console. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.BrowseAndOpenFile() + +If Props Is Nothing Then + Debug.Print "No file selected." +Else + Debug.Print "File: " & Props.FilePath + Dim i As Long + For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " = " & Prop.ValueDesc + Next i +End If +``` + +### See Also + +- [FilePropertyExplorer](.) class -- the predeclared factory class +- [OpenFile](OpenFile) function -- opens a file by path and returns a **FileProperties** collection +- [FileProperties](../FileProperties/) class -- the collection returned by this function +- [FileProperty](../FileProperty/) class -- one shell property in the collection diff --git a/docs/Reference/Contributed/FileProps/FilePropertyExplorer/OpenFile.md b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/OpenFile.md new file mode 100644 index 000000000..701e24bff --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/OpenFile.md @@ -0,0 +1,51 @@ +--- +title: OpenFile +parent: FilePropertyExplorer +has_toc: false +permalink: /tB/Packages/Contributed/FileProps/FilePropertyExplorer/OpenFile +--- +# OpenFile +{: .no_toc } + +Opens a file by path and returns a **FileProperties** collection of its Windows shell properties. + +Syntax: *object*.**OpenFile**(*FilePath* [ **,** *WriteSupport* ]) + +*object* +: *required* An object expression that evaluates to a **FilePropertyExplorer** object. The predeclared default instance is available as `FilePropertyExplorer`. + +*FilePath* +: *required* A **String** giving the path to a valid file. + +*WriteSupport* +: *optional* A **Boolean** that controls whether the returned **FileProperties** collection is opened with write support for property values. **False** (default) opens it without write support. Pass **True** to allow setting [**FileProperty.Value**](../FileProperty/Value). + +**OpenFile** returns a [**FileProperties**](../FileProperties/) collection for the specified file. The collection contains the [**FileProperty**](../FileProperty/) entries for the properties the operating system exposes for that file. Common examples include the duration of an audio file such as an MP3 and the EXIF properties of a JPEG image. + +Write support requires Windows Vista or newer. + +### Example + +This example opens an MP3 file and prints all its shell properties to the Debug console. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Music\track.mp3") + +Debug.Print "File: " & Props.FilePath +Debug.Print "Properties: " & Props.Count + +Dim i As Long +For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " = " & Prop.ValueDesc +Next i +``` + +### See Also + +- [FilePropertyExplorer](.) class -- the predeclared factory class +- [BrowseAndOpenFile](BrowseAndOpenFile) function -- displays a file-open dialog and returns a **FileProperties** collection +- [FileProperties](../FileProperties/) class -- the collection returned by this function +- [FileProperty](../FileProperty/) class -- one shell property in the collection diff --git a/docs/Reference/Contributed/FileProps/FilePropertyExplorer/index.md b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/index.md new file mode 100644 index 000000000..88a37d848 --- /dev/null +++ b/docs/Reference/Contributed/FileProps/FilePropertyExplorer/index.md @@ -0,0 +1,121 @@ +--- +title: FilePropertyExplorer +parent: FileProps Package +permalink: /tB/Packages/Contributed/FileProps/FilePropertyExplorer/ +has_toc: false +--- + +# FilePropertyExplorer class +{: .no_toc } + +A predeclared factory class that opens a file and returns a [**FileProperties**](../FileProperties/) collection of its Windows shell properties. + +**FilePropertyExplorer** is a Virtual-COM wrapper that gives access to the detailed file properties the operating system exposes, commonly called shell property handlers. Common examples include the duration of an audio file such as an MP3 and the EXIF properties of a JPEG image. + +The class has the `[ PredeclaredId ]` attribute, so it acts as a default instance and its methods are callable without creating an explicit object variable: + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Music\track.mp3") +``` + +* TOC +{:toc} + +## Methods + +### BrowseAndOpenFile +{: .no_toc } + +Displays a file dialog for the user to select a file, and returns a [**FileProperties**](../FileProperties/) collection for the selected file. + +Syntax: **FilePropertyExplorer**.**BrowseAndOpenFile** ( [ *WriteSupport* ] ) **As FileProperties** + +*WriteSupport* +: *optional* A **Boolean**. Pass **True** to open the file with write support so that [**FileProperty.Value**](../FileProperty/Value) can be assigned. Default: **False**. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.BrowseAndOpenFile() + +If Not Props Is Nothing Then + Dim i As Long + For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " = " & Prop.ValueDesc + Next i +End If +``` + +### OpenFile +{: .no_toc } + +Opens a file by path and returns a [**FileProperties**](../FileProperties/) collection of its shell properties. + +Syntax: **FilePropertyExplorer**.**OpenFile** ( *FilePath* [, *WriteSupport* ] ) **As FileProperties** + +*FilePath* +: *required* A **String** containing the path to a valid file. + +*WriteSupport* +: *optional* A **Boolean**. Pass **True** to open the file with write support so that [**FileProperty.Value**](../FileProperty/Value) can be assigned. Default: **False**. + +```tb +Dim Props As FileProperties +Set Props = FilePropertyExplorer.OpenFile("C:\Pictures\photo.jpg") + +If Not Props Is Nothing Then + Debug.Print "File: " & Props.FilePath + Debug.Print "Property count: " & Props.Count + + ' Look up a specific property by system name: + Dim Prop As FileProperty + Set Prop = Props.Item("System.Photo.CameraModel") + If Not Prop Is Nothing Then + Debug.Print "Camera: " & Prop.ValueDesc + End If +End If +``` + +## Remarks + +**FilePropertyExplorer** uses a Virtual-COM library --- a self-contained native-code COM object loaded into memory without registering a DLL. The library supports both 32-bit and 64-bit hosts. + +The shell property handler infrastructure requires Windows 2000 or later. If the memory for the native code cannot be allocated when the class is created, the class raises error 7 (*Out of memory*). + +> [!NOTE] +> Write support for [**FileProperty.Value**](../FileProperty/Value) requires Windows Vista or newer. + +## Example + +This example opens a file-open dialog, then prints all shell properties for the selected file to the Debug console. + +```tb +Sub ShowFileProps() + Dim Props As FileProperties + Set Props = FilePropertyExplorer.BrowseAndOpenFile() + + If Props Is Nothing Then + Debug.Print "No file selected." + Exit Sub + End If + + Debug.Print "File: " & Props.FilePath + Debug.Print "Properties: " & Props.Count & Chr(10) + + Dim i As Long + For i = 0 To Props.Count - 1 + Dim Prop As FileProperty + Set Prop = Props.Item(i) + Debug.Print Prop.NameDesc & " (" & Prop.Name & ")" & " = " & Prop.ValueDesc + Next i +End Sub +``` + +## See Also + +- [FileProperties](../FileProperties/) class -- the read-only collection returned by this class +- [FileProperty](../FileProperty/) class -- one shell property in the collection +- [FilePropertyExplorer.OpenFile](OpenFile) -- opens a file by path and returns a **FileProperties** collection +- [FilePropertyExplorer.BrowseAndOpenFile](BrowseAndOpenFile) -- displays a file-open dialog and returns a **FileProperties** collection diff --git a/docs/Reference/Contributed/FileProps/index.md b/docs/Reference/Contributed/FileProps/index.md new file mode 100644 index 000000000..d62b96dbd --- /dev/null +++ b/docs/Reference/Contributed/FileProps/index.md @@ -0,0 +1,35 @@ +--- +title: FileProps Package +parent: Contributed Packages +has_toc: false +exclude_from_docs: + - VCOMObject + - Example + - FilePropertyExplorer_Helper +indexed_from: 1.7.1.0 +permalink: /tB/Packages/Contributed/FileProps/ +--- + +# FileProps Package +{: .no_toc } + +The **FileProps** contributed package provides access to Windows shell file properties through a Virtual-COM wrapper. It exposes a predeclared **FilePropertyExplorer** class that opens a file and returns a **FileProperties** collection; each entry in that collection is a **FileProperty** object with the system name, localized name, unique ID, and current value of one shell property. + +* TOC +{:toc} + +## Classes + +- [FileProperties](FileProperties/) -- a read-only collection of Windows shell properties for a single file, returned by FilePropertyExplorer + - [Count](FileProperties/Count) -- returns the number of properties in the collection + - [FilePath](FileProperties/FilePath) -- returns the full file path of the file that was opened + - [Item](FileProperties/Item) -- returns the FileProperty object at the given index, name, or ID in the collection +- [FileProperty](FileProperty/) -- one Windows shell property of a file + - [ID](FileProperty/ID) -- returns a unique identifier string for the shell property + - [Name](FileProperty/Name) -- returns the system identity name of the property + - [NameDesc](FileProperty/NameDesc) -- returns the localized display name of the property + - [Value](FileProperty/Value) -- returns or sets the current value of the shell property as a Variant + - [ValueDesc](FileProperty/ValueDesc) -- returns the current value of the property as a localized string +- [FilePropertyExplorer](FilePropertyExplorer/) -- a predeclared factory class that opens a file and returns a FileProperties collection of its Windows shell properties + - [BrowseAndOpenFile](FilePropertyExplorer/BrowseAndOpenFile) -- displays a file-open dialog and returns a FileProperties collection for the selected file + - [OpenFile](FilePropertyExplorer/OpenFile) -- opens a file by path and returns a FileProperties collection of its shell properties diff --git a/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/Show.md b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/Show.md new file mode 100644 index 000000000..097c4f65d --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/Show.md @@ -0,0 +1,53 @@ +--- +title: Show +parent: cListboxHScroll +permalink: /tB/Packages/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/Show +has_toc: false +--- +# Show +{: .no_toc } + +Attaches the horizontal scroll bar to a **ListBox** control and initialises scroll handling. + +Syntax: *object*.**Show** *ListBoxInst* + +*ListBoxInst* +: *required* An object expression that evaluates to a **ListBox** control. The class assigns it to a **ListBox** variable, so an object of another type causes a run-time error. The class holds this reference for the lifetime of the object; [**UnShow**](UnShow) does not release it. + +**Show** performs three actions in sequence: + +1. Calls the Win32 `ShowScrollBar` API to make the horizontal scroll bar visible on *ListBoxInst*. +2. Iterates every item in the list, measures each item's pixel width using the GDI `GetTextExtentPoint32` API with the control's own font, then sets the horizontal scrollable extent via the `LB_SETHORIZONTALEXTENT` message and the scroll range and page size via `SetScrollInfo`. A 10-pixel margin is added to the widest item. When the list is empty, or every item is empty, the extent and the scroll range are not set. +3. Installs a window subclass (`SetWindowSubclass` from `comctl32`) on the control's `hWnd` to intercept `WM_HSCROLL` messages. The subclass procedure updates the scroll bar position with `SetScrollInfo` and then passes each message on to `DefSubclassProc`. + +After **Show** returns, the **ListBox** scrolls horizontally when any item is wider than the visible area. + +> [!IMPORTANT] +> **Show** must be called after the **ListBox** has been populated. If items are added or removed after the call, the horizontal extent is not updated automatically. Call **Show** again on the same control to recalculate the extent for the updated item list. + +> [!NOTE] +> The subclass installed by **Show** is removed automatically when the class instance is destroyed (`Class_Terminate`). It can also be removed explicitly by calling [**UnShow**](UnShow). + +### Example + +This example attaches a horizontal scroll bar to a **ListBox** named `List1` after filling it with items. + +```tb +Private hScroll As New cListboxHScroll + +Private Sub Form_Load() + List1.AddItem "Short item" + List1.AddItem "A much longer item that exceeds the visible width of the list box" + List1.AddItem "Another moderately long entry" + + hScroll.Show List1 +End Sub + +Private Sub Form_Unload(Cancel As Integer) + hScroll.UnShow +End Sub +``` + +### See Also + +- [UnShow](UnShow) method diff --git a/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/UnShow.md b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/UnShow.md new file mode 100644 index 000000000..19fd40dcf --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/UnShow.md @@ -0,0 +1,44 @@ +--- +title: UnShow +parent: cListboxHScroll +permalink: /tB/Packages/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/UnShow +has_toc: false +--- +# UnShow +{: .no_toc } + +Removes the window subclass installed by [**Show**](Show). + +Syntax: *object*.**UnShow** + +*object* +: *required* An object expression that evaluates to a **cListboxHScroll** instance. + +**UnShow** calls `RemoveWindowSubclass` (comctl32) to detach the scroll message handler that was installed by **Show**. After this call, the **ListBox** control associated with the instance no longer receives the subclassed `WM_HSCROLL` processing added by the class. + +> [!NOTE] +> **UnShow** does not hide the horizontal scrollbar itself, and does not reset the horizontal extent or release the **ListBox** reference---it removes only the subclass procedure. Call `ShowScrollBar` directly with `SB_HORZ` and `0` if the scrollbar must also be hidden. + +> [!IMPORTANT] +> The class destructor (`Class_Terminate`) calls the internal `RemoveListBoxSubclass` helper automatically, so **UnShow** need only be called explicitly when the subclass must be removed before the **cListboxHScroll** instance goes out of scope. + +### Example + +This example adds a horizontal scrollbar to a ListBox on a form, then removes it when a button is clicked. + +```tb +Private HScroll As cListboxHScroll + +Private Sub Form_Load() + Set HScroll = New cListboxHScroll + HScroll.Show List1 +End Sub + +Private Sub cmdRemove_Click() + HScroll.UnShow +End Sub +``` + +### See Also + +- [Show](Show) method diff --git a/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/index.md b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/index.md new file mode 100644 index 000000000..d9f4bacee --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/index.md @@ -0,0 +1,99 @@ +--- +title: cListboxHScroll +parent: TBMANLIB_ListBoxHScroll Package +permalink: /tB/Packages/Contributed/TBMANLIB_ListBoxHScroll/cListboxHScroll/ +has_toc: false +--- + +# cListboxHScroll class +{: .no_toc } + +A helper class that adds a functional horizontal scrollbar to a standard VB **ListBox** control by combining the `LB_SETHORIZONTALEXTENT` message, Win32 scroll-info APIs, and window subclassing. + +The class measures the pixel width of each list item using GDI's `GetTextExtentPoint32W`, sets the scroll range to fit the widest item, and installs a subclass procedure to intercept `WM_HSCROLL` messages so the scrollbar thumb tracks correctly. Call [**Show**](#show) after populating the list and [**UnShow**](#unshow) (or allow the class instance to be destroyed) when the scroll handling is no longer needed. + +```tb +Private HScroll As New cListboxHScroll + +Private Sub Form_Load() + List1.AddItem "A short item" + List1.AddItem "A much longer item that overflows the default width" + HScroll.Show List1 +End Sub + +Private Sub Form_Unload(Cancel As Integer) + HScroll.UnShow +End Sub +``` + +* TOC +{:toc} + +## Methods + +### Show +{: .no_toc } + +Activates horizontal scrolling on a **ListBox** control. + +Syntax: *object*.**Show** *ListBoxInst* + +*ListBoxInst* +: *required* An **Object** reference to the **ListBox** control to instrument. The class assigns it to a **ListBox** variable, so an object of another type causes a run-time error. The control must already have its items populated; **Show** measures the text width of every item at call time to compute the scroll range. + +**Show** performs three operations in sequence: + +1. Calls the Win32 `ShowScrollBar` API to make the horizontal scrollbar visible. +2. Iterates every list item, measures its pixel width using the GDI device context of the control, and sends `LB_SETHORIZONTALEXTENT` with the widest measurement plus a 10-pixel margin. It also calls `SetScrollInfo` to set the scroll range and page size so the scrollbar thumb reflects the visible proportion of the content. When the list is empty, or every item is empty, neither is set. +3. Installs a window subclass procedure via `SetWindowSubclass` (comctl32) to intercept `WM_HSCROLL` messages. The subclass updates the scroll position on line-left / line-right (20 px per step), page-left / page-right, thumb-track / thumb-position, and left / right scrolls, then passes the message to `DefSubclassProc`. + +The scroll range is calculated from the widest item's pixel width measured with the font that the control reports through `WM_GETFONT`, so a **ListBox** that uses a non-default font is measured with that font. + +> [!NOTE] +> **Show** measures item widths at the moment it is called. If items are added or removed after **Show**, the scroll range is not updated automatically. Call **Show** again after bulk changes to refresh the extent. + +> [!IMPORTANT] +> The control's **hWnd** must be valid (the form must be loaded and the control fully created) before calling **Show**. Calling **Show** before the control's window exists returns silently without installing any scrolling behavior. + +### UnShow +{: .no_toc } + +Removes the window subclass installed by [**Show**](#show). + +Syntax: *object*.**UnShow** + +Calls `RemoveWindowSubclass` to detach the `WM_HSCROLL` handler. After **UnShow** the **ListBox** no longer receives the class's `WM_HSCROLL` handling. The scroll bar and the horizontal extent set by **Show** are not reset; send the `LB_SETHORIZONTALEXTENT` message with a width of 0 to the control, and hide the bar with `ShowScrollBar`, if clearing them is required. + +`Class_Terminate` removes the subclass with the same internal helper, so the subclass is removed when the **cListboxHScroll** instance is destroyed. + +## Example + +This example attaches a horizontal scrollbar to a **ListBox** and removes it when the form closes. + +```tb +Private HScroll As cListboxHScroll + +Private Sub Form_Load() + Set HScroll = New cListboxHScroll + + List1.AddItem "Alpha" + List1.AddItem "Beta -- a much longer entry that would normally be clipped" + List1.AddItem "Gamma" + + HScroll.Show List1 +End Sub + +Private Sub Form_Unload(Cancel As Integer) + HScroll.UnShow +End Sub +``` + +## Remarks + +**cListboxHScroll** uses window subclassing via the comctl32 `SetWindowSubclass` / `RemoveWindowSubclass` / `DefSubclassProc` API family. The subclass is identified by the constant ID `1` in every instance, so use one instance per **ListBox**. + +The class stores the **ListBox** reference in a class-level variable (`Ctl`). Replacing the control by calling **Show** with a different **ListBox** does not automatically remove the subclass from the first control; call **UnShow** before switching targets. + +## See Also + +- [TBMANLIB_ListBoxHScroll](../) package -- overview and installation diff --git a/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/index.md b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/index.md new file mode 100644 index 000000000..972e1131d --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_ListBoxHScroll/index.md @@ -0,0 +1,21 @@ +--- +title: TBMANLIB_ListBoxHScroll Package +parent: Contributed Packages +has_toc: false +indexed_from: 1.0.0.0 +permalink: /tB/Packages/Contributed/TBMANLIB_ListBoxHScroll/ +--- + +# TBMANLIB_ListBoxHScroll Package +{: .no_toc } + +The **TBMANLIB_ListBoxHScroll** contributed package provides a helper class that adds a functional horizontal scrollbar to a standard VB **ListBox** control by combining the `LB_SETHORIZONTALEXTENT` message, Win32 scroll-info APIs, and window subclassing. + +* TOC +{:toc} + +## Classes + +- [cListboxHScroll](cListboxHScroll/) -- a helper class that adds a functional horizontal scrollbar to a standard VB ListBox control using GDI text measurement, `LB_SETHORIZONTALEXTENT`, and window subclassing + - [Show](cListboxHScroll/Show) -- attaches the horizontal scrollbar to a ListBox control and initialises scroll handling + - [UnShow](cListboxHScroll/UnShow) -- removes the window subclass installed by Show diff --git a/docs/Reference/Contributed/TBMANLIB_RES/Base64Prefix.md b/docs/Reference/Contributed/TBMANLIB_RES/Base64Prefix.md new file mode 100644 index 000000000..5dd158457 --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_RES/Base64Prefix.md @@ -0,0 +1,32 @@ +--- +title: Base64Prefix +parent: TBMANLIB_RES Package +permalink: /tB/Packages/Contributed/TBMANLIB_RES/Base64Prefix +has_toc: false +--- +# Base64Prefix +{: .no_toc } + +Specifies whether, and with what MIME type, a data URI prefix is prepended to the base64 string returned by [**ReturnBase64**](cRes/#returnbase64). + +| Constant | Value | Description | +|----------|-------|-------------| +| **Base64Prefix_None**{: #Base64Prefix_None } | 0 | No prefix. The returned string is raw base64 with no leading data URI scheme. | +| **Base64Prefix_ImagePNG**{: #Base64Prefix_ImagePNG } | 1 | Prepends `data:image/png;base64,`. | +| **Base64Prefix_ImageJPEG**{: #Base64Prefix_ImageJPEG } | 2 | Prepends `data:image/jpeg;base64,`. | +| **Base64Prefix_ImageGIF**{: #Base64Prefix_ImageGIF } | 3 | Prepends `data:image/gif;base64,`. | +| **Base64Prefix_ImageBMP**{: #Base64Prefix_ImageBMP } | 4 | Prepends `data:image/bmp;base64,`. | +| **Base64Prefix_ImageICO**{: #Base64Prefix_ImageICO } | 5 | Prepends `data:image/x-icon;base64,`. | +| **Base64Prefix_ImageWebP**{: #Base64Prefix_ImageWebP } | 6 | Prepends `data:image/webp;base64,`. | +| **Base64Prefix_VideoMP4**{: #Base64Prefix_VideoMP4 } | 7 | Prepends `data:video/mp4;base64,`. | +| **Base64Prefix_VideoWebM**{: #Base64Prefix_VideoWebM } | 8 | Prepends `data:video/webm;base64,`. | +| **Base64Prefix_VideoOGG**{: #Base64Prefix_VideoOGG } | 9 | Prepends `data:video/ogg;base64,`. | +| **Base64Prefix_AudioMP3**{: #Base64Prefix_AudioMP3 } | 10 | Prepends `data:audio/mpeg;base64,`. | +| **Base64Prefix_AudioWAV**{: #Base64Prefix_AudioWAV } | 11 | Prepends `data:audio/wav;base64,`. | +| **Base64Prefix_AudioOGG**{: #Base64Prefix_AudioOGG } | 12 | Prepends `data:audio/ogg;base64,`. | + +The default value used by **ReturnBase64** when *Prefix* is omitted is **Base64Prefix_None**. + +### See Also + +- [cRes](cRes/) class -- loads and converts embedded resources diff --git a/docs/Reference/Contributed/TBMANLIB_RES/TBMAN.md b/docs/Reference/Contributed/TBMANLIB_RES/TBMAN.md new file mode 100644 index 000000000..30c516e33 --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_RES/TBMAN.md @@ -0,0 +1,41 @@ +--- +title: TBMAN +parent: TBMANLIB_RES Package +permalink: /tB/Packages/Contributed/TBMANLIB_RES/TBMAN +has_toc: false +--- + +# TBMAN module +{: .no_toc } + +A standard module that exposes a pre-instantiated [**cRes**](cRes/) object as a public variable, providing package-wide access to resource loading without requiring a separate **cRes** instance. + +## Members + +### Res + +A pre-instantiated **cRes** object. + +```tb +Public Res As New cRes +``` + +Because of **As New**, the instance is created automatically the first time **Res** is referenced. It provides the same interface as a manually constructed **cRes** instance: [**Read**](cRes/Read), [**ReturnBytes**](cRes/ReturnBytes), [**ReturnString**](cRes/ReturnString), [**ReturnHex**](cRes/ReturnHex), [**ReturnBase64**](cRes/ReturnBase64), and [**ReturnPicture**](cRes/ReturnPicture). + +> [!NOTE] +> **TBMAN.Res** is a single shared instance for the entire project. Calling **Res.Read** replaces its internal byte buffer. If multiple callers read different resources in the same execution path, use separate **cRes** instances rather than sharing **TBMAN.Res**. + +## Example + +This example loads a PNG resource and assigns it to a **PictureBox** control. + +```tb +Private Sub Form_Load() + Picture1.Picture = TBMAN.Res.Read(101, "PNG").ReturnPicture() +End Sub +``` + +## See Also + +- [cRes](cRes/) class -- loads and converts binary resources embedded in the project +- [TBMANLIB_RES](.) package -- overview diff --git a/docs/Reference/Contributed/TBMANLIB_RES/cRes/Read.md b/docs/Reference/Contributed/TBMANLIB_RES/cRes/Read.md new file mode 100644 index 000000000..cc8c8f8c1 --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_RES/cRes/Read.md @@ -0,0 +1,52 @@ +--- +title: Read +parent: cRes +permalink: /tB/Packages/Contributed/TBMANLIB_RES/cRes/Read +has_toc: false +--- +# Read +{: .no_toc } + +Loads a resource from the compiled executable into the **cRes** instance. + +Syntax: *object*.**Read**( *id*, *Type* ) **As cRes** + +*id* +: *required* A **Variant** identifying the resource to load. Pass a numeric **Long** to identify the resource by its integer ID, or a **String** to identify it by name. + +*Type* +: *required* A **Variant** identifying the resource type. Pass a numeric **Long** for a predefined resource type (for example, `2` for `RT_BITMAP`), or a **String** for a named custom resource type (for example, `"CUSTOM"`). + +**Read** calls the **LoadResData** function with the supplied *id* and *Type* arguments and stores the resulting byte array internally. The method returns the **cRes** instance itself, so calls to the retrieval methods ([**ReturnBytes**](ReturnBytes), [**ReturnString**](ReturnString), [**ReturnHex**](ReturnHex), [**ReturnBase64**](ReturnBase64), [**ReturnPicture**](ReturnPicture)) can be chained directly onto the **Read** call. + +> [!IMPORTANT] +> **Read** must be called before any retrieval method. The resource data is not populated at construction time; a retrieval method called without a prior **Read** will operate on an empty byte array and may raise a runtime error. + +> [!NOTE] +> **Read** can load only a resource that is part of the project. *Type* names a folder under **Resources** in the Project Explorer (or is the number of a standard resource type), and *id* identifies a resource in it. If no resource matches, **LoadResData** raises a run-time error. + +### Example + +This example loads a custom binary resource by name and retrieves it as a byte array, then loads an image resource by integer ID and assigns it to a **PictureBox**. + +```tb +Private Sub Form_Load() + ' Load a named custom resource and retrieve the raw bytes. + Dim res As New cRes + res.Read "CONFIG_DATA", "CUSTOM" + Dim data() As Byte + data = res.ReturnBytes() + + ' Load an image stored as a PNG resource by integer ID and display it. + Dim imgRes As New cRes + Picture1.Picture = imgRes.Read(101, "PNG").ReturnPicture() +End Sub +``` + +### See Also + +- [ReturnBytes](ReturnBytes) method +- [ReturnString](ReturnString) method +- [ReturnHex](ReturnHex) method +- [ReturnBase64](ReturnBase64) method +- [ReturnPicture](ReturnPicture) method diff --git a/docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnBase64.md b/docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnBase64.md new file mode 100644 index 000000000..383254946 --- /dev/null +++ b/docs/Reference/Contributed/TBMANLIB_RES/cRes/ReturnBase64.md @@ -0,0 +1,66 @@ +--- +title: ReturnBase64 +parent: cRes +permalink: /tB/Packages/Contributed/TBMANLIB_RES/cRes/ReturnBase64 +has_toc: false +--- +# ReturnBase64 +{: .no_toc } + +Returns the resource bytes as a Base64-encoded string, with an optional MIME-type data-URI prefix. + +Syntax: *object*.**ReturnBase64** ( [ *Prefix* ] ) **As String** + +*Prefix* +: *optional* A **Base64Prefix** enumeration value that selects a data-URI prefix to prepend to the encoded string. Defaults to **Base64Prefix_None**, which returns the raw Base64 string with no prefix. + +**ReturnBase64** encodes the byte array held by the **cRes** instance using MSXML2's `bin.base64` data type and returns the result as a **String**. MSXML puts a line feed (`vbLf`) after every 72 characters of Base64, and **ReturnBase64** does not remove them. When *Prefix* is any value other than **Base64Prefix_None**, the corresponding `data:;base64,` header is prepended, producing a data URI that can be used in an ``, `