jami-docs

Forked version of Jami documentation, see wrycode.com/jami-docs-demo
git clone git://git.wrycode.com/wrycode/jami-docs.git
Log | Files | Refs

Qt-and-QML-coding-guidelines.md (2958B)

      1 # Qt/c++
      2 ## Signal and slot naming
      3 Both signals and slots should use camelCase.
      4 A signal should use the simple past tense or past participle of some verb, likely prefixed by a short subject. A corresponding slot should be the signal prefixed with the word "on" and not the word "slot". Here are some examples:
      5 ```c
      6 // correct
      7 signal:
      8     void shutdownScheduled();
      9     void navigationRequested();
     10 ...
     11 slot:
     12     void onShutdownScheduled();
     13     void onNavigationRequested();
     14 
     15 // incorrect
     16 signal:
     17     void shutdown();
     18     void navigateToHomeView();
     19 ...
     20 slot:
     21     void onShutdown();
     22     void slotNavigateToHomeView();
     23 ```
     24 
     25 ---
     26 # QML
     27 # Code formatting
     28 The Qt 5.15.0 version of qmlformat has some issues dealing with comment sections and currently does not discriminate against max columns, so we will continue to format using these guidelines for now.
     29 The following is a comprehensive sample component, adapted from https://doc.qt.io/qt-5/qml-codingconventions.html, that attempts to illustrate the ideally formatted component.
     30 ```javascript
     31 /*
     32  * authored by/copyright ...
     33  */
     34 
     35 // Id always on the first line, and always present and called root
     36 // for root component. Only present if referenced for children.
     37 // Multi-line comments use '//'.
     38 // There should always be a brief description of a component.
     39 // Multi-line comments start with a capital letter and end with
     40 // a period.
     41 Rectangle {
     42     id: root
     43 
     44     // property declarations
     45     property bool thumbnail: false                          
     46     property alias image: photoImage.source
     47 
     48     // signal declarations
     49     signal clicked                                          
     50 
     51     // javascript functions
     52     function doSomething(x) {
     53         return x + photoImage.width
     54     }
     55 
     56     // object properties
     57     color: "gray"
     58     // try to group related properties together
     59     x: 20
     60     y: 20
     61     height: 150
     62     // large bindings
     63     width: {
     64         // Always space all operators, and add a single space
     65         // before opening brackets.
     66         if (photoImage.width > 200) {
     67             photoImage.width
     68         } else {
     69             height
     70         }
     71     }
     72 
     73     // child objects (contentItem, defaults, etc. first)
     74     Rectangle {
     75         id: border
     76         anchors.centerIn: parent
     77         color: "white"
     78 
     79         Image {
     80             id: photoImage
     81             anchors.centerIn: parent
     82         }
     83     }
     84     
     85     Text {
     86         anchors.centerIn: photoImage
     87         // Use the ellipsis character (…) for manual ellision within
     88         // UI text and don't translate untranslatables.
     89         text: qsTr("an emoji: %1 and a number: %2 …").arg("💡").arg(42)
     90     }
     91 
     92     // states
     93     states: State {
     94         name: "selected"
     95         PropertyChanges {
     96             target: border
     97             color: "red"
     98         }
     99     }
    100 
    101     // transitions
    102     transitions: Transition {
    103         from: ""
    104         to: "selected"
    105         ColorAnimation {
    106             target: border
    107             duration: 200
    108         }
    109     }
    110 }
    111 ```