view release on metacpan or  search on metacpan

lib/Antsy.pm  view on Meta::CPAN

=item * downloads

https://iterm2.com/documentation-images.html

The width and height are given as a number followed by a unit, or the word "auto".

iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is:

ESC ] 1337 ; key = value ^G
Whitespace is shown here for ease of reading: in practice, no spaces should be used.

For file transfer and inline images, the code is:

ESC ] 1337 ; File = [arguments] : base-64 encoded file contents ^G
The arguments are formatted as key=value with a semicolon between each key-value pair. They are described below:

Key		Description of value
name	  	base-64 encoded filename. Defaults to "Unnamed file".
size	  	File size in bytes. The file transfer will be canceled if this size is exceeded.
width	  	Optional. Width to render. See notes below.
height	  	Optional. Height to render. See notes below.
preserveAspectRatio	  	Optional. If set to 0, then the image's inherent aspect ratio will not be respected; otherwise, it will fill the specified width and height as much as possible without stretching. Defaults to 1.
inline	  	Optional. If set to 1, the file will be displayed inline. Otherwise, it will be downloaded with no visual representation in the terminal session. Defaults to 0.
N: N character cells.
Npx: N pixels.
N%: N percent of the session's width or height.
auto: The image's inherent size will be used to determine an appropriate dimension.
More on File Transfers
By omitting the inline argument (or setting its value to 0), files will be downloaded and saved in the Downloads folder instead of being displayed inline. Any kind of file may be downloaded, but only images will display inline. Any image format that ...

If the file's size exceeds the declared size, the transfer may be canceled. This is a security measure to prevent a download gone wrong from using unbounded memory.

=item * uploads

To request the user select one or more files to upload, send:

OSC 1337 ; RequestUpload=format=[type] ST
In the future the [type] may be configurable, but for now it must always be tgz, which is a tar and gzipped file.

When iTerm2 receives this it will respond with a status of ok or abort followed by a newline. If the status is ok then it will be followed by a base-64 encoded tar.gz file.

If the user selects multiple files they will be placed in a directory within the tar file.

=item * set_touchbar_key_levels

You can configure touch bar key labels for function keys and for the "status" button. The code used is:

OSC 1337 ; SetKeyLabel=[key]=[value] ST
Where [key] is one of F1, F2, ..., F24, to adjust a function key label; or it can be status to adjust the touch bar status button. You can also save and restore sets of key labels using a stack. To push the current key labels on the stack use:

OSC 1337 ; PushKeyLabels ST
To pop them:

OSC 1337 ; PopKeyLabels ST
You can optionally label the entry in the stack when you push so that pop will pop multiple sets of key labels if needed. This is useful if a program crashes or an ssh session exits unexpectedly. The corresponding codes with labels are:

OSC 1337 ; PushKeyLabels=[label] ST
OSC 1337 ; PopKeyLabels=[label] ST
Where [label] is an ASCII string that works best if it is unique in the stack.

=item * unicode_version

iTerm2 by default uses Unicode 9's width tables. The user can opt to use Unicode 8's tables with a preference (for backward compatibility with older locale databases). Since not all apps will be updated at the same time, you can tell iTerm2 to use a ...

OSC 1337 ; UnicodeVersion=[n] ST
Where [n] is 8 or 9

You can push the current value on a stack and pop it off to return to the previous value by setting n to push or pop. Optionally, you may affix a label after push by setting n to something like push mylabel. This attaches a label to that stack entry....

=back

=head1 SEE ALSO

=over 4

=item * Everything you never wanted to know about ANSI escape codes https://notes.burke.libbey.me/ansi-escape-codes/

=item * https://gist.github.com/fnky/458719343aabd01cfb17a3a4f7296797

=item * iTerm2 ANSI codes https://iterm2.com/documentation-escape-codes.html

=back

=head1 SOURCE AVAILABILITY

This source is in Github:

	http://github.com/briandfoy/antsy

=head1 AUTHOR

brian d foy, C<< <briandfoy@pobox.com> >>

=head1 COPYRIGHT AND LICENSE

Copyright © 2021-2025, brian d foy, All Rights Reserved.

You may redistribute this under the terms of the Artistic License 2.0.

=cut

1;