API documentation and naming convention (#395)

* added api documentation

* api consistency improvement

* fixed documentation typos

* added pull request template

Author: willbelr

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,3 @@
+<!--- If this pull request is related to a change in the API, please       --->
+<!--- remember to update the documentation accordingly in README.md        --->
+

README.md

@@ -5,7 +5,7 @@
 A terminal emulator widget for Qt 5.
 
 QTermWidget is an open-source project originally based on the KDE4 Konsole application, but it took its own direction later on.
-The main goal of this project is to provide a unicode-enabled, embeddable Qt widget for using as a built-in console (or terminal emulation widget).
+The main goal of this project is to provide a Unicode-enabled, embeddable Qt widget for using as a built-in console (or terminal emulation widget).
 
 It is compatible with BSD, Linux and OS X.
 
@@ -78,3 +78,269 @@ Translations can be done in [LXQt-Weblate](https://translate.lxqt-project.org/pr
 <img src="https://translate.lxqt-project.org/widgets/lxqt-desktop/-/qtermwidget/multi-auto.svg" alt="Translation status" />
 </a>
 
+## API
+### Public Types
+Type | Variable
+| ---: | :---
+enum | ScrollBarPosition { NoScrollBar, ScrollBarLeft, ScrollBarRight }
+enum | KeyboardCursorShape { BlockCursor, UnderlineCursor, IBeamCursor }
+
+### Properties
+* flowControlEnabled : bool
+* getPtySlaveFd : const int
+* getShellPID : int
+* getTerminalFont : QFont
+* historyLinesCount : int
+* icon : const QString
+* keyBindings : QString
+* screenColumnsCount : int
+* selectedText(bool _preserveLineBreaks_ = true) : QString
+* sizeHint : const QSize
+* terminalSizeHint : bool
+* title : const QString
+* workingDirectory : QString
+
+### Public Functions
+Type | Function
+| ---: | :---
+| | QTermWidget(int _startnow_ = 1, QWidget *_parent_ = 0)
+virtual | ~QTermWidget()
+void | changeDir(const QString _&dir_)
+void | getSelectionEnd(int &_row_, int &_column_)
+void | getSelectionStart(int &_row_, int &_column_)
+void | scrollToEnd()
+void | sendText(QString &_text_)
+void | setArgs(QStringList &_args_)
+void | setAutoClose(bool _enabled_)
+void | setColorScheme(const QString &_name_)
+void | setEnvironment(const QStringList &_environment_)
+void | setFlowControlEnabled(bool _enabled_)
+void | setFlowControlWarningEnabled(bool _enabled_)
+void | setHistorySize(int _lines_)
+void | setKeyboardCursorShape(QTermWidget::KeyboardCursorShape _shape_)
+void | setMonitorActivity(bool _enabled_)
+void | setMonitorSilence(bool _enabled_)
+void | setMotionAfterPasting(int _action_)
+void | setScrollBarPosition(QTermWidget::ScrollBarPosition _pos_)
+void | setSelectionEnd(int _row_, int _column_)
+void | setSelectionStart(int _row_, int _column_)
+void | setShellProgram(const QString &_program_)
+void | setSilenceTimeout(int _seconds_)
+void | setTerminalFont(QFont &_font_)
+void | setTerminalOpacity(qreal _level_)
+void | setTerminalSizeHint(bool _enabled_)
+void | setTextCodec(QTextCodec *_codec_)
+void | setWorkingDirectory(const QString &_dir_)
+void | startShellProgram()
+void | startTerminalTeletype()
+
+### Public Slots
+Type | Function
+| ---: | :---
+void | copyClipboard()
+void | pasteClipboard()
+void | pasteSelection()
+void | zoomIn()
+void | zoomOut()
+void | setSize(_const QSize &_)
+void | setKeyBindings(const QString &_kb_)
+void | clear()
+void | toggleShowSearchBar()
+
+### Signals
+Type | Function
+| ---: | :---
+void | activity()
+void | bell(const QString &_message_)
+void | copyAvailable(bool)
+void | finished()
+void | profileChanged(const QString &_profile_)
+void | receivedData(const QString &_text_)
+void | sendData(const char*, int)
+void | silence()
+void | termGetFocus()
+void | termKeyPressed(QKeyEvent*)
+void | termLostFocus()
+void | titleChanged()
+void | urlActivated(const QUrl &, bool _fromContextMenu_)
+
+### Static Public Members
+Type | Function
+| ---: | :---
+static QStringList | availableColorSchemes()
+static QStringList | availableKeyBindings()
+static void | addCustomColorSchemeDir(const QString &*custom_dir*)
+
+### Protected Functions
+Type | Function
+| ---: | :---
+virtual void | resizeEvent(_QResizeEvent_*)
+
+### Protected Slots
+Type | Function
+| ---: | :---
+void | sessionFinished()
+void | selectionChanged(bool _textSelected_)
+
+### Member Type Documentation
+**enum QTermWidget::ScrollBarPosition**\
+This enum describes the location where the scroll bar is positioned in the display widget when calling QTermWidget::setScrollBarPosition().
+
+Constant | Value | Description
+| --- | :---: | --- |
+QTermWidget::NoScrollBar | 0x0 | Do not show the scroll bar.
+QTermWidget::ScrollBarLeft | 0x1 | Show the scroll bar on the left side of the display.
+QTermWidget::ScrollBarRight | 0x2 | Show the scroll bar on the right side of the display.
+
+\
+**enum QTermWidget::KeyboardCursorShape**\
+This enum describes the available shapes for the keyboard cursor when calling QTermWidget::setKeyboardCursorShape().
+
+Constant | Value | Description
+| --- | :---: | --- |
+QTermWidget::BlockCursor | 0x0 | A rectangular block which covers the entire area of the cursor character.
+QTermWidget::UnderlineCursor | 0x1 | A single flat line which occupies the space at the bottom of the cursor character's area.
+QTermWidget::IBeamCursor | 0x2 | A cursor shaped like the capital letter 'I', similar to the IBeam cursor used in Qt/KDE text editors.
+
+### Property Documentation
+**flowControlEnabled : bool**\
+Returns whether flow control is enabled.
+
+**getPtySlaveFd : const int**\
+Returns a pty slave file descriptor. This can be used for display and control a remote terminal.
+
+<!--**getShellPID : int**\-->
+<!--**getTerminalFont : QFont**\-->
+
+**historyLinesCount : int**\
+Returns the number of lines in the history buffer.
+
+<!--**icon : const QString**\-->
+
+**keyBindings : QString**\
+Returns current key bindings.
+
+<!--**screenColumnsCount : int**\-->
+
+**selectedText(bool _preserveLineBreaks_ = true) : QString**\
+Returns the currently selected text.
+
+<!--**sizeHint : const QSize**\-->
+<!--**terminalSizeHint : bool**\-->
+<!--**title : const QString**\-->
+<!--**workingDirectory : QString**\-->
+
+### Member Function Documentation
+<!--__void activity()__\-->
+<!--__void bell(const QString &_message_)__\-->
+
+__void changeDir(const QString _&dir_)__\
+Attempt to change shell directory (Linux only).
+
+__void clear()__\
+Clear the terminal content and move to home position.
+
+<!--__void copyAvailable(bool)__\-->
+
+__void copyClipboard()__\
+Copy selection to clipboard.
+
+<!--__void finished()__\-->
+<!--__void getSelectionEnd(int &_row_, int &_column_)__\-->
+<!--__void getSelectionStart(int &_row_, int &_column_)__\-->
+
+__void pasteClipboard()__\
+Paste clipboard to terminal.
+
+__void pasteSelection()__\
+Paste selection to terminal.
+
+<!--__void profileChanged(const QString &_profile_)__\-->
+
+__void receivedData(const QString &_text_)__\
+Signals that we received new data from the process running in the terminal emulator.
+
+__void scrollToEnd()__\
+Wrapped, scroll to end of text.
+
+__void sendData(const char*, int)__\
+Emitted when emulator send data to the terminal process (redirected for external recipient). It can be used for control and display the remote terminal.
+
+__void sendText(QString &_text_)__\
+Send text to terminal.
+
+__void setArgs(QStringList &_args_)__\
+Sets the shell program arguments, default is none.
+
+__void setAutoClose(bool _enabled_)__\
+Automatically close the terminal session after the shell process exits or keep it running.
+
+__void setColorScheme(const QString &_name_)__\
+Sets the color scheme, default is white on black.
+
+__void setEnvironment(const QStringList &_environment_)__\
+Sets environment variables.
+
+__void setFlowControlEnabled(bool _enabled_)__\
+Sets whether flow control is enabled.
+
+__void setFlowControlWarningEnabled(bool _enabled_)__\
+Sets whether the flow control warning box should be shown when the flow control stop key (Ctrl+S) is pressed.
+
+__void setHistorySize(int _lines_)__\
+History size for scrolling.
+
+__void setKeyBindings(const QString &_kb_)__\
+Set named key binding for given widget.
+
+__void setKeyboardCursorShape(QTermWidget::KeyboardCursorShape _shape_)__\
+Sets the shape of the keyboard cursor.  This is the cursor drawn at the position in the terminal where keyboard input will appear.
+
+<!--__void setMonitorActivity(bool _enabled_)__\-->
+<!--__void setMonitorSilence(bool _enabled_)__\-->
+<!--__void setMotionAfterPasting(int _action_)__\-->
+
+__void setScrollBarPosition(QTermWidget::ScrollBarPosition _pos_)__\
+Sets presence and position of scrollbar.
+
+<!--__void setSelectionEnd(int _row_, int _column_)__\-->
+<!--__void setSelectionStart(int _row_, int _column_)__\-->
+
+__void setShellProgram(const QString &_program_)__\
+Sets the shell program, default is /bin/bash.
+
+<!--__void setSilenceTimeout(int _seconds_)__\-->
+<!--__void setSize(_const QSize &_)__\-->
+
+__void setTerminalFont(QFont &_font_)__\
+Sets terminal font. Default is application font with family Monospace, size 10. Beware of a performance penalty and display/alignment issues when using a proportional font.
+
+<!--__void setTerminalOpacity(qreal _level_)__\-->
+
+__void setTerminalSizeHint(bool _enabled_)__\
+Exposes TerminalDisplay::TerminalSizeHint.
+
+__void setTextCodec(QTextCodec *_codec_)__\
+Sets text codec, default is UTF-8.
+
+<!--__void setWorkingDirectory(const QString &_dir_)__\-->
+<!--__void silence()__\-->
+
+__void startShellProgram()__\
+Starts shell program if it was not started in constructor.
+
+__void startTerminalTeletype()__\
+Starts terminal teletype as is and redirect data for external recipient. It can be used for display and control a remote terminal.
+
+<!--__void termGetFocus()__\-->
+<!--__void termKeyPressed(QKeyEvent*)__\-->
+<!--__void termLostFocus()__\-->
+<!--__void titleChanged()__\-->
+<!--__void toggleShowSearchBar()__\-->
+<!--__void urlActivated(const QUrl &, bool _fromContextMenu_)__\-->
+
+__void zoomIn()__\
+Zooms in on the text.
+
+__void zoomOut()__\
+Zooms out in on the text.

lib/qtermwidget.cpp

@@ -227,9 +227,9 @@ QSize QTermWidget::sizeHint() const
     return size;
 }
 
-void QTermWidget::setTerminalSizeHint(bool on)
+void QTermWidget::setTerminalSizeHint(bool enabled)
 {
-    m_impl->m_terminalDisplay->setTerminalSizeHint(on);
+    m_impl->m_terminalDisplay->setTerminalSizeHint(enabled);
 }
 
 bool QTermWidget::terminalSizeHint()
@@ -379,11 +379,11 @@ void QTermWidget::setTerminalBackgroundMode(int mode)
     m_impl->m_terminalDisplay->setBackgroundMode((Konsole::BackgroundMode)mode);
 }
 
-void QTermWidget::setShellProgram(const QString &progname)
+void QTermWidget::setShellProgram(const QString &program)
 {
     if (!m_impl->m_session)
         return;
-    m_impl->m_session->setProgram(progname);
+    m_impl->m_session->setProgram(program);
 }
 
 void QTermWidget::setWorkingDirectory(const QString& dir)
@@ -689,14 +689,14 @@ QString QTermWidget::selectedText(bool preserveLineBreaks)
     return m_impl->m_terminalDisplay->screenWindow()->screen()->selectedText(preserveLineBreaks);
 }
 
-void QTermWidget::setMonitorActivity(bool monitor)
+void QTermWidget::setMonitorActivity(bool enabled)
 {
-    m_impl->m_session->setMonitorActivity(monitor);
+    m_impl->m_session->setMonitorActivity(enabled);
 }
 
-void QTermWidget::setMonitorSilence(bool monitor)
+void QTermWidget::setMonitorSilence(bool enabled)
 {
-    m_impl->m_session->setMonitorSilence(monitor);
+    m_impl->m_session->setMonitorSilence(enabled);
 }
 
 void QTermWidget::setSilenceTimeout(int seconds)
@@ -767,9 +767,9 @@ bool QTermWidget::isTitleChanged() const
     return m_impl->m_session->isTitleChanged();
 }
 
-void QTermWidget::setAutoClose(bool autoClose)
+void QTermWidget::setAutoClose(bool enabled)
 {
-    m_impl->m_session->setAutoClose(autoClose);
+    m_impl->m_session->setAutoClose(enabled);
 }
 
 void QTermWidget::cursorChanged(Konsole::Emulation::KeyboardCursorShape cursorShape, bool blinkingCursorEnabled)

lib/qtermwidget.h

@@ -62,7 +62,7 @@ class QTERMWIDGET_EXPORT QTermWidget : public QWidget {
     QSize sizeHint() const override;
 
     // expose TerminalDisplay::TerminalSizeHint, setTerminalSizeHint
-    void setTerminalSizeHint(bool on);
+    void setTerminalSizeHint(bool enabled);
     bool terminalSizeHint();
 
     //start shell program if it was not started in constructor
@@ -94,7 +94,7 @@ class QTERMWIDGET_EXPORT QTermWidget : public QWidget {
     void setEnvironment(const QStringList & environment);
 
     //  Shell program, default is /bin/bash
-    void setShellProgram(const QString & progname);
+    void setShellProgram(const QString & program);
 
     //working directory
     void setWorkingDirectory(const QString & dir);