DOCSEARCHbyAlgolia
Submit Docs

AtlantaFX Documentation

repository·master·Indexed 23 days ago

https://github.com/mkpaz/atlantafx

A modern JavaFX CSS theme collection providing a flat interface inspired by web component frameworks. Built with modular SASS, it supports multiple themes including Primer (Light/Dark) and Nord. The library offers a customizable color system based on GitHub Primer guidelines, additional custom controls, and integration options for Maven, Gradle, and SceneBuilder.

Tokens
6.5K
Snippets
20
Records
45
Agent score
72%

What's inside AtlantaFX

  1. Overview of AtlantaFX

    master

    AtlantaFX is a modern JavaFX CSS theme collection designed to provide a flat interface inspired by web component frameworks. It is built with a 'CSS first' approach, meaning it works with existing standard JavaFX controls while providing additional custom controls for modern GUI development.

    Key features include:

    • Customizable Color System: Uses a simple and intuitive color system based on GitHub Primer guidelines. You can easily change the global accent (brand) color or individual control styles using looked-up color variables.
    • SASS-based Architecture: The themes are written in modular SASS, making them easier to maintain and customize compared to massive monolithic CSS files.
    • Theme Support: Supports multiple themes including Primer (Light/Dark), Nord (Light/Dark), Cupertino (Light/Dark), and Dracula.
    • Extensibility: Supports custom themes via SASS compilation.

  2. Use Spins skins for the Spin control

    master

    The Spins module provides a collection of skins for the atlantafx.base.controls.Spin control. Each skin is self-contained, meaning you can copy and paste a single skin directly into your project if you do not want to include the entire module.

    To use these skins, you must include the atlantafx-styles module, which contains the necessary CSS styling.

  3. Understand Color Scales and when to use them

    master

    Color scales consist of 10 shades (0 to 9) for various color families.

    Warning: Avoid referencing scale variables directly when building standard UI. Scale variables are primarily intended for theme developers to replace dynamic brightness calculation functions. Using functional variables (like -color-fg-default) ensures your UI maintains correct contrast across all themes. Only use scale variables if you need to define custom functional variables for your specific application.

    Available scales:

    • -color-dark
    • -color-light
    • -color-base-[0-9]
    • -color-accent-[0-9]
    • -color-success-[0-9]
    • -color-warning-[0-9]
    • -color-danger-[0-9]

  4. How looked-up colors work in AtlantaFX

    master

    AtlantaFX uses looked-up colors, which are essentially CSS variables prefixed with -color-*. These colors are resolved according to standard CSS specificity rules starting from the Scene root.

    There are two types of looked-up colors:

    1. Global colors: Defined at the Scene root level.
    2. Individual control colors: Specific to certain UI components (refer to the component's documentation for details).

    Because they follow CSS specificity, you can override colors for specific branches of your UI hierarchy by applying styles to parent containers. For example, setting -color-background on a specific Region will affect that region and all its descendants unless they define their own -color-background value.

  5. Use Functional Colors for UI development

    master

    AtlantaFX provides functional color variables defined at the Scene root level. These variables are designed to maintain optimal contrast across different themes. You should use these functional variables instead of direct color scale references when building UI components to ensure your application adapts correctly to theme changes.

    Functional colors are categorized into Foreground, Background, Border, and Accent colors.

  6. Understand AtlantaFX typography and font constraints

    master

    AtlantaFX does not bundle specific font files; it relies on the operating system's default font family.

    Important Constraints:

    • Default Font Size: The library is designed around a default font size of 14px (~= 11pt). While you can change this, all stylesheets are tested only with the default size. Changing the base font size may cause some UI controls to break or render incorrectly.
    • Font Weight Limitations: JavaFX only supports bold or regular font weights. While the CSS parser may recognize other weight values, they will be automatically reduced to one of these two supported states.

  7. Modify theme variables in SASS

    master

    AtlantaFX themes use SASS modules. Variables marked with !default in the source files can be overridden during compilation.

    Important: Customization Order Matters. SASS loads modules only once. If module A imports B, and B imports C, you must override C's variables first, then B, then A. If you attempt to change a variable in a module that has already been loaded, an exception will occur.

    Example of correct override pattern:

    // 1. Color customization (lowest level)
@forward "relative/path/to/settings/color-vars" with (
    // ...
);

// 2. Shared property customization
@forward "relative/path/to/settings/config" with (
    // ...
);

// 3. General styles (must precede component styles)
@use "general";

// 4. Individual component property customization
// Use 'as name-*' to prevent namespace conflicts
@forward "relative/path/to/components/split-pane" as split-pane-*  with (
    // ...
);
    @forward "relative/path/to/settings/color-vars" with (
    //   ...
);

@forward "relative/path/to/settings/config" with (
    //   ...
);

@use "general";

@forward "relative/path/to/components/split-pane" as split-pane-*  with (
    //   ...
);

  9. Test custom themes using the Sampler app

    master

    The Sampler app is a tool for developing and testing custom themes with hot reload support.

    1. Run Sampler in development mode: If you are using a packaged version of the Sampler app, set the ATLANTAFX_MODE environment variable to dev.
      export ATLANTAFX_MODE=dev
    2. Load your CSS: Navigate to the Theme page within the Sampler app and add your compiled CSS file to see the changes applied live.
    ATLANTAFX_MODE=dev

  10. Build individual Maven modules

    master

    You can build specific modules of the project individually using the following commands:

    • Build the whole project structure (non-recursive): mvn install -N
    • Build the styles module: mvn install -pl styles
    • Build the base module: mvn install -pl base
    • Run the sampler: mvn javafx:run -pl sampler
    mvn install -N
mvn install -pl styles
mvn install -pl base
mvn javafx:run -pl sampler

  11. Install AtlantaFX locally without dependencies

    master

    If you prefer not to use a dependency manager, you can manually include the compiled CSS themes:

    1. Download the AtlantaFX-*-themes.zip from the GitHub Releases page.
    2. Unpack the archive and place the contents into your project's classpath.
    3. Apply the theme using one of the following methods:

    Method 1: Programmatically via Java

    Application.setUserAgentStylesheet(/* path to the CSS file */);

    Method 2: Via Java System Property

    -Djavafx.userAgentStylesheetUrl=[URL]

  12. Build and run the full project

    master

    To build the entire project and run the Sampler application (including the packaged app image), use the following Maven commands:

    1. Install the project modules: mvn install
    2. Run the Sampler application: mvn javafx:run -pl sampler
    mvn install
mvn javafx:run -pl sampler