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 ```