| Support the Project! |
|---|
| This project is open-source and free to use, both commercially and non-commercially, which is why we need your help in its development. If you like it, please give it a star ⭐ on GitHub — it helps others discover the project and increases its visibility. You can also contribute, for example, by fixing bugs 🐛 or suggesting improvements 💡, see Contributing. If you can, financial support 💰 is always appreciated, see Support Us. |
- Overview
- Demo
- Features
- Requirements
- Dependencies
- Usage
- Code building
- Running Demo
- License
- Contributing
- 👉 Support Us
Techsenger TabShell is a lightweight platform for building tab-based applications in JavaFX using the MVVM pattern.
The platform consists of two parts: TabShell and TabShell Kit. TabShell contains the core shell and classes for creating components. TabShell Kit includes pre-built components. Using TabShell Kit is optional.
Key features of TabShell include:
- Abstract classes to simplify component development.
- Dynamically configurable menu.
- Ability to preserve component history.
- Support for dialogs with two scopes — shell and tab.
- Window styling that matches the theme.
- Support for 7 themes (4 dark and 3 light).
- Styling with CSS.
Currently, TabShell Kit includes:
- Terminal.
- Text Viewer/Editor.
- Dialogs.
The library requires Java 17 or later. Due to some bugs, use JavaFX versions 19–20, or a version of JavaFX after 24-ea+19 (see JDK-8344372).
This project will be available on Maven Central in a few weeks.
To get started with TabShell, it is recommended to follow these steps:
- Familiarize yourself with the mvvm4fx framework and its sampler.
- Explore and run tabshell-demo. See TabShell Demo for details.
- Explore and run tabshell-kit-demo. See TabShell Kit Demo for details.
The component is the main building block for creating an application using this platform. There are the following types of components:
- TabShell component.
- Tab component.
- Dialog component.
- Page component, which represents a titled component that can be selected.
- Pane component, which represents a rectangular area.
- Node component, which is used for the simplest and smallest elements.
TabShell is the main component and it is responsible for the following tasks:
- Window management.
- Dynamic menu management.
- Shell tab management.
- Shell-scoped dialog management.
- Theme management.
TabShell core doesn't have any business logic. It is only a shell for tabs that contain logic.
Working with the main menu of the TabShell is carried out in two directions:
- Configuring menu elements
- Managing the state of elements and responding to user actions
The configuration of menu elements is performed dynamically and in any order, with the final result being unknown in advance. This feature is crucial in cases where plugins/extensions are used, as they can be added/removed dynamically by the user. Each plugin may introduce its own menu items and interact with existing menus. Therefore, it is impossible to predict the final structure of the menu that the user will work with.
The implementation of this feature is structured as follows. There are three key elements: the menu, the group, and the
item. Each element has its own key, which is used for identification. A menu consists of groups separated by a
separator. Items are added to groups, and empty groups are ignored. All three elements are registered/unregistered in
the ControlRegistry. When the menu needs to be updated, this ControlRegistry is passed to TabShell, which then
constructs the final menu.
The MenuManager is responsible for managing the state of menu elements and responding to their actions. It interacts
with a component that implements the MenuAware interface. This interface is always implemented by both TabShell and
ShellTab. If all tabs are closed, MenuManager interacts with TabShell. When tabs are present, MenuManager
interacts with the currently selected tab.
It is also important to remember that the MenuManager also interacts with MenuAware when the user uses accelerators.
To gain a complete understanding of working with the menu, it is recommended to familiarize yourself with the
MenuAware interface, experiment with the menu in the demo, and pay attention to log messages at the debug level.
There are two types of tabs: ShellTab and Tab. A ShellTab component can be opened through the TabShell, so
ShellTab components are second-level components under the TabShell. ShellTab manages tab-scoped dialogs.
A Tab component cannot be opened directly through the TabShell, so it always resides inside a ShellTab.
All dialogs in TabShell have a scope that affects what will be blocked when the dialog is open. There are two types of
scope: Shell and Tab. If a dialog has a Shell scope, the user will not be able to do anything in TabShell
while this dialog is displayed until it is closed. If a dialog has a Tab scope, only the tab that triggered the
dialog will be blocked when it is displayed. All other tabs, the main menu, etc., will be available to the user.
Dialogs are invoked from the ViewModel using ComponentHelper.
To build the library use standard Git and Maven commands:
git clone https://github.com/techsenger/tabshell
cd tabshell
mvn clean install
The project includes two demo modules - tabshell-demo, tabshell-kit-demo.
To run the demo, execute the following commands in the project root:
cd tabshell-demo
mvn javafx:run
Please note, that debugger settings are in pom.xml file.
To run the demo, execute the following commands in the project root:
cd tabshell-kit/tabshell-kit-demo
mvn javafx:run
Please note, that debugger settings are in pom.xml file.
Techsenger TabShell is licensed under the Apache License, Version 2.0.
We welcome all contributions. You can help by reporting bugs, suggesting improvements, or submitting pull requests with fixes and new features. If you have any questions, feel free to reach out — we’ll be happy to assist you.
You can support us financially through GitHub Sponsors. Your contribution directly helps us keep our open-source projects active, improve their features, and offer ongoing support. Besides, we offer multiple sponsorship tiers, with different rewards.