A high-level interface to a PixInsight processing console. More...

#include <Console.h>

Public Member Functions
	Console ()

	Console (Console &&x)

	Console (const Console &)=delete

virtual	~Console ()

void	Abort ()

bool	AbortEnabled () const

bool	AbortRequested () const

void	Clear ()

void	Critical (const String &s)

void	CriticalLn (const String &s)

void	DisableAbort ()

void	EnableAbort ()

void	ExecuteScript (const String &filePath, const StringKeyValueList &arguments=StringKeyValueList())

void	ExecuteScriptGlobal (const String &filePath, const StringKeyValueList &arguments=StringKeyValueList())

void	ExecuteScriptOn (const View &view, const String &filePath, const StringKeyValueList &arguments=StringKeyValueList())

void	Flush ()

bool	Hide (bool hide=true)

bool	IsCurrentThreadConsole () const

bool	IsValid () const

void	Note (const String &s)

void	NoteLn (const String &s)

Console &	operator= (Console &&x)

Console &	operator= (const Console &)=delete

int	ReadChar ()

String	ReadString ()

void	ResetStatus ()

bool	Show (bool show=true)

bool	Suspended () const

bool	Waiting () const

void	Warning (const String &s)

void	WarningLn (const String &s)

void	Write (const String &s)

void	WriteLn ()

void	WriteLn (const String &s)

Detailed Description

The PixInsight platform provides three different user interfaces implemented in the PixInsight core application: a graphical user interface (GUI), a scripting interface (the PixInsight JavaScript runtime), and a command-line interface. The Console class is a high-level abstraction that represents the Process Console window of the PixInsight core application, which implements the entire command-line and console text input/output functionality in PixInsight.

A module can instantiate Console to perform direct text input/output operations. Console objects are often used to display information about ongoing processes, to let the user abort a process, or to put a process in a wait state to perform a modal user interface operation (e.g., showing a message box) in a thread-safe way.

From the module developer perspective, each module has an associated console. Such associations between modules and consoles are managed automatically by internal core and PCL routines: module developers just need to instantiate the Console class and use its member functions.

For example, writing a message to the console can be as simple as:

Console().WriteLn( "Hello, PixInsight" );

pcl::Console::Console

Console()

Stream-style console insertion and extraction operators are also available. For example, this is equivalent to the above code:

Console() << "Hello, PixInsight" << '\n';

When you need to output formatted data, you can use the String::Format() family of functions. These functions are similar to the standard printf() C runtime function:

Console console;

console.WriteLn( String().Format( "Radius = %.6f, Angle = %+.2f°", r, Deg( a ) ) );

pcl::Deg

constexpr T Deg(T x) noexcept

Definition: Math.h:606

PixInsight consoles can understand and reproduce the full set of ISO-8859-1 HTML entities. You see an example on the code fragment above: the "°" entity prints a degree symbol on the console.

PixInsight consoles can also interpret a number of tags, similar to HTML, to perform special actions and formatting operations. For example:

Console() << "<end><cbr>This is bold and this is italics ";

In this example, the "<end>" tag moves the cursor after the last character in the console, then the "<cbr>" tag (conditional break) generates a new line only if the current line is not empty. This ensures that subsequent text output will start on an empty line at the end of the current console contents. The "" and "" tags write text in a bold type face, and the "" and "" pair write text in italics. This is just a minimal fraction of the rich set of tags understood by PixInsight consoles.

As we describe in detail below, PixInsight consoles support standard ANSI escape codes, and can also be used to render inline HTML contents.

It must be pointed out that the entire text output functionality of Console is also available for TextBox controls. A module can instantiate a TextBox control to provide rich text-based output as a process log, the output of an external process, or an information panel based on HTML tables, just to name a few possibilities implemented frequently.

Console Tags

Here is a comprehensive list of supported console tags at the time of publishing this documentation. New functionality implemented through console tags will be documented here as new versions are released.

<b></b>	Enables/disables bold text.
<i></i>	Enables/disables italics text.
<u></u>	Enables/disables underlined text.
<o></o>	Enables/disables overlined text.
<sub></sub>	Enables/disables subscript text.
<sup></sup>	Enables/disables superscript text.
<br>	Line break.
<br/>	Line break, XML compliant (same as <br>).
<cbr>	Conditional line break: sends a line break if the cursor is not at the beginning of an empty line.
<cbr/>	Conditional line break, XML compliant (same as <cbr>).
<bsp>	Backspace: deletes the previous character and moves the cursor one step left, only if it is not at the beginning of a line.
<end>	Moves the cursor to the end of the console.
<beg>	Moves the cursor to the beginning of the console.
<bwd>	Moves the cursor to the previous character, only if it is not at the beginning of a line.
<fwd>	Moves the cursor to the next character, only if it is not at the end of a line.
<eol>	Moves the cursor to the end of the current line.
<bol>	Moves the cursor to the beginning of the current line.
<up>	Moves the cursor to the previous line, if it is not already at the first line.
<down>	Moves the cursor to the next line, if it is not already at the last line.
<clr>	Clears the console. Avoid issuing this tag arbitrarily - please see the documentation for Console::Clear() for more information.
<clreol>	Deletes the text from the current cursor position (included) to the end of the current line.
<clrbol>	Deletes the text from the current cursor position (included) to the beginning of the current line.
<clrend>	Deletes the text from the current cursor position (included) to the end of the console.
<clrbeg>	Deletes the text from the current cursor position (included) to the beginning of the console. Avoid issuing this tag arbitrarily - please see the documentation for Console::Clear() for more information.
<nowrap></nowrap>	Disables/enables word wrapping of text lines.
<notags></notags>	Disables/enables tag interpretation, except the </notags> tag, which is always interpreted.
<noentities></noentities>	Disables/enables interpretation of ISO-8859-1 entities.
<raw></raw>	Disables/enables interpretation of tags, except the </raw> tag, and ISO-8859-1 entities. <raw> is equivalent to (but faster than) <noentities><notags>.
<code></code>	Equivalent to <monospace><raw>. Useful to show source code fragments.
<monospace>	Selects a platform-dependent, monospaced font.
<sans>	Selects a platform-dependent, sans-serif font.
<serif>	Selects a platform-dependent, serif font.
<courier>	Selects the Courier font, or the nearest available monspaced font, depending on the platform.
<helvetica>	Selects the Helvetica font, or the nearest available sans-serif font, depending on the platform.
<times>	Selects the Times font, or the nearest available serif font, depending on the platform.
<default-font>	Selects the default console font (usually a monospaced font; but user-selectable through preferences).
<reset-font>	Resets all text settings and styles to default values.
<show>	If this console corresponds to the processing console window, shows it if it's currently hidden and docked in the PixInsight core application window; otherwise this tag is ignored. Equivalent to calling the Console::Show() member function.
<hide>	If this console corresponds to the processing console window, hides it if it's currently visible and docked in the PixInsight core application window; otherwise this tag is ignored. Equivalent to calling the Console::Hide() member function.
<flush>	Causes any pending data to be written immediately to the console. If there is no unwritten data for this console, this tag has no effect. Equivalent to calling the Console::Flush() member function.
<html></html>	Enables/disables HTML mode. In HTML mode, the console interprets and renders a comprehensive set of HTML 4 tags, including full support of tables, as well as a significant part of Level 2 CSS (Cascading Style Sheets) directives. In HTML mode, PixInsight console tags are either ignored or interpreted with their corresponding meaning in HTML 4.

In addition, the \n, \r and \b escape characters can be used in place of the , <bol> and <bsp> tags, respectively.

Character Entities

PixInsight consoles fully recognize and interpret the whole set of HTML 4 character entities, including all ISO 8859-1 characters and all character entities for symbols, mathematical symbols, Greek letters, markup-significant and internationalization characters.

Character entities are of the form:

<entity-name>;

where <entity-name> is one of the references included in the following W3C Recommendation document:

http://www.w3.org/TR/REC-html40/sgml/entities.html

HTML Mode

The <html> tag allows you to put a PixInsight console in HTML mode. In this mode you can embed HTML 4 contents directly. For example, this code:

Console console;
console.Write( "<html>"
               "<table border="1" cellpadding="4" cellspacing="0">"
               "<tr><td>If this is foo</td>  <td>and this is bar,</td></tr>"
               "<tr><td>then</td>            <td>this can only be foo bar.</td></tr>"
               "</table>"
               "</html>" ); 

generates an HTML table with two rows and two columns. PixInsight consoles support most of the HTML 4 specification, including a subset of CSS2. For detaled information, this document describes HTML support in Qt, which is the underlying implementation in current versions of PixInsight:

http://qt-project.org/doc/qt-4.8/richtext-html-subset.html

In HTML mode, that is, within a pair of <html></html> tags, no PixInsight console tags or ANSI escape codes are recognized or interpreted.

ANSI Escape Codes

Since version 1.8.1 of the PixInsight core application, PixInsight consoles support a large set of ANSI CSI (Control Sequence Introducer) codes. For a detailed description of ANSI escape codes, refer to the following documents:

http://en.wikipedia.org/wiki/ANSI_escape_code http://invisible-island.net/xterm/ctlseqs/ctlseqs.html

The following table describes the supported CSI codes in the current version of PixInsight. ESC represents the escape control character, whose ASCII code is 27₁₀ = 1B₁₆. The CSI sequence is ESC followed by the left square bracket character, represented as the ESC[ sequence. See the examples given at the end of the table.

ESC[ n A Cursor up n Times (default n=1) (CUU)

ESC[ n B Cursor down n Times (default n=1) (CUD)

ESC[ n C Cursor forward n Times (default n=1) (CUF)

ESC[ n D Cursor backward n Times (default n=1) (CUB)

ESC[ n E Cursor to next line n Times (default n=1) (CNL)

ESC[ n F Cursor to preceding line n Times (default n=1) (CPL)

ESC[ n G Cursor to character absolute column n (default n=1) (CHA)

ESC[ n;m H Cursor position to row n and column m (default n=m=1) (CUP)

ESC[ n;m f

Horizontal & Vertical Position (HVP). Same as H.

ESC[ n J

Erase in Display (ED)

`n = 0`	Erase below up to the end of text. This is the default if no n is specified.
`n = 1`	Erase above up to the start of text.
`n = 2`	Erase all (entire console).

ESC[ n K

Erase in Line (EL)

`n = 0`	Erase to right up to the end of line. This is the default if no n is specified.
`n = 1`	Erase to left up to the start of line.
`n = 2`	Erase the whole line.

ESC[ n L Insert n line(s) (default n=1) (IL)

ESC[ n M Delete n line(s) (default n=1) (DL)

ESC[ n P

Delete n character(s) (default n=1) (DCH)

ESC[ ... m

Set graphics rendition (SGR)
The ellipsis represents a list of one or more integer arguments separated by semi-colons. The following arguments are recognized:

`0`	Reset all font and color properties to default values.
`1`	Bold font
`2`	Faint (decreased intensity) - ignored (not implemented)
`3`	Italic font
`4`	Underline font
`5`	Blink (slow) - reinterpreted - selects a bold font.
`6`	Blink (fast) - reinterpreted - selects a bold font.
`7`	Inverse colors (swap default foreground and background)
`8`	Invisible - ignored (not implemented)
`9`	Strike out font
`21`	Bold font: disable
`22`	Normal color - ignored (not implemented)
`23`	Italic font: disable
`24`	Underline font: disable
`25`	Blink: disable - reinterpreted - disables bold font (same as 21).
`27`	Inverse colors: disable
`28`	Visible - ignored (not implemented)
`29`	Strike out font: disable
`30 ... 37`	Set foreground color to n-30: 0=black, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan, 7=white.
`38`	KDE's Konsole extended 24-bit color space: Set foreground color (see note below).
`39`	Default foreground color.
`40 ... 47`	Set background color to n-40. Colors are the same as for 30 ... 37.
`48`	KDE's Konsole extended 24-bit color space: Set background color (see note below).
`49`	Default background color.
`53`	Overline font
`55`	Overline font: disable

ESC[s Save Cursor Position (SCP)

ESC[u

Restore Cursor Position (RCP)

KDE Konsole 24-bit colors use the following format:

Select RGB foreground color: ESC[ ... 38;2;r;g;b ... m
Select RGB background color: ESC[ ... 48;2;r;g;b ... m

where r, g and b are the red, green and blue components in the [0,255] range. For detailed information on these codes, see the following document:

https://projects.kde.org/projects/kde/applications/konsole/repository/revisions/master/entry/doc/user/README.moreColors

Examples

Write a text line using a bold font:

Console().WriteLn( "\x1b[1mThis is bold text\x1b[21m" );

Write a text line in orange color using an italic font:

String programName;

Console().WriteLn( "<end><cbr> \x1b[3;38;2;255;128;0m" + programName + "\x1b[39;23m" );

Write some text at the beginning of the current line, removing any previous contents:

Console().Write( "\x1b[2KThis text replaces the whole line" );

See also: StatusMonitor, StandardStatus, SpinStatus, MuteStatus, Thread

Definition at line 358 of file Console.h.

Constructor & Destructor Documentation

◆ Console() [1/3]

pcl::Console::Console ( )

Constructs a Console object.

◆ Console() [2/3]

pcl::Console::Console ( const Console & )

delete

Copy constructor, disabled because Console instances represent unique objects that cannot be copied.

◆ Console() [3/3]

pcl::Console::Console ( Console && x )

inline

Move constructor.

Definition at line 376 of file Console.h.

◆ ~Console()

virtual pcl::Console::~Console ( )

virtual

Destroys a Console object.

Member Function Documentation

◆ Abort()

void pcl::Console::Abort ( )

Accepts a pending abort request.

Note: This function must only be called when there is an active process running in the current module. It can only be called from the thread where either a reimplemented ProcessImplementation::ExecuteOn() or ProcessImplementation::ExecuteGlobal() member function has been invoked. An Error exception will be thrown otherwise.

◆ AbortEnabled()

bool pcl::Console::AbortEnabled ( ) const

Returns true iff the current processing thread can be aborted by the user.

◆ AbortRequested()

bool pcl::Console::AbortRequested ( ) const

Returns true iff the user has requested to abort execution of the current processing thread.

◆ Clear()

void pcl::Console::Clear ( )

Clears the console. This is a convenience function that simply writes the <clr> tag to the console.

Note: Calling this function from a running thread has no effect. The console output text of a Thread object cannot be erased by this function.; In general, call this function only as a result of an explicit user request to clear the console. Clearing the console arbitrarily, without having an extremely good reason, is considered bad practice and can be a good argument to deny certification of a module.

◆ Critical()

void pcl::Console::Critical ( const String & s )

inline

Writes a critical error message to this console.

This function writes the specified Unicode string s using standard ANSI terminal color number 1 (red in the default palette). The implementation of this member function uses ANSI escape codes.

Definition at line 483 of file Console.h.

◆ CriticalLn()

void pcl::Console::CriticalLn ( const String & s )

inline

Writes a critical error message to this console and appends a newline escape character ('\n').

See the description of Critical( const String& ).

Definition at line 494 of file Console.h.

◆ DisableAbort()

void pcl::Console::DisableAbort ( )

Disables abort requests for the current processing thread.

Note: This function must only be called when there is an active process running in the current module. It can only be called from the thread where either a reimplemented ProcessImplementation::ExecuteOn() or ProcessImplementation::ExecuteGlobal() member function has been invoked. An Error exception will be thrown otherwise.

◆ EnableAbort()

void pcl::Console::EnableAbort ( )

Enables abort requests for the current processing thread.

Note: This function must only be called when there is an active process running in the current module. It can only be called from the thread where either a reimplemented ProcessImplementation::ExecuteOn() or ProcessImplementation::ExecuteGlobal() member function has been invoked. An Error exception will be thrown otherwise.

◆ ExecuteScript()

void pcl::Console::ExecuteScript	(	const String &	filePath,
		const StringKeyValueList &	arguments = `StringKeyValueList()`
	)

Executes a script file.

Parameters

filePath	Path to the script file that will be executed. Must be a path to an existing script on the local filesystem.
arguments	A dynamic array, possibly empty, of StringKeyValue objects. Each object in this array represents a script argument. The key member is the parameter name, and the value member is the corresponding parameter value.

The core application will load, parse, authorize and execute the specified script file. The scripting language will be detected automatically from the file name suffix in filePath. Currently the .scp and .js suffixes are interpreted for command-line shell scripts and JavaScript scripts, respectively. Future versions may accept more languages and apply language detection heuristics besides file suffixes.

This member function returns normally if the script was loaded and executed. In the event of error, for example if the specified file does not exist or can't be accessed, or in the event of security errors or failure to authorize script execution from the calling module, this member function throws an Error exception.

Note that command-line or JavaScript runtime execution errors cannot be reported by this function. That means that this function knows nothing about whether the script worked or not correctly, or if it did what was expected.

For execution of JavaScript scripts, this function is equivalent to ExecuteScriptGlobal(), that is, JavaScript scripts are always executed in the global context by default. When executed, the JavaScript script will see the following static properties of the Parameters JS runtime object:

Parameters.isGlobalTarget will be set to true.
Parameters.isViewTarget will be set to false.
Parameters.targetView will be set to undefined.

See ExecuteScriptOn() for execution of scripts in view contexts.

Note: If this function is called from a running thread, an Error exception will be thrown and nothing will be executed. In current versions of the PixInsight platform, scripts can only be executed from the root thread. The main reason for this limitation is that the JavaScript and command-line execution engines are not reentrant.

◆ ExecuteScriptGlobal()

void pcl::Console::ExecuteScriptGlobal	(	const String &	filePath,
		const StringKeyValueList &	arguments = `StringKeyValueList()`
	)

Executes a script file in the global context. This is the default execution execution mode for all scripts.

When a JavaScript script is executed through this member function, the following static properties of the Parameters runtime object will be defined as described below:

Parameters.isGlobalTarget will be set to true.
Parameters.isViewTarget will be set to false.
Parameters.targetView will be set to undefined.

See ExecuteScript() for a detailed description of script execution from PCL/C++ code.

◆ ExecuteScriptOn()

void pcl::Console::ExecuteScriptOn	(	const View &	view,
		const String &	filePath,
		const StringKeyValueList &	arguments = `StringKeyValueList()`
	)

Executes a script file in the context of the specified view.

When a JavaScript script is executed through this member function, the following static properties of the Parameters runtime object will be defined as described below:

Parameters.isGlobalTarget will be set to false.
Parameters.isViewTarget will be set to true.
Parameters.targetView will reference the specified view.

See ExecuteScript() for a detailed description of script execution from PCL/C++ code.

◆ Flush()

void pcl::Console::Flush ( )

Causes any pending data to be written immediately to this console. If there is no unwritten data for this console, this function has no effect.

◆ Hide()

bool pcl::Console::Hide ( bool hide = true )

inline

Hides the Process Console window in the PixInsight core application.

This is a convenience function, equivalent to: Show( !hide )

Returns true iff the console could be hidden (or shown) successfully. Refer to the Show() member function for more information.

Note: Calling this function from a running thread has no effect. Console visibility can only be changed from the root thread.

Definition at line 644 of file Console.h.

◆ IsCurrentThreadConsole()

bool pcl::Console::IsCurrentThreadConsole ( ) const

Returns true iff this console is valid and has been created by the calling thread; either by the root thread or by a running Thread object.

◆ IsValid()

bool pcl::Console::IsValid ( ) const

Returns true iff this is a valid console object associated to an active processing thread.

◆ Note()

void pcl::Console::Note ( const String & s )

inline

Writes an informative note message to this console.

This function writes the specified Unicode string s using standard ANSI terminal color number 2 (green in the default palette). The implementation of this member function uses ANSI escape codes.

Definition at line 437 of file Console.h.

◆ NoteLn()

void pcl::Console::NoteLn ( const String & s )

inline

Writes an informative note message to this console and appends a newline escape character ('\n').

See the description of Note( const String& ).

Definition at line 448 of file Console.h.

◆ operator=() [1/2]

Console& pcl::Console::operator= ( Console && x )

inline

Move assignment operator. Returns a reference to this object.

Definition at line 392 of file Console.h.

◆ operator=() [2/2]

Console& pcl::Console::operator= ( const Console & )

delete

Copy assignment operator, disabled because Console instances represent unique objects that cannot be copied.

◆ ReadChar()

int pcl::Console::ReadChar ( )

Reads a single character from this console and returns it.

This function puts the current thread in wait state, then waits until a character can be obtained in the core application's GUI thread. This usually involves waiting for a keyboard event.

Note: This member function has not been implemented in the current PCL version. Calling it has not effect, and zero is always returned.

Referenced by pcl::operator>>().

◆ ReadString()

String pcl::Console::ReadString ( )

Reads a string from this console and returns it.

This function puts the current thread in wait state, then opens a simple modal dialog box with a single-line edit control, where the user may enter a string. If the user cancels the input dialog, an empty string is returned.

Note: This member function has not been implemented in the current PCL version. Calling it has not effect, and an empty string is always returned.

Referenced by pcl::operator>>().

◆ ResetStatus()

void pcl::Console::ResetStatus ( )

Resets the current processing thread status.

This function is useful to ignore an abort request for the current processing thread. For example, if the user requests to abort execution, a module may ask if she or he really wants to cancel, and if the user answers 'No', then this member function can be called to clear the existing abort request condition.

Note: This function must only be called when there is an active process running in the current module. It can only be called from the thread where either a reimplemented ProcessImplementation::ExecuteOn() or ProcessImplementation::ExecuteGlobal() member function has been invoked. An Error exception will be thrown otherwise.

◆ Show()

bool pcl::Console::Show ( bool show = true )

Shows the Process Console window in the PixInsight core application.

The visibility of a console can only be controlled if it is the process console window. Furthermore, a module cannot show or hide the console if it is not owned by a docked window; the visibility of a floating window cannot be changed programmatically from a module.

This function returns true if the console could be shown (or hidden) successfully. Unlike most interface operations, console hide/show operations are not cached, so if this function returns true then you know that the Process Console window is currently visible.

Note: Calling this function from a running thread has no effect. Console visibility can only be changed from the root thread.

◆ Suspended()

bool pcl::Console::Suspended ( ) const

Returns true iff the current processing thread has been suspended by the PixInsight core application.

◆ Waiting()

bool pcl::Console::Waiting ( ) const

Returns true iff the current processing thread is in wait state.

◆ Warning()

void pcl::Console::Warning ( const String & s )

inline

Writes a warning message to this console.

This function writes the specified Unicode string s using standard ANSI terminal color number 5 (magenta in the default palette). The implementation of this member function uses ANSI escape codes.

Definition at line 460 of file Console.h.

◆ WarningLn()

void pcl::Console::WarningLn ( const String & s )

inline

Writes a warning message to this console and appends a newline escape character ('\n').

See the description of Warning( const String& ).

Definition at line 471 of file Console.h.

◆ Write()

void pcl::Console::Write ( const String & s )

Writes an Unicode string s to this console.

Referenced by pcl::operator<<().

◆ WriteLn() [1/2]

void pcl::Console::WriteLn ( )

Sends a single newline escape character ('\n') to the console.

Note that this function is faster than writing a newline directly with a call to Write( '\n' ).

◆ WriteLn() [2/2]

void pcl::Console::WriteLn ( const String & s )

Writes an Unicode string s to this console and appends a newline escape character ('\n').

Note that this function is faster than appending a newline character to the string, such as a call to Write( s + '\n' ).

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

Console.h

Public Member Functions

Detailed Description

Console Tags

Character Entities

HTML Mode

ANSI Escape Codes

Constructor & Destructor Documentation

◆ Console() [1/3]

◆ Console() [2/3]

◆ Console() [3/3]

◆ ~Console()

Member Function Documentation

◆ Abort()

◆ AbortEnabled()

◆ AbortRequested()

◆ Clear()

◆ Critical()

◆ CriticalLn()

◆ DisableAbort()

◆ EnableAbort()

◆ ExecuteScript()

◆ ExecuteScriptGlobal()

◆ ExecuteScriptOn()

◆ Flush()

◆ Hide()

◆ IsCurrentThreadConsole()

◆ IsValid()

◆ Note()

◆ NoteLn()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReadChar()

◆ ReadString()

◆ ResetStatus()

◆ Show()

◆ Suspended()

◆ Waiting()

◆ Warning()

◆ WarningLn()

◆ Write()

◆ WriteLn() [1/2]

◆ WriteLn() [2/2]