Help Add-In
Shows this documentation inside the IDE: press F1 on a name in the code editor, and its reference page opens in a tool window beside the code.
The add-in is named twinBASIC Documentation Help in the IDE. It works from an index of every symbol this documentation describes, built with the documentation itself, so it knows which page documents each function, statement, class and member. With the compiler’s help it also tells apart names that are spelled the same: c.Add on a Collection opens Collection.Add, and a bare Close opens the Close statement.
F1 and the help pane
Put the cursor on a name and press F1. The page that documents the name opens in the TWINBASIC HELP tool window. The cursor can be anywhere in the name, or just after it, as it is after typing the name.
The help pane is an ordinary IDE tool window: it can float, or be docked like the other tool windows. The page in it follows the IDE’s theme, dark or light, and its links work as they do on the website. Above the page are a search box and three buttons:
- Open in browser
- Opens the page on docs.twinbasic.com in the default web browser.
- Detach
- Moves the help into a window of its own — see The help window.
- The gear
- Opens the settings.
The Help button the add-in adds to the IDE’s toolbar shows the pane and puts the cursor in its search box, ready to type.
F1 takes the whole dotted name to the left of the cursor, up to the end of the name the cursor is in: with the cursor on Add in Host.ToolWindows.Add(Name, Id), it looks up Host.ToolWindows.Add. A selection on one line is looked up exactly as it is selected. F1 on an empty spot shows the pane and puts the cursor in its search box.
When no page documents the name, the pane stays as it is, and a notification says so: No help for ‘Name’.
Note
F1 also expands or collapses the IDE’s signature help when it is showing. F1 does nothing while the keyboard focus is inside the page in the pane: click in the code editor first.
Hover help
With Hover help ticked in the settings, the information box the IDE shows when the mouse rests on a name gains a link to the name’s page, at its top. Clicking the link shows the page in the pane, as F1 does.
A link names the symbol, its kind and where it is declared: Help: MsgBox function (VBA.Interaction). A name that several pages document gets a link for each, up to five. A name without a page gets no link. Hover help is off until it is ticked.
Searching
Type in the search box to find a page by its symbol’s name. The list shows the names that start with the text first, then those that contain it, with each one’s kind. Text with a dot in it is matched against qualified names such as Collection.Add. Click a name to show its page, or press Enter for the first one. The clear button at the right of the box empties it and hides the list.
The search finds symbols, not words in the pages: to search the text of the documentation, use the search on the website.
When F1 finds several pages
Sometimes the name alone cannot say which page is meant. A member called through a variable declared As Object is the common case: the object’s type is known only when the program runs. F1 then puts the name in the search box and lists every page that documents it, and the page in the pane stays as it was. Click the one that applies.
Your own procedures
F1 on a name declared in the project itself, or in a package or type library this documentation does not cover, shows a summary in place of a page. The summary gives the declaration, the text of the procedure’s Description attribute, and where the name is declared.
The summary for the procedure above comes from this code:
[Description("Adds up the prices held in a Dictionary.")]
Public Function TotalPrice(ByVal prices As Object) As Double
Without a Description attribute, the summary says No description. Open in browser is unavailable while a summary is shown.
Settings
The gear opens the settings. A click anywhere else, or Esc, closes them.
- Hover help
- Adds the links described under Hover help. Off by default.
- All packages
- Offers the pages of every package this documentation covers. Off by default: F1, the hover links and the search then offer only the language itself and the packages the project references, so that a name from a package the project does not use never hides the one it does. With this off, F1 on a name that only an unreferenced package documents says No help for ‘Name’ in the packages this project references.
- Ctrl and Alt shortcuts of add-ins
- Runs the keyboard shortcuts that other add-ins define with Ctrl or Alt, which the IDE on its own does not run: see Other add-ins’ shortcuts. On by default.
- Find in the shortcut editors
- Ctrl+F and F3 in the text of Manage Keyboard Shortcuts and Manage Panel Layouts: see Finding text in the shortcut editors. On by default.
- Keyboard shortcut editor
- Shows the groups of Manage Keyboard Shortcuts as a table of commands: see The keyboard shortcut editor. On by default. Turned off, the dialog shows the IDE’s own pane again at once.
- Panel layout editor
- Shows the layouts of Manage Panel Layouts as a picture: see The panel layout editor. On by default. Turned off, the dialog shows the layout’s text again at once.
The settings, the last page shown and the help window’s place are kept in the registry, under HKEY_CURRENT_USER\Software\VB and VBA Program Settings\tbDocsHelp. After the IDE restarts, the pane shows the page it showed last.
The help window
Detach moves the whole pane — search box, buttons and page — into a window of its own. The window has a button on the taskbar, can be moved to another monitor, and keeps its position and size from one session to the next. While it is detached, F1, the Help button and the hover links show their page in the window.
The window’s title bar holds, from the left:
- Attach
- Puts the help back in the pane in the IDE, with the same search text and page.
- The gear
- Opens the settings.
- Minimize, Maximize, Close
- Work as in any window. Close only hides the window: the help stays detached, and the next F1 shows the window again.
The window is open again the next time the IDE starts, if it was open when the IDE closed. With Show real OS titlebar turned on in the IDE’s options, the window has an ordinary Windows title bar instead, in the IDE’s dark or light colours, and Attach and the gear move next to the search box.
The help window in panel layouts
Each panel layout also keeps where the help is: in its pane, or in its own window and where that window is on the screen. Window > Panel Layouts > Save Current Panel Layout As… records where the help is at that moment. Choosing the layout later puts the help back there: it detaches the help into its window at the recorded place, or attaches it to its pane. A built-in layout, and a layout saved while the add-in was not loaded, leave the help where it is. The add-in keeps this itself, by the layout’s name, and not in the layout’s text. In Manage Panel Layouts, the help’s panel has a box to change it: see The panel layout editor.
Other add-ins’ shortcuts
While this add-in is loaded, the keyboard shortcuts that other add-ins register with Ctrl or Alt work. Without it, the IDE does not run an add-in’s shortcut that includes Ctrl or Alt: see KeyboardShortcuts. The IDE’s own command on the same keys still runs as well. The setting Ctrl and Alt shortcuts of add-ins turns this off.
Finding text in the shortcut editors
The text of Window > Keyboard Shortcuts > Manage Keyboard Shortcuts, and of Manage Panel Layouts, has no find of its own. While this add-in is loaded, these keys work there, as in Visual Studio:
- Ctrl+F
- Opens a find box at the top right of the text, like the search bar of the Project Explorer, holding the selected text if it is on one line. Its close button closes it, as Esc does.
- Enter, F3
- Selects the next match. Shift+Enter and Shift+F3 select the one before. F3 and Shift+F3 also work after the find box is closed, with the last text searched for.
- Ctrl+F3
- Searches for the selected text, or for the word at the caret, without opening the find box. Ctrl+Shift+F3 searches backwards.
- Esc
- Closes the find box. The dialog stays open.
The search goes round past the end, and ignores case. The text scrolls to show each match. A search that finds nothing draws a red ring inside the box where the text is typed, and leaves the selection where it was. The setting Find in the shortcut editors turns this off.
The keyboard shortcut editor
On its own, Window > Keyboard Shortcuts > Manage Keyboard Shortcuts shows each group of shortcuts as JSON text, and with Edit as JSON cleared only the line Keyboard editor coming soon. While this add-in is loaded, the dialog shows the selected group as a table instead, with a row for every command of the IDE. Keyboard shortcuts explains the groups and how they are layered.
A row has the command’s name, its keys, and a line on what the command does, from the keyboard shortcuts reference. The rows are grouped by the prefix of the command’s name; clicking a prefix folds its rows. In a group of your own, the keys of a row show what the earlier groups give the command and what this group changes:
- a grey key comes from an earlier group;
- a blue key is set by this group;
- a dashed key that is struck through is one this group removes;
- a yellow key is also bound to another command, and a group of your own made one of the two bindings. Its tooltip names the other command and the group. The IDE runs each command bound to a key whose context applies, in its own order, until one of them ends the key’s handling. Keys that the built-in group gives to several commands are not marked, since those commands apply in different places;
- a red key that is struck through can never run, such as a key the IDE has no name for, or a key with Ctrl or Alt that runs when released. Its tooltip says why.
The conflicts are found across every group that is switched on, the group shown and any group added in the dialog included. A row also says when a later group changes the command again, since this group’s keys are then not the ones that apply.
The box at the top finds commands by name, by description, or by the name of a key, such as ctrl+d. Find a key waits for a key and finds the commands bound to it. The buttons beside it show every command, only those with keys, only those this group changes, or only those with a problem.
Clicking a row of a group of your own opens its editor:
- Keys from earlier groups
- Keep them, and add these writes the entry as
+command, and Replace them with these ascommand, so that only this group’s keys apply. - Add a key
- Waits for a key: press it with its modifiers. Esc stops waiting. Esc and Tab on their own, and keys the IDE has no name for, such as
;, cannot be added here; the JSON view takes any key string. - When a key runs
- When pressed, When pressed, and while held, or When released. A key with Ctrl or Alt never runs when released, so that choice is not offered for it.
- With an argument
- For
tbDebugConsole_ExecuteCode, a key that runs the command with an argument, such as? Now. Type the argument, then add its key. - Reset to earlier groups
- Removes the group’s entry for the command.
- No keys
- Gives the command no keys, whatever the earlier groups give it.
Each change is written into the group’s text: Save Changes saves it, and Cancel discards it. The built-in group is read-only, and its rows open no editor. The JSON button at the bottom shows the group’s text, as the IDE shows it with Edit as JSON ticked, and Table shows the table again. A group whose text is not valid JSON is shown as text until it is corrected. Entries for a command the IDE does not have are listed at the top of the table, where a group of your own can remove them.
In the table, Esc closes the open editor, then clears the search, and never closes the dialog. Ctrl+F goes to the search box. While the table is on, the dialog’s text leaves out its last line, which promises a proper editor. The setting Keyboard shortcut editor turns the table off, and gives the dialog its own pane and text back.
The panel layout editor
On its own, Window > Panel Layouts > Manage Panel Layouts shows each layout as JSON text. While this add-in is loaded, the dialog shows the selected layout as a picture instead: a small IDE window, at the proportions of the IDE’s own, with every docked panel in its place and every floating panel over them. Panel layouts explains the layouts and their text.
Each tile shows the panel’s name and its size: a share of its group, takes the rest or fits its contents. Clicking a tile selects it, and clicking the gap round a group selects the group. The box beside the picture then shows what can be changed:
- Where
- The groups that hold the panel, from the whole window inwards. Clicking one selects it.
- Its members are
- For a group: Side by side or One above another. In the layout’s text these are
verticalandhorizontal. - Its width, Its height
- The rest gives the panel the room its neighbours leave, A share a percentage of its group, and To fit as much as its contents need.
- Move left, Move right, Move up, Move down
- Swaps the panel with its neighbour.
- Make it float
- Takes the panel out of its group and floats it where the IDE floats a panel it shows: 100 pixels from the left and from the top, 300 wide and 500 high. A group left with one member is replaced by it.
- Remove from this layout
- Takes the panel out of the layout.
A floating panel’s box has its place in the IDE window, in pixels, and Dock it…. Dragging a splitter between two tiles resizes them, and dragging a floating panel by its title moves it.
The panels the layout lacks are listed above the picture, the tool windows of the add-ins that are loaded among them. Clicking one, or Dock it…, then clicking near an edge of a tile docks the panel on that side of it: in the tile’s group when the group’s members run that way, or in a new group of the two. Make it float floats it instead.
Use the current arrangement replaces the layout with the panels as the IDE shows them now, and with where the help is now.
The help’s own panel, TWINBASIC HELP, has one more box, With the Help Add-In, for where the layout puts the help:
- In this panel
- Choosing the layout attaches the help to its pane. Chosen for a layout whose help was in its own window, it also floats the pane where the window was, at the window’s size and inside the IDE window, and adds the pane to the layout if it lacked it. Dock it again if you wish.
- In its own window
- Choosing the layout detaches the help into its window, placed at Left and Top and sized to Width and Height: pixels on the screen. The window is drawn in the picture at that place, inside the picture if it is outside the IDE window. Clicking it selects the help’s panel, or shows the box alone when the layout has no pane for the help.
A layout for which neither has been chosen leaves the help where it is. Like every other change, the choice is kept by Save Changes and discarded by Cancel. Save Changes also forgets what the add-in kept for the layouts deleted in the dialog.
A tile of an add-in’s window that no loaded add-in has is marked not loaded. That is no problem: the IDE keeps the window’s place, empty and marked (currently unavailable), until the add-in opens it. The line under the picture counts the layout’s panels and its problems: a layout with no Editor, a panel in it twice, or an id that is not a panel of the IDE. A layout with a problem is marked with ! in the list.
Each change is written into the layout’s text: Save Changes saves it, and Cancel discards it. The built-in layouts are read-only. The JSON button at the bottom shows the layout’s text, and Picture shows the picture again. A layout whose text is not valid JSON is shown as text until it is corrected. In the picture, Esc ends what is being done — docking a panel, then the selection — and never closes the dialog. The setting Panel layout editor turns the picture off, and gives the dialog its text back.
Getting the add-in
The add-in is a twinBASIC project, which the IDE builds into two DLLs, one for each bitness.
- Download the project file, tbDocsHelp.twinproj, about 61 MB. It is made from the add-in’s source code each time this documentation is published. It holds the index of the symbols these pages document and a copy of the whole documentation.
- Open
tbDocsHelp.twinprojin the twinBASIC IDE and build it. Then set the build target to win64 and build it again. The two DLLs,tbDocsHelp_win32.dllandtbDocsHelp_win64.dll, are written to aBuildfolder next to the project file. - Copy each DLL to the matching
win32orwin64add-ins folder, as Add Ins describes, and restart the IDE.
An add-in built this way serves the pages itself, from the copy of the documentation in its DLL, so the pane needs no internet connection. Open in browser still opens the page on the website, docs.twinbasic.com.
The add-in’s version is in the DLL’s file properties. CHANGELOG.md, in the project and in the source folder, lists what changed in each version.
From the source code
The add-in’s source code is in the add-in folder of the documentation’s repository. Build from it to change the add-in. The folder holds the project’s files, not a project file, so pack it into one first with the Import/Export Tool, from the repository’s root folder:
python scripts/impexp.py import tbDocsHelp.twinproj add-in
Then build tbDocsHelp.twinproj and copy the DLLs as in steps 2 and 3 above.
For help that works offline, build the documentation before packing the folder, as Building and Deployment describes. The build writes a copy of the site into the add-in’s source folder, add-in\Resources\HELP\site.zip, about 60 MB. A DLL built with that file in place serves the pages itself, without the internet. The copy leaves out the pages about developing this documentation, the videos, the challenges and the files to download, which open from the website. Without the file, the add-in shows all the pages from the website.
See Also
- Add Ins – installing and loading add-ins
- Global Search add-in
- tbIDE Package – the API an add-in is written against