NW.js object

The NW.js object allows access to features specific to the NW.js exporter, such as reading and writing files to the local disk drive.

Note that the AJAX object can read files from the application folder (but not write files) when exporting to NW.js. This may allow you to implement file reading in a cross-platform manner. Also note the AJAX object reads files asynchronously, whereas the NW.js object conducts all operations synchronously.

What is NW.js?

NW.js is essentially a standalone version of the Google Chrome web browser, but while looking like an ordinary desktop app (so there are no browser tabs, address bar, back/forward buttons etc). Exporting using NW.js allows your project to run as a standalone desktop app on Windows, Mac and Linux, and does not require any particular other browser to be installed.

Note NW.js was formerly known as node-webkit.

Previewing

Since NW.js is based on the Google Chrome browser, usually previewing in Chrome will run it identically to when exported with NW.js. However the features of the NW.js plugin (such as file access) do not work in the Google Chrome web browser. In order to test these features in preview mode, it is possible to choose NW.js for the Preview browser project property. This allows you to test your game with the features of this plugin working.

Note that previewing with NW.js runs directly from its install directory. As a consequence, the AppFolder expression will return the install path. If this poses a problem for you, use the following workaround: have a global string variable; if 'Is in preview' is true hard-code it to some development folder somewhere else, otherwise set it to NWjs.AppFolder. Then use the global variable instead of the AppFolder expression.

Using file paths correctly

Never hard-code paths (such as using an action to write to a fixed file path like "C:\MyGame\MyFile.txt"). This unfriendly to users, and is often perceived as unprofessional, untidy, or filling the user's system with junk. Not only that but in many cases it simply will not work, since not all users have permission to read or write to folders outside of their user directory.

It is tempting to solve this by writing files to the application's folder. However this also may not work; on many versions of Windows, the Program Files folder requires administrator permission to write to, although you can read from it.

The solution is to write to the user's folder, which you almost certainly have write permission for. This is provided by the UserFolder expression. The correct way to determine a file path in the user's folder is like this:

NWjs.UserFolder & "myfile.txt"

If you only need to read files, and don't need to write them, you can safely use the application folder (NWjs.AppFolder) instead.

Text file encoding

The NW.js object has the ability to read and write text files on disk. To support all possible languages, it always reads and writes with the UTF-8 encoding. To ensure the plugin reads your own text files correctly, ensure they are encoded as UTF-8.

NW.js conditions

On folder dialog OK
On folder dialog cancel
Triggered after the Show folder dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected folder after an OK.

On open dialog OK
On open dialog cancel
Triggered after the Show open dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected file to open after an OK.

On save dialog OK
On save dialog cancel
Triggered after the Show save dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected file to save after an OK.

On file dropped
Triggered after the user drag-and-drops a file in to the application window. The DroppedFile expression contains the path to the file that was dropped in, allowing you to load it to read its contents.

Path exists
Test if a given folder or file path exists on the user's system.

NW.js actions

Clear clipboard
Remove any thing cut or copied to the clipboard. The user will not be able to paste anything immediately after this action.

Set clipboard text
Set some text to be copied to the clipboard. This has the same effect as if the user had selected the text in a text box and selected 'Copy'. They can then paste the text in to any other application.

Show folder dialog
Open a dialog allowing the user to pick a folder on their local system. If the user selects OK, On folder dialog OK triggers and the ChosenPath expression contains the selected folder.

Show open dialog
Open a dialog allowing the user to choose a file to open on their local system. If the user selects OK, On open dialog OK triggers and the ChosenPath expression contains the selected file. The Accept parameter is a comma-separated list of file extensions or MIME types that the dialog can use to filter possible files. For example, ".txt,.json" will allow filtering by all .txt or .json files, and "text/*" will allow filtering by any file with a text MIME type.

Show save dialog
Open a dialog allowing the user to choose a file to save to on their local system. If the user selects OK, On save dialog OK triggers and the ChosenPath expression contains the selected file. The Accept parameter is a comma-separated list of file extensions or MIME types that the dialog can use to filter possible files. For example, ".txt,.json" will allow filtering by all .txt or .json files, and "text/*" will allow filtering by any file with a text MIME type.

Append file
Add some text to the end of the file. This is usually faster than writing the full file again with some new content at the end. Appending to files can be useful for logging.

Copy file
Make an identical binary copy of a file at a new location.

Create folder
Create a new folder on the user's local system.

Delete file
Delete a file from the user's local system. Be sure to use this carefully, since a mistake could mean deleting the wrong file.

List files
Read a list of every subfolder and file in a given folder. After this action the ListCount and ListAt expressions can be used to return the items in the list.

Move file
Make an identical binary copy of a file at a new location, then delete the old file. Note you should use the Rename file rather than the Move file action if you intend to move it to a new name in the same folder.

Open browser
Open the default browser on the system to a given URL.

Rename file
Set a new name for an existing file path.

Run file
Run the file at an existing file path. This is analogous to double-clicking the file in the OS file explorer. For executable programs, it will attempt to run the program; for other file types, it will open the default associated program, such as the system default image editor if an image file is given.

Write file
Write a text file to the user's local system. If the file does not exist, it is created. If the file already exists, its content is overwritten.

Maximize
Maximize the window on the user's desktop. It will take up most (but usually not all) of the display.

Minimize
Minimize the window to the operating system start bar or dock.

Request attention
Perform an operating-specific activity to show attention is required from the user, such as by flashing the title bar of the window.

Restore
Restore the window to show it again after minimizing.

Set always on top
Set whether the window always appears on top of other windows.

Set width
Set height
Set the dimensions of the window. Note this includes the window title bar and borders, so the actual displayed area of the game may be less than the window size you set.

Set maximum size
Set minimum size
Set the maximum and minimum sizes that the user can resize the window to.

Set resizable
Enable or disable resizing of the window.

Set title
Set the text that appears in the title bar or caption of the window.

Set X
Set Y
Set the position of the window on the user's desktop, in pixels relative to the top-left of the primary monitor.

Show dev tools
Since NW.js is based on Chromium, this action brings up the Chromium developer tools (such as Javascript debugger and console). This may be useful to inspect console messages or for developing plugins with the Javascript SDK.

Unmaximize
Undo a window maximize, restoring the window to its previous size.

NW.js expressions

ClipboardText
The current text that the user has copied to the clipboard, if any. This allows you to 'paste' the data automatically.

ChosenPath
Return the path that was selected after On folder dialog OK, On open dialog OK or On save dialog OK.

AppFolder
Return the path to the application's folder, including the trailing slash. Read permission can be expected, but write permission cannot be guaranteed (for example the Program Files folder on Windows requires administrator permission to write to).

DroppedFile
In On file dropped, the path to the file that was dropped in to the application's window.

FileSize(path)
Return the size of a given file, in bytes.

ListAt(index)
After the List files action, returns the file or folder name at the zero-based index in the list.

ListCount
After the List files action, returns the number of files or folders in the list.

ReadFile(path)
Open the given file and return its text content as a string. Note that each time this expression is used the file is opened and read from disk. Therefore if the expression is used twice, the file is opened and read twice, which can impact performance. If necessary first read the file to a variable, then reference the variable multiple times.

UserFolder
Return the path to the user folder, which is typically where the user's documents and other personal files are kept. Both read and write permissions can be expected.

WindowWidth
WindowHeight
Retrieve the current size of the window in pixels. Note this includes the window title bar and borders, so may be larger than the display area of the game.

WindowTitle
Get the current text showing in the window title bar or caption.

WindowX
WindowY
Get the current position of the window in pixels relative to the top-left point of the user's primary monitor.

Tags: