Build-in implementation of the ETerminal frontend. More...

#include <Terminal.h>

Inheritance diagram for etm::Terminal:

Public Types
typedef std::function< void()>	winActionCB_t
	Callback for a window action callback. More...

typedef std::function< void(const termError &error)>	errCallback_t
	Error callback function. More...

Public Member Functions
	Terminal (bool postponeInit=false)
	Creates a Terminal. More...

	Terminal (const std::shared_ptr< EtmFont > &font, bool postponeInit=false)
	Creates a Terminal. More...

	Terminal (const errCallback_t &errorCallback, const std::shared_ptr< EtmFont > &font, bool postponeInit=false)
	Creates a Terminal with a custom error callback. More...

	~Terminal ()
	Destucts the terminal.

	Terminal (Terminal &&other)
	Initialize with moved object. More...

Terminal &	operator= (Terminal &&other)
	Set to moved object. More...

void	init ()
	Initialize the terminal's openGL context resources. More...

void	deInit ()
	Free the terminal's openGL context resources. More...

void	setFont (const std::shared_ptr< EtmFont > &font)
	Changes the in-use font. More...

void	invalidate ()

void	notifyScroll ()

void	postError (const termError &error)
	Pass an error to the current error callback. More...

void	setCursorDefault (const winActionCB_t &callback)
	Set the cursor default callback. More...

void	setCursorIBeam (const winActionCB_t &callback)
	Set the cursor i-beam callback. More...

void	setHovering (bool value)
	Set whether the mouse is hovering over the terminal. More...

void	setErrorCallback (const errCallback_t &callback)
	Sets the global error callback for this Terminal. More...

void	clearInput () override
	Clears the input area (the area after the cursor lock).

void	clear () override
	Clears the screen. More...

void	setBackgroundColor (const Color &color)
	Sets the background color of the terminal. More...

void	setTextColor (const Color &color)
	Sets the default foreground color of printed text. More...

void	setScrollSensitivity (float value)
	Sets the mouse scroll sensitivity. More...

void	setScrollCooldown (int millis)
	Time between scrolls when holding down the scrollbar arrow. More...

void	setScrollWait (int millis)
	Time to wait until doing scroll repeat from when user first presses scroll button. More...

void	setShell (EShell &shell)
	Sets the shell to which user input should be directed. More...

void	setTakeInput (bool value) override
	Sets whether the shell wants input. More...

void	requestInput (TermInput &callback) override
	Each call adds `callback` to the input queue. More...

void	cancelInputRequest (TermInput *callback) override
	Removes all instances of a callback from the input queue. More...

void	clearInputRequests () override
	Deletes all input requests. More...

std::string	pollInput () override
	Get the current input text. More...

void	dispText (const std::string &str) override
	Append text to the display buffer. More...

void	flush () override
	Pushes the display buffer to the display. More...

void	softFlush () override
	Pushes the display buffer to the display. More...

void	setX (float x)
	Set the x coordinate of the top-left corner of the terminal. More...

void	setY (float y)
	Set the y coordinate of the top-left corner of the terminal. More...

void	setWidth (int width)
	Sets the pixel width of the terminal. More...

void	setHeight (int height)
	Sets the pixel height of the terminal. More...

void	setRows (int rows, int margin=7)
	Sets the pixel height of the terminal based off of a desired number of rows, with one row being the height of a line of text. More...

void	setColumns (int columns)
	Sets the pixel width of the terminal based off of a desired number of columns, with one columns being the height of a single character. More...

void	setFontSize (unsigned int size)
	Sets the font pixel size. More...

void	setMaxLines (TextBuffer::lines_number_t count)
	Set the maximum number of lines. More...

void	updatePosition ()
	Update element positioning.

void	inputChar (unsigned int codepoint)
	Input a char to the terminal, typically due to user input. More...

void	inputChar (const Line::codepoint &c)
	Input a char to the terminal, typically due to user input. More...

void	inputString (const std::string &text)
	Input a string to the terminal, typically due to a user pasting text. More...

void	inputActionKey (actionKey key)
	Inputs an "action" key, one that is not printable but represents some sort of command. More...

void	inputMouseScroll (float yOffset, float mouseX, float mouseY)
	Notify the terminal of user scroll input. More...

void	inputMouseClick (bool isPressed, float mouseX, float mouseY)
	Notify the terminal of user mouse button input. More...

void	inputMouseMove (float mouseX, float mouseY)
	Notify the terminal of user mouse movement. More...

void	render ()
	Renders the terminal to the current framebuffer. More...

bool	isFocused ()
	Gets if the terminal is focused by the user. More...

void	setFocused (bool val)
	Sets whether the terminal is focused or not. More...

std::string	getTextSelection ()
	Gets the text highlighted by the user. More...

std::string	getText ()
	Gets all the text in the terminal. More...

Protected Member Functions
int	sync () override
	Calls flush(). More...

std::streamsize	showmanyc () override
	Returns the size of the display buffer. More...

std::streamsize	xsgetn (char *c, std::streamsize n) override
	Extracts characters from the start of the display buffer. More...

int	underflow () override
	Get the first character in the display buffer. More...

int	uflow () override
	Extract the first character in the display buffer. More...

int	pbackfail (int c=EOF) override
	Put back a char.

std::streamsize	xsputn (const char *s, std::streamsize n) override
	Input chars. More...

int	overflow (int c=EOF) override
	Input a char. More...

	Terminal (const errCallback_t &errorCallback, bool postponeInit)
	Construct a terminal (internal). More...

Detailed Description

Build-in implementation of the ETerminal frontend.

The multible constructors operate under the philosophy that there should be an option to construct the terminal so that is completely ready to render.

Member Typedef Documentation

◆ errCallback_t

typedef std::function<void(const termError &error)> etm::Terminal::errCallback_t

Error callback function.

Parameters

[in] error An object with error information

◆ winActionCB_t

typedef std::function<void()> etm::Terminal::winActionCB_t

Callback for a window action callback.

Used to allow user to supply their own procedures for interfacing with the window.

Constructor & Destructor Documentation

◆ Terminal() [1/5]

etm::Terminal::Terminal	(	const errCallback_t &	errorCallback,
		bool	postponeInit
	)

protected

Construct a terminal (internal).

Parameters

[in]	errorCallback	The error callback
[in]	postponeInit	`true` to postpone OpenGL resource initialization

◆ Terminal() [2/5]

etm::Terminal::Terminal ( bool postponeInit = false )

Creates a Terminal.

Warning: The terminal will NOT have an active font. Attempts at rendering WILL fail unless you first call setFont(const std::shared_ptr<EtmFont>&).; The terminal will be tied to the current OpenGL context if postponeInit is set to false.

Note: If an error occurred during initialization, the default callback will be called.

Parameters

[in] postponeInit If this is set to true, the terminal WILL NOT initialize it's OpenGL resources right away, allowing you to later on generate the resources in the context you want to render to terminal to. NOTE WELL that you must call init() before you do any rendering. If set to false, you can still call init() later on when your desired context is bound, however bad things will happen if an OpenGL context isn't active. The bottom line is: if the context you want to render to is current, keep it at false. Otherwise, set it to true and call init() later on.

◆ Terminal() [3/5]

etm::Terminal::Terminal	(	const std::shared_ptr< EtmFont > &	font,
		bool	postponeInit = `false`
	)

Creates a Terminal.

Warning: The terminal will be tied to the current OpenGL context if postponeInit is set to false.

Note: If an error occurred during initialization, the default callback will be called.

Parameters

[in]	font	The initial font
[in]	postponeInit	If this is set to `true`, the terminal WILL NOT initialize it's OpenGL resources right away, allowing you to later on generate the resources in the context you want to render to terminal to. NOTE WELL that you must call init() before you do any rendering. If set to `false`, you can still call init() later on when your desired context is bound, however bad things will happen if an OpenGL context isn't active. The bottom line is: if the context you want to render to is current, keep it at `false`. Otherwise, set it to `true` and call init() later on.

◆ Terminal() [4/5]

etm::Terminal::Terminal	(	const errCallback_t &	errorCallback,
		const std::shared_ptr< EtmFont > &	font,
		bool	postponeInit = `false`
	)

Creates a Terminal with a custom error callback.

It's important to specify how you want errors handled on creation, as errors can occur during initialization.

Warning: The terminal will be tied to the current OpenGL context if postponeInit is set to false.

Parameters

[in]	errorCallback	The error callback
[in]	font	The initial font (See Font and BmpFont)
[in]	postponeInit	If this is set to `true`, the terminal WILL NOT initialize it's OpenGL resources right away, allowing you to later on generate the resources in the context you want to render to terminal to. NOTE WELL that you must call init() before you do any rendering. If set to `false`, you can still call init() later on when your desired context is bound, however bad things will happen if an OpenGL context isn't active. The bottom line is: if the context you want to render to is current, keep it at `false`. Otherwise, set it to `true` and call init() later on.

See also: setErrorCallback(const errCallback_t &callback)

◆ Terminal() [5/5]

etm::Terminal::Terminal ( Terminal && other )

Initialize with moved object.

Parameters

[in,out] other The object to move

Member Function Documentation

◆ cancelInputRequest()

void etm::Terminal::cancelInputRequest ( TermInput * callback )

overridevirtual

Removes all instances of a callback from the input queue.

Parameters

[in] callback pointer to the callback to be removed

See also: requestInput(TermInput &callback)

Implements etm::ETerminal.

◆ clear()

void etm::Terminal::clear ( )

overridevirtual

Clears the screen.

Causes all caches and other data related to the text and screen to be cleared.

Warning: Will also clear the display buffer [dispText(const std::string &str)]

See also: dispText(const std::string &str); flush()

Implements etm::ETerminal.

◆ clearInputRequests()

void etm::Terminal::clearInputRequests ( )

overridevirtual

Deletes all input requests.

See also: requestInput(TermInput &callback); cancelInputRequest(TermInput *callback)

Implements etm::ETerminal.

◆ deInit()

void etm::Terminal::deInit ( )

Free the terminal's openGL context resources.

Warning: Must not render until init() is called again!

◆ dispText()

void etm::Terminal::dispText ( const std::string & str )

overridevirtual

Append text to the display buffer.

The buffer will not be displayed until flush() is called.

Parameters

[in] str UTF-8 encoded string to be appended to the display buffer

See also: flush()

Implements etm::ETerminal.

◆ flush()

void etm::Terminal::flush ( )

overridevirtual

Pushes the display buffer to the display.

Note: Pushes the cursor with it.

See also: dispText(const std::string &str)

Implements etm::ETerminal.

◆ getText()

std::string etm::Terminal::getText ( )

Gets all the text in the terminal.

Returns: The text in the terminal

◆ getTextSelection()

std::string etm::Terminal::getTextSelection ( )

Gets the text highlighted by the user.

Highlight is determined by where the user clicking and dragging.

This is useful for copy/paste operations - which is exectly what this fuction was made for.

Returns: UTF-8 encoded string

◆ init()

void etm::Terminal::init ( )

Initialize the terminal's openGL context resources.

Note: This will generate a bunch of stuff, only call when you need to bind the terminal to a context.

Warning: The terminal will be tied to the current OpenGL context!

◆ inputActionKey()

void etm::Terminal::inputActionKey ( actionKey key )

Inputs an "action" key, one that is not printable but represents some sort of command.

Parameters

[in] key The pressed key

◆ inputChar() [1/2]

void etm::Terminal::inputChar ( const Line::codepoint & c )

Input a char to the terminal, typically due to user input.

This function, however, takes an encoded codepoint.

Note: Not buffered

Parameters

[in] c The codepoint

See also: Line::codepoint; inputChar(unsigned int codepoint); inputString(const std::string &text)

◆ inputChar() [2/2]

void etm::Terminal::inputChar ( unsigned int codepoint )

Input a char to the terminal, typically due to user input.

Note: Not buffered

Parameters

[in] codepoint A Unicode codepoint

See also: inputChar(const Line::codepoint &c); inputString(const std::string &text)

◆ inputMouseClick()

void etm::Terminal::inputMouseClick	(	bool	isPressed,
		float	mouseX,
		float	mouseY
	)

Notify the terminal of user mouse button input.

For simplicity, the terminal doesn't care what mouse button was pressed - however, it would probally be more intuitive if it was the left mouse button.

Parameters

[in]	isPressed	Was the mouse button pressed?
[in]	mouseX	Current x-coordinate of the mouse
[in]	mouseY	Current y-coordinate of the mouse

◆ inputMouseMove()

void etm::Terminal::inputMouseMove	(	float	mouseX,
		float	mouseY
	)

Notify the terminal of user mouse movement.

Parameters

[in]	mouseX	New x-coordinate of the mouse
[in]	mouseY	New y-coordinate of the mouse

◆ inputMouseScroll()

void etm::Terminal::inputMouseScroll	(	float	yOffset,
		float	mouseX,
		float	mouseY
	)

Notify the terminal of user scroll input.

Parameters

[in]	yOffset	The difference from the last scroll position
[in]	mouseX	Current x-coordinate of the mouse
[in]	mouseY	Current y-coordinate of the mouse

◆ inputString()

void etm::Terminal::inputString ( const std::string & text )

Input a string to the terminal, typically due to a user pasting text.

Note: Not buffered

Parameters

[in] text UTF-8 encoded string

See also: inputChar(unsigned int codepoint); inputChar(const Line::codepoint &c)

◆ isFocused()

bool etm::Terminal::isFocused ( )

Gets if the terminal is focused by the user.

The default value is true.

This is determined by the user clicking inside the terminal (true) or elseware (false).

Note: Used soley by you (the user) to determine if the terminal should recieve input.

Returns: true if the terminal is focused.

See also: setFocused(bool val)

◆ operator=()

Terminal& etm::Terminal::operator= ( Terminal && other )

Set to moved object.

Parameters

[in,out] other The object to move

Returns: *this

◆ overflow()

int etm::Terminal::overflow ( int c = EOF )

overrideprotected

Input a char.

Parameters

[in] c The char.

Returns: The char

◆ pollInput()

std::string etm::Terminal::pollInput ( )

overridevirtual

Get the current input text.

Note: This is only a get operation. Nothing is changed as a result of this call.

Returns: The input text, UTF-8 encoded

Implements etm::ETerminal.

◆ postError()

void etm::Terminal::postError ( const termError & error )

Pass an error to the current error callback.

Parameters

[in] error The error object

See also: setErrorCallback(const errCallback_t &callback)

◆ render()

void etm::Terminal::render ( )

Renders the terminal to the current framebuffer.

Warning: The context within which the terminal was created must be the one that's active due to the way OpenGL resources are tied to a particular context.

Note: Preserves the OpenGL state from when it was called, so you don't have to worry about preserving your own state.

See also: State

◆ requestInput()

void etm::Terminal::requestInput ( TermInput & callback )

overridevirtual

Each call adds callback to the input queue.

Each time input is entered, the callback is called and removed. Be careful of multible calls to this, for you could become locked in.

Parameters

[in] callback The callback to recieve the input text as a UTF-8 encoded string

See also: cancelInputRequest(TermInput *callback)

Implements etm::ETerminal.

◆ setBackgroundColor()

void etm::Terminal::setBackgroundColor ( const Color & color )

Sets the background color of the terminal.

This also sets the default background color of text.

Parameters

[in] color The color

See also: setTextColor(const Color &color)

◆ setColumns()

void etm::Terminal::setColumns ( int columns )

Sets the pixel width of the terminal based off of a desired number of columns, with one columns being the height of a single character.

This does not affect the scrollbar width or text width.

Parameters

[in] columns The desired columns

See also: setWidth(int width); setRows(int rows, int margin)

◆ setCursorDefault()

void etm::Terminal::setCursorDefault ( const winActionCB_t & callback )

Set the cursor default callback.

This is called whenever the terminal would like to set the cursor to its default state.

The callback does not have to be callable.

Parameters

[in] callback The callback

See also: setCursorIBeam(const winActionCB_t &callback)

◆ setCursorIBeam()

void etm::Terminal::setCursorIBeam ( const winActionCB_t & callback )

Set the cursor i-beam callback.

This is called whenever the terminal would like to set the cursor to i-beam (aka text input-mode).

The callback does not have to be callable.

Parameters

[in] callback The callback

See also: setCursorDefault(const winActionCB_t &callback)

◆ setErrorCallback()

void etm::Terminal::setErrorCallback ( const errCallback_t & callback )

Sets the global error callback for this Terminal.

All errors will be directed to this function.

Note: callback must be callable. If not, the error callback isn't changed

Parameters

[in] callback A new callable error callback

See also: postError(const termError &error)

◆ setFocused()

void etm::Terminal::setFocused ( bool val )

Sets whether the terminal is focused or not.

The default value is true.

While normally determined by user mouse clicks, if you feel the need you can manually set it yourself.

Note: Used soley by you (the user) to determine if the terminal should recieve input. If your code does not rely on the value of isFocused(), a call to this does nothing.

Parameters

[in] val New focused status

See also: isFocused()

◆ setFont()

void etm::Terminal::setFont ( const std::shared_ptr< EtmFont > & font )

Changes the in-use font.

Parameters

[in] font The font

◆ setFontSize()

void etm::Terminal::setFontSize ( unsigned int size )

Sets the font pixel size.

Parameters

[in] size The pixel size

◆ setHeight()

void etm::Terminal::setHeight ( int height )

Sets the pixel height of the terminal.

This does not affect the scrollbar height or text height.

Parameters

[in] height The new height

See also: setRows(int rows, int margin); setWidth(int width)

◆ setHovering()

void etm::Terminal::setHovering ( bool value )

Set whether the mouse is hovering over the terminal.

If set to true and hovering is false, will call the callback set by setCursorIBeam(const winActionCB_t &callback) (if it's callable), and vice versa with the callback set by setCursorDefault(const winActionCB_t &callback).

Parameters

[in] value The value

See also: setCursorDefault(const winActionCB_t &callback); setCursorIBeam(const winActionCB_t &callback)

◆ setMaxLines()

void etm::Terminal::setMaxLines ( TextBuffer::lines_number_t count )

Set the maximum number of lines.

If the limit is exceed, the oldest lines will be removed.

Parameters

[in] count number of lines

◆ setRows()

void etm::Terminal::setRows	(	int	rows,
		int	margin = `7`
	)

Sets the pixel height of the terminal based off of a desired number of rows, with one row being the height of a line of text.

This does not affect the scrollbar height or text height.

Parameters

[in]	rows	The desired rows
[in]	margin	Ammount of space at the bottom of the terminal, so that the input area doesn't feel so cramped.

See also: setHeight(int height); setColumns(int columns)

◆ setScrollCooldown()

void etm::Terminal::setScrollCooldown ( int millis )

Time between scrolls when holding down the scrollbar arrow.

Parameters

[in] millis Time in milliseconds

◆ setScrollSensitivity()

void etm::Terminal::setScrollSensitivity ( float value )

Sets the mouse scroll sensitivity.

Note: Negative values will result in inverted scroll.

Parameters

[in] value The sensitivity

◆ setScrollWait()

void etm::Terminal::setScrollWait ( int millis )

Time to wait until doing scroll repeat from when user first presses scroll button.

Parameters

[in] millis Time in milliseconds

◆ setShell()

void etm::Terminal::setShell ( EShell & shell )

Sets the shell to which user input should be directed.

Note: If this isn't set and the terminal recieves input, an error will be set.

Parameters

[in] shell The shell object

See also: EShell

◆ setTakeInput()

void etm::Terminal::setTakeInput ( bool value )

overridevirtual

Sets whether the shell wants input.

If this is false and there are no queued input requests, the terminal will ignore input.

Parameters

[in] value Whether the shell wants input

See also: requestInput(TermInput &callback); EShell

Implements etm::ETerminal.

◆ setTextColor()

void etm::Terminal::setTextColor ( const Color & color )

Sets the default foreground color of printed text.

Parameters

[in] color The color

See also: setBackgroundColor(const Color &color)

◆ setWidth()

void etm::Terminal::setWidth ( int width )

Sets the pixel width of the terminal.

This does not affect the scrollbar width or text width.

Parameters

[in] width The new width

See also: setColumns(int columns); setHeight(int height)

◆ setX()

void etm::Terminal::setX ( float x )

Set the x coordinate of the top-left corner of the terminal.

Parameters

[in] x The x coordinate

See also: setY(float y)

◆ setY()

void etm::Terminal::setY ( float y )

Set the y coordinate of the top-left corner of the terminal.

Parameters

[in] y The y coordinate

See also: setX(float x)

◆ showmanyc()

std::streamsize etm::Terminal::showmanyc ( )

overrideprotected

Returns the size of the display buffer.

Returns: The char count

◆ softFlush()

void etm::Terminal::softFlush ( )

overridevirtual

Pushes the display buffer to the display.

Unlike flush(), does not move the cursor.

See also: dispText(const std::string &str)

Implements etm::ETerminal.

◆ sync()

int etm::Terminal::sync ( )

overrideprotected

Calls flush().

Returns: 0

◆ uflow()

int etm::Terminal::uflow ( )

overrideprotected

Extract the first character in the display buffer.

Returns: The character

◆ underflow()

int etm::Terminal::underflow ( )

overrideprotected

Get the first character in the display buffer.

Returns: The character

◆ xsgetn()

std::streamsize etm::Terminal::xsgetn	(	char *	c,
		std::streamsize	n
	)

overrideprotected

Extracts characters from the start of the display buffer.

Parameters

[out]	c	The output string
[in]	n	Size of the output string

Returns: The number of chars put

◆ xsputn()

std::streamsize etm::Terminal::xsputn	(	const char *	s,
		std::streamsize	n
	)

overrideprotected

Input chars.

Parameters

[in]	s	The data
[in]	n	Length of data

Returns: Length of data put

The documentation for this class was generated from the following file:

Terminal.h

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ errCallback_t

◆ winActionCB_t

Constructor & Destructor Documentation

◆ Terminal() [1/5]

◆ Terminal() [2/5]

◆ Terminal() [3/5]

◆ Terminal() [4/5]

◆ Terminal() [5/5]

Member Function Documentation

◆ cancelInputRequest()

◆ clear()

◆ clearInputRequests()

◆ deInit()

◆ dispText()

◆ flush()

◆ getText()

◆ getTextSelection()

◆ init()

◆ inputActionKey()

◆ inputChar() [1/2]

◆ inputChar() [2/2]

◆ inputMouseClick()

◆ inputMouseMove()

◆ inputMouseScroll()

◆ inputString()

◆ isFocused()

◆ operator=()

◆ overflow()

◆ pollInput()

◆ postError()

◆ render()

◆ requestInput()

◆ setBackgroundColor()

◆ setColumns()

◆ setCursorDefault()

◆ setCursorIBeam()

◆ setErrorCallback()

◆ setFocused()

◆ setFont()

◆ setFontSize()

◆ setHeight()

◆ setHovering()

◆ setMaxLines()

◆ setRows()

◆ setScrollCooldown()

◆ setScrollSensitivity()

◆ setScrollWait()

◆ setShell()

◆ setTakeInput()

◆ setTextColor()

◆ setWidth()

◆ setX()

◆ setY()

◆ showmanyc()

◆ softFlush()

◆ sync()

◆ uflow()

◆ underflow()

◆ xsgetn()

◆ xsputn()