NAME
    XTerm::Util - Utility routines for xterm-compatible terminal (emulator)s

VERSION
    This document describes version 0.003 of XTerm::Util (from Perl
    distribution XTerm-Util), released on 2018-09-26.

SYNOPSIS
     use XTerm::Util qw(
         get_term_bgcolor
         set_term_bgcolor
     );

     # when you're on a black background
     say get_term_bgcolor(); # => "000000"

     # when you're on a dark purple background
     say get_term_bgcolor(); # => "310035"

     # set terminal background to dark blue
     set_term_bgcolor("00002b");

DESCRIPTION
    Keywords: xterm, xterm-256color, terminal

FUNCTIONS
  get_term_bgcolor
    Usage:

     get_term_bgcolor() -> any

    Get terminal background color.

    Get the terminal's current background color, or undef if unavailable.
    This uses the following xterm control sequence:

     \e]11;?\a

    and a compatible terminal will issue back the same sequence but with the
    question mark replaced by the RGB code, e.g.:

     \e]11;rgb:0000/0000/0000\a

    I have tested this works on the following terminal software (and
    version) on Linux:

     MATE Terminal (1.18.2)
     GNOME Terminal (3.18.3)
     Konsole (16.04.3)

    And does not work with the following terminal software (and version) on
    Linux:

     LXTerminal (0.2.0)
     rxvt (2.7.10)

    A 6-hexdigit RGB value will be returned, e.g.:

     000000
     310035

    This function is not exported by default, but exportable.

    No arguments.

    Return value: (any)

  set_term_bgcolor
    Usage:

     set_term_bgcolor($rgb, $stderr) -> any

    Set terminal background color.

    Set terminal background color. This prints the following xterm control
    sequence to STDOUT (or STDERR, if ~stderr~ is set to true:

     \e]11;#123456\a

    where *123456* is the 6-hexdigit RGB color code.

    This function is not exported by default, but exportable.

    Arguments ('*' denotes required arguments):

    *   $rgb* => *color::rgb24*

    *   $stderr => *true*

    Return value: (any)

HOMEPAGE
    Please visit the project's homepage at
    <https://metacpan.org/release/XTerm-Util>.

SOURCE
    Source repository is at <https://github.com/perlancar/perl-XTerm-Util>.

BUGS
    Please report any bugs or feature requests on the bugtracker website
    <https://rt.cpan.org/Public/Dist/Display.html?Name=XTerm-Util>

    When submitting a bug or request, please include a test-file or a patch
    to an existing test-file that illustrates the bug or desired feature.

SEE ALSO
    Color::ANSI::Util

    XTerm control sequence:
    <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>.

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2018 by perlancar@cpan.org.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

