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.