@nodert-win10-rs3/windows.ui.webui on NPM (2024)

💻 Example

npm install --save @nodert-win10-rs3/windows.ui.notifications

For an in-depth overview, check out our //build talk.

In general, any WinRT/UWP API that can be called by a desktop app can by called byNode.js or Electron using NodeRT. There are notable exceptions, but UWP APIsare generally callable from desktop applications.

For more examples of what NodeRT can do, check out the samples.

We've split the documentation up into two parts. If you want to use NodeRT modules,read on. If you want to use NodeRT to compile your own WinRT modules, seethe module creation guide.

• Using NodeRT modules
• Naming and Properties
• Namespaces
• Class inheritance and object casting
• Using WinRT streams in Node.js
• Building and Consuming in Electron
• License
• Attributions
• Contribute

NodeRT automatically exposes Microsoft’s UWP/WinRT APIs to the Node.js environmentby generating Node modules for all Windows namespaces. This enables Node.js developersto write code that consumes native Windows capabilities. The generated modules' APIsare (almost) the same as the WinRT APIs listed on MSDN.

As an example, let's check out the Windows.Devices.Geolocation namespace tolocate the user from Node.js.

1️⃣ First, ensure that you have the Windows 10 SDK installed. In this example,we're using the Fall Creators Update SDK.:two: Then, install @nodert-win10-rs3/windows.devices.geolocation. The npmorganization denotes the used SDK version - in this case, it's the Fall CreatorsUpdate, which has the codename "Redstone 3".

npm i --save @nodert-win10-rs3/windows.devices.geolocation

Once you've installed the module, you're ready to use your computer's geolocationfeatures. In this example, we're creating a new Geolocator and are callingits instance method getGeopositionAsync().

const { Geolocator } = require('windows.devices.geolocation')const locator = new Geolocator()locator.getGeopositionAsync((error, result) => { if (error) { console.error(error) return } const { coordinate } = result const { longitude, latitude } = coordinate console.info(longitude, latitude)})

Let's take a closer look at the whole module:

As you can see, you can create new WinRT objects using the new operator. Inorder to inspect the method and properties of the object, you can inspectit* prototype. For example, a new Geolocator object looks like this:

console.log(new geolocation.Geolocator().__proto__)

And the output will be:

📝 Note that property values are fetched on the fly, and hence have undefinedvalues when printing the prototype.

NodeRT uses the same JavaScript conventions as Microsoft does forJavaScript-based UWP applications.

• Class/Enum names have the first letter in upper-case
• Class/Enum fields (properties, methods, and events) always start with alower-case letter. The remainder of the name is identical to what you'dfind on MSDN.
• Enums are JavaScript objects with keys corresponding to the enumfields and values to the enum field's numeric values.

Properties on WinRT objects behave like JavaScript properties.

locator.reportInterval = 2000console.info(locator.reportInterval)

Straight-forward JavaScript: Make the call with the appropriate argumentsand don't even worry about the fact that you're calling native code. Ifthere are several WinRT overloads for the method, make the call with theright set of arguments and the correct overload of the method will becalled:

const { XmlDocument } = require('windows.data.xml.dom')const xmlDoc = new xml.XmlDocument();xmlDoc.loadXml('<node>some text here</node>')

Asynchronous method accepts the same variables as listed on MSDN - with theaddition of a completion callback as the last argument.

This callback will be called when the function has finished, and will receivean error as the first argument, and the result as the second argument:

locator.getGeopositionAsync((err, result) => { if (error) { console.error(error) return } // Result is of type "Geoposition" const { coordinate } = result const { longitude, latitude } = coordinate console.info(longitude, latitude)})

Registering to events is done using the class' on method (which is equivalentto addListener), which receives the event name (case insensitive) and theevent handler function.

For example:

const handler = (sender, eventArgs) => { console.info('status is:', eventArgs.status)}locator.on('statusChanged', handler)

Unregistering from an event is done the same way, using the class's off orremoveListener methods.

// Using same event handler as in the example abovelocator.off('statusChanged', handler);

Each NodeRT module represents a single namespace. For instance, windows.storageis its own NodeRT module - and windows.storage.streams is another NodeRT module.

The reason for this separation is strictly due to performance considerations.Separating the code allows you to load only the code you actually intend touse, meaning that Node.js won't fill the machine's memory.

This architecture means that in case you are using a NodeRT module whichcontains a function, property, or event which returns an object from anothernamespace, then you will need to require that namespace before callingthat function/property/event.

For example:

const capture = require('windows.media.capture')// We also require this module in order to be able to access// device controller propertiesconst devices = require('windows.media.devices')const capture = new capture.MediaCapture()capture.initializeAsync((error, result) => { if (error) { return console.error(error); } // Get the device controller, its type (VideoDeviceController) is defined in // the windows.media.devices namespace. That's why we had to load // windows.media.devices before calling this method. const deviceController = capture.videoDeviceController // We can now use the VideoDeviceController regularly deviceController.brightness.trySetValue(-1)})

Since some WinRT classes inherit from other classes. You might also need to cast anobject of a certain type to another type.

In order to do so, each NodeRT object has a static method named castFromwhich accepts another object and tries to cast it to the class' type. Magical, right?

The following example casts an IXmlNode object to anXmlElement:

const xml = require('windows.data.xml.dom')...// Obtain a list of nodes:const nodesList = ....const xmlNode = nodesList.getAt(0)// Cast xmlNode to XmlElementconst xmlElement = xml.XmlElement.castFrom(xmlNode)// We can now use XmlElement functionsxmlElement.setAttribute('attr', 'value')

In order to support the use of WinRT streams in Node.js, we have created thenodert-streams module, which bridges between WinRT streams andNode.js streams.

This bridge enable the conversion of WinRT streams to Node.js streams, suchthat WinRT streams could be used just as regular Node.js streams.

NodeRT modules are native Node addons. As such, you'll need to compilethem for usage with Electron. If you're using an Electron boilerplateor CLI (like electron-forge or electron-builder), the embedded toolswill automatically compile the native code correctly.

If you are not using a boilerplate or are having trouble correctly compilingNodeRT modules, see Electron's documentation for how to use native Node addonsin Electron.

From Electron v14 on, you'll have to require NodeRT modules in the main process.See #158 for details.

NodeRT is released under the Apache 2.0 license.For more information, please take a look at the license file.

In order to build NodeRT we used these 2 great libraries:

• RazorTemplates - https://github.com/volkovku/RazorTemplates
• RX.NET - https://github.com/Reactive-Extensions/Rx.NET/

You are welcome to send us any bugs you may find, suggestions, or any othercomments. Before sending anything, please go over the repository issues list,just to make sure that it isn't already there.

You are more than welcome to fork this repository and send us a pull requestif you feel that what you've done should be included.