Plasma/QMLStyle

Directory Structure

• QML files have the .qml suffix go into ui/ they use CamelCase in their filename.
• Javascript files have the .js suffix and go into code/
• If and only if we are in a qml-only plasmoid, the javascript files should be imported with the following keyword:

  import "plasmapackage:/code/Foo.js" as Foo

This way becomes easier to have device-specific qml files, while keeping a single copy of the javascript code. (And we really, really need to find a way to make this magic happen for generic packages.)

JS Code Blocks

For all Javascript code blocks follow the kdelibs code style and must validate when passed through JSLint. This means spaces around operators, if/else on same line as braces, four space indentation (not tabs), semicolons at the end of lines, etc, see techbase.

Items

QML Item declarations follow this pattern:

Item { // brace on same line
    // line indentation
    id: topLevelItem // the id, if any, is the first line

    // Geometry properties
    // grouped propertes as anchors should be in this notation,
    // unless there is only one property
    anchors {
        fill: parent
        rightMargin: 6
    }
    width: 
    height:

    // Signals
    signal somethingJustHappened

    // Properties of this item
    property bool foo

    // Property aliases
    property alias bar: actual.property

    // Properties defined by Item class, except geometry properties
    someProperty: 123

    // Data models, including Plasma.DataSources
    model: { }

    // all on* change functions
    onFooChanged: fooFunction()
    onSomePropertyChanged: { // brace on same line as these use the "name:" style
        fooFunction(); // in blocks, kdelibs style, including semicolons at EOL
    }

    // all functions
    function fooFunction()
    { // open brace on its OWN line
        // code goes here; kdelibs style
    }

    function barFunction()
    {
        // note the newline between this function and the one above it
    }

    // all non-UI sub-items, such as timers
    Timer {
        id: timer
        interval: 100
        onTriggered: fooFunction()
    }

    // all UI sub-items
    Item {
        anchors.fill: parent
    }

    Item {
        // note the newline between items
        id: secondItem
    }

    // all components
    Component {
        id: firstComponent
    }

    Component {
        // note the newline between components
        id: secondComponent
    }

    // States
    states: [
        State {
            name: firstState
            // changes
        },

        State {
            name: secondState
        }
    ] // states

    // Transitions
    transitions: [
            Transition {
                from: "foo"
                to: "bar"
                // transition definition
            },
            Transition {
                from: "foo"
                to: "bar"
                // transition definition
            },
    ] // transitions

    // the "onCompleted" function goes last, as befits the name
    Component.onCompleted: {
        // if multi-line block, brace goes on same line due to "name:" style of declaration
        fooFunction();
    }
} // topLevelItem: for items with considerable contents, comment the last } with what it matches

Best Practices

These are just notes for now, gathered from the discussion on the mailing list, to be turned into something more concrete once the dust settles. Things in this section are not requirements, but recommendations and preferred methods.

• Wrap each block of a QML Item definition with "//BEGIN: <section>" and "//END: <section>" to allow for code folding
• Geometry management, such as anchors, should usually be done where the item is used, not in the item definition (e.g. if there is a MyButton component that is used inside of MyFrame, MyButton anchors should be set in its actual use within MyFrame)
• The top level item in a QML file should have "id: root" for consistency

Scrollbars

Don't use the ScrollBar component directly: use the PlasmaExtras.ScrollArea instead when you need a Flickable, a ListView or a GridView with scrollbars.

ScrollArea {
    id: scrollArea
    ListView {
        model: ....
        /*All ListView code here*/
    }
}

This gives several advantages:

• more memory efficient: it actually creates and instantiates the scrollbars only when needed (i.e. the contents are bigger than the container)
• Automatically sets the proper anchors of the scrollbars to the listview
• On the desktop it will create actual interactive scrollbars, positioned besides the ListView contents, reserving space for it
• On a touch interface it will create non interactive scroll indicators visible only when scrolling. They will be an overlay on top of the ListView. no space will be reserved for them