From 7434787d99b1737865dc35e17f4d71fc00de2395 Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Wed, 18 Dec 2024 14:52:23 -0500 Subject: [PATCH 01/11] Add breaklines and changes to the widgets' section --- docs/qt_introduction.md | 78 +++++++++++++++++++++++++++++++++-------- 1 file changed, 63 insertions(+), 15 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 47e8b3f..c86697e 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -3,18 +3,31 @@ # Qt Fundamentals -**Qt** is a multiplatform widget toolkit for creating native graphical user interfaces. Qt is also a very complete development framework that offers utilities for building applications, and libraries of extensions for Networking, Bluetooth, Charts, 3D rendering, Navigation (as GPS), among others. +[Qt](https://www.qt.io/) is an open source, multiplatform toolkit for creating graphical user interfaces. +Qt is also a complete development framework that offers utilities for building applications and libraries of extensions for networking, Bluetooth, charts, 3D rendering, navigation, among others. +Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. -## Basic Qt Components +To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. +Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. +The following sections describe with more detail some QT components and their main functions. -As mentioned before, Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. +## Basic Qt Components -To develop a GUI we will add graphical elements of interaction known as widgets, arrange them using layouts. Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. In the following, we will develop these ideas in more detail. +According to the official [Qt documentation](https://doc.qt.io/qtdesignstudio/quick-components.html): "a component is a reusable building block for a UI". +Qt has some preset components that can include simple representations (shapes, text or images) or complex UI controls (such as sliders). Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. -The core component of Qt is the ``QApplication`` class. Every Qt application needs a single instance of this class as the base, from where the Qt *event loop* is controlled. + Below, we list some of the Qt components that are related with the plugin development??? + +### QApplication ### + +The core component of Qt is the ``QApplication`` class. +This class manages the GUI application's control flow and main settings. +It is important to know that any GUI application using QT requires to have only one QApplication object. This is applicable no matter how many windows the application has any given time. +Due to the QApplication object is in charge to do different initializations, it must be created before any other objects related to the user interface. + Spyder itself is an instance of ``QApplication``, its starting point is in the following two lines of code (Spyder/Spyder/app/mainwindow.py): ```python @@ -22,24 +35,56 @@ Spyder itself is an instance of ``QApplication``, its starting point is in the f qapp = QApplication.instance() ``` -``QMainWindow`` is a pre-built widget that provides many standard window features as toolbars, menus, a status bar, dockable widgets and more, which serves as the basis for the application. + Every Qt application needs a single instance of this class as the base, from where the Qt *event loop* is controlled. + +QApplication has some responsabilities such as, it: +- Initializes the application with the user's desktop settings. +- Receives events from the underlying window system and transmits them to the applicable widgets. +- Defines the application's appearance. +- Knows the application's windows. For example, you can request which widget is in a specific position using widgetAt(). + +For more details, you can refer to the official documentation in the [QApplication website](https://doc.qt.io/qt-6/qapplication.html#details). + +### QMainWindow ### + +``QMainWindow`` class provides a main application window and it has its own layout in which you can include toolbars (QToolBars), menus (QMenuBar), status bars (QStatusBar), and dockable widgets (QDockWidgets). + +These features serve as the basis for an application. + +How the QMainWindow is related to the QApplication? + +For more details, you can refer to the official documentation in the [QMainWindow website](https://doc.qt.io/qt-6/qmainwindow.html#details) ### Signals & Slots -**Signals** are notifications emitted by widgets when something happens. That something could be different things, from pressing a button, to changing text in an input box, to changing text in the window. - Many signals are initiated by user action, but this is not a rule. +In the GUI programming is important to provide a way to communicate objects through notifications. +In Qt, signals and slots are used to support this communication. -**Slots** are signal receivers. Functions or methods could be used as slots, by connecting a signal to them. -If a signal sends data, the receiver callable will also receive it. +**Signal** is a notification emitted by a widget when a particular event ocurrs. +Example of these events includes: pressing a button, changing text in an input box, changing text in the window. +Many signals are initiated by an user action, but this is not a rule. +Qt's widgets have different predermined signals, but you can add your own signals to the widgets. + +**Slot** is a function that is invoked in response to a specific signal. +Functions or methods could be used as slots, by connecting a signal to them. +If a signal sends data, the receiver callable will also receive it. Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. +Qt's widgets have many pre-defined slots, but it is usual practice to subclass widgets and add your own slots. +For more details, you can refer to the official documentation in the [Signals and slots website](https://doc.qt.io/qt-6/signalsandslots.html) ### Widgets -In computer science a *Widget* is a shortened form of “window gadget”. A widget is an element of interaction, such as a button, or a container for other widgets, as panels or tabs. -The ``QWidget`` class is the fundamental class for creating interfaces in Qt, it receives events from the window system, and renders its representation on the screen. A widget can provide a container for grouping other widgets, and if it is not embedded in a parent widget, it becomes a window. +In computer science a *Widget* is a shortened form of “window gadget”. +A widget is an element of interaction, such as a button, or a container for other widgets, as panels or tabs. + +"Widgets are the primary elements for creating user interfaces in Qt. Widgets can display data and status information, receive user input, and provide a container for other widgets that should be grouped together. A widget that is not embedded in a parent widget is called a window." (https://doc.qt.io/qt-6/qtwidgets-index.html) + +The ``QWidget`` class is the fundamental class for creating interfaces in Qt, it receives events from the window system, and renders its representation on the screen. +A widget can provide a container for grouping other widgets, and if it is not embedded in a parent widget, it becomes a window. +"The QWidget class provides the basic capability to render to the screen and to handle user input events. All UI elements that Qt provides are either subclasses of QWidget or are used in connection with a QWidget subclass. To create custom widgets, subclass QWidget or a suitable subclass and reimplement the virtual event handlers." ### Layouts @@ -51,13 +96,15 @@ Those are the 4 basic layouts available in Qt: ``QHBoxLayout``, ``QVBoxLayout``, ### Actions, Toolbars & Menus -User interfaces of desktop applications usually use ``QToolbar`` and ``QMenu``. Since these are alternative ways to access the same functionality, Qt provides ``QAction`` as a way to avoid duplication of functions. +User interfaces of desktop applications usually use ``QToolbar`` and ``QMenu``. +Since these are alternative ways to access the same functionality, Qt provides ``QAction`` as a way to avoid duplication of functions. Thus, each time a menu option or a toolbar button gives access to the same function, they point to the same action. ### Dialogs -A *Dialog* is a GUI component that communicates with the user. Dialogs are commonly used for functions that do not fit into the main interface. +A *Dialog* is a GUI component that communicates with the user. +Dialogs are commonly used for functions that do not fit into the main interface. In Qt, by design ``QDialog`` is a modal (or blocking) window that show in front of the main Window until it is dismissed. Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. @@ -71,5 +118,6 @@ These are used for tasks that happen in parallel over long-running processes suc ### Events -An *Event* denote every interaction the user has with a Qt application. There are several types of events designed to address different types of interactions. +An *Event* denote every interaction the user has with a Qt application. +There are several types of events designed to address different types of interactions. In Qt they are represented by ``QEvent`` instances that contain information about what prompted them, and are passed to specific handlers that are responsible for triggering further actions. From 3b96b95d6042c1ac0f8cad4ec355e55af85122cc Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Wed, 18 Dec 2024 15:07:55 -0500 Subject: [PATCH 02/11] Remove QApplication component --- docs/qt_introduction.md | 33 +++++---------------------------- 1 file changed, 5 insertions(+), 28 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index c86697e..dadcfda 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -3,13 +3,13 @@ # Qt Fundamentals -[Qt](https://www.qt.io/) is an open source, multiplatform toolkit for creating graphical user interfaces. +[Qt](https://www.qt.io/) is an open source, multiplatform toolkit for creating graphical user interfaces (GUI). Qt is also a complete development framework that offers utilities for building applications and libraries of extensions for networking, Bluetooth, charts, 3D rendering, navigation, among others. -Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. - To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. + +Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. The following sections describe with more detail some QT components and their main functions. ## Basic Qt Components @@ -19,31 +19,8 @@ Qt has some preset components that can include simple representations (shapes, t Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. - Below, we list some of the Qt components that are related with the plugin development??? - -### QApplication ### - -The core component of Qt is the ``QApplication`` class. -This class manages the GUI application's control flow and main settings. -It is important to know that any GUI application using QT requires to have only one QApplication object. This is applicable no matter how many windows the application has any given time. -Due to the QApplication object is in charge to do different initializations, it must be created before any other objects related to the user interface. - -Spyder itself is an instance of ``QApplication``, its starting point is in the following two lines of code (Spyder/Spyder/app/mainwindow.py): - - ```python - QMainWindow.__init__(self) - qapp = QApplication.instance() - ``` - - Every Qt application needs a single instance of this class as the base, from where the Qt *event loop* is controlled. - -QApplication has some responsabilities such as, it: -- Initializes the application with the user's desktop settings. -- Receives events from the underlying window system and transmits them to the applicable widgets. -- Defines the application's appearance. -- Knows the application's windows. For example, you can request which widget is in a specific position using widgetAt(). - -For more details, you can refer to the official documentation in the [QApplication website](https://doc.qt.io/qt-6/qapplication.html#details). +Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. +Below, we list some of the Qt components that are related with Spyder and its plugins. ### QMainWindow ### From 39a4cfd6fc712fe5ee39b5dd7a2a0eabed5336e2 Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Wed, 18 Dec 2024 15:43:53 -0500 Subject: [PATCH 03/11] Reorganize titles and content. --- docs/qt_introduction.md | 52 ++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index dadcfda..9758840 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -9,7 +9,6 @@ Qt is also a complete development framework that offers utilities for building a To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. -Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. The following sections describe with more detail some QT components and their main functions. ## Basic Qt Components @@ -20,36 +19,21 @@ Qt has some preset components that can include simple representations (shapes, t Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. -Below, we list some of the Qt components that are related with Spyder and its plugins. - -### QMainWindow ### - -``QMainWindow`` class provides a main application window and it has its own layout in which you can include toolbars (QToolBars), menus (QMenuBar), status bars (QStatusBar), and dockable widgets (QDockWidgets). -These features serve as the basis for an application. - -How the QMainWindow is related to the QApplication? +Some of these Qt components are explained below. -For more details, you can refer to the official documentation in the [QMainWindow website](https://doc.qt.io/qt-6/qmainwindow.html#details) +### MainWindow ### +``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). -### Signals & Slots - -In the GUI programming is important to provide a way to communicate objects through notifications. -In Qt, signals and slots are used to support this communication. +These features serve as the basis for an application. -**Signal** is a notification emitted by a widget when a particular event ocurrs. -Example of these events includes: pressing a button, changing text in an input box, changing text in the window. -Many signals are initiated by an user action, but this is not a rule. -Qt's widgets have different predermined signals, but you can add your own signals to the widgets. +For more details, you can refer to the official Qt documentation [MainWindow](https://doc.qt.io/qt-6/qmainwindow.html#details) -**Slot** is a function that is invoked in response to a specific signal. -Functions or methods could be used as slots, by connecting a signal to them. -If a signal sends data, the receiver callable will also receive it. -Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. -Qt's widgets have many pre-defined slots, but it is usual practice to subclass widgets and add your own slots. +### Windows -For more details, you can refer to the official documentation in the [Signals and slots website](https://doc.qt.io/qt-6/signalsandslots.html) +If an application requires additional windows that do not block the main window, these are generated as non-parent ``QWidget`` instances. +These are used for tasks that happen in parallel over long-running processes such as displaying graphs or document editing. ### Widgets @@ -69,8 +53,6 @@ Interfaces are built by embedding widgets inside widgets, and since they are vis A layout indicates how the widgets fill their container, either as columns, rows, cells in a matrix or stacked so that only one is visible at a time. Those are the 4 basic layouts available in Qt: ``QHBoxLayout``, ``QVBoxLayout``, ``QGridLayout``, and ``QStackedLayout``. - - ### Actions, Toolbars & Menus User interfaces of desktop applications usually use ``QToolbar`` and ``QMenu``. @@ -86,11 +68,23 @@ In Qt, by design ``QDialog`` is a modal (or blocking) window that show in front Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. +### Signals & Slots -### Windows +In the GUI programming is important to provide a way to communicate objects through notifications. +In Qt, signals and slots are used to support this communication. -If an application requires additional windows that do not block the main window, these are generated as non-parent ``QWidget`` instances. -These are used for tasks that happen in parallel over long-running processes such as displaying graphs or document editing. +**Signal** is a notification emitted by a widget when a particular event ocurrs. +Example of these events includes: pressing a button, changing text in an input box, changing text in the window. +Many signals are initiated by an user action, but this is not a rule. +Qt's widgets have different predermined signals, but you can add your own signals to the widgets. + +**Slot** is a function that is invoked in response to a specific signal. +Functions or methods could be used as slots, by connecting a signal to them. +If a signal sends data, the receiver callable will also receive it. +Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. +Qt's widgets have many pre-defined slots, but it is usual practice to subclass widgets and add your own slots. + +For more details, you can refer to the official documentation in the [Signals and slots website](https://doc.qt.io/qt-6/signalsandslots.html) ### Events From 4e32df8e055da605c36526a53fc1f6e380b3f5b5 Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Wed, 18 Dec 2024 16:58:27 -0500 Subject: [PATCH 04/11] Improving the "Windows" and "Widgets" sections --- docs/qt_introduction.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 9758840..d514843 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -14,7 +14,7 @@ The following sections describe with more detail some QT components and their ma ## Basic Qt Components According to the official [Qt documentation](https://doc.qt.io/qtdesignstudio/quick-components.html): "a component is a reusable building block for a UI". -Qt has some preset components that can include simple representations (shapes, text or images) or complex UI controls (such as sliders). +Qt has some preset components that can include simple representations (shapes, text or images) or complex user interface (UI) controls (such as sliders). Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. @@ -26,26 +26,31 @@ Some of these Qt components are explained below. ``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). -These features serve as the basis for an application. - For more details, you can refer to the official Qt documentation [MainWindow](https://doc.qt.io/qt-6/qmainwindow.html#details) ### Windows -If an application requires additional windows that do not block the main window, these are generated as non-parent ``QWidget`` instances. -These are used for tasks that happen in parallel over long-running processes such as displaying graphs or document editing. +A window is a widget that is not embedded in a parent widget. +When an application requires additional windows, which do not block the main window, they can be generated as non-parent ``QWidget`` instances. +These are used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. ### Widgets -In computer science a *Widget* is a shortened form of “window gadget”. -A widget is an element of interaction, such as a button, or a container for other widgets, as panels or tabs. +Widgets are the main elements for creating a UI in Qt. +They can present data and updated information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. + +``QWidget`` is the fundamental class in Qt that provides the capability to handleuser input events and renders its representation on the screen. + +All UI elements provided by Qt are subclasses of QWidget or are used in connection with a QWidget subclass. -"Widgets are the primary elements for creating user interfaces in Qt. Widgets can display data and status information, receive user input, and provide a container for other widgets that should be grouped together. A widget that is not embedded in a parent widget is called a window." (https://doc.qt.io/qt-6/qtwidgets-index.html) +You can define your own custom widgets by creating a QWidget or a suitable subclass, and reimplement the virtual event handlers. -The ``QWidget`` class is the fundamental class for creating interfaces in Qt, it receives events from the window system, and renders its representation on the screen. -A widget can provide a container for grouping other widgets, and if it is not embedded in a parent widget, it becomes a window. +There are top-level and child widgets. +The first one is a widget without a parent and it is an independent window. +The second one is a non-window widget, which is displayed within its parent widget. +Most widgets in Qt are mainly useful as child widgets. -"The QWidget class provides the basic capability to render to the screen and to handle user input events. All UI elements that Qt provides are either subclasses of QWidget or are used in connection with a QWidget subclass. To create custom widgets, subclass QWidget or a suitable subclass and reimplement the virtual event handlers." +For more details, you can refer to the official Qt documentation [QWidget](https://doc.qt.io/qt-6/qwidget.html). ### Layouts From 08256ab89c46e2d809bd4c2fdc11ff2168d71bfd Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Fri, 20 Dec 2024 12:02:31 -0500 Subject: [PATCH 05/11] Improve the "Layouts" and "Actions, Toolbars & Menus" sections --- docs/qt_introduction.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index d514843..3fb5ad8 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -39,7 +39,7 @@ These are used for parallel tasks that take place in long-running processes, suc Widgets are the main elements for creating a UI in Qt. They can present data and updated information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. -``QWidget`` is the fundamental class in Qt that provides the capability to handleuser input events and renders its representation on the screen. +``QWidget`` is the fundamental class in Qt that provides the capability to handle user input events and renders its representation on the screen. All UI elements provided by Qt are subclasses of QWidget or are used in connection with a QWidget subclass. @@ -54,16 +54,22 @@ For more details, you can refer to the official Qt documentation [QWidget](https ### Layouts -Interfaces are built by embedding widgets inside widgets, and since they are visual components they are visually organized by means of *layouts*. -A layout indicates how the widgets fill their container, either as columns, rows, cells in a matrix or stacked so that only one is visible at a time. -Those are the 4 basic layouts available in Qt: ``QHBoxLayout``, ``QVBoxLayout``, ``QGridLayout``, and ``QStackedLayout``. +Qt layout system provides a way to arrange and distribute automatically child widgets within a widget taking advantage of the available space. +This layout system can automatically position and resize widgets when the space available for them changes, ensuring that the user interface remains usable. +You can use the built-in layout managers to organize your widgets:[QHBoxLayout](https://doc.qt.io/qt-6/qhboxlayout.html), [QVBoxLayout](https://doc.qt.io/qt-6/qvboxlayout.html), [QGridLayout](https://doc.qt.io/qt-6/qgridlayout.html), [QFormLayoutClass](https://doc.qt.io/qt-6/qformlayout.html),and [QStackedLayout](https://doc.qt.io/qt-6/qstackedlayout.html). +For more details, you can refer to the official Qt documentation [Layout Management](https://doc.qt.io/qt-6/layout.html). ### Actions, Toolbars & Menus -User interfaces of desktop applications usually use ``QToolbar`` and ``QMenu``. -Since these are alternative ways to access the same functionality, Qt provides ``QAction`` as a way to avoid duplication of functions. -Thus, each time a menu option or a toolbar button gives access to the same function, they point to the same action. - +User interfaces of desktop applications usually use toolbars and menus. +A toolbar is a GUI element that facilites the acces of functions and controls commonly used in an app. +It can include elements such as buttons, menus, iceons, and search fields. +It is usually located at the top or bottom of a window. +A menu is a GUI element that presents a list of options to a user. +Qt provides the [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt-6/qmenu.html) classes. +Since QToolBar and QMenu are alternative ways to access the same functionality, Qt provides [QAction](https://doc.qt.io/qt-6/qaction.html) as a way to avoid duplication of functions. +Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI in sync. +For example, in a word processor, if the user presses a button on the Bold toolbar, the Bold menu item will be automatically checked. ### Dialogs From 0c4b7382711a4d2269c94a16f8af83950eca174f Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Fri, 20 Dec 2024 16:31:45 -0500 Subject: [PATCH 06/11] Improve the "Actions, Toolbars & Menus" and "Dialogs" sections --- docs/qt_introduction.md | 39 ++++++++++++++++++++------------------- 1 file changed, 20 insertions(+), 19 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 3fb5ad8..365b8bd 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -9,22 +9,18 @@ Qt is also a complete development framework that offers utilities for building a To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. -The following sections describe with more detail some QT components and their main functions. - ## Basic Qt Components According to the official [Qt documentation](https://doc.qt.io/qtdesignstudio/quick-components.html): "a component is a reusable building block for a UI". Qt has some preset components that can include simple representations (shapes, text or images) or complex user interface (UI) controls (such as sliders). - Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. - Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. -Some of these Qt components are explained below. +The following sections describe with more detail some QT components and their main functions. ### MainWindow ### -``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). +``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). For more details, you can refer to the official Qt documentation [MainWindow](https://doc.qt.io/qt-6/qmainwindow.html#details) @@ -40,9 +36,7 @@ Widgets are the main elements for creating a UI in Qt. They can present data and updated information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. ``QWidget`` is the fundamental class in Qt that provides the capability to handle user input events and renders its representation on the screen. - All UI elements provided by Qt are subclasses of QWidget or are used in connection with a QWidget subclass. - You can define your own custom widgets by creating a QWidget or a suitable subclass, and reimplement the virtual event handlers. There are top-level and child widgets. @@ -55,29 +49,36 @@ For more details, you can refer to the official Qt documentation [QWidget](https ### Layouts Qt layout system provides a way to arrange and distribute automatically child widgets within a widget taking advantage of the available space. -This layout system can automatically position and resize widgets when the space available for them changes, ensuring that the user interface remains usable. +This layout system can automatically position and resize widgets when the space available for them changes, ensuring that the UI remains usable. You can use the built-in layout managers to organize your widgets:[QHBoxLayout](https://doc.qt.io/qt-6/qhboxlayout.html), [QVBoxLayout](https://doc.qt.io/qt-6/qvboxlayout.html), [QGridLayout](https://doc.qt.io/qt-6/qgridlayout.html), [QFormLayoutClass](https://doc.qt.io/qt-6/qformlayout.html),and [QStackedLayout](https://doc.qt.io/qt-6/qstackedlayout.html). + For more details, you can refer to the official Qt documentation [Layout Management](https://doc.qt.io/qt-6/layout.html). ### Actions, Toolbars & Menus User interfaces of desktop applications usually use toolbars and menus. -A toolbar is a GUI element that facilites the acces of functions and controls commonly used in an app. -It can include elements such as buttons, menus, iceons, and search fields. +A toolbar is a GUI element that facilites acces to commonly used functions and controls in an application. +It can include elements such as buttons, menus, icons, and search fields. It is usually located at the top or bottom of a window. -A menu is a GUI element that presents a list of options to a user. +A menu is a GUI element that presents a list of options to the user. Qt provides the [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt-6/qmenu.html) classes. -Since QToolBar and QMenu are alternative ways to access the same functionality, Qt provides [QAction](https://doc.qt.io/qt-6/qaction.html) as a way to avoid duplication of functions. -Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI in sync. +Since QToolBar and QMenu are alternative ways to access the same functionality, Qt includes [QAction](https://doc.qt.io/qt-6/qaction.html) as a way to avoid duplication of functions. +Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI syncronized. For example, in a word processor, if the user presses a button on the Bold toolbar, the Bold menu item will be automatically checked. ### Dialogs -A *Dialog* is a GUI component that communicates with the user. -Dialogs are commonly used for functions that do not fit into the main interface. -In Qt, by design ``QDialog`` is a modal (or blocking) window that show in front of the main Window until it is dismissed. +A Dialog is a GUI component used for brief communications with the user. +Dialogs are commonly used for functions that do not fit into the main interface. +A dialog can be included in an application using the QDialog class. +QDialogs may be modal or modeless. +A modal dialog blocks input to other visible windows in the same application. +The user has to end the interaction with the modal dialog and close it to access to any other window in the application. +For example, dialogs for requesting information or selecting preferences for an application may be modal. +A modeless dialog operates independently of other windows of the same application. +For example, find and replace dialogs allow the user to interact with both the modeless dialog and the application's main window. -Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. +Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. ### Signals & Slots @@ -95,7 +96,7 @@ Qt's widgets have different predermined signals, but you can add your own signal Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. Qt's widgets have many pre-defined slots, but it is usual practice to subclass widgets and add your own slots. -For more details, you can refer to the official documentation in the [Signals and slots website](https://doc.qt.io/qt-6/signalsandslots.html) +For more details, you can refer to the official Qt documentation [Signals and slots](https://doc.qt.io/qt-6/signalsandslots.html) ### Events From 01e1e0c541f56f14f1b4c2022e1488c397740080 Mon Sep 17 00:00:00 2001 From: yeimiyaz Date: Fri, 20 Dec 2024 17:22:35 -0500 Subject: [PATCH 07/11] Improve the "Signals & Slots" and "Events" sections --- docs/qt_introduction.md | 36 ++++++++++++++++++++++++------------ 1 file changed, 24 insertions(+), 12 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 365b8bd..37291b9 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -9,6 +9,7 @@ Qt is also a complete development framework that offers utilities for building a To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. + ## Basic Qt Components According to the official [Qt documentation](https://doc.qt.io/qtdesignstudio/quick-components.html): "a component is a reusable building block for a UI". @@ -18,18 +19,21 @@ Spyder's plugin development consists of extending the functionality of its Qt-ba The following sections describe with more detail some QT components and their main functions. -### MainWindow ### + +### MainWindow ``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). For more details, you can refer to the official Qt documentation [MainWindow](https://doc.qt.io/qt-6/qmainwindow.html#details) + ### Windows A window is a widget that is not embedded in a parent widget. When an application requires additional windows, which do not block the main window, they can be generated as non-parent ``QWidget`` instances. These are used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. + ### Widgets Widgets are the main elements for creating a UI in Qt. @@ -46,6 +50,7 @@ Most widgets in Qt are mainly useful as child widgets. For more details, you can refer to the official Qt documentation [QWidget](https://doc.qt.io/qt-6/qwidget.html). + ### Layouts Qt layout system provides a way to arrange and distribute automatically child widgets within a widget taking advantage of the available space. @@ -54,22 +59,24 @@ You can use the built-in layout managers to organize your widgets:[QHBoxLayout]( For more details, you can refer to the official Qt documentation [Layout Management](https://doc.qt.io/qt-6/layout.html). + ### Actions, Toolbars & Menus User interfaces of desktop applications usually use toolbars and menus. -A toolbar is a GUI element that facilites acces to commonly used functions and controls in an application. +A toolbar is a GUI element that facilities access to commonly used functions and controls in an application. It can include elements such as buttons, menus, icons, and search fields. It is usually located at the top or bottom of a window. A menu is a GUI element that presents a list of options to the user. Qt provides the [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt-6/qmenu.html) classes. Since QToolBar and QMenu are alternative ways to access the same functionality, Qt includes [QAction](https://doc.qt.io/qt-6/qaction.html) as a way to avoid duplication of functions. -Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI syncronized. +Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI synchronized. For example, in a word processor, if the user presses a button on the Bold toolbar, the Bold menu item will be automatically checked. + ### Dialogs A Dialog is a GUI component used for brief communications with the user. -Dialogs are commonly used for functions that do not fit into the main interface. +Dialogs are commonly used for functions that do not fit into the main interface. A dialog can be included in an application using the QDialog class. QDialogs may be modal or modeless. A modal dialog blocks input to other visible windows in the same application. @@ -78,29 +85,34 @@ For example, dialogs for requesting information or selecting preferences for an A modeless dialog operates independently of other windows of the same application. For example, find and replace dialogs allow the user to interact with both the modeless dialog and the application's main window. -Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. +Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. + ### Signals & Slots In the GUI programming is important to provide a way to communicate objects through notifications. In Qt, signals and slots are used to support this communication. -**Signal** is a notification emitted by a widget when a particular event ocurrs. +**Signal** is a notification emitted by a widget when a particular event occurs. Example of these events includes: pressing a button, changing text in an input box, changing text in the window. Many signals are initiated by an user action, but this is not a rule. Qt's widgets have different predermined signals, but you can add your own signals to the widgets. **Slot** is a function that is invoked in response to a specific signal. -Functions or methods could be used as slots, by connecting a signal to them. -If a signal sends data, the receiver callable will also receive it. +Functions or methods could be used as slots, by connecting a signal to them. +If a signal sends data, the receiver callable will also receive it. Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. -Qt's widgets have many pre-defined slots, but it is usual practice to subclass widgets and add your own slots. +Qt's widgets have many pre-defined slots, but you can add your own slots to manage particular signals that you are interested in. -For more details, you can refer to the official Qt documentation [Signals and slots](https://doc.qt.io/qt-6/signalsandslots.html) +For more details, you can refer to the official Qt documentation [Signals and Slots](https://doc.qt.io/qt-6/signalsandslots.html) ### Events -An *Event* denote every interaction the user has with a Qt application. +An *Event* denotes every interaction the user has with a Qt application. There are several types of events designed to address different types of interactions. -In Qt they are represented by ``QEvent`` instances that contain information about what prompted them, and are passed to specific handlers that are responsible for triggering further actions. +In Qt, events are objects, derived from the abstract ``QEvent`` class. +According to the [Qt Event System documentation](https://doc.qt.io/qt-6/eventsandfilters.html), "when an event occurs, Qt creates an event object to represent it by constructing an instance of the appropriate QEvent subclass, and delivers it to a particular instance of QObject (or one of its subclasses) by calling its event() function. +This function does not handle the event itself; based on the type of event delivered, it calls an event handler for that specific type of event, and sends a response based on whether the event was accepted or ignored." + +For more details about the type of events and event handlers, please check the official Qt documentation [Qt Event System](https://doc.qt.io/qt-6/eventsandfilters.html). From 61c2ec5e174a593ba44e9ef3b0b61077e7528f0a Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 27 Jan 2025 20:08:44 -0600 Subject: [PATCH 08/11] Revise Qt Introduction after Yeimi's changes --- docs/qt_introduction.md | 115 ++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 64 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 37291b9..8c64700 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -3,116 +3,103 @@ # Qt Fundamentals -[Qt](https://www.qt.io/) is an open source, multiplatform toolkit for creating graphical user interfaces (GUI). -Qt is also a complete development framework that offers utilities for building applications and libraries of extensions for networking, Bluetooth, charts, 3D rendering, navigation, among others. +[Qt](https://www.qt.io/) is an open source, multiplatform toolkit for creating graphical user interfaces (GUIs). +It is a complete development framework that offers utilities for building applications, and has extensions for networking, Bluetooth, charts, 3D rendering, and navigation, among others. + +To develop a GUI, we start with the core building blocks—graphical elements known as *widgets*—and arrange them using *layouts*, themselves contained within other widgets and ultimately application *windows*. +Then, we interconnect these widgets using special functions and methods (called *slots*) that are triggered by receiving connected *signals*, while *events* are emitted on user interaction. +In turn, *actions* are the common building blocks of toolbars and menu items representing a specific option the user can select. -To develop a GUI, we will add graphical elements of interaction known as widgets and arrange them using layouts. -Then, we interconnect those widgets using customized procedures implemented as functions or methods, allowing to trigger behavior from user interaction. ## Basic Qt Components According to the official [Qt documentation](https://doc.qt.io/qtdesignstudio/quick-components.html): "a component is a reusable building block for a UI". -Qt has some preset components that can include simple representations (shapes, text or images) or complex user interface (UI) controls (such as sliders). -Each type of Qt component is a class starting with the letter ``Q`` followed by a name related to its functionality. -Spyder's plugin development consists of extending the functionality of its Qt-based graphical interface. +Qt has some preset components that can include simple representations (shapes, text or images) or complex user interface controls (sliders or dropdowns). +Each type of Qt component is a class starting with the letter ``Q``, followed by the name of the component (such as ``QSlider`` or ``QCombobox``). +Much of Spyder plugin development consists of extending the functionality of its Qt-based graphical interface. -The following sections describe with more detail some QT components and their main functions. +Common Qt components are summarized below in the following sections, and linked to their full reference in the Qt documentation. ### MainWindow -``MainWindow`` class provides a main application window and it has its own layout in which you can include toolbars [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html), menus [QMenuBar](https://doc.qt.io/qt-6/qmenubar.html), status bars [QStatusBar](https://doc.qt.io/qt-6/qstatusbar.html), and dockable widgets [QDockWidgets](https://doc.qt.io/qt-6/qdockwidget.html). - -For more details, you can refer to the official Qt documentation [MainWindow](https://doc.qt.io/qt-6/qmainwindow.html#details) +The [MainWindow](https://doc.qt.io/qt/qmainwindow.html#details) class provides a main application window with its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt/qtoolbar.html)), menus ([QMenuBar](https://doc.qt.io/qt/qmenubar.html)), status bars ([QStatusBar](https://doc.qt.io/qt/qstatusbar.html)), and dockable widgets ([QDockWidget](https://doc.qt.io/qt/qdockwidget.html)). ### Windows -A window is a widget that is not embedded in a parent widget. -When an application requires additional windows, which do not block the main window, they can be generated as non-parent ``QWidget`` instances. -These are used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. +A [window](https://doc.qt.io/qt/application-windows.html) is a widget that is not embedded in a parent widget. +When an application requires additional windows that do not block the main window, they can be provided as ``QWidget`` instances without a parent. +These can be used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. ### Widgets -Widgets are the main elements for creating a UI in Qt. -They can present data and updated information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. +[Widgets](https://doc.qt.io/qt/qtwidgets-index.html) are the main building blocks for creating a UI in Qt. +They can display information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. -``QWidget`` is the fundamental class in Qt that provides the capability to handle user input events and renders its representation on the screen. +[QWidget](https://doc.qt.io/qt/qwidget.html) is the fundamental class in Qt that provides the capability to handle user input events and renders its representation on the screen. All UI elements provided by Qt are subclasses of QWidget or are used in connection with a QWidget subclass. -You can define your own custom widgets by creating a QWidget or a suitable subclass, and reimplement the virtual event handlers. +You can define your own custom widgets by creating a QWidget or a suitable subclass, and reimplementing the virtual event handlers. -There are top-level and child widgets. -The first one is a widget without a parent and it is an independent window. -The second one is a non-window widget, which is displayed within its parent widget. +Top-level widgets have no parent and are an independent window, while child widgets are displayed within its parent widget. Most widgets in Qt are mainly useful as child widgets. -For more details, you can refer to the official Qt documentation [QWidget](https://doc.qt.io/qt-6/qwidget.html). - ### Layouts -Qt layout system provides a way to arrange and distribute automatically child widgets within a widget taking advantage of the available space. -This layout system can automatically position and resize widgets when the space available for them changes, ensuring that the UI remains usable. -You can use the built-in layout managers to organize your widgets:[QHBoxLayout](https://doc.qt.io/qt-6/qhboxlayout.html), [QVBoxLayout](https://doc.qt.io/qt-6/qvboxlayout.html), [QGridLayout](https://doc.qt.io/qt-6/qgridlayout.html), [QFormLayoutClass](https://doc.qt.io/qt-6/qformlayout.html),and [QStackedLayout](https://doc.qt.io/qt-6/qstackedlayout.html). +Qt's [layout](https://doc.qt.io/qt/layout.html) system provides a way to arrange and automatically distribute child widgets, taking advantage of the available space. +It can automatically position and resize widgets when the space available for them changes, ensuring that the UI remains usable. +You can use the built-in layout managers to organize your widgets: -For more details, you can refer to the official Qt documentation [Layout Management](https://doc.qt.io/qt-6/layout.html). +* [QHBoxLayout](https://doc.qt.io/qt/qhboxlayout.html) +* [QVBoxLayout](https://doc.qt.io/qt/qvboxlayout.html) +* [QGridLayout](https://doc.qt.io/qt/qgridlayout.html) +* [QFormLayoutClass](https://doc.qt.io/qt/qformlayout.html), and +* [QStackedLayout](https://doc.qt.io/qt/qstackedlayout.html) -### Actions, Toolbars & Menus +### Actions, Menus & Toolbars -User interfaces of desktop applications usually use toolbars and menus. -A toolbar is a GUI element that facilities access to commonly used functions and controls in an application. -It can include elements such as buttons, menus, icons, and search fields. -It is usually located at the top or bottom of a window. -A menu is a GUI element that presents a list of options to the user. -Qt provides the [QToolBar](https://doc.qt.io/qt-6/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt-6/qmenu.html) classes. -Since QToolBar and QMenu are alternative ways to access the same functionality, Qt includes [QAction](https://doc.qt.io/qt-6/qaction.html) as a way to avoid duplication of functions. -Actions can be added to UI elements such as menus and toolbars, and will automatically keep the UI synchronized. -For example, in a word processor, if the user presses a button on the Bold toolbar, the Bold menu item will be automatically checked. +User interfaces of desktop applications often rely on menus and toolbars, for which Qt provides the [QToolBar](https://doc.qt.io/qt/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt/qmenu.html) classes. +Menus present a list of items to the user when clicked and may be either global or context-specific. +Toolbars display commonly-used controls as a ribbon of buttons (and often other interactive elements). +Since the same individual items can be included multiple places in the UI, items only need to be created once as a [QActions](https://doc.qt.io/qt/qaction.html) that can be added to any menu or toolbar. +Their state will then be automatically synchronized: for example, if the user toggles the "Bold" toolbar button, the "Bold" menu item will also be (un)checked. ### Dialogs -A Dialog is a GUI component used for brief communications with the user. -Dialogs are commonly used for functions that do not fit into the main interface. -A dialog can be included in an application using the QDialog class. -QDialogs may be modal or modeless. -A modal dialog blocks input to other visible windows in the same application. -The user has to end the interaction with the modal dialog and close it to access to any other window in the application. -For example, dialogs for requesting information or selecting preferences for an application may be modal. -A modeless dialog operates independently of other windows of the same application. -For example, find and replace dialogs allow the user to interact with both the modeless dialog and the application's main window. +A [dialog](https://doc.qt.io/qt/dialogs.html) is a GUI component used for temporary messages and interactions, such as an error message or configuration panel. +The [QDialog](https://doc.qt.io/qt/qdialog.html) class is used to create dialogs, which can be set as either modal or modeless. +A modal dialog blocks interaction with other windows in the same application until it is dismissed, useful for an error message or requesting key information to complete a requested action. +A modeless dialog behaves as an independent window without blocking the user from doing anything else, such as for a find and replace feature where a user needs to interact with other windows. +Modal dialogs should only be used where truly necessary, as they can harm user productivity and create frustration if a user wants to interact with the rest of the application before dismissing the dialog. -Qt provides some *special dialogs* for the most common use-cases as *file Open/Save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. +Qt provides some [special dialogs](https://doc.qt.io/qt/dialogs.html) for common use-cases, such as *file open/save*, *font selection*, *error messages*, *color choosing*, *printing*, among others. ### Signals & Slots -In the GUI programming is important to provide a way to communicate objects through notifications. -In Qt, signals and slots are used to support this communication. +GUI programming requires a way to notify and communicate with other objects, which Qt provides via [signals and slots](https://doc.qt.io/qt/signalsandslots.html). -**Signal** is a notification emitted by a widget when a particular event occurs. -Example of these events includes: pressing a button, changing text in an input box, changing text in the window. -Many signals are initiated by an user action, but this is not a rule. -Qt's widgets have different predermined signals, but you can add your own signals to the widgets. +A [Signal](https://doc.qt.io/qt/signalsandslots.html#signals) is a notification emitted by a widget when a particular event occurs. +For example, this might include pressing a button, changing text in an input box, or moving a slider. +Many signals are initiated by an user action, but this is not always the case. +Qt's widgets have different predetermined signals, and you can also add your own. -**Slot** is a function that is invoked in response to a specific signal. -Functions or methods could be used as slots, by connecting a signal to them. -If a signal sends data, the receiver callable will also receive it. +A [Slot](https://doc.qt.io/qt/signalsandslots.html#slots) is a function that is invoked in response to a specific signal. +Functions and methods can be used as slots by connecting a signal to them. +If a signal sends data, the receiving callable will receive it. Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. -Qt's widgets have many pre-defined slots, but you can add your own slots to manage particular signals that you are interested in. - -For more details, you can refer to the official Qt documentation [Signals and Slots](https://doc.qt.io/qt-6/signalsandslots.html) +You can also add your own slots to manage particular signals that you are interested in. ### Events -An *Event* denotes every interaction the user has with a Qt application. +An [Event](https://doc.qt.io/qt/eventsandfilters.html) denotes every interaction the user has with a Qt application. +In Qt, events are objects, derived from the abstract [QEvent](https://doc.qt.io/qt/qevent.html) class. There are several types of events designed to address different types of interactions. -In Qt, events are objects, derived from the abstract ``QEvent`` class. -According to the [Qt Event System documentation](https://doc.qt.io/qt-6/eventsandfilters.html), "when an event occurs, Qt creates an event object to represent it by constructing an instance of the appropriate QEvent subclass, and delivers it to a particular instance of QObject (or one of its subclasses) by calling its event() function. +According to the [Qt Event System documentation](https://doc.qt.io/qt/eventsandfilters.html), "when an event occurs, Qt creates an event object to represent it by constructing an instance of the appropriate QEvent subclass, and delivers it to a particular instance of QObject (or one of its subclasses) by calling its event() function. This function does not handle the event itself; based on the type of event delivered, it calls an event handler for that specific type of event, and sends a response based on whether the event was accepted or ignored." - -For more details about the type of events and event handlers, please check the official Qt documentation [Qt Event System](https://doc.qt.io/qt-6/eventsandfilters.html). From 078f078f348373a87962bb63abd17ba1acd67310 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 27 Jan 2025 20:11:40 -0600 Subject: [PATCH 09/11] Move Widgets section up since its the building block of everything --- docs/qt_introduction.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 8c64700..06d5e55 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -22,18 +22,6 @@ Much of Spyder plugin development consists of extending the functionality of its Common Qt components are summarized below in the following sections, and linked to their full reference in the Qt documentation. -### MainWindow - -The [MainWindow](https://doc.qt.io/qt/qmainwindow.html#details) class provides a main application window with its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt/qtoolbar.html)), menus ([QMenuBar](https://doc.qt.io/qt/qmenubar.html)), status bars ([QStatusBar](https://doc.qt.io/qt/qstatusbar.html)), and dockable widgets ([QDockWidget](https://doc.qt.io/qt/qdockwidget.html)). - - -### Windows - -A [window](https://doc.qt.io/qt/application-windows.html) is a widget that is not embedded in a parent widget. -When an application requires additional windows that do not block the main window, they can be provided as ``QWidget`` instances without a parent. -These can be used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. - - ### Widgets [Widgets](https://doc.qt.io/qt/qtwidgets-index.html) are the main building blocks for creating a UI in Qt. @@ -47,6 +35,18 @@ Top-level widgets have no parent and are an independent window, while child widg Most widgets in Qt are mainly useful as child widgets. +### MainWindow + +The [MainWindow](https://doc.qt.io/qt/qmainwindow.html#details) class provides a main application window with its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt/qtoolbar.html)), menus ([QMenuBar](https://doc.qt.io/qt/qmenubar.html)), status bars ([QStatusBar](https://doc.qt.io/qt/qstatusbar.html)), and dockable widgets ([QDockWidget](https://doc.qt.io/qt/qdockwidget.html)). + + +### Windows + +A [window](https://doc.qt.io/qt/application-windows.html) is a widget that is not embedded in a parent widget. +When an application requires additional windows that do not block the main window, they can be provided as ``QWidget`` instances without a parent. +These can be used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. + + ### Layouts Qt's [layout](https://doc.qt.io/qt/layout.html) system provides a way to arrange and automatically distribute child widgets, taking advantage of the available space. From 33485445815357bac1705567f5e3466e999f8586 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 27 Jan 2025 20:51:02 -0600 Subject: [PATCH 10/11] Remove events section as its confusing for an introduction --- docs/qt_introduction.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index 06d5e55..c77128b 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -7,7 +7,7 @@ It is a complete development framework that offers utilities for building applications, and has extensions for networking, Bluetooth, charts, 3D rendering, and navigation, among others. To develop a GUI, we start with the core building blocks—graphical elements known as *widgets*—and arrange them using *layouts*, themselves contained within other widgets and ultimately application *windows*. -Then, we interconnect these widgets using special functions and methods (called *slots*) that are triggered by receiving connected *signals*, while *events* are emitted on user interaction. +Then, we interconnect these widgets using special functions and methods (called *slots*) that are triggered by receiving connected *signals*. In turn, *actions* are the common building blocks of toolbars and menu items representing a specific option the user can select. @@ -94,12 +94,3 @@ Functions and methods can be used as slots by connecting a signal to them. If a signal sends data, the receiving callable will receive it. Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. You can also add your own slots to manage particular signals that you are interested in. - - -### Events - -An [Event](https://doc.qt.io/qt/eventsandfilters.html) denotes every interaction the user has with a Qt application. -In Qt, events are objects, derived from the abstract [QEvent](https://doc.qt.io/qt/qevent.html) class. -There are several types of events designed to address different types of interactions. -According to the [Qt Event System documentation](https://doc.qt.io/qt/eventsandfilters.html), "when an event occurs, Qt creates an event object to represent it by constructing an instance of the appropriate QEvent subclass, and delivers it to a particular instance of QObject (or one of its subclasses) by calling its event() function. -This function does not handle the event itself; based on the type of event delivered, it calls an event handler for that specific type of event, and sends a response based on whether the event was accepted or ignored." From 8c9466932da3b5ab1a70988e51a1ecac3e83f5bc Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 28 Jan 2025 16:14:26 -0600 Subject: [PATCH 11/11] Implement Qt intro changes suggested by Carlos and Yeimi Co-authored-by: Carlos Cordoba --- docs/qt_introduction.md | 39 ++++++++++++++------------------------- 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/docs/qt_introduction.md b/docs/qt_introduction.md index c77128b..57de4ff 100644 --- a/docs/qt_introduction.md +++ b/docs/qt_introduction.md @@ -28,28 +28,18 @@ Common Qt components are summarized below in the following sections, and linked They can display information, receive user input (mouse, keyboard, and other events from the window system), and provide a container for grouping other widgets. [QWidget](https://doc.qt.io/qt/qwidget.html) is the fundamental class in Qt that provides the capability to handle user input events and renders its representation on the screen. -All UI elements provided by Qt are subclasses of QWidget or are used in connection with a QWidget subclass. -You can define your own custom widgets by creating a QWidget or a suitable subclass, and reimplementing the virtual event handlers. +All UI elements provided by Qt are subclasses of ``QWidget`` or are used in connection with a ``QWidget`` subclass. +You can define your own custom widget class by subclassing QWidget, and adding or reimplementing the methods that you need. -Top-level widgets have no parent and are an independent window, while child widgets are displayed within its parent widget. -Most widgets in Qt are mainly useful as child widgets. +### Windows and MainWindows -### MainWindow - -The [MainWindow](https://doc.qt.io/qt/qmainwindow.html#details) class provides a main application window with its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt/qtoolbar.html)), menus ([QMenuBar](https://doc.qt.io/qt/qmenubar.html)), status bars ([QStatusBar](https://doc.qt.io/qt/qstatusbar.html)), and dockable widgets ([QDockWidget](https://doc.qt.io/qt/qdockwidget.html)). - - -### Windows - -A [window](https://doc.qt.io/qt/application-windows.html) is a widget that is not embedded in a parent widget. -When an application requires additional windows that do not block the main window, they can be provided as ``QWidget`` instances without a parent. -These can be used for parallel tasks that take place in long-running processes, such as displaying graphs or editing documents. +A Qt [window](https://doc.qt.io/qt/application-windows.html) is a widget that is not embedded in a parent widget. The [MainWindow](https://doc.qt.io/qt/qmainwindow.html#details) class provides a main application window with its own layout in which you can include toolbars ([QToolBar](https://doc.qt.io/qt/qtoolbar.html)), menus ([QMenuBar](https://doc.qt.io/qt/qmenubar.html)), status bars ([QStatusBar](https://doc.qt.io/qt/qstatusbar.html)), and dockable widgets ([QDockWidget](https://doc.qt.io/qt/qdockwidget.html)). ### Layouts -Qt's [layout](https://doc.qt.io/qt/layout.html) system provides a way to arrange and automatically distribute child widgets, taking advantage of the available space. +Qt's [layout](https://doc.qt.io/qt/layout.html) system provides a way for a widget to arrange and automatically distribute child widgets, taking advantage of the available space. It can automatically position and resize widgets when the space available for them changes, ensuring that the UI remains usable. You can use the built-in layout managers to organize your widgets: @@ -62,16 +52,16 @@ You can use the built-in layout managers to organize your widgets: ### Actions, Menus & Toolbars -User interfaces of desktop applications often rely on menus and toolbars, for which Qt provides the [QToolBar](https://doc.qt.io/qt/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt/qmenu.html) classes. +User interfaces of desktop applications often rely on menus and toolbars to display groups of commands and options to the user, for which Qt provides the [QToolBar](https://doc.qt.io/qt/qtoolbar.html#details) and [QMenu](https://doc.qt.io/qt/qmenu.html) classes. Menus present a list of items to the user when clicked and may be either global or context-specific. Toolbars display commonly-used controls as a ribbon of buttons (and often other interactive elements). -Since the same individual items can be included multiple places in the UI, items only need to be created once as a [QActions](https://doc.qt.io/qt/qaction.html) that can be added to any menu or toolbar. +Since the same individual items can be included in multiple places in the UI, items only need to be created once as a [QAction](https://doc.qt.io/qt/qaction.html) that can be added to any menu or toolbar. Their state will then be automatically synchronized: for example, if the user toggles the "Bold" toolbar button, the "Bold" menu item will also be (un)checked. ### Dialogs -A [dialog](https://doc.qt.io/qt/dialogs.html) is a GUI component used for temporary messages and interactions, such as an error message or configuration panel. +A [dialog](https://doc.qt.io/qt/dialogs.html) is a new, smaller window for temporary interactions and messages, such as a configuration panel or a warning notification. The [QDialog](https://doc.qt.io/qt/qdialog.html) class is used to create dialogs, which can be set as either modal or modeless. A modal dialog blocks interaction with other windows in the same application until it is dismissed, useful for an error message or requesting key information to complete a requested action. A modeless dialog behaves as an independent window without blocking the user from doing anything else, such as for a find and replace feature where a user needs to interact with other windows. @@ -82,15 +72,14 @@ Qt provides some [special dialogs](https://doc.qt.io/qt/dialogs.html) for common ### Signals & Slots -GUI programming requires a way to notify and communicate with other objects, which Qt provides via [signals and slots](https://doc.qt.io/qt/signalsandslots.html). +GUI programming requires a way to notify and communicate with other objects in the application, which Qt provides via [signals and slots](https://doc.qt.io/qt/signalsandslots.html). -A [Signal](https://doc.qt.io/qt/signalsandslots.html#signals) is a notification emitted by a widget when a particular event occurs. +A [Signal](https://doc.qt.io/qt/signalsandslots.html#signals) is a notification emitted by a widget (as well as non-graphical Qt objects) when a particular event occurs. For example, this might include pressing a button, changing text in an input box, or moving a slider. -Many signals are initiated by an user action, but this is not always the case. +Many signals are initiated by an user action, but they can also be issued for other events, like completing a process. Qt's widgets have different predetermined signals, and you can also add your own. -A [Slot](https://doc.qt.io/qt/signalsandslots.html#slots) is a function that is invoked in response to a specific signal. +A [Slot](https://doc.qt.io/qt/signalsandslots.html#slots) is a function or method that is invoked in response to a specific signal. Functions and methods can be used as slots by connecting a signal to them. -If a signal sends data, the receiving callable will receive it. -Many Qt widgets also have their own built-in slots, so the corresponding widgets are notified automatically. -You can also add your own slots to manage particular signals that you are interested in. +If a signal sends data, the receiving callable will receive it as arguments. +You can add your own functions as slots to manage particular signals (built-in or custom) that you are interested in.