Class TerminalGraphicsManager


  • public class TerminalGraphicsManager
    extends java.lang.Object
    Manager for terminal graphics protocols.

    This class provides a unified interface for displaying images in terminals using the best available graphics protocol. It automatically detects which protocols are supported by the terminal and selects the most appropriate one.

    The manager supports multiple graphics protocols:

    • Kitty Graphics Protocol - Modern, feature-rich protocol
    • iTerm2 Inline Images - iTerm2's proprietary protocol
    • Sixel - Widely supported legacy protocol

    Protocols are selected based on priority and terminal support. Higher priority protocols are preferred when multiple protocols are available.

    Since:
    3.30.0
    • Constructor Detail

      • TerminalGraphicsManager

        public TerminalGraphicsManager()
        Creates a new TerminalGraphicsManager instance.
    • Method Detail

      • registerProtocol

        public static void registerProtocol​(TerminalGraphics protocol)
        Registers a graphics protocol implementation. The protocol list is automatically re-sorted by priority after registration. If a protocol of the same type is already registered, it will not be added again.
        Parameters:
        protocol - the protocol implementation to register
      • forceProtocol

        public static void forceProtocol​(TerminalGraphics.Protocol protocol)
        Forces the use of a specific graphics protocol, overriding automatic detection. This is useful for testing or when automatic detection fails.
        Parameters:
        protocol - the protocol to force, or null to enable automatic detection
      • getForcedProtocol

        public static TerminalGraphics.Protocol getForcedProtocol()
        Gets the forced protocol, if any.
        Returns:
        the forced protocol, or null if automatic detection is enabled
      • isJavaDesktopAvailable

        public static boolean isJavaDesktopAvailable()
        Checks if the java.desktop module is available. Graphics features require java.desktop for AWT imaging types.
        Returns:
        true if java.desktop is available, false otherwise
      • getBestProtocol

        public static java.util.Optional<TerminalGraphics> getBestProtocol​(Terminal terminal)
        Finds the best graphics protocol for the given terminal.
        Parameters:
        terminal - the terminal to check
        Returns:
        the best available graphics protocol, or empty if none are supported
      • getAvailableProtocols

        public static java.util.List<TerminalGraphics> getAvailableProtocols()
        Gets all available graphics protocols.
        Returns:
        a list of all registered graphics protocols
      • getSupportedProtocols

        public static java.util.List<TerminalGraphics> getSupportedProtocols​(Terminal terminal)
        Gets all graphics protocols supported by the given terminal.
        Parameters:
        terminal - the terminal to check
        Returns:
        a list of supported graphics protocols, sorted by priority
      • isGraphicsSupported

        public static boolean isGraphicsSupported​(Terminal terminal)
        Checks if any graphics protocol is supported by the given terminal.
        Parameters:
        terminal - the terminal to check
        Returns:
        true if at least one graphics protocol is supported
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.awt.image.BufferedImage image)
                                 throws java.io.IOException
        Displays a BufferedImage on the terminal using the best available protocol.
        Parameters:
        terminal - the terminal to display the image on
        image - the image to display
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.awt.image.BufferedImage image,
                                        TerminalGraphics.ImageOptions options)
                                 throws java.io.IOException
        Displays a BufferedImage on the terminal with custom options.
        Parameters:
        terminal - the terminal to display the image on
        image - the image to display
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.io.File file)
                                 throws java.io.IOException
        Displays an image file on the terminal using the best available protocol.
        Parameters:
        terminal - the terminal to display the image on
        file - the image file to display
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.io.File file,
                                        TerminalGraphics.ImageOptions options)
                                 throws java.io.IOException
        Displays an image file on the terminal with custom options.
        Parameters:
        terminal - the terminal to display the image on
        file - the image file to display
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.io.InputStream inputStream)
                                 throws java.io.IOException
        Displays an image from an input stream on the terminal using the best available protocol.
        Parameters:
        terminal - the terminal to display the image on
        inputStream - the input stream containing the image data
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available
      • displayImage

        public static void displayImage​(Terminal terminal,
                                        java.io.InputStream inputStream,
                                        TerminalGraphics.ImageOptions options)
                                 throws java.io.IOException
        Displays an image from an input stream on the terminal with custom options.
        Parameters:
        terminal - the terminal to display the image on
        inputStream - the input stream containing the image data
        options - display options for the image
        Throws:
        java.io.IOException - if an I/O error occurs
        java.lang.UnsupportedOperationException - if no graphics protocol is supported or java.desktop is not available