Examples Revamping Qt SQL

From Qt Wiki
Jump to: navigation, search

Examples from the QtSql module

Fill in the table below, see Examples Revamping for overview.

If all examples in this module adhere to the definition of the given column, mark it with , if the column doesn't apply to the given module, mark it with NA, and if there are caveats, write a comment.

The columns in the table refer to the following definitions:

  • Are the examples written according to good coding practices and current conventions?
  • Are there such examples that show how to use the module in conjunction with other modules as typically would be done by the user?
  • Do the examples have comments?
  • Are the examples easy to understand?
  • If example has UI, is it scalable according to current best practices of Qt?
  • Are the most useful examples of the module highlighted in Creator's Welcome view?
  • If there are bad examples, should these be removed or hidden?
  • Is the visual appearance of the examples (at least the highlight ones) nicely showing value of Qt in making good looking applications?
  • Do the examples work with our tools? For example works with Qt Quick Designer (and Widget designer)?
  • If QML example, has the UI been separated to .ui.qml file?

Questions for the whole module:

  • Is there a section / link in the module's documentation to its examples?

Notes

  • Books:
    • Lacks descriptive text (source only).
    • Label with name Label_2_2_2_2 makes the example look unpolished.
    • Resizing the star column (rightmost column) to the minimum width lets the star graphic asset escape the bounds of the column.
  • Cached Table Example:
    • Revert button in the example application could be more intuitive, as it is available after a 'Submit' but does not revert submitted changes.
    • The table layout does not fill the default application size, which makes it look a little unpolished.
    • Wrong order of arguments in description of TableEditor constructor.
    • The text "class can be used to provide data to view classes" is ambiguous: are we using 'view' as noun or verb? (It is used as noun, but reads as a verb).
    • Overall language can be simplified somewhat, to make the text clearer for non-native English readers.
    • "It is build" -> "It is built".
    • Sub-section "Connecting to a Database" is enclosed in a table - the formatting makes it look like a sidebar, although the text seems to be a continuation of the main text. Is this done on purpose?
    • The text content that goes into the 'items' table in the database is marketing speech (or an attempt at clever SEO trickery). It feels a little contrived. Perhaps rename the table to 'slogans', 'marketing_pitches', or something similar that justifies the content? Or replace content with something that is more benign.
    • The text mixes active/passive voice as well as point of view (first person vs second person).
    • Use of possessives, Latin expressions: rewrite to improve readability for non-native English readers.
  • Drill Down Example:
    • Example application has wrong window title ('drilldown', should be 'Drill Down').
    • Old logo in application and screenshot.
    • Graphics in application has tearing/artifacts.
    • Mixes first person plural and second person POV.
    • The class descriptions should be reordered: first main application, then the other two.
    • 'data base' -> 'database' (one word).
    • Use of possessives, Latin expressions: rewrite to improve readability for non-native English readers.
  • Master Detail Example:
    • The entire text on the example landing page is "The example also shows how to add as well as remove data from both the database and the associated XML file using the API provided by the Qt SQL and Qt XML modules, respectively.". The preamble from the example listing page is missing, so the text seems completely out of context (this is a known issue when generating this part of documentation). As this is the only text available, it makes the entire example come off as unfinished.
    • Column titles in the application are all lower-case (i.e. "title", "artist", "year").
    • Detail view uses Title Case for "Number of Albums".
    • Detail view and album covers is a (or an outdated?) promotional poster for Qt. A developer who is looking at Qt examples to learn how to use Qt, probably doesn't need to be sold on the idea that they should consider Qt in the first place (this is like online advertising algorithms that pitch the product you just bought). Maybe make the content more relevant (e.g. pitch use-cases, rolling ads for upcoming Qt events, relevant and related feature highlight).
    • Displaying a text about the example in Help->About is a nice touch and should be replicated in other example applications.
  • Query Model Example:
    • Not entirely clear what the example exemplifies; in particular the "Custom Query Model".
    • The three windows open on top of each other in a cascaded fashion.
    • The windows are not sized to match their contents (they are too small).
  • Relational Table Model Example:
    • It is hard to see what the example adds to the documentation in the current state, and the example application is neither engaging, nor does it showcase functionality in a good way.
  • SQL Browser Example:
    • Table overview pane does not default to full content width (adds scrollbar).
    • Resizing the id column to a sensible size makes the example more visually appealing (and solves the point above).
    • The database pane title is lower-case.
    • Clicking Submit with an empty SQL Query returns "Query OK, number of affected rows: -1" as status. This is not informative nor intuitive. The Clear and Submit buttons should be inactive until they actually do something.
  • SQL Widget Mapper Example:
    • The application is buggy (at least when running from Creator 4.6.1/Qt 5.10.1 on Linux). The values in the Type field act in a weird way, e.g. changing the first entry from Home to Other, then going back and forth in the list of entries using Next and Previous, sets this entry type to Work.
    • The text description seems to be written as the continuation of a different Widget example, and not as a SQL example. The text contains implicit references to this other material.
  • Table Model Example:
    • The example does not have an accompanying text, nor does it contain comments in code to explain the purpose of the example.

Examples

Qt Essentials
Examples Coding conventions With other modules Comments Understandable Scalable UI Qt Creator Bad examples Visually appealing Work with Qt tools .ui.qml
Books Uses SIGNAL/SLOT Yes (Widgets) NA Not really NA NA
Cached Table Example Yes One NA Not really No NA
Drill Down Example NA For the most part, and depending on experience. NA No No NA
Master Detail Example Two regarding code that is commented out due to the specifics of the example. NA No NA
Query Model Example Widgets No No NA Yes, as is. No No NA
Relational Table Model Example Widgets No Yes NA Yes No No NA
SQL Browser Breaks 80 col width rule Widgets No Yes NA comme ci comme ça Yes NA
SQL Widget Mapper Example Widgets No Yes, with the accompanying text description. NA Yes, as is. No No NA
Table Model Example QTableView, QSqlTableView,

QApplication

No No. What is the purpose of the example? NA Yes, as is. No No NA