@nativescript/windows-napi 1.0.0-beta.23 → 1.0.0-beta.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -42,6 +42,77 @@ The host executable's manifest must declare `<maxversiontested Id="10.0.18362.0"
42
42
  `electron.exe` does and `node.exe` doesn't, so `XamlWindow` throws in plain Node. XAML events run
43
43
  from the host's message loop, so a host with its own UI loop needs no `pumpMessages`.
44
44
 
45
+ ## Win32
46
+
47
+ `win32` calls exported functions of any DLL:
48
+
49
+ ```js
50
+ const { win32 } = require('@nativescript/windows-napi');
51
+
52
+ win32.call('user32.dll', 'MessageBeep', 'bool', { type: 'u32', value: 0 });
53
+
54
+ const { lstrlenW } = win32.bind('kernel32.dll'); // arguments typed from their JS values
55
+ lstrlenW('hello'); // 5
56
+
57
+ const user32 = win32.define('user32.dll', {
58
+ GetSystemMetrics: ['i32'], // argument types; returns the default (i32)
59
+ IsWindow: { args: ['pointer'], ret: 'bool' },
60
+ });
61
+ ```
62
+
63
+ - Types: `void`, `bool`, `i8`–`i64`, `u8`–`u64`, `f32`, `f64`, `pointer`, `wstr` (UTF-16 string),
64
+ `str` (UTF-8 string). 64-bit values beyond 2^53 come back as `BigInt`; arguments take numbers or
65
+ `BigInt`s.
66
+ - A `pointer` argument also takes an `ArrayBuffer`, a typed array or `DataView` (its memory, for
67
+ structs and out-parameters) or a pointer object. `null` is a null pointer, also for strings.
68
+ - `win32.import(dll)` installs every export of the DLL as a global function.
69
+ - `define` and `bind` resolve a function once and call it through the platform's argument
70
+ registers; `bind` locks a function's argument types in from its first call. `call` parses the
71
+ signature on every call: use it for one-offs.
72
+
73
+ ### Callbacks and window messages
74
+
75
+ `win32.callback(retType, argTypes, fn)` returns `{ pointer, release() }`: a native function
76
+ pointer that calls `fn` synchronously, for APIs that take one (`EnumWindows`, a `WNDPROC`). Keep it
77
+ until native code no longer uses it, then `release()` it.
78
+
79
+ `win32.messageWindow(listener)` returns `{ hwnd, close() }`, a hidden window whose messages are
80
+ delivered to `listener(msg, wParam, lParam)`. Use it as the window of a tray icon (its callback
81
+ message), `RegisterHotKey` (`WM_HOTKEY`) or a popup menu (`WM_COMMAND`). It is a top-level window,
82
+ so it also receives broadcasts such as `TaskbarCreated`.
83
+
84
+ ```js
85
+ const shell32 = win32.define('shell32.dll', { Shell_NotifyIconW: { args: ['u32', 'pointer'], ret: 'bool' } });
86
+ const user32 = win32.define('user32.dll', {
87
+ LoadIconW: { args: ['pointer', 'pointer'], ret: 'pointer' },
88
+ RegisterHotKey: { args: ['pointer', 'i32', 'u32', 'u32'], ret: 'bool' },
89
+ });
90
+
91
+ const WM_TRAY = 0x8001; // WM_APP + 1
92
+ const WM_HOTKEY = 0x0312, WM_LBUTTONUP = 0x0202;
93
+
94
+ const window = win32.messageWindow((msg, wParam, lParam) => {
95
+ if (msg === WM_TRAY && lParam === WM_LBUTTONUP) console.log('tray icon clicked');
96
+ if (msg === WM_HOTKEY && wParam === 1) console.log('Ctrl+Alt+S');
97
+ });
98
+
99
+ // NOTIFYICONDATAW, 64-bit layout
100
+ const nid = new DataView(new ArrayBuffer(976));
101
+ nid.setUint32(0, 976, true); // cbSize
102
+ nid.setBigUint64(8, BigInt(window.hwnd), true); // hWnd
103
+ nid.setUint32(16, 1, true); // uID
104
+ nid.setUint32(20, 0x1 | 0x2 | 0x4, true); // NIF_MESSAGE | NIF_ICON | NIF_TIP
105
+ nid.setUint32(24, WM_TRAY, true); // uCallbackMessage
106
+ nid.setBigUint64(32, BigInt(user32.LoadIconW(null, 32512)), true); // hIcon: IDI_APPLICATION
107
+ [...'My app'].forEach((c, i) => nid.setUint16(40 + i * 2, c.charCodeAt(0), true)); // szTip
108
+ shell32.Shell_NotifyIconW(0, nid); // NIM_ADD
109
+
110
+ user32.RegisterHotKey(window.hwnd, 1, 0x2 | 0x1 | 0x4000, 0x53); // Ctrl+Alt+S, MOD_NOREPEAT
111
+ ```
112
+
113
+ Messages arrive while the thread pumps them: Electron's main process does; in plain Node call
114
+ `enableAutoPump()`. In the standalone runtimes an open message window keeps the event loop running.
115
+
45
116
  ## Embedding outside Node
46
117
 
47
118
  Any host that provides Node-API can load the addon: load the `.node` file as a DLL and call its
package/index.d.ts CHANGED
@@ -154,3 +154,5 @@ export declare function installInterop(): void
154
154
  * `dotnet-bridge/publish/DotNetBridge.dll` exists next to the app.
155
155
  */
156
156
  export declare function installDotnet(): void
157
+ /** Installs `NSWinRT.win32`. Idempotent. */
158
+ export declare function installWin32(): void
package/index.js CHANGED
@@ -310,7 +310,7 @@ if (!nativeBinding) {
310
310
  throw new Error(`Failed to load native binding`)
311
311
  }
312
312
 
313
- const { formatValue, tableFor, makeDelegate, invokeDelegate, releaseDelegate, callStaticMethod, callInstanceMethod, makeNativeProxy, ffiRoundtrip, pointerValue, makeExternal, bufferInfo, structPtr, writeReadPtr, outParamValue, setOutParam, structFieldBytes, boxTyped, pumpMessages, lastError, installGlobals, getNamespace, nsUuid, createWindow, attachCompositorToWindow, pollWindowEvents, getWindowSize, setWindowTitle, xamlHostCreate, xamlHostSetListener, xamlHostPlace, xamlHostShow, xamlHostHide, xamlHostIsVisible, xamlHostDestroy, foregroundWindow, activateWindow, enableWindow, windowProcessId, classIsSealed, registerWinmd, scanWinmdDir, arrayBufferFromBuffer, installInterop, installDotnet } = nativeBinding
313
+ const { formatValue, tableFor, makeDelegate, invokeDelegate, releaseDelegate, callStaticMethod, callInstanceMethod, makeNativeProxy, ffiRoundtrip, pointerValue, makeExternal, bufferInfo, structPtr, writeReadPtr, outParamValue, setOutParam, structFieldBytes, boxTyped, pumpMessages, lastError, installGlobals, getNamespace, nsUuid, createWindow, attachCompositorToWindow, pollWindowEvents, getWindowSize, setWindowTitle, xamlHostCreate, xamlHostSetListener, xamlHostPlace, xamlHostShow, xamlHostHide, xamlHostIsVisible, xamlHostDestroy, foregroundWindow, activateWindow, enableWindow, windowProcessId, classIsSealed, registerWinmd, scanWinmdDir, arrayBufferFromBuffer, installInterop, installDotnet, installWin32 } = nativeBinding
314
314
 
315
315
  module.exports.formatValue = formatValue
316
316
  module.exports.tableFor = tableFor
@@ -357,3 +357,4 @@ module.exports.scanWinmdDir = scanWinmdDir
357
357
  module.exports.arrayBufferFromBuffer = arrayBufferFromBuffer
358
358
  module.exports.installInterop = installInterop
359
359
  module.exports.installDotnet = installDotnet
360
+ module.exports.installWin32 = installWin32
package/nswinrt.js CHANGED
@@ -113,6 +113,9 @@ const interop = globalThis.NSWinRT.interop;
113
113
  native.installDotnet();
114
114
  const dotnet = globalThis.NSWinRT.dotnet;
115
115
 
116
+ native.installWin32();
117
+ const win32 = globalThis.NSWinRT.win32;
118
+
116
119
  // Windows.UI.Xaml content in a Win32 window (XAML Islands). Needs a thread that pumps messages.
117
120
  let xamlManager = null;
118
121
 
@@ -213,5 +216,6 @@ module.exports = {
213
216
  disableAutoPump,
214
217
  interop,
215
218
  dotnet,
219
+ win32,
216
220
  XamlWindow,
217
221
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nativescript/windows-napi",
3
- "version": "1.0.0-beta.23",
3
+ "version": "1.0.0-beta.25",
4
4
  "description": "Node-API WinRT interop for Windows.",
5
5
  "main": "nswinrt.js",
6
6
  "types": "index.d.ts",
Binary file
Binary file