Python API

Import the Python API as

import pynwjs

and use the offered functions to interact with your NWJS app as described in the following.

pynwjs.open(app_root)

Open the specified NWJS app. Only one application can run at the same time.

Parameters:app_root (str) – File path to the root folder of the app, i.e., the folder which contains the package.json.

Note

It is highly recommended to only use this method in combination with a with context, see example below. This reduces the risk for runtime errors and ensures that the app is closed when the Python program exits.

Example

Open the GUI and interact with it inside a with context:

# open your the NWJS app by providing the path to its root folder
with pynwjs.open('path/to/my_app'):
    # do stuff, for example:
    pynwjs.emit('hello', 'Hello JavaScript World!')
# when leaving this context, the app will be closed

The app is only left open while inside the context. Also, the context will be left immediately whenever the user closes the app manually.

pynwjs.wait()

Wait for the NWJS app to be closed manually. This blocks any further execution in the main thread, but still processes callbacks.

pynwjs.close()

Close the currently opened NWJS app explicitly. Calling this method is only required when not using the with context. However, it can still be used to force closing of the app at any point and leave the context.

Decorators

The decorators enable a declarative style of NWJS integration that is well-suited for separating NWJS from program logic.

pynwjs.callback(event)

Decorator to identify a function as callback for the specified event.

Parameters:event (str) – Name of the custom event.

Example

Assume that we want to define an event called 'print' and implement a Python callback for it to print text to the terminal.

@pynwjs.callback('print')
def some_callback_function(text):
    print(text)

Each callback should accept one argument to receive data about the event. In this case, we consider it as the text to be printed.

To trigger the event from NWJS, emit it in JavaScript as follows.

pynwjs.emit("print", "Hello from nwjs");

pynwjs.event_listener(id, event)

Decorator to identify a function as event listener. This is a special type of callback for built-in HTML events.

Parameters:

• id (str) – ID assigned to the HTML element associated with the event.
• event (str) – Name of the HTML event.

Note

In order for events to be forwarded to Python, they need to be registered in JavaScript (see example).

Example

Assume that we want to implement a Python callback that is triggered when clicking some button with the ID 'my_button'.

In JavaScript, register the event handler for the button:

document.getElementById('my_button').addEventListener('click', pynwjs.eventHandler);

Then, in Python, implement and decorate the callback:

@pynwjs.event_listener('my_button', 'click')
def some_callback_function(data):
    print('my_button has been clicked!')

Each callback should accept one argument to receive data about the event.

pynwjs.emit_result(event)

Decorator to let a function emit an event as a side-effect whenever it returns a value. The return value is sent as data of the event.

Parameters:event (str) – Name of the custom event.

Note

This will not emit an event whenever the function returns None or no NWJS app is open.

Example

Assume that we want to display the return value of the following function in an HTML element of the GUI.

@pynwjs.emit_result('show_result')
def some_function():
    return 'this text is my result'

In JavaScript, we can now implement the desired reaction to the event:

pynwjs.on('show_result', text => {
    var element = document.getElementById('my_text_display');
    element.innerText = 'Python function returned: ' + text;
});

Functions

Interaction with NWJS can also be done in a classical programmatic way by using the following functions.

pynwjs.on(event, callback)

Dynamically connect a callback for the specified event. Each event can have multiple callbacks.

Parameters:

• event (str) – Name of the custom event.
• callback (function) – Callback that is triggered. Should accept one argument which will contain the event data.

pynwjs.add_event_listener(id, event, callback)

Dynamically add an event listener for the specified HTML event.

Parameters:

• id (str) – ID assigned to the HTML element associated with the event.
• event (str) – Name of the HTML event.
• callback (function) – Callback that is triggered. Should accept one argument which will contain the event data.

Note

In order for events to be forwarded to Python, they need to be registered in JavaScript (see example).

Example

Assume that we want to implement a Python callback that is triggered when clicking some button with the ID 'my_button'.

In JavaScript, register the event handler for the button:

document.getElementById('my_button').addEventListener('click', pynwjs.eventHandler);

Then, in Python, add the event listener:

pynwjs.add_event_listener('my_button', 'click', some_callback_function)

Each callback should accept one argument to receive data about the event.

pynwjs.emit(event, data=None)

Instantly emit an event with the given data. If no data is given, this instead creates a function to emit the event later.

Parameters:

• event (str) – Name of the custom event.
• data (object) – Any event data to be sent to NWJS. The data will be serialized as JSON object. This argument is optional, see the example for what happens without it.

Example

The following code illustrates different examples how this function can be used.

# emit the given data dictionary
pynwjs.emit('my_event', {'purpose': 'example', 'message': 'Hello World!'})

# always trigger 'pong' when receiving 'ping'
pynwjs.on('ping', pynwjs.emit('pong'))

# use pynwjs.emit as callback in any other context
my_callback = pynwjs.emit('my_event')
# for illustration, let's invoke it directly
my_callback(some_data)

pynwjs.clear(event=None)

Clear all callbacks of the given event.

Parameters:event (str) – Name of the custom event. If not set, clear all events (including those of decorators).