Always on Top Mode
Relevant source files
The following files were used as context for generating this wiki page:
The Always on Top Mode is a desktop-specific feature in Messenger Unleashed that allows the application window to stay floating above all other open windows on the operating system. This feature is designed for power users who need to keep their conversations within reach while multi-tasking across different applications.
Sources: landing-page/src/app/HomeClient.tsx:313, src/main/index.ts:1330
Architecture and Logic
The "Always on Top" functionality is implemented using Electron's native BrowserWindow API. The state of the feature is persisted using electron-store, ensuring that the user's preference survives application restarts. The logic is primarily split between the Main process (handling window state and menu updates) and the Preload/Renderer layers (providing the UI for toggling).
Sources: CLAUDE.md:27-33, src/main/index.ts:752-757
Control Flow and State Management
The feature follows a standard toggle pattern used throughout the application. When a user interacts with the UI or a global shortcut, the toggleAlwaysOnTop() function is executed in the Main process.
The diagram shows how user interactions from various sources trigger the toggle logic, which subsequently updates persistence and the native window state.
Sources: src/main/index.ts:752-757, src/preload/settings-modal.ts:241-244
Implementation Details
Main Process Integration
In src/main/index.ts, the application window is initialized with the alwaysOnTop value retrieved from the store. The toggleAlwaysOnTop function directly interfaces with the Electron BrowserWindow instance.
| Function/Element | Description | Source |
|---|---|---|
toggleAlwaysOnTop() | Toggles the boolean state in the store and applies it to the mainWindow. | src/main/index.ts:752 |
mainWindow.setAlwaysOnTop() | The native Electron method used to change window level. | src/main/index.ts:756 |
store.get("alwaysOnTop") | Retrieves the persistent configuration. | src/main/index.ts:753 |
updateMenu() | Rebuilds the native menu to reflect the checked/unchecked state. | src/main/index.ts:757 |
Settings UI and Preload Bridge
The feature is exposed to the user through a dedicated "System & Tools" section in the settings modal. This modal is constructed in the preload environment and communicates with the Main process via IPC (Inter-Process Communication).
The sequence diagram illustrates the communication flow when the feature is toggled from the settings interface.
Sources: src/preload/settings-modal.ts:241-244, src/main/index.ts:1330-1335
Global Shortcuts
For faster access, the feature can be bound to a global keyboard shortcut. By default, the shortcut CmdOrCtrl+Shift+T is used to toggle the window's "Always on Top" status regardless of whether the app is currently focused.
Sources: src/main/index.ts:1330, src/main/index.ts:1614
Configuration Summary
The following table outlines the configuration properties related to the Always on Top mode found in the application state.
| Setting Key | Type | Default Source | Description |
|---|---|---|---|
alwaysOnTop | Boolean | src/main/state.ts | Determines if the window stays above others. |
toggleAlwaysOnTop (Shortcut) | String | src/main/index.ts | The accelerator key string for global toggle. |
Sources: src/main/index.ts:1330, src/preload/settings-modal.ts:400
Conclusion
Always on Top Mode is a core utility of the Messenger Unleashed desktop experience, leveraging native Electron capabilities to provide persistent window layering control. It is integrated deeply into the application's menu system, settings UI, and global shortcut handler to ensure maximum accessibility for the user.