Add Qt help view

.github/workflows/build.yml

@@ -29,3 +29,8 @@ jobs:
       #  npm test
       env:
         CI: true
+    - name: Upload Artifact
+      uses: actions/upload-artifact@v2
+      with:
+        name: qtvsctools.vsix
+        path: '*.vsix'

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change Log
 
+## 0.8
+
+- Add Qt online help commands. Thanks to for the request [@Shatur95](https://github.com/Shatur95)
+
 ## 0.7
 
 - Add support for open multiple selected files at once in Qt designer. Thanks to [@cobalt77](https://github.com/cobalt77) for the contribution 🙏.

README.md

@@ -9,10 +9,12 @@ This is a Qt extension for VSCode. It is designed to be an similar tool to the [
 At the moment the extension extracts the Qt file locations from CMake only (from [CMake Tools extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) setting `cmake.buildDirectory`), so choosing and different Qt version from disk is not supported at the moment (but if you use cmake already, everything is automatically detected :-) ).
 
 ## Features
+
 * [x] Launch Qt Designer
 * [x] Edit `.ui` file in Qt Designer
 * [x] Launch Qt Assistant
-* [x] Launch Visual Studio (Windows only) 
+* [x] Launch Qt online documenation
+* [x] Launch Visual Studio (Windows only)
 * [x] Launch Qt Creator<br>
   `.ui` and `.qrc` files can be opened in Qt Creator. You can also open the whole workspace in Qt Creator too.<br>
   This extension try to detect the Qt Creator installation automatically (on Windows and MacOS). You can set the executable path via `qttools.creator` settings if the extension can't find Qt Creator (for whatever reason)
@@ -26,25 +28,54 @@ At the moment the extension extracts the Qt file locations from CMake only (from
 * ...
 
 ## Requirements
+
 * You need to have the [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) installed, because this extension extracts some data from it!
 * [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) is highly recommended
 
 ## Limitations
+
 * There are some situation where the automatic detection mechanism of Qt is not working. If that is the case you can always trigger the `Scan for Qt kits` command in the command palette.
 * The debugger extension use normal natvis xml files (used via the `launch.json` setting `visualizerFile` from the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) ). They work really well on windows, but on mac and linux there are some problems, because it is not based on the same implementation. If you have any problems with them create an issue on their issue tracker.
 
 ## Variable substitution
+
 The `cmake.buildDirectory` from `cmake tools` support variable substitution which looks like `${myvariable}` (example `${generator}`).
 
 This extension supports every variable substitution from `cmake tools` when the `cmake tools` extension is installed and active.
 
 If `cmake tools` is not active the extension will fallback to the content of the `cmake.buildDirectory`. In this mode only `${buildType}`, `${buildKit}` and `${workspaceFolder}` are supported variable substitutions!
 
+## Online help
+
+The Qt online help can be used with this extension. Right now only the latest Qt 5 version will be searched.
+
+You  have 2 commands:
+
+* Qt: Online help  
+  This will open the Qt documentation. When you are in a `.cpp` or `.h` file and your cursor is inside a text block then the command will search that word as a class in the documenation.
+* Qt: Search online help  
+  This command will create a textbox inside vscode where you can enter your search term. This search term will be send to the search of the Qt Documenation.
+
+By default the qt website will be opened inside VSCode itself.
+
+The integrate webview has some limitations:
+
+* Open the find menu via `CTRL` + `F` does not work in many scenarios, see [#96307](https://github.com/microsoft/vscode/issues/96307)  
+  Most of the time it works when you can click on the document tab (Qt online help) and then press `CTRL` + `F`
+* The normal mouse-click on a link which would open a new tab also don't work  
+  You can click the middle mouse button on that link and it will open in your external browser.
+* No navigation buttons
+
+You can also turn of the embedded webview for the online help and use your external browser by setting the `qttools.useExternalBrowser` to `true`. Be aware that you will get a popup from VSCode which informs you about opening an external website. To avoid getting this popup every time just press on `Configure Trsuted Domains` and choose `trust qt.io and all its subdomains`.
+
 ## Troubleshooting
+
 If you have problems with the extension just file a issue on [GitHub](https://github.com/tonka3000/vscode-qt-tools/issues). It's mostly a good idea to attach the log output of this extension to the issue. You can active the logger by adding `"qttools.loglevel": "debug"` to your `settings.json` file. Just copy the content of the `Qt` output pane into your GitHub issue.
 
 ## Contributions
+
 Pull requests are welcome :-D
 
 ## License
+
 MIT

package.json

@@ -2,7 +2,7 @@
 	"name": "qtvsctools",
 	"displayName": "Qt tools",
 	"description": "Qt tools support for VSCode",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"publisher": "tonka3000",
 	"preview": true,
 	"license": "MIT",
@@ -25,6 +25,8 @@
 		"onCommand:qttools.currentfileindesigner",
 		"onCommand:qttools.launchdesigneronly",
 		"onCommand:qttools.launchassistant",
+		"onCommand:qttools.launchonlinehelp",
+		"onCommand:qttools.searchonlinehelp",
 		"onCommand:qttools.launchcreatoronly",
 		"onCommand:qttools.workspaceincreator",
 		"onCommand:qttools.currentfileincreator",
@@ -49,6 +51,16 @@
 				"title": "Launch Qt Assistant",
 				"category": "Qt"
 			},
+			{
+				"command": "qttools.launchonlinehelp",
+				"title": "Online help",
+				"category": "Qt"
+			},
+			{
+				"command": "qttools.searchonlinehelp",
+				"title": "Search Online help",
+				"category": "Qt"
+			},
 			{
 				"command": "qttools.scanqtkit",
 				"title": "Scan for Qt Kit",
@@ -151,6 +163,12 @@
 						"description": "automatically inject the natvis.xml of Qt into existing launch.json entries",
 						"scope": "resource"
 					},
+					"qttools.useExternalBrowser": {
+						"type": "boolean",
+						"default": false,
+						"description": "use external browser for online help",
+						"scope": "resource"
+					},
 					"qttools.visualizerFile": {
 						"type": "string",
 						"default": "",

src/extension.ts

@@ -9,6 +9,7 @@ import { NatvisDownloader } from './downloader';
 import * as open from 'open';
 import { Logger, LogLevel } from './logging';
 import { fileExists } from './tools';
+import { QtHelp } from './help';
 
 class ExtensionManager implements vscode.Disposable {
 	public qtManager: qt.Qt | null = null;
@@ -19,9 +20,11 @@ class ExtensionManager implements vscode.Disposable {
 	private _cmakeCacheWatcher: fs.FSWatcher | null = null;
 	public natvisDownloader: NatvisDownloader | null = null;
 	public logger: Logger = new Logger();
+	public help: QtHelp | null = null;
 
 	constructor(public readonly extensionContext: vscode.ExtensionContext) {
 		this._context = extensionContext;
+		this.help = new QtHelp(extensionContext);
 		this._channel = vscode.window.createOutputChannel("Qt");
 		this.logger.outputchannel = this._channel;
 		this.qtManager = new qt.Qt(this._channel, this._context.extensionPath);
@@ -45,6 +48,9 @@ class ExtensionManager implements vscode.Disposable {
 		this._channel.appendLine("update state of ExtensionManager");
 		this.logger.level = this.getLogLevel();
 		this.logger.debug("update state");
+		if (this.help) {
+			this.help.useExternalBrowser = this.getUseExternalBrowserForOnlineHelp();
+		}
 		if (this.cmakeCache) {
 			this.logger.debug(`cmake build directory: ${await this.getCMakeBuildDirectory()}`);
 			this.cmakeCache.filename = await this.getCmakeCacheFilename();
@@ -92,6 +98,16 @@ class ExtensionManager implements vscode.Disposable {
 		return result;
 	}
 
+	public getUseExternalBrowserForOnlineHelp(): boolean {
+		let result = false;
+		const workbenchConfig = vscode.workspace.getConfiguration();
+		let useExternalBrowser = workbenchConfig.get('qttools.useExternalBrowser') as boolean;
+		if (useExternalBrowser) {
+			result = useExternalBrowser;
+		}
+		return result;
+	}
+
 	public getLogLevel(): LogLevel {
 		const config = vscode.workspace.getConfiguration();
 		const logleveltext = config.get("qttools.loglevel") as string;
@@ -366,6 +382,9 @@ class ExtensionManager implements vscode.Disposable {
 		if (this.logger) {
 			this.logger.dispose();
 		}
+		if (this.help) {
+			this.help.dispose();
+		}
 		this.natvisDownloader = null;
 	}
 
@@ -477,6 +496,59 @@ export async function activate(context: vscode.ExtensionContext) {
 		}
 	});
 
+	_EXT_MANAGER.registerCommand('qttools.launchonlinehelp', async () => {
+		if (_EXT_MANAGER && _EXT_MANAGER.qtManager) {
+			await _EXT_MANAGER.updateState();
+			try {
+				let word = "";
+				const editor = vscode.window.activeTextEditor;
+				if (editor) {
+					if (editor.document.fileName.endsWith(".cpp") || editor.document.fileName.endsWith(".h")) {
+						if (editor.selection.isEmpty) {
+							const wordrange = editor.document.getWordRangeAtPosition(editor.selection.active);
+							if (wordrange) {
+								word = editor.document.getText(wordrange);
+								_EXT_MANAGER.logger.debug(`marked word: ${word}`);
+							}
+						}
+					}
+				}
+				if (_EXT_MANAGER.help) {
+					await _EXT_MANAGER.help.searchKeyword(word);
+					return;
+				}
+			} catch (error) {
+				const ex: Error = error;
+				_EXT_MANAGER.outputchannel.appendLine(`error during launching Qt help: ${ex.message}`);
+				vscode.window.showErrorMessage(`error launching Qt help: ${ex.message}`);
+			}
+		}
+	});
+
+	_EXT_MANAGER.registerCommand('qttools.searchonlinehelp', async () => {
+		if (_EXT_MANAGER && _EXT_MANAGER.qtManager) {
+			await _EXT_MANAGER.updateState();
+			try {
+				const query = await vscode.window.showInputBox({
+					value: '',
+					placeHolder: 'enter search term',
+					validateInput: text => {
+						return text === "" ? "search term could not be empty" : null;
+					}
+				});
+				if (query && _EXT_MANAGER.help) {
+					await _EXT_MANAGER.help.displaySearchResults(query);
+					return;
+				}
+			}
+			catch (error) {
+				const ex: Error = error;
+				_EXT_MANAGER.outputchannel.appendLine(`error query Qt help: ${ex.message}`);
+				vscode.window.showErrorMessage(`error query Qt help: ${ex.message}`);
+			}
+		}
+	});
+
 	_EXT_MANAGER.registerCommand('qttools.launchassistant', async () => {
 		if (_EXT_MANAGER && _EXT_MANAGER.qtManager) {
 			await _EXT_MANAGER.updateState();

src/help.ts

@@ -0,0 +1,100 @@
+import * as vscode from 'vscode';
+
+export class QtHelp implements vscode.Disposable {
+    private _webview: vscode.WebviewPanel | undefined;
+    private _context: vscode.ExtensionContext;
+    public useExternalBrowser = false;
+
+    constructor(public readonly extensionContext: vscode.ExtensionContext) {
+        this._context = extensionContext;
+    }
+
+    private async displayUrl(url: string) {
+        if (this.useExternalBrowser) {
+            vscode.env.openExternal(vscode.Uri.parse(url));
+        }
+        else {
+            try {
+
+                const content = await this.getWebViewContent(url);
+                if (this._webview) {
+                    this._webview.reveal(vscode.ViewColumn.Beside);
+                }
+                else {
+                    this._webview = vscode.window.createWebviewPanel(
+                        'docs',
+                        'Qt Online help',
+                        {
+                            viewColumn: vscode.ViewColumn.Beside,
+                            preserveFocus: false
+                        },
+                        {
+                            enableScripts: true,
+                            enableFindWidget: true,
+                            retainContextWhenHidden: true
+                        }
+                    );
+                    this._webview.onDidDispose(() => {
+                        this._webview = undefined;
+                    }, null, this._context.subscriptions);
+                }
+                this._webview.webview.html = content;
+            }
+            catch (error) {
+                if ((error as Error).message !== "") {
+                    vscode.window.showInformationMessage((error as Error).message);
+                }
+            }
+        }
+    }
+
+    public async displaySearchResults(text: string) {
+        const safeparam = encodeURIComponent(text);
+        const url = `https://doc.qt.io/qt-5/search-results.html?q=${safeparam}`;
+        await this.displayUrl(url);
+    }
+
+    public async searchKeyword(text: string) {
+        let url = "https://doc.qt.io/qt-5/";
+        if (text) {
+            const term = text.toLowerCase();
+            url += term + ".html";
+        }
+        await this.displayUrl(url);
+    }
+
+    private async getWebViewContent(url: string): Promise<string> {
+        return `
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>C++ Reference</title>
+            <style>
+                body, html
+                {
+                    margin: 0;
+                    padding: 0;
+                    height: 100%;
+                    overflow: hidden;
+                    background-color: #fff;
+                }
+                iframe
+                {
+                    border: 0px;
+                }
+              </style>
+        </head>
+        <body>
+        <iframe src="${url}" width="100%" height="100%" ></iframe>
+        </body>
+        </html>`;
+    }
+
+    dispose() {
+        if (this._webview) {
+            this._webview.dispose();
+        }
+    }
+}

src/qt.ts

@@ -173,13 +173,13 @@ export class Qt {
         this._creatorFilename = value;
     }
 
-    public async launchAssistant() {
+    public async launchAssistant(args: string[] = []) {
         this.outputchannel.appendLine(`launch assistant process`);
         const assistantFilename = await this.assistantFilename();
         if (!await tools.fileExists(assistantFilename)) {
             throw new Error(`qt assistant executable does not exist '${assistantFilename}'`);
         }
-        const assistant = spawn(assistantFilename, []);
+        const assistant = spawn(assistantFilename, args);
         assistant.on('close', (code) => {
             this.outputchannel.appendLine(`qt assistant child process exited with code ${code}`);
         });