CommonQtStuffes.md

• QT
  • QT Program Requirements or Basics
  • QT IOs
  • Model-View-Controller (MVC) in Qt
    • Architecture
    • Model
      • Explanation
      • Model Indexes, Rows, Columns and Parents
      • Item Roles
      • Model Test
    • View
      • Explanation
      • Selections
        • Selection Models
        • Selection Objects
        • Create a Selection Object and Submit it to the Selection Model
        • Selection Commands
        • Selecting all Items in a Model
    • Delegates
      • Explanation
      • Providing an Editor and Submitting Data to the Model
    • Sorting
    • Convenience classes
  • QT Threads
  • QT Widgets (Desktop GUI) (Traditional GUI)

QT

QT Program Requirements or Basics

1. QApplication.
2. QObject.
3. QMetaObject.
4. Qt Fundamentals.
5. Q_OBJECT.
6. QEvent.
7. Qt for Linux/X11.
8. Qt for Windows.
9. Recommend:
   • The Q_OBJECT macro should be used with Qt classes in a header file to avoid unexpected behavior.
   • Q_SIGNALS, Q_SLOTS and Q_EMIT should be used instead of signals, slots and emit.
   • If enable Q_OBJECT macro, should inherit QObject or one of its subclasses.
10. The system event delivery sequence:
    • From leaf to root, normally, except for installing a global event filter;
    • The child event filter (eventFilter(...)) → The general event function of the child (event(...), in fact, calling event handlers)→ Its parent event filter → The general event function of its parent → Specific event functions (event handlers, xxxEvent(...), in fact, called by event() functions of base classes.) of its parent and it. (Because their base classes' event functions call specific event functions to handle events.)
    • Normally, the event filter intercepts an event and try to process it.
    • However, the general event function does not process an event, instead, it call correspoding and specific event functions.
    • Programmers can choose to either reimplement the entire process of the general event function or reimplement part of it and call its parent's general event function to handle other events or specific event functions to handl specific events.
    • The reimplemented part can process events by itself or by calling user-defined or parent-specific functions.
    • In addition, programmers can choose whether and how to reimplement the specific event functions, like the general event function.
    • Key concetps: a event filter, a event function, a event handler or a spcific event function.
11. Signals: public method, return void, automatically generated; can't be emitted in a const method; means that the object's state is changed; automatically generated by the moc; allow default arguments.
12. Slots: manually written, no limitations except that the number of their parameters must be less than or equal to the number of parameters of the connected signal; used to response to the signal.
13. Six types of emitting a signal:
    • Normal Emission: Slots are executed immediately when the signal is emitted, and the code following the emit statement is executed afterward.
    • Queued Emission: The code following the emit statement is executed immediately, and the slots are executed later.
    • Connection Type
14. Connections are destoried once the related contexts are destoried.
15. QObject and its subclasses are neither copyable nor assignable data types. Their copy constructor and assignment operators are explicitly disabled. However, pointers to these objects are copyable and assignable.
16. Qt containers are designed to work with copyable and assignable data types. They employ implicit sharing, a mechanism also known as copy-on-write or value semantics, to optimize memory usage and performance.
    • When using a range-based for loop to iterate over a container in a non-const context, std::as_const() should be used to prevent implicit sharing from triggering an undesired detach of the container.
    • Read-only iterators should be used wherever possible because they are faster than read-write iterators.
    • When using Qt containers with user-defined types, it is better to declare those types with Q_DECLARE_TYPEINFO. (Optimal performance)
    • QT Container
    • Implicit Sharing
    • Q_DECLARE_TYPEINFO
17. QString uses UTF-16 internally.
18. If you want to store data in a file and read it later, you should not add this file to a .qrc file or use the Qt Resource System (qrc) to read it. This is because files added to the Qt Resource System are read-only at runtime. When you use the qrc mechanism, the file is embedded into the application binary, and the app reads from this embedded copy rather than the original file on the filesystem. To allow writing and reading modifications, you should store the file in a writable location, such as the application directory, user's home directory, or a platform-specific data directory.
19. The title bar of a QDockWidget is managed by the operating system, which means its two buttons (close and dock/undock) cannot be interacted with programmatically when the QDockWidget is floating. If you need to implement a fully customizable floating window, you should move the QDockWidget's content into a new, separate window.

QT IOs

1. UI Frameworks.
2. QIODevice.
3. QTextStream.
4. QDataStream.
5. QFile.
6. QFileInfo.
7. QDir.
8. The Qt Resource System.
9. Common usages:
   • Use QFile to open a file.
   • Use QTextStream to read or write a file.

Model-View-Controller (MVC) in Qt

Architecture

1. Model: Communicate wit a source of data and provide an interface for the other components.
2. View: Obtain indexes referencing to items of data from the model, retrieve items of data from data source and present data to users.
3. Delegate: Render the items of data and modify the items of data.
4. Data: The original data from users.
5. They communicate with each other using signals and slots, except for Data.
   • Signals from the model inform the view about changes to the data held by the data source.
   • Signals from the view provide information about the user's interaction with the items being displayed.
   • Signals from the delegate are used during editing to tell the model and view about the state of the editor.
6. Item: An object within the model that holds or refers to the data, also providing additional information about the data, such as:
   • Display roles: How the data should be displayed (text, icon, color, etc.).
   • Editability: Whether the data can be modified by the user.
   • Hierarchy: The item's position within a tree or other hierarchical structure.
   • Other attributes: Custom data associated with the item.
7. Only the model needs to know how to obtain data, and the type of data managed by the model can be defined fairly generally.
8. Flowchart:

   flowchart TB
       B -->|Rendering| C
       A[Data] <--> B[Model] <-->|Editing| D((Delegate)) <-->|Rendering| C[View]
   

   Loading

Model

Explanation

1. Link
2. Interface: QAbstractItemModel.
3. Abstract models and proxy models do not store data themselves and rely on implemented methods like data() and setData() to provide and modify the data.
4. The data() method also needs to be changed to set fonts, background colour, alignment and a checkbox.
5. Item-based models do store data internally.
6. Merely presents an interface that the views use to access the data.
7. Communicate with Data.
8. One model, several views.
9. Ready-made models:
   • QAbstractListModel: A simple list of items. Not store data.
   • QAbstractTableModel: A simple table of items. Not store data.
   • QStringListModel: A simple list of QString items. Stores a simple list of strings.
   • QStandardItemModel: A complex tree structures of items. A multi-purpose standard models. Uses QStandardItem objects to hold data in a tree-like structure. Holding data does not necessarily mean storing the actual data. In many cases, it may involve holding a reference (e.g., a pointer) to the data instead.
   • QFileSystemModel: Provide information about files and directories in the local filing system. A standard model. Not hold any items of data itself. Asynchronous.
   • QSqlQueryModel: Access database using model/view conventions.
   • QSqlTableModel: Access database using model/view conventions.
   • QSqlRelationalTableModel: Access database using model/view conventions.
10. Custom models: Subclass these model classes.
11. All subclasses of QAbstractItemModel represent the data as a hierarchical structure containing tables of items.
12. Views use this convention to access items of data in the model.
13. Use signals and slots mechanism to inform any attached views about data changes.
14. Model subclassing reference.
15. Qt::ItemFlag describes the properties of an item.

Model Indexes, Rows, Columns and Parents

1. Each piece of information that can be obtained via a model is represented by a model index.
2. Views and delegates use these indexes to request items of data to display.
3. Contain a pointer to the model that created them.
4. Provide references to pieces of information:
   • A long-term reference, a persistent model index, the model keeps the information up-to-date, created by QPersistentModelIndex.
   • A temporary reference, created by QModelIndex.
   • Three properties(arguments) : a row number, a column number and the model index of a parent item.
   • QAbstractItemModel::index( row, column, parent ).
   • QAbstractItemModel::index( row, column, QModelIndex() ) returns top level items.
   • If a valid model index is specified for the parent item when an index is requested using index(), the index returned refers to an item beneath that parent item in the model. The index obtained refers to a child of that item.
   • If an invalid model index is specified for the parent item when an index is requested using index(), the index returned refers to a top-level item in the model.
5. Used to retrieve or modify data via the model.
6. May become invalid and should not be stored.
7. Can retrieve information about any given item by specifying its row and column numbers to the model and receive an index that represents the item.
8. Form top-level indexes to bottom-level indexes like finding a director manually.
9. setModel() automatically connect the dataChanged() signal to the view.

Item Roles

1. One item, several roles.
2. One role, one data type, one situation.
3. The standard roles are defined by Qt::ItemDataRole.
4. QVariant value = QAbstractItemModel::data( index, role ). Retrieve item's data.
5. By supplying appropriate item data for each role, models can provide hints to views and delegates about how items should be presented to the user.

Model Test

1. Model test.

View

Explanation

1. Link
2. Interface: QAbstractItemView.
3. Not store data.
4. Retrieve items of data from the model and present data to the users.
5. Manage the lifetime of the editor and the overall layout of the data obtained from models.
6. Provide default editing facilities for items, or work with a delegate to provide a custom editor.
7. Render individual items of data themselves, or use delegates to handle both rendering and editing features.
8. Can keep track of the selected items with selections.
9. The selections can be maintained separately for each view, or shared between multiple views.
10. One selections, several views.
11. Some views display headers as well as items. QAbstractItemModel::headerData() and QHeaderView.
12. Ready-made views:
    • QListView: Display items from a model as a simple list, or in the form of a classic icon view. The most suitable views to use with QFileSystemModel.
    • QTreeView: Show model items of data in a hierarchical list, allowing deeply nested structures to be represented in a compact way. The most suitable views to use with QFileSystemModel.
    • QTableView: Display data from a model in a table.
13. Custom views: Subclass these view classes.

Selections

Selection Models

1. All of the standard views construct their own selection models by default, and interact with them in the normal way.
2. QAbstractItemView::selectionModel() returns a selection model of the view.
3. QAbstractItemView::setSelectionModel() is used to replace the original selection model of the view.
4. One selection model, several views, sharing selections among views.
5. Information about the items selected in a view is stored in an instance of the QItemSelectionModel class that is a record of the selection state of all the items in an item model (selected or deselected).
6. This maintains model indexes for items in a single model, and is independent of any views.
7. const QModelIndexList indexes = selectionModel->selectedIndexes(); returns an unsorted list of model indexes.
8. Emits selectionChanged() signals to indicate changes in the selection.
9. Two arguments in selectionChanged(): two QItemSelection objects
   • one contains a list of indexes that correspond to newly selected items;
   • the other contains indexes that correspond to newly deselected items.
10. currentChanged():
    • A signal used to keep track of the currently focused item;
    • Two arguments or model indexes: the previously focused item, and the currently focused item.

Selection Objects

1. Applied to a collection of model indexes held by a selection model.
2. The most recent selection of items applied is known as the current selection.
3. Made up of selection ranges: Recording only the starting(topLeft) and ending(bottomRight) model indexes for each range of selected items
4. One contiguous selection, one selection object, one selection range, two model indexes.
5. One non-contiguous selection, multiple selection object, multiple selection ranges, multiple model indexes.
6. Two independent states: A current item and a selected item.
7. A selection is created by specifying a model, and a pair of model indexes to a QItemSelection. Its selection range is always from the top-left to bottom-right.
8. Only QItemSelection is used to create a selection object.
9. const QModelIndexList indexes = selectionModel->selectedIndexes(); is used to get the selected indexes.
10. Selection flags.

Create a Selection Object and Submit it to the Selection Model

QModelIndex topLeft = model->index( row1, column1, parent1 );
QModelIndex bottomRight = model->index( row2, column2, parent2 );
QItemSelection selection( topLeft, bottomRight );
selectionModel->select( selection, QItemSelectionModel::Select /* selection flags */);

Selection Commands

1. Selection flags.
2. Are provided by a combination of selection flags.
3. By default, the selection commands only operate on the individual items specified by the model indexes.
4. However, the flag used to describe the selection command can be combined with additional flags to change entire rows and columns.
5. The results of slection commands are accumlated.
6. This means the results of subsequent commands depend on the results of previous commands because the selection states of all items are stored in the same selection model.

Selecting all Items in a Model

1. Need to create a selection for each level of the model that covers all items in that level.
2. Need to be performed for all levels in the model:

   QItemSelection selection( topLeft, bottomRight );
   selectionModel->select( selection, QItemSelectionModel::Select );

3. For hierarchical models, the hasChildren() function is used to determine whether any given item is the parent of another level of items.

Delegates

Explanation

1. Link
2. Interface: QAbstractItemDelegates.
3. Not store data.
4. Not manage the lifetime of the editor and store an editor.
5. Paint and provide editors for items in view.
6. Provide input capabilities and are also responsible for rendering individual items in some views.
7. Two methods are used to implement editors for delegates:
   • Use widgets to manage the editing process. Need to install a default event filter supplied by QStyledItemDelegate or a custom event filter.
   • Provide our own editor widget to handle events directly. Not need a event filter.
8. Note that no editor widgets are set up when the delegate is constructed. We only construct an editor widget when it is needed.
9. The default delegate instance in standard views: QStyledItemDelegate.
10. QAbstractItemView::itemDelegate returns a delegate that the view is using.
11. QAbstractItemView::setItemDelegate installs or sets a delegate for a view.
12. Ready-made delegates:
    • QStyledItemDelegate: Default delegates. Use the current style to paint items. With some default display functions.
    • QItemDelegate.
13. Custom delegates: Subclass these delegate classes and work with editor widgets.
14. Delegates are expected to be able to render their contents themselves by implementing the paint() and sizeHint() functions.
15. Need to implement the following four functions:

    QWidget* createEditor( QWidget* parent,
                           const QStyleOptionViewItem& option,
                           const QModelIndex& index ) const override;
    void setEditorData( QWidget* editor, const QModelIndex& index ) const override;
    void setModelData( QWidget* editor,
                       QAbstractItemModel* model,
                       const QModelIndex& index ) const override;
    void updateEditorGeometry( QWidget* editor,
                               const QStyleOptionViewItem& option,
                               const QModelIndex& index ) const override;

Providing an Editor and Submitting Data to the Model

```mermaid
flowchart LR
    C[User] -->|Edit data| A[View]
    A -->|Request an editor| B((Delegate))
    B -->|Check whether the item is editable, create an editor and transfer the ownership| A
    A -->|Request setting the data of the editor| B
    B -->|Set the data of the editor| A
    A -->|Request storing the edited data of the editor| B
    B -->|Request storing the data| D[Mode]
    D -->|Store the data and emit dataChanged signal| A
    D -->|Store the data and emit dataChanged signal| B
    B -->|Emit the closeEditor signal with a suitable hint like EditNextItem| A
    A -->|Close and destory| E[Editor]
```

Sorting

1. Reimplments the QAbstractItemModel::sort() function:
   • Enable interactive sorting(i.e. allowing the users to sort the data by clicking the view's headers).
   • Connecting the QHeaderView::sortIndicatorChanged() signal to the QTableView::sortByColumn() slot or the QTreeView::sortByColumn() slot, respectively.
2. Use Proxy Model.

Convenience classes

1. Not intended to be subclassed.
2. Derived from the standard view classes.
3. An item-based set of classes.
4. Can replace View.
5. Not recommend using these classes to replace View.
6. Instead, using view classes, such as QListView, QTableView, and QTreeView with QStandardItemModel.
7. Cannot be used with arbitrary models.
8. QListWidget.
9. QTreeWidget.
10. QTableWidget.

QT Threads

1. The "main thread" is the thread created when a program starts.
2. In Qt applications, this thread is also known as the "GUI thread".
3. Other threads are referred to as "worker threads" or "secondary threads".
4. All widgets and several related classes must operate in the "main thread" and do not work in secondary threads.
5. Each thread has its own stack but shares the same address space.
6. QThread by itself does not automatically start an event loop in the new thread.
7. You have to explicitly call exec() within the run() method of your QThread subclass to start one.
8. To execute methods in a new thread, the following requirements must be met::
   • Use the worker-object approach;
   • All methods intended for execution in the new thread must be slots of the worker object;
   • Use connect(this, &Controller::operate, worker, &Worker::slot); to connect the signal and slot.

QT Widgets (Desktop GUI) (Traditional GUI)

1. QWidget.
2. QFrame.
3. QGridLayout.
4. QLabel.
5. QPushButton.
6. connect.
7. QMainWindow.
8. QAction.
9. QPixmap.
10. QVBoxLayout.
11. QHBoxLayout.
12. QListWidget.
13. QGridLayout.
14. QLineEdit.
15. QFormLayout.
16. QLabel.
17. QTextEdit.
18. QKeyEvent.
19. QCheckBox.