Qfield Plugins Workshop

# QField Plugins workshop

### QGIS User Conference 2025 - Norrköping, Sweden
<img src="assets/qfield_logo.png" style="width:150px">

---

### Who we are

![alt text](assets/opengis.jpg)

--v--

### Who you are

![alt text](assets/norrkoeping.png)

--v--

### AGENDA

1. Why plugins for QField?
2. Types of QField plugins
3. Intro to QML 
4. Developing QField plugins 
5. Implementing the Weather Forecast plugin! 
6. Plugin showcase
7. Resources

---

### Why plugins for QField?

+ Address clients specific needs
+ Keeping the UX simple
+ QField is *your* tool

---

### Types of QField Plugins

PROJECT PLUGINS | APPLICATION PLUGINS
----------------|--------------------
Shared alongside QField project | Shared via URL (ZIP file)
Single plugin | Multiple plugins
Installation not required | Required installation
Lasts project session | Lasts QField session

Project plugins don't need any knowhow to load and can be distributet over the cloud.

</aside>

---

## Intro to QML

--v--

### Why QML

+ Qt Modeling Language, declarative, design-oriented
 + Elements (aka types)
 + Attributes: Properties, Signals, Handlers and Methods
<aside class="notes">
We thought about what language? Python? But QField is delivering a great experience through QML.
</aside>

--v--

### \.\./Elements (aka value types)

```Item, Rectangle, Text, TextInput, MouseArea, Dialog, ...```

----

``` qml
Text {

[...]

}
```

--v--

### \.\./Elements (aka value types)

```Item, Rectangle, Text, TextInput, MouseArea, Dialog, ...```

----

``` qml
Rectangle {
  [...]
  Text {
    [...]
  }
}
```

--v--

### \.\./Elements (aka value types)

```Item, Rectangle, Text, TextInput, MouseArea, Dialog, ...```

----

``` qml
Item {
  [...]
  Text {
    [...]
  }
}
```

<aside class="notes">
An item is a non-visual element. It's the base class of the other elements. Often used as the main element.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  ...

MouseArea {
    id: myArea

...

}
}

```

<aside class="notes">
MouseArea is a non-visual element as well. Talk about the id.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

}
}

```

<aside class="notes">
Id removde for simplicity. And tell them that rectangle has other (invisible) properties, just with default values.
And that if they are testing it, they would need `width: ...; height: ...` and best would be to put into an Item.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

onClicked: ...
  }
}

```

<aside class="notes">
There is an event called `clicked` in MouseArea. To handle this event, we have the handler `onClicked`.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

onClicked: parent.color = "red"
  }
}

```

<aside class="notes">
Show it...
</aside>
--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

onClicked: { parent.color = "red" }
  }
}

```

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

onClicked: myCustomMethod()
    
    function myCustomMethod() {

parent.color = "red"

}
 }
}
```

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {    
  color: theColor
  property var theColor: "green"

MouseArea {
    
    anchors.fill: parent

onClicked: {

parent.theColor = "red"

}
 }
}
```

<aside class="notes">
Example for a property binding. color is connected over theColor. When theColor changes, color changes as well.
Of course here the result will be the same like before and it makes not much sense to implement this. But...
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {    
  color: theColor
  property var theColor: "green"

MouseArea {
    
    anchors.fill: parent

onClicked: {
 if (theColor == "green") {
 theColor = "red"
 } else {
 theColor = "green"
 }
 }
 }
}
```

<aside class="notes">
Show it... We can not make `if(parent.color == "green")` because color is not a string but a color property.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {    
  color: isGreen ? "red" : "green"
  property bool isGreen: true

MouseArea {
    
    anchors.fill: parent

onClicked: {
 isGreen = !isGreen
 }
 }
}
```

<aside class="notes">
Or an alternative way to show this behavior to explain the power of bindings.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"

MouseArea {

anchors.fill: parent

onClicked: { parent.color = "red" }
  }
}

```

<aside class="notes">
Again is an event called `clicked` in MouseArea. To handle this event, we have the handler `onClicked`.
Those follow the signal-slot technic. But we can do signal-slots also ourself.
</aside>

--v--

### \.\./Attributes

```Properties, Signals, Handlers and Methods```

----

``` qml
Rectangle {
  color: "green"
      
  signal colorChanged(info: string)

MouseArea {

anchors.fill: parent

onClicked: {
      parent.color = "red"
      parent.colorChanged("by in the mouse area")
    }
  }

onColorChanged: {
 console.log("Color changed to:", parent.color, " info:", info)
 }
}
```

--v--

## Resources

- QML Docu https://doc.qt.io/qt-6/qtquick-index.html
- QML Reference: https://doc.qt.io/qt-6/qmlreference.html
- QML Tutorial: https://doc.qt.io/qt-6/qml-tutorial.html
- Introduction to Qt/QML, by KDAB: [YouTube Playlist](https://www.youtube.com/watch?v=JxyTkXLbcV4&list=PL6CJYn40gN6hdNC1IGQZfVI707dh9DPRc&index=2)

--v--

## Hello world (QML)

--v--

### \.\./Check it out

``` qml
import QtQuick 2.0

Text {
  text: "Hello world!"
}
```

or here https://qmlweb.github.io

--v--

### \.\./Exercise online

- Go to: https://qmlweb.github.io

- Modify it to change the **text color** on clicking on it.
- ... and *optionally* to change the color back with another click

--v--

## Break ☕

---

## Developing QField plugins

---

### \.\./QField GUI

--v--

### \.\./QField GUI

--v--

### \.\./QField GUI

--v--

### \.\./QField GUI

--v--

### \.\./QField GUI

--v--

### \.\./QField GUI

--v--

### \.\./QField API

--------
```
iface

qgisProject

settings

clipboardManager

...

```

--------

_See [qgismobileapp.cpp](https://github.com/opengisch/QField/blob/master/src/core/qgismobileapp.cpp#L574-L591) for details._

--v--

### \.\./QField API

--------
```
iface.mainWindow()

iface.mapCanvas()

iface.findItemByObjectName("...")

iface.logMessage("...")

iface.addItemToPluginsToolbar()
iface.addItemToMainMenuActionsToolbar()
iface.addItemToCanvasActionsToolbar()

```
--------

_See [appinterface.h](https://github.com/opengisch/QField/blob/master/src/core/appinterface.h) for details._

--v--

### \.\./QField API

--------
``` qml
Theme.mainColor  // #80cc28

Theme.mainTextColor

Theme.mainBackgroundColor

Theme.darkGray

Theme.defaultFont

Theme.getThemeVectorIcon("...")

```
--------

_See [Theme.qml](https://github.com/opengisch/QField/blob/master/src/qml/imports/Theme/Theme.qml) for details._

--v--

### \.\./QField API

--------

```
QfButton

QfToolButton

QfTextField

QfSwitch

QfComboBox

...

```

--------

_See [src/qml/imports/Theme/*](https://github.com/opengisch/QField/blob/master/src/qml/imports/Theme/Theme.qml) for details._

--v--

### \.\./QField API

--------
```
QgsFeature

QgsGeometry

QgsAttributes

QgsPointXY

QgsField

...

```

--------

_See [qgismobileapp.cpp::initDeclarative](https://github.com/opengisch/QField/blob/master/src/core/qgismobileapp.cpp#L381-L407) for details._

--v--

### \.\./QField API

#### Root objects | iface | Theme | QField GUI types | Utils

--------
```
LayerUtils

GeometryUtils

FeatureUtils

CoordinateReferenceSystemUtils

SnappingUtils

...

```

--------

_See [src/core/utils/*](https://github.com/opengisch/QField/tree/master/src/core/utils) for details._

--v--

### \.\./Plugin Location
#### Application Plugins

- Install Plugins via *QField Settings > Manage Plugins*
![alt text](assets/plugin-loc0.png)

--v--

### \.\./Plugin Location
#### Application Plugins

- Find location in "About QField"
![alt text](assets/plugin-loc1.png)
- Folder structure
![alt text](assets/plugin-loc2.png)

--v--

### \.\./Plugin Location
#### Project Plugins

- Copy to project folder
- Name the main-file like the project qgz
![alt text](assets/plugin-loc3.png)

--v--

### \.\./Install "First Demo"

- Get the link on the Schedule...
- Install  "First Demo" via *QField Settings > Manage Plugins*
![alt text](assets/plugin-loc0.png)

--v--

### \.\./Install "First Demo"

Check out the `main.qml` in the plugin directory.

``` qml
import QtQuick

Item {
  Component.onCompleted: {
    iface.mainWindow().displayToast('First demo!')
  }
}
```

--v--

### \.\./Debugging

- Popup on application display

```mainWindow.displayToast("")```

- Log message in the log panel

```iface.logMessage("")```

- Console output (not visible in QField)

```console.log("")```

--v--

### \.\./Let's play
#### All the world is green

```qml
  Rectangle{
    id: myRectangle
    parent: iface.mapCanvas()
    anchors.fill: parent
    color: '#5000ff00'
  }
```

--v--

### \.\./Let's play
#### Template Plugin

https://github.com/opengisch/qfield-template-plugin

--v--

## Break ☕

---

### Weather Forecast plugin

Let's create a forecast plugin!

--v--

### \.\./What we need

+ Button to fetch a weather forecast *(reuse the edited template plugin)*
 + Show an info dialog *(reuse the edited template plugin)*
 + Our location *(reuse the edited template plugin)*
 + API call
   + `XmlHttpRequest` to do an API call and fetch the forecast from open-meteo.com
 + Whatever we want

--v--

### \.\./What we do

+ Check out open-meteo.com
 + Get snippets at pad.opengis.ch (or the slides below)
 + We test the Java Script at https://runjs.app/play
 + We map the weather code to description and image
 + We integrate it into our template plugin

--v--

### \.\./API Request snippet

The Java Script for using `XmlHttpRequest`

``` JavaScript
//Norrköping
lat = 58.5833;
lon = 16.1833;

let request = new XMLHttpRequest();

request.onreadystatechange = function() {
  if (request.readyState === XMLHttpRequest.DONE) {
    console.log(request.response)
  }
}

request.open("GET", "https://api.open-meteo.com/v1/forecast?latitude=" + lat + "&longitude=" + lon + "&daily=weather_code,temperature_2m_max&timezone=auto");

request.send();

```

--v--

### \.\./Code Mapping

```JSON
{
  "0": {
    "description": "Sunny", 
    "image": "http: //openweathermap.org/img/wn/01d@2x.png"
  }, 
  "1": {
    "description": "Mainly Sunny", 
    "image": "http://openweathermap.org/img/wn/01d@2x.png"
  }, 
  [...]
};

---

### Plugin showcase

--v--

### Plugin showcase

Snap!

![](assets/showcase_snap.gif)

--v--

### Plugin showcase

Nominatim locator plugin

![](assets/showcase_nominatim.gif)

--v--

### Plugin showcase

LiveField plugin

---

### Resources

QML Docu https://doc.qt.io/qt-6/qtquick-index.html

QML Reference: https://doc.qt.io/qt-6/qmlreference.html

QML Tutorial: https://doc.qt.io/qt-6/qml-tutorial.html

Introduction to Qt/QML, by KDAB ([YouTube Playlist](https://www.youtube.com/watch?v=JxyTkXLbcV4&list=PL6CJYn40gN6hdNC1IGQZfVI707dh9DPRc&index=2))

QML online editor: https://qmlweb.github.io

QML advanced online editor: https://patrickelectric.work/qmlonline/

QField plugins: https://github.com/topics/qfield-plugin

Plugin icons: https://fonts.google.com/icons

JavaScript online editor: https://runjs.app/play

---

![os_love](assets/love-os.png)

Thanks, and happy coding!