Class SBGUIPlainTextEdit#

The SBGUIPlainTextEdit class extends QFrame to include a QPlainTextEdit with additional features.More...

#include <SBGUIPlainTextEdit.hpp>

Inherits the following classes: QFrame, SBGUIPlainTextEditGUI

Public Signals#

Type	Name
signal void	committed (const QString & text) Emitted when the text is committed. This signal is triggered when the user finalizes their input, which could be through an explicit commit action (e.g., pressing an Enter key or a dedicated button). It signifies that the pending changes have been accepted and the internal state of the text should be updated to reflect this.
signal void	discarded (const QString & text) Emitted when changes to the text are discarded. This signal is triggered when the user decides to revert their input back to the last committed state. This is useful in scenarios where temporary modifications to text are allowed but the user opts to cancel these changes.
signal void	limitExceeded (int value) Emitted when the text exceeds the set character limit. This signal is triggered when an attempt is made to input more characters than the current limit allows. It can be used to provide feedback to the user, such as displaying a warning message or altering the visual state of the input field to indicate an error.
signal void	originalValueChanged (const QString & text) Emitted whenever the original value of the text changes. This signal is useful for tracking changes to the baseline state of the text input. It can be used to monitor resets or updates to the original text from which changes are being made.
signal void	pendingValueChanged (const QString & text) Emitted whenever the pending value of the text changes. This signal provides a hook for external components to react to changes in the staged (pending) text. It is useful for enabling or disabling UI components based on whether there are uncommitted changes in the input field.

Public Functions#

Type	Name
	SBGUIPlainTextEdit (QWidget * parent=nullptr, int characterLimit=-1) Constructs a new SBGUIPlainTextEdit widget.
bool	charLimitValid () const Checks whether the text changes are ok with the limit.
int	getCharLimit () const Retrieves the current character limit for the QPlainTextEdit.
QString	getOriginalValue () const Returns the original value of the text.
QString	getPendingValue () const Returns the pending value of the text.
QPlainTextEdit *	getPlainTextEdit () const Retrieves a pointer to the internal QPlainTextEdit.
bool	isCommittable () const Checks whether the text changes are committable.
void	keyPressEvent (QKeyEvent * event) Custom key event handler that manages key press events for commit and discard operations.
void	setCharLimit (int characterLimit=-1) Sets the character limit for the QPlainTextEdit.
void	setCommittable (bool committable=true) Enables or disables the ability to commit changes.
void	setOriginalValue (const QString & value) Sets the original value of the text.
void	setPendingValue (const QString & value) Sets the pending value of the text, which is the value staged for commit.
void	setPlainText (const QString & text) Sets the text displayed in the QPlainTextEdit, respecting the character limit if set.
void	setValues (const QString & originValue, const QString & pendingValue) Sets both the original and pending values at once.
QString	toLimitedPlainText () const Returns the text trimmed to the current character limit.
QString	toPlainText () const Returns the text currently displayed in the QPlainTextEdit.

Protected Functions#

Type	Name
void	resizeEvent (QResizeEvent * event) override Handles the resize event to update the layout and appearance of the widget.

Detailed Description#

This class supports character limits, commit/discard mechanisms, and the handling of "original" and "pending" text values. It is useful for input fields where changes can be staged and either committed or discarded.

Short name: SBPlainTextEdit

Example Usage:

textEdit *lineEdit = new SBGUIPlainTextEdit(0, 50); // 50 character limit
textEdit->setPlainText("Hello world");
lineEdit->setCommittable(true);

Note:

This class also emits signals when text is committed or discarded, providing hooks for further action.

Public Signals Documentation#

signal committed#

Emitted when the text is committed. This signal is triggered when the user finalizes their input, which could be through an explicit commit action (e.g., pressing an Enter key or a dedicated button). It signifies that the pending changes have been accepted and the internal state of the text should be updated to reflect this.

void committed;

Parameters:

text The text that was committed. This is typically the content that was pending and has now been confirmed.

signal discarded#

Emitted when changes to the text are discarded. This signal is triggered when the user decides to revert their input back to the last committed state. This is useful in scenarios where temporary modifications to text are allowed but the user opts to cancel these changes.

void discarded;

Parameters:

text The text that was discarded. This could reflect the content that was pending before being reverted to the original.

signal limitExceeded#

Emitted when the text exceeds the set character limit. This signal is triggered when an attempt is made to input more characters than the current limit allows. It can be used to provide feedback to the user, such as displaying a warning message or altering the visual state of the input field to indicate an error.

void limitExceeded;

Parameters:

value The character limit that has been exceeded. This is the maximum number of characters that were set as allowable.

signal originalValueChanged#

Emitted whenever the original value of the text changes. This signal is useful for tracking changes to the baseline state of the text input. It can be used to monitor resets or updates to the original text from which changes are being made.

void originalValueChanged;

Parameters:

text The new original text. This reflects the baseline or committed state of the text to which any new changes will be compared.

signal pendingValueChanged#

Emitted whenever the pending value of the text changes. This signal provides a hook for external components to react to changes in the staged (pending) text. It is useful for enabling or disabling UI components based on whether there are uncommitted changes in the input field.

void pendingValueChanged;

Parameters:

text The new pending text. This text is the current content of the QPlainTextEdit that has not yet been committed.

Public Functions Documentation#

function SBGUIPlainTextEdit#

Constructs a new SBGUIPlainTextEdit widget.

explicit SBGUIPlainTextEdit::SBGUIPlainTextEdit (
    QWidget * parent=nullptr,
    int characterLimit=-1
)

Parameters:

parent The parent widget of this line edit, typically a form or another container.
characterLimit Initial character limit, defaults to -1 (no limit).

function charLimitValid#

Checks whether the text changes are ok with the limit.

bool SBGUIPlainTextEdit::charLimitValid () const

Returns:

True if pending text length is below the limit.

function getCharLimit#

Retrieves the current character limit for the QPlainTextEdit.

int SBGUIPlainTextEdit::getCharLimit () const

Returns:

The current character limit; returns -1 if no limit is set.

function getOriginalValue#

Returns the original value of the text.

QString SBGUIPlainTextEdit::getOriginalValue () const

Returns:

The original text before any edits were made.

function getPendingValue#

Returns the pending value of the text.

QString SBGUIPlainTextEdit::getPendingValue () const

Returns:

The pending text that is staged for commit.

function getPlainTextEdit#

Retrieves a pointer to the internal QPlainTextEdit.

QPlainTextEdit * SBGUIPlainTextEdit::getPlainTextEdit () const

Returns:

Pointer to the encapsulated QPlainTextEdit object.

function isCommittable#

Checks whether the text changes are committable.

bool SBGUIPlainTextEdit::isCommittable () const

Returns:

True if changes can be committed, otherwise false.

function keyPressEvent#

Custom key event handler that manages key press events for commit and discard operations.

void SBGUIPlainTextEdit::keyPressEvent (
    QKeyEvent * event
)

Parameters:

event The QKeyEvent triggered by key presses.

function setCharLimit#

Sets the character limit for the QPlainTextEdit.

void SBGUIPlainTextEdit::setCharLimit (
    int characterLimit=-1
)

Parameters:

characterLimit The maximum number of characters allowed; set to -1 for no limit.

function setCommittable#

Enables or disables the ability to commit changes.

void SBGUIPlainTextEdit::setCommittable (
    bool committable=true
)

Parameters:

committable Set to true to allow committing changes, false to disable.

function setOriginalValue#

Sets the original value of the text.

void SBGUIPlainTextEdit::setOriginalValue (
    const QString & value
)

Parameters:

value The text to set as the original value.

function setPendingValue#

Sets the pending value of the text, which is the value staged for commit.

void SBGUIPlainTextEdit::setPendingValue (
    const QString & value
)

Parameters:

value The text to set as the pending value.

function setPlainText#

Sets the text displayed in the QPlainTextEdit, respecting the character limit if set.

void SBGUIPlainTextEdit::setPlainText (
    const QString & text
)

Parameters:

text The text to set in the line edit.

function setValues#

Sets both the original and pending values at once.

void SBGUIPlainTextEdit::setValues (
    const QString & originValue,
    const QString & pendingValue
)

Parameters:

originValue The text for the original value.
pendingValue The text for the pending value.

function toLimitedPlainText#

Returns the text trimmed to the current character limit.

QString SBGUIPlainTextEdit::toLimitedPlainText () const

Returns:

A QString of the text limited by the current character count.

function toPlainText#

Returns the text currently displayed in the QPlainTextEdit.

QString SBGUIPlainTextEdit::toPlainText () const

Returns:

A QString containing the current text.

Protected Functions Documentation#

function resizeEvent#

Handles the resize event to update the layout and appearance of the widget.

void SBGUIPlainTextEdit::resizeEvent (
    QResizeEvent * event
) override

Parameters:

event The resize event information.