|Scroll Prev Top Next More|
To unify the Windows and MacOS platforms, we have implemented the same URL-style command syntax in both versions of eViewer. The syntax is identical, but the calling conventions are slightly different because of the different platforms.
How context help calls work on Windows
On Windows, you can call an executable with command line parameters. Multiple calls to the same executable will normally start multiple instances of the program. However, this is prevented by the eViewer application. It always displays just one instance of the viewer for the same help file, even when you make multiple calls to it.
How context help calls work on MacOS
On MacOS, when an application is opened by another program, it is possible to specify command line parameters as well. But only once. Because of the general single-instance policy on MacOS, a subsequent call to the same executable does not create a new instance. Instead, it brings the running instance into foreground. At this point, the already running application does not receive the (different) command line parameters after the --args command line switch.
All is not lost, however, because MacOS also makes it pretty simple to register a custom URL scheme for an app, which can be used both to open your app and pass commands to a running instance.
The references for topic files in your call URLs are slightly different for standard Help+Manual skins and frameless Premium Pack skins. With the standard skins you need to call both the layout page (index.html) and the topic page (topic.htm or topic_id.html, depending on what you set as your topic extension in your project).
Premium Pack V3, V4 and V5 skins
The URL command combines 3 parts: a) the protocol, b) the domain which is our ewriter file and c) the optional command parameters as the URL query part.
The URL is preceded by the viewer reference
All examples are the argument. They must always be preceded by a reference eViewer app or the eWriter EXE file name if you are using that format on Windows. When using standalone Windows EXE files the file is both the viewer and the target and calls itself.
You can use two ? separators in the same URL
Note that you use the ? character after the index.html reference as the first separator, even though it also comes after the eWriter Help file name. This is because the URL is actually two combined URLs that are split internally by the viewer.
Calls on Windows with eViewer.exe and data help files
The calling convention on Windows is:
Open: eViewer.exe "urlstring"
Escaping (percent encoding) URLs:
The URL can be escaped (percent encoded) on Windows. When served in quotes as a command line string, the URL is technically a simple string and eViewer.exe will take it at face value, even if it is not escaped. Escaped URLs will be unescaped internally. See How to escape a URL below.
Calls on Windows with integrated EXE help files
On Windows you can also create eWriter Help files as a standalone EXE with an integrated viewer. The calling syntax for these files is exactly the same, with the difference that the file calls itself. This is because the file is both the viewer and the help file. So it looks like this:
The calling convention on MacOS is two-fold. You can use the command line (but only once) and you can also optionally open the custom URL directly:
Open: eViewer.app --args "urlstring"
If the protocol doesn't work immediately after modification, start the app with a double click. This should be sufficient to register the custom URL scheme on the Mac.
(a) Command line arguments
(b) Custom URL scheme
The URL must be escaped with percent encoding on MacOS. It will work unescaped when served in quotes as a command line string, but the direct call to a custom URL scheme requires a properly escaped URL.
A URL is a single string without spaces. It is made up of a protocol, a domain and trailing query strings. No spaces are allowed in the domain or the query strings. The domain and query strings are separated by a question mark (?). Multiple query strings are separated by an ampersand (&). For detailed information, see the W3C website HTML URL Encoding Reference.
To serve the URL string correctly, we must at least escape all spaces in the entire URL and the question marks within parameters: