terminal.h

Go to the documentation of this file.

/*
  Created by Fabrizio Di Vittorio (fdivitto2013@gmail.com) - <http://www.fabgl.com>
  Copyright (c) 2019-2022 Fabrizio Di Vittorio.
  All rights reserved.
 
 
* Please contact fdivitto2013@gmail.com if you need a commercial license.
 
 
* This library and related software is available under GPL v3.
 
  FabGL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
 
  FabGL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with FabGL.  If not, see <http://www.gnu.org/licenses/>.
 */
 
 
#pragma once
 
 
 
#ifdef ARDUINO
  #include "Arduino.h"
  #include "Stream.h"
#endif
 
#include <ctype.h>
#include <string.h>
 
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/timers.h"
#include "freertos/semphr.h"
 
#include "fabglconf.h"
#include "canvas.h"
#include "devdrivers/keyboard.h"
#include "terminfo.h"
#include "devdrivers/soundgen.h"
 
 
 
namespace fabgl {
 
 
 
 
enum class FlowControl {
  None,              
  Software,          
  Hardware,          
  Hardsoft,          
};
 
 
// used by saveCursorState / restoreCursorState
struct TerminalCursorState {
  TerminalCursorState *   next;
  int16_t                 cursorX;
  int16_t                 cursorY;
  uint8_t *               tabStop;
  bool                    cursorPastLastCol;
  bool                    originMode;
  GlyphOptions            glyphOptions;
  uint8_t                 characterSetIndex;
  uint8_t                 characterSet[4];
};
 
 
enum KeypadMode {
  Application,  // DECKPAM
  Numeric,      // DECKPNM
};
 
 
enum CharStyle {
  Bold,               
  ReducedLuminosity,  
  Italic,             
  Underline,          
  Blink,              
  Blank,              
  Inverse,            
};
 
 
enum class TerminalTransition {
  None,
  LeftToRight,    
  RightToLeft,    
};
 
 
struct EmuState {
 
  // Index of characterSet[], 0 = G0 (Standard)  1 = G1 (Alternate),  2 = G2,  3 = G3
  uint8_t      characterSetIndex;
 
  // 0 = DEC Special Character and Line Drawing   1 = United States (USASCII)
  uint8_t      characterSet[4];
 
  Color        foregroundColor;
  Color        backgroundColor;
 
  // cursor position (topleft = 1,1)
  int          cursorX;
  int          cursorY;
 
  bool         cursorPastLastCol;
 
  bool         originMode;
 
  bool         wraparound;
 
  // top and down scrolling regions (1 = first row)
  int          scrollingRegionTop;
  int          scrollingRegionDown;
 
  bool         cursorEnabled;
 
  // true = blinking cursor, false = steady cursor
  bool         cursorBlinkingEnabled;
 
  // 0,1,2 = block  3,4 = underline  5,6 = bar
  int          cursorStyle;
 
  // column 1 at m_emuState.tabStop[0], column 2 at m_emuState.tabStop[1], etc...  0=no tab stop,  1 = tab stop
  uint8_t *    tabStop;
 
  // IRM (Insert Mode)
  bool         insertMode;
 
  // NLM (Automatic CR LF)
  bool         newLineMode;
 
  // DECSCLM (Smooth scroll)
  // Smooth scroll is effective only when vertical sync refresh is enabled,
  // hence must be BitmappedDisplayController.enableBackgroundPrimitiveExecution(true),
  // that is the default.
  bool         smoothScroll;
 
  // DECKPAM (Keypad Application Mode)
  // DECKPNM (Keypad Numeric Mode)
  KeypadMode   keypadMode;
 
  // DECCKM (Cursor Keys Mode)
  bool         cursorKeysMode;
 
  // DESSCL (1 = VT100 ... 5 = VT500)
  int          conformanceLevel;
 
  // two values allowed: 7 and 8
  int          ctrlBits;
 
  bool         keyAutorepeat;
 
  bool         allow132ColumnMode;
 
  bool         reverseWraparoundMode;
 
  // DECBKM (false = BACKSPACE sends BS, false BACKSPACE sends DEL)
  bool         backarrowKeyMode;
 
  // DECANM (false = VT52 mode, true = ANSI mode)
  bool         ANSIMode;
 
  // VT52 Graphics Mode
  bool         VT52GraphicsMode;
 
  // Allow FabGL specific sequences (ESC FABGLEXT_STARTCODE .....)
  int          allowFabGLSequences;  // >0 allow, 0 = don't allow
};
 
 
#ifndef ARDUINO
 
struct Print {
  virtual size_t write(uint8_t) = 0;
  virtual size_t write(const uint8_t * buffer, size_t size);
  size_t write(const char *str) {
    if (str == NULL)
        return 0;
    return write((const uint8_t *)str, strlen(str));
  }
  void printf(const char * format, ...) {
    va_list ap;
    va_start(ap, format);
    int size = vsnprintf(nullptr, 0, format, ap) + 1;
    if (size > 0) {
      va_end(ap);
      va_start(ap, format);
      char buf[size + 1];
      auto l = vsnprintf(buf, size, format, ap);
      write((uint8_t*)buf, l);
    }
    va_end(ap);
  }
};
 
struct Stream : public Print{
};
 
#endif  // ifdef ARDUINO
 
 
 
class Terminal : public Stream {
 
public:
 
  Terminal();
 
  ~Terminal();
 
  bool begin(BaseDisplayController * displayController, int maxColumns = -1, int maxRows = -1, Keyboard * keyboard = nullptr);
 
  void end();
 
  #ifdef ARDUINO
  void connectSerialPort(HardwareSerial & serialPort, bool autoXONXOFF = true);
  #endif
 
  void connectSerialPort(uint32_t baud, int dataLength, char parity, float stopBits, int rxPin, int txPin, FlowControl flowControl, bool inverted = false, int rtsPin = -1, int ctsPin = -1);
 
  #ifdef ARDUINO
  void pollSerialPort();
  #endif
 
  void disableSerialPortRX(bool value)         { m_uartRXEnabled = !value; }
 
  void connectLocally();
 
  void disconnectLocally();
 
  void localWrite(uint8_t c);
 
  void localWrite(char const * str);
 
  void localInsert(uint8_t c);
 
  void unRead(uint8_t c) { localInsert(c); }
 
  void setLogStream(Stream & stream) { m_logStream = &stream; }
 
  void logFmt(const char * format, ...);
  void log(const char * txt);
  void log(char c);
 
  void loadFont(FontInfo const * font);
 
  void setBackgroundColor(Color color, bool setAsDefault = true);
 
  void setForegroundColor(Color color, bool setAsDefault = true);
 
  void clear(bool moveCursor = true);
 
  void flush(bool waitVSync);
 
  int getColumns() { return m_columns; }
 
  int getRows()    { return m_rows; }
 
  void enableCursor(bool value);
 
  int availableForWrite();
 
  void setTerminalType(TermType value);
 
  TermInfo const & terminalType() { return *m_termInfo; }
 
 
 
  int available();
 
  int read();
 
  int read(int timeOutMS);
 
  bool waitFor(int value, int timeOutMS = -1);
 
  int peek();
 
  void flush();
 
  size_t write(const uint8_t * buffer, size_t size);
 
  size_t write(uint8_t c);
 
  using Print::write;
 
  void send(uint8_t c);
 
  void send(char const * str);
 
 
  Keyboard * keyboard() { return m_keyboard; }
 
  Canvas * canvas() { return m_canvas; }
 
  void activate(TerminalTransition transition = TerminalTransition::None);
 
  void deactivate();
 
  bool isActive() { return s_activeTerminal == this; }
 
  void setColorForAttribute(CharStyle attribute, Color color, bool maintainStyle);
 
  void setColorForAttribute(CharStyle attribute);
 
  SoundGenerator * soundGenerator();
 
  bool XOFFStatus()                    { return m_sentXOFF; }
 
  bool RTSStatus()                     { return m_RTSStatus; }
 
  void setRTSStatus(bool value);
 
  bool CTSStatus()                     { return m_ctsPin != GPIO_UNUSED ? gpio_get_level(m_ctsPin) == 0 : false; }
 
  void flowControl(bool enableRX);
 
  bool flowControl();
 
 
 
  Delegate<VirtualKey *, bool> onVirtualKey;
 
 
  Delegate<VirtualKeyItem *> onVirtualKeyItem;
 
 
  Delegate<char const *> onUserSequence;
 
 
 
  // statics (used for common default properties)
 
 
  static int inputQueueSize;
 
  static int inputConsumerTaskStackSize;
 
  static int keyboardReaderTaskStackSize;
 
 
private:
 
  void reset();
  void int_clear();
  void clearMap(uint32_t * map);
 
  void freeFont();
  void freeTabStops();
  void freeGlyphsMap();
 
  void set132ColumnMode(bool value);
 
  bool moveUp();
  bool moveDown();
  void move(int offset);
  void setCursorPos(int X, int Y);
  int getAbsoluteRow(int Y);
 
  void int_setBackgroundColor(Color color);
  void int_setForegroundColor(Color color);
 
  void syncDisplayController();
 
  // tab stops
  void nextTabStop();
  void setTabStop(int column, bool set);
  void resetTabStops();
 
  // scroll control
  void scrollDown();
  void scrollDownAt(int startingRow);
  void scrollUp();
  void scrollUpAt(int startingRow);
  void setScrollingRegion(int top, int down, bool resetCursorPos = true);
  void updateCanvasScrollingRegion();
 
  // multilevel save/restore cursor state
  void saveCursorState();
  void restoreCursorState();
  void clearSavedCursorStates();
 
  void erase(int X1, int Y1, int X2, int Y2, uint8_t c, bool maintainDoubleWidth, bool selective);
 
  void consumeInputQueue();
  void consumeESC();
  void consumeCSI();
  void consumeOSC();
  void consumeFabGLSeq();
  void consumeFabGLGraphicsSeq();
  void consumeCSIQUOT(int * params, int paramsCount);
  void consumeCSISPC(int * params, int paramsCount);
  uint8_t consumeParamsAndGetCode(int * params, int * paramsCount, bool * questionMarkFound);
  void consumeDECPrivateModes(int const * params, int paramsCount, uint8_t c);
  void consumeDCS();
  void execSGRParameters(int const * params, int paramsCount);
  void consumeESCVT52();
 
  void execCtrlCode(uint8_t c);
 
  static void charsConsumerTask(void * pvParameters);
  static void keyboardReaderTask(void * pvParameters);
 
  static void blinkTimerFunc(TimerHandle_t xTimer);
  void blinkText();
  bool enableBlinkingText(bool value);
  void blinkCursor();
  bool int_enableCursor(bool value);
 
  static void IRAM_ATTR uart_isr(void *arg);
 
  uint8_t getNextCode(bool processCtrlCodes);
 
  bool setChar(uint8_t c);
  GlyphOptions getGlyphOptionsAt(int X, int Y);
 
  void insertAt(int column, int row, int count);
  void deleteAt(int column, int row, int count);
 
  bool multilineInsertChar(int charsToMove);
  void multilineDeleteChar(int charsToMove);
 
  void reverseVideo(bool value);
 
  void refresh();
  void refresh(int X, int Y);
  void refresh(int X1, int Y1, int X2, int Y2);
 
  void setLineDoubleWidth(int row, int value);
  int getCharWidthAt(int row);
  int getColumnsAt(int row);
 
  void useAlternateScreenBuffer(bool value);
 
  void sendCSI();
  void sendDCS();
  void sendSS3();
  void sendCursorKeyCode(uint8_t c);
  void sendKeypadCursorKeyCode(uint8_t applicationCode, const char * numericCode);
 
  void ANSIDecodeVirtualKey(VirtualKeyItem const & item);
  void VT52DecodeVirtualKey(VirtualKeyItem const & item);
 
  void convHandleTranslation(uint8_t c, bool fromISR);
  void convSendCtrl(ConvCtrl ctrl, bool fromISR);
  void convQueue(const char * str, bool fromISR);
  void TermDecodeVirtualKey(VirtualKeyItem const & item);
 
  bool addToInputQueue(uint8_t c, bool fromISR);
  bool insertToInputQueue(uint8_t c, bool fromISR);
 
  void write(uint8_t c, bool fromISR);
 
  //static void uart_on_apb_change(void * arg, apb_change_ev_t ev_type, uint32_t old_apb, uint32_t new_apb);
 
  void uartCheckInputQueueForFlowControl();
 
  void enableFabGLSequences(bool value);
 
  void int_setTerminalType(TermType value);
  void int_setTerminalType(TermInfo const * value);
 
  void sound(int waveform, int frequency, int duration, int volume);
 
  uint8_t extGetByteParam();
  int extGetIntParam();
  void extGetCmdParam(char * cmd);
 
  void freeSprites();
 
  uint32_t makeGlyphItem(uint8_t c, GlyphOptions * glyphOptions, Color * newForegroundColor);
 
  // indicates which is the active terminal when there are multiple instances of Terminal
  static Terminal *  s_activeTerminal;
 
 
  BaseDisplayController * m_displayController;
  Canvas *           m_canvas;
  bool               m_bitmappedDisplayController;  // true = bitmapped, false = textual
 
  Keyboard *         m_keyboard;
 
  Stream *           m_logStream;
 
  // characters, characters attributes and characters colors container
  // you may also call this the "text screen buffer"
  GlyphsBuffer       m_glyphsBuffer;
 
  // used to implement alternate screen buffer
  uint32_t *         m_alternateMap;
 
  // true when m_alternateMap and m_glyphBuffer.map has been swapped
  bool               m_alternateScreenBuffer;
 
  // just to restore some properties when swapping screens (alternate screen)
  int                m_alternateCursorX;
  int                m_alternateCursorY;
  int                m_alternateScrollingRegionTop;
  int                m_alternateScrollingRegionDown;
  bool               m_alternateCursorBlinkingEnabled;
 
  FontInfo           m_font;
 
  PaintOptions       m_paintOptions;
  GlyphOptions       m_glyphOptions;
 
  EmuState           m_emuState;
 
  Color              m_defaultForegroundColor;
  Color              m_defaultBackgroundColor;
 
  // states of cursor and blinking text before consumeInputQueue()
  bool               m_prevCursorEnabled;
  bool               m_prevBlinkingTextEnabled;
 
  // task that reads and processes incoming characters
  TaskHandle_t       m_charsConsumerTaskHandle;
 
  // task that reads keyboard input and send ANSI/VT100 codes to serial port
  TaskHandle_t       m_keyboardReaderTaskHandle;
 
  // true = cursor in reverse state (visible), false = cursor invisible
  volatile bool      m_cursorState;
 
  // timer used to blink
  TimerHandle_t      m_blinkTimer;
 
  // main terminal mutex
  volatile SemaphoreHandle_t m_mutex;
 
  volatile bool      m_blinkingTextVisible;    // true = blinking text is currently visible
  volatile bool      m_blinkingTextEnabled;
 
  volatile int       m_columns;
  volatile int       m_rows;
 
  // checked in loadFont() to limit m_columns and m_rows (-1 = not checked)
  int                m_maxColumns;
  int                m_maxRows;
 
  #ifdef ARDUINO
  // optional serial port
  // data from serial port is processed and displayed
  // keys from keyboard are processed and sent to serial port
  HardwareSerial *          m_serialPort;
  #endif
 
  // optional serial port (directly handled)
  // data from serial port is processed and displayed
  // keys from keyboard are processed and sent to serial port
  volatile bool             m_uart;
 
  // if false all inputs from UART are discarded
  volatile bool             m_uartRXEnabled;
 
  // contains characters to be processed (from write() calls)
  volatile QueueHandle_t    m_inputQueue;
 
  // contains characters received and decoded from keyboard (or as replyes from ANSI-VT queries)
  QueueHandle_t             m_outputQueue;
 
  // linked list that contains saved cursor states (first item is the last added)
  TerminalCursorState *     m_savedCursorStateList;
 
  // a reset has been requested
  bool                      m_resetRequested;
 
  volatile FlowControl      m_flowControl;
  volatile bool             m_sentXOFF;       // true if XOFF has been sent or RTS is disabled (high)
  volatile bool             m_recvXOFF;       // true if XOFF has been received
 
  // hardware flow pins
  gpio_num_t                m_rtsPin;
  gpio_num_t                m_ctsPin;
  bool                      m_RTSStatus;      // true = asserted (low)
 
  // used to implement m_emuState.keyAutorepeat
  VirtualKey                m_lastPressedKey;
 
  uint8_t                   m_convMatchedCount;
  uint8_t                   m_convMatchedChars[EmuTerminalMaxChars];
  TermInfoVideoConv const * m_convMatchedItem;
  TermInfo const *          m_termInfo;
 
  // last char added with write()
  volatile uint8_t          m_lastWrittenChar;
 
  // when a FabGL sequence has been detected in write()
  volatile bool             m_writeDetectedFabGLSeq;
 
  // used by extGetIntParam(), extGetCmdParam(), extGetByteParam() to store next item (to avoid insertToInputQueue() which can cause dead-locks)
  int                       m_extNextCode; // -1 = no code
 
  SoundGenerator *          m_soundGenerator;
 
  Sprite *                  m_sprites;
  int                       m_spritesCount;
 
  bool                      m_coloredAttributesMaintainStyle;
  int                       m_coloredAttributesMask;    // related bit 1 if enabled
  Color                     m_coloredAttributesColor[4];
 
};
 
 
 
// TerminalController
 
 
class TerminalController {
 
public:
 
  TerminalController(Terminal * terminal = nullptr);
 
  ~TerminalController();
 
  void clear();
 
  void setTerminal(Terminal * terminal = nullptr);
 
  void enableCursor(bool value);
 
  void setCursorPos(int col, int row);
 
  void getCursorPos(int * col, int * row);
 
  void cursorLeft(int count);
 
  void cursorRight(int count);
 
  int getCursorCol();
 
  int getCursorRow();
 
  bool multilineInsertChar(int charsToMove);
 
  void multilineDeleteChar(int charsToMove);
 
  bool setChar(uint8_t c);
 
  bool isVKDown(VirtualKey vk);
 
  void disableFabGLSequences();
 
  void setTerminalType(TermType value);
 
  void setForegroundColor(Color value);
 
  void setBackgroundColor(Color value);
 
  void setCharStyle(CharStyle style, bool enabled);
 
 
 
  Delegate<int *> onRead;
 
  Delegate<int> onWrite;
 
 
private:
 
  void waitFor(int value);
  void write(uint8_t c);
  void write(char const * str);
  int read();
 
 
  Terminal * m_terminal;
};
 
 
 
// LineEditor
 
 
enum class LineEditorSpecialChar {
  CursorUp,    
  CursorDown,  
};
 
 
class LineEditor {
 
public:
 
  LineEditor(Terminal * terminal);
 
  ~LineEditor();
 
  void setText(char const * text, bool moveCursor = true);
 
  void setText(char const * text, int length, bool moveCursor = true);
 
  void typeText(char const * text);
 
  char const * edit(int maxLength = 0);
 
  char const * get() { return m_text; }
 
  void setInsertMode(bool value) { m_insertMode = value; }
 
 
  // delegates
 
  Delegate<int *> onRead;
 
  Delegate<int> onWrite;
 
  Delegate<int *>  onChar;
 
  Delegate<int *> onCarriageReturn;
 
  Delegate<LineEditorSpecialChar> onSpecialChar;
 
 
private:
 
  void beginInput();
  void endInput();
  void setLength(int newLength);
 
  void write(uint8_t c);
  int read();
 
  void performCursorUp();
  void performCursorDown();
  void performCursorLeft();
  void performCursorRight();
  void performCursorHome();
  void performCursorEnd();
  void performDeleteRight();
  void performDeleteLeft();
 
 
  Terminal *          m_terminal;
  TerminalController  m_termctrl;
  char *              m_text;
  int                 m_textLength;
  int                 m_allocated;
  int16_t             m_inputPos;
  int16_t             m_state;     // -1 = begin input, 0 = normal input, 1 = ESC, 2 = CTRL-Q, >=31 = CSI (actual value specifies the third char if present)
  int16_t             m_homeCol;
  int16_t             m_homeRow;
  bool                m_insertMode;
  char *              m_typeText;
  int                 m_typingIndex;
};
 
 
 
} // end of namespace