.. currentmodule:: chafa

=============
Terminal Info
=============

::
    
    import chafa

    db           = chafa.TermDb()
    capabilities = db.detect_capabilities()

    print("CanvasMode:", capabilities.canvas_mode)
    print("PixelMode: ", capabilities.pixel_mode)



TermInfo
--------

A :py:class:`TermInfo` describes the characteristics of one particular kind of display terminal. It stores control sequences that can be used to move the cursor, change text attributes, mark the beginning and end of sixel graphics data, etc.

:py:class:`TermInfo` also implements an efficient low-level API for formatting these sequences with marshaled arguments so they can be sent to the terminal.

.. py:class:: TermInfo

    .. py:method:: copy()

        Returns a new :py:class:`TermInfo` that is a copy of this one.

        :rtype: TermInfo

    .. py:method:: supplement(source: TermInfo)

        Supplements missing sequences in this :py:class:`TermInfo` with ones copied from source.

        :param TermInfo source: The :py:class:`TermInfo` to copy sequences from.

    .. py:method:: have_seq(seq: TermSeq)

        Checks if :py:class:`TermInfo` can emit seq.
        
        :param TermSeq seq: A :py:class:`TermSeq` to query for.

        :rtype: bool

    .. py:method:: detect_capabilities()

        A method that tries to automatically detect the current terminal's capabilities.

        The priority for :py:class:`CanvasMode` is

        #. :py:attr:`CanvasMode.CHAFA_CANVAS_MODE_TRUECOLOR` 
        #. :py:attr:`CanvasMode.CHAFA_CANVAS_MODE_INDEXED_240` 
        #. :py:attr:`CanvasMode.CHAFA_CANVAS_MODE_INDEXED_16` 
        #. :py:attr:`CanvasMode.CHAFA_CANVAS_MODE_FGBG_BGFG` 
        #. :py:attr:`CanvasMode.CHAFA_CANVAS_MODE_FGBG` 

        The priority for :py:class:`PixelMode` is

        #. :py:attr:`PixelMode.CHAFA_PIXEL_MODE_KITTY`
        #. :py:attr:`PixelMode.CHAFA_PIXEL_MODE_SIXELS`
        #. :py:attr:`PixelMode.CHAFA_PIXEL_MODE_SYMBOLS`

        You can use the results for :py:attr:`CanvasConfig.canvas_mode` and :py:attr:`CanvasConfig.pixel_mode` in your :py:class:`CanvasConfig`.

        :rtype: TerminalCapabilities


TerminalCapabilities
--------------------

This class is just a simple dataclass representing the capabilities of a terminal. It is generated by :py:meth:`TermInfo.detect_capabilities`

.. py:class:: TermInfo.TerminalCapabilities

    .. py:attribute:: canvas_mode

        :type: CanvasMode

    .. py:attribute:: pixel_mode

        :type: PixelMode

    .. py:method:: __eq__(other)

        Returns ``True`` if both of
        
        #. ``other.canvas_mode == this.canvas_mode``
        #. ``other.pixel_mode == this.pixel_mode``
        
        are ``True``. Returns ``False`` otherwise.

        :rtype: bool

    .. versionadded:: 1.1.0