Windows
React Native has no API for any of this: on a phone there is one window, it is the screen, and nothing an app says would change it. On a desktop the window is the first thing an app wants after it has drawn something.
import {
useWindow,
windowControl,
useCloseRequest,
useQuitRequest,
quit,
Window,
useDisplays,
} from 'basalt-core';useWindow()
const window = useWindow();
window.setSize(900, 700);
window.center();
window.setFullScreen(true);
window.toggleMaximize();
const {width, height, x, y, fullScreen, maximized} = window.bounds;setSize(width, height) | a request; a tiling window manager may ignore it |
setPosition(x, y) | |
center() | |
setFullScreen(on?) | defaults to true |
minimize() | |
toggleMaximize() | |
close() | asks, so a close handler still gets to refuse |
setMinimumSize(width, height) | the app's own window's; see the note below |
setMaximumSize(width, height) | 0 in either direction clears that limit |
setResizable(on?) | defaults to true |
setAlwaysOnTop(on?) | defaults to false |
bounds | live; see below |
capabilities | what this desktop will actually do |
bounds is live
It re-renders when the window moves, is resized, or changes state, because the
alternative, a getBounds() an app calls and caches, is an app whose layout is
right until somebody drags a corner.
Reading it before there is a window gives zeroes rather than null, so
const {width} = window.bounds never throws during a first render. And because
setSize is a request rather than an instruction, bounds is what reports
what happened rather than what was asked for.
capabilities
const {position, minimumSize, maximumSize, resizable, alwaysOnTop} =
useWindow().capabilities;All five are true on macOS and Windows. On Linux, minimumSize and resizable
are, and the other three are not: GTK4 removed gtk_window_move,
gtk_window_set_geometry_hints and gtk_window_set_keep_above because Wayland
has no protocol a client can use for any of them. A client has no idea where its
window is and no say in it.
So this is settled rather than pending, and it is a value rather than a
paragraph: an app can put its "always on top" switch away on the desktop that
has no such thing, which is better than a switch that lies. bounds.x and
bounds.y are always zero on Linux for the same reason, and both display
servers centre an unplaced window by default, so an app that never moves its
window already gets what center() would have asked for.
The five are read once. They are booleans a platform knows at compile time, not a question for the window manager.
windowControl
The same calls, usable outside a component: windowControl.setSize(...),
windowControl.close(), windowControl.getBounds(),
windowControl.getCapabilities(). useWindow() is this object plus the live
bounds, so the two cannot disagree.
useCloseRequest()
useCloseRequest(close => (unsaved ? setAsking(true) : close()));A window with a close handler stops closing on its own. Every attempt, its close
button, Cmd-W, Alt+F4, the window manager, is refused and reported, and the
window goes when the app says so by calling the close it was handed. Which is
the point: there is nowhere else to put "are you sure".
Pass null or nothing to stop being asked, which is also what unmounting does.
The decision has to exist before the attempt, which is why this is a
registration rather than a handler that returns false: the system wants a
synchronous yes or no and the handler is JavaScript on another thread.
On macOS this covers closing the window and not Cmd-Q, which terminates the
application without asking any window whether it minds. That is
useQuitRequest.
useQuitRequest()
useQuitRequest(allow => (unsaved ? setAsking(true) : allow()));
// later, when the person said yes
quit();The same mechanism one level up, and it exists because the window half is not enough: an app can guard every window it owns and still lose the person's work to Cmd-Q.
Quitting is one event no matter how many windows are open, so the handler takes no window id. Register it once, near the top of the app. An app that registers from two components gets asked twice, which is harmless and is not the intended shape.
What each desktop means by quitting differs, and usefully so. On macOS this is
Cmd-Q, the Quit menu item, and logging out. On Windows and Linux there is no
application-level quit gesture to intercept, because an app ends when its last
window closes, which is useCloseRequest's business. What this catches there is
the session ending: logout, shutdown, reboot.
<Window>, a second window
<Window title="Preview" width={600} height={400} onClose={hide}>
<Preview id={id} />
</Window>Mount it and a window opens; unmount it and the window closes.
| prop | |
|---|---|
title | |
width, height | |
onClose | the person closed it; see below |
onCloseRequest | the person is trying to; refuses and reports, like useCloseRequest |
A window is a React root
That is Fabric's grain rather than a decision Basalt made. A surface is what has
a size, a layout context and a root shadow node, and two windows sharing one
would be two windows sharing a layout. So a second window runs a second React
tree, and <Window>'s children are rendered there rather than where they were
written.
Which has a consequence worth stating plainly, because it is the one thing that
surprises people: the children do not see React context from the tree they
were written in. A theme provider, a navigation container or a Redux store
wrapping the <Window> is not wrapping its children.
What does cross is props. The elements themselves are passed through, so anything captured in a closure or given as a prop arrives intact, including state and callbacks:
const [count, setCount] = useState(0);
<Window>
<Text onPress={() => setCount(count + 1)}>{count}</Text>
</Window>works, and re-renders the window when count changes. A useContext inside
<Preview> does not. An app that needs context in a window should pass the
value as a prop and re-provide it inside.
onClose and onCloseRequest
onClose means the person closed the window, through its own close button or
the window manager, and not that the app unmounted the <Window>. An app that
unmounted it already knows. It is the half that keeps the two sides agreeing:
without it an app's open flag would stay true after the window had gone, the
next render would try to close a window that closed itself, and the window could
never be reopened.
onCloseRequest is the earlier half. Somebody is trying to close the window and
it has not closed:
<Window onCloseRequest={close => (dirty ? ask() : close())}>There are two ways to then say yes, and they are not the same one written twice.
Unmounting the <Window> is the React-shaped one and usually right: the window
is a render of some state, and agreeing to close it is that state changing. The
close the handler is handed is the other, for when the app has no such state
to change, and it closes the window without calling onClose, because an app
that just said yes is not waiting to be told.
useWindow() inside a <Window> means that window. Its bounds are that
window's, setSize resizes it, and it does not re-render when another window
moves. Outside any <Window>, and from windowControl, it means the window
the app started in.
Two calls are still the app's own window's whoever asks: minimize() and
toggleMaximize(), and the size limits. close() is not: a second window
closes itself.
useDisplays()
What screens the desktop has, where they are, and how dense they are. React
Native's Dimensions reports the window, which is the right answer to a
different question: an app placing a window, or deciding how much it can show,
is asking about the screen it is on and the ones beside it.
const screens = useDisplays();
// or, outside a component
import {displays, primaryDisplay, pointerPosition} from 'basalt-core';| field | |
|---|---|
x, y, width, height | the screen, in layout units |
workX, workY, workWidth, workHeight | what is left after a menu bar, taskbar or dock |
scaleFactor | |
primary |
primaryDisplay() is the one with primary set, or null. pointerPosition()
resolves to {x, y, known}.
Bounds and scale factor come from all three desktops. The work area comes from macOS and Windows, and GTK4 reports the full bounds instead; the pointer's position comes from macOS and Windows and never from GTK.
None of those are gaps waiting to be filled.
gdk_monitor_get_workarea, gdk_display_get_primary_monitor and reading the
pointer were all in GTK 3 and were removed, because Wayland has no protocol a
client can use for any of them. So an app that needs the work area should treat
"equal to bounds" as the answer rather than as a failure, and one that needs the
pointer should check known.