Construct 3 icon

Construct 3

Documentation

NW.js

Published 24 Aug, 2017
1,742 words
~7-12 mins

The NW.js object allows access to features specific to the NW.js exporter Paid plans only, 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.

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. Typically this is used for executable programs. To open a different kind of file, use the Shell open action.

Shell open

Open a file with the system default application. (The name "Shell" means the operating system user interface, which handles the default applications.) For example using Shell open on a .pdf file will open the default PDF viewer on the system to view that file.

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

AppFolderURL

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.

ProjectFilesFolder

ProjectFilesFolderURL

Return the path to the folder containing project files, including the trailing slash. This is useful for accessing any additional files imported to the project. 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).

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.