Ivan-Alone / PHP-ConsoleGraph

ConsoleGraph - немного "графики" для унылого терминала

PHP-ConsoleGraph

Библиотека для "рисования" окон в консоли. Учитывая возможности PHP - "окна" получаются линейными, но достаточно приятными.

Создаются окна размером 120x30 символов, что достаточно для небольших "окошек" в вашем приложении.

Библиотека кросс-платформенна (т.е. поддерживается режим "windows" - с использованием команд терминала и режим "ANSI" - с использованием escape-последовательностей).

Доступно рисование "графических" линий, стенок окон, полей ввода текста и паролей, установка заголовка окна терминала, прогресс-бары (односессионные, однако на PHP - какие есть).

Бонусом идёт конвертер изображений из PNG в снимок окна терминала (текстовый файл из необходимой псевдографики), позволяющий преобразовывать чёрно-белые изображения в текст, для последующего вывода на экран в качестве экрана загрузки, например (принимаются на вход 120x60px чёрно-белые изображения).

Ниже - описание класса и его публичных функций.

Описание функционала

Содержание

Список классов:

• ConsoleGraph

Список функций:

• ConsoleGraph->graphTitle($title)

• ConsoleGraph->graphColor($bg, $txt)

• ConsoleGraph->graphColorReset()

• ConsoleGraph->graphClear()

• ConsoleGraph->graphSetSlide($slide)

• ConsoleGraph->graphReadLn($text = null)

• ConsoleGraph->graphReadPassword($text = null)

• ConsoleGraph->graphDrawPicFile($bg_color, $fg_color, $filename, $show_timer = 0, $args = array())

• ConsoleGraph->graphDrawPic($bg_color, $fg_color, $data, $show_timer = 0, $args = array())

• ConsoleGraph->graphStartingLine()

• ConsoleGraph->graphEmptyLine()

• ConsoleGraph->graphFilledLine()

• ConsoleGraph->graphDottedLine()

• ConsoleGraph->graphEndingLine()

• ConsoleGraph->graphWriteToLine($text)

• ConsoleGraph->graphWriteToCenterLine($text)

• ConsoleGraph->graphProgressBarCreate()

• ConsoleGraph->graphProgressBarUpdate($current, $count)

• ConsoleGraph->graphProgressBarClose()

• ConsoleGraph->graphPause()

• ConsoleGraph->graphFinish()

• ConsoleGraph->graphExit()

Описание классов

ConsoleGraph

Главный и единственный класс, реализующий "графическую систему" библиотеки. Является публичным нестатическим классом, то есть для использования необходимо создать его инстанцию.

Создание инстанции:

$console = new ConsoleGraph();

Конструктор класса может принимать несколько типов данных: строковой и булевский (остальные будут так или иначе интерпретированны PHP, возможно - неверно).

Значения переменных:

• $useStarsAsWinBuilders - по умолчанию в качестве декорации окна используются псевдографические символы. Также есть возможность использовать звёздочки "*". False - не изпользовать звёздочки, True - использовать, также существует отладочная опция '__do_not_configure_window' - не конфигурировать окно при инициализации, то есть не изменять размер терминала на необходимые 120x30 символов и не фиксировать прокрутку.

Описание функций

ConsoleGraph->graphTitle($title)

Устанавливает имя окна терминала.

Значения переменных:

• String $title

ConsoleGraph->graphColor($bg, $txt)

Устанавливает цвета фона и текста в терминале (работает только на Windows!)

Значения переменных:

• int $bg - цвет фона (0x0 - 0xF)
• int $txt - цвет текса (0x0 - 0xF)

ConsoleGraph->graphColorReset()

Сбрасывает цвета фона и текста в терминале (работает только на Windows!)

ConsoleGraph->graphClear()

Очистка экрана терминала

ConsoleGraph->graphSetSlide($slide)

Устанавливает сдвиг текста от начала отсчёта, полезно при кастомном позиционировании текста на экране

Значения переменных:

• int $slide - размер сдвига в символах

ConsoleGraph->graphReadLn($text = null)

Читает строку с клавиатуры, возвращая её значение. Параметром можно указать текст, указываемый перед индикатором ввода '> '.

Значения переменных:

• string $text - текст перед индикатором ввода '> '.

Тип данных:

• string

ConsoleGraph->graphReadPassword($text = null)

Читает строку с клавиатуры, возвращая её значение, а затем скрывая введённый текст спец. символами, как для пароля (работает на Windows 10 и *NIX, на Windows 7, Windows 8 и т.д. текст не скрывается из-за "особенностей" командной строки). Параметром можно указать текст, указываемый перед индикатором ввода '> '

Значения переменных:

• string $text - текст перед индикатором ввода '> '

Тип данных:

• String

ConsoleGraph->graphDrawPicFile($bg_color, $fg_color, $filename, $show_timer = 0, $args = array())

Рисует изображение conpic2 из файла

Значения переменных:

• int $bg_color - цвет фона картинки (0-15, список цветов указан ниже)
• int $fg_color - цвет фона картинки (0-15, список цветов указан ниже)
• string $filename - путь к файлу картинки
• int $show_timer - время, на которое надо показать картинку. 0 = показать картинку до нажатия Enter
• array $args - аргументы для вывода картинки. Передаётся массив с допустимыми аргументами restore и clear. Первый - требование восстановить оригинальные цвета терминала после показа картинки, второй - очистить терминал после вывода картинки. По умолчанию делается и то, и то. Передать можно так: array('restore' => true, 'clear' => false)

ConsoleGraph->graphDrawPic($bg_color, $fg_color, $data, $show_timer = 0, $args = array())

Рисует изображение conpic2, переданное в виде набора бит (ранее считанного из файла или сгенерированного в программе)

Значения переменных:

• int $bg_color - цвет фона картинки (0-15, список цветов указан ниже)
• int $fg_color - цвет фона картинки (0-15, список цветов указан ниже)
• string $data - биты сгенерированной картинки
• int $show_timer - время, на которое надо показать картинку. 0 = показать картинку до нажатия Enter
• array $args - аргументы для вывода картинки. Передаётся массив с допустимыми аргументами restore и clear. Первый - требование восстановить оригинальные цвета терминала после показа картинки, второй - очистить терминал после вывода картинки. По умолчанию делается и то, и то. Передать можно так: array('restore' => true, 'clear' => false)

Список цветов (в скобках указан цвет на *NIX'ах):

• 0 - чёрный (чёрный)
• 1 - синий (синий)
• 2 - зелёный (зелёный)
• 3 - голубой (голубой)
• 4 - тёмно-красный (тёмно-красный)
• 5 - фиолетовый (фиолетовый)
• 6 - золотой (золотой)
• 7 - серый (белый)
• 8 - тёмно-серый (чёрный)
• 9 - светло-синий (синий)
• 10 - светло-зелёный (зелёный)
• 11 - бирюзовый (голубой)
• 12 - ярко-красный (тёмно-красный)
• 13 - пурпурный (фиолетовый)
• 14 - жёлтый (золотой)
• 15 - белый (белый)

ConsoleGraph->graphStartingLine()

Рисует начальную линию окна, с углами начала и т.п.

ConsoleGraph->graphEmptyLine()

Рисует пустую линию окна с боковыми "огородками"

ConsoleGraph->graphFilledLine()

Рисует заполненную линию окна, подходит для отделения разделов GUI друг от друга

ConsoleGraph->graphDottedLine()

Рисует заполненную тире линию окна, подходит для отделения подразделов GUI друг от друга

ConsoleGraph->graphEndingLine()

Рисует финальную линию окна, с углами конца и т.п.

ConsoleGraph->graphWriteToLine($text)

Рисует пустую линию окна с боковыми "огородками", а затем поверх неё печатает указанный в параметре текст.

Значения переменных:

• string $text - текст, который надо вывести на экран.

ConsoleGraph->graphWriteToCenterLine($text)

Рисует пустую линию окна с боковыми "огородками", а затем поверх неё печатает указанный в параметре текст, центруя его посередине экрана.

Значения переменных:

• string $text - текст, который надо вывести на экран по центру.

ConsoleGraph->graphProgressBarCreate()

Открывает сессию обновления прогресс-бара. Внимание! При открытой сессии прогресс-бара другие попытки ввода-вывода в консоль средстами библиотеки неработоспособны, в дальнейшем код сессии будет изменён на блокирующий, дабы сессия действительно не позволяла вывести в консоль что-либо иное.

ConsoleGraph->graphProgressBarUpdate($current, $count)

Обновляет прогресс-бар.

Значения переменных:

• int $current - текущая позиция прогресса
• int $count - максимальная длина прогресс-бара, нужна для рассчёта соотношения размера "летны" с текущим прогрессом, а также для вывода на экран

ConsoleGraph->graphProgressBarClose()

Закрывает сессию обновления прогресс-бара

ConsoleGraph->graphPause()

Вызывает системную приостановку выполнения программы. Полезно для отладки, или если нужно попросить пользователя нажать Enter

ConsoleGraph->graphFinish()

Завершение работы графической библиотеки. При вызове вызывается пауза, а после нажатия Enter (на Windows - любой клавиши) производится завершение выполнения программы.

ConsoleGraph->graphExit()

Завершение работы графической библиотеки. При вызове производится завершение выполнения программы.

Утилита ImageExport

С её помощью можно выводить на экран консоли чёрно-белые PNG изображения. На самом деле цвет может быть любым, однако чёрный является основным контрастрым цветом (#000000), остальные цвета без исключения считаются белым.

Утилита состоит из двух подпрограмм-библиотек (могут работать самостоятельно) и основной программы

• imageExport.php - основная программа
• conpic1.php - подпрограмма обработки картинок первой версии (принцип - распечатанное в виде текста изображение)
• conpic2.php - подпрограмма для обработки картинок второй версии (принцип - битовое кодирование каждого пиксела)

Требования к входному файлу:

• Формат PNG
• Чёрный цвет ( rgb(0,0,0) ) означает видимую часть изображения, остальные - невидимую

Конвертирование производится в терминале (командной строке)

Работа с полной программой imageExport.php

php imageExport.php $file_in $file_out

• $file1 [png|conpic|conpic2] - исходный файл в одном из перечисленных форматов
• $file2 [png|conpic|conpic2] - выходной файл, аргумент может отсутствовать

Без указания второго аргумента на экране будет нарисовано изображение, переданное первым аргументом. В противном случае по расширению будет определён формат и произведено преобразование

Работа с подпрограммой conpic1.php

php imageExport.php $action $file

• $action - действие над файлом (draw - нарисовать, convert2conpic - преобразовать PNG в conpic, convert2png - преобразовать conpic в PNG)
• $file - входной файл

При конвертации выходной файл будет записан как $file.conpic

Работа с подпрограммой conpic2.php

php imageExport.php $action $file

• $action - действие над файлом (draw - нарисовать, convert2conpic2 - преобразовать PNG в conpic2, convert2png - преобразовать conpic2 в PNG)
• $file - входной файл

При конвертации выходной файл будет записан как $file.conpic2