You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page is a collection of QField plugin framework APIs and behaviors to guide you into writing your own plugins.
9
-
10
-
To see what's possible and get inspiration from the community, you can browse a list of all available plugins on the [QField Plugin Topic on GitHub](https://github.com/topics/qfield-plugin).
11
-
12
-
## Hello QField World
13
-
14
-
Scripting QField plugins require basic knowledge of QML and Javascript.
15
-
Qt offers a useful [introductory tutorial](https://doc.qt.io/qt-6/qml-tutorial.html) worth reading.
16
-
17
-
Once you’ve familiarized yourself with the QML environment, you are set to go.
18
-
This is a minimal example that will display a toast message upon successfully loading a QField plugin:
19
-
20
-
```qml
21
-
import QtQuick
22
-
import org.qfield
23
-
24
-
Item {
25
-
Component.onCompleted: {
26
-
iface.mainWindow().displayToast('Hello world!')
27
-
}
28
-
}
29
-
```
30
-
31
-
## Creating a zipped plugin
32
-
33
-
A valid zipped plugin must contain a main.qml file at the root of the zip archive, which will be used by QField to activate the plugin.
34
-
An optional metadata.txt can also be used to provide basic details such as the plugin name, brief description, and author name.
35
-
A sample typical `metadata.txt` content would look like this:
36
-
37
-
```ini
38
-
[general]
39
-
name=Hello World Plugin
40
-
description=This is simple and brief description.
41
-
author=OPENGIS.ch
42
-
icon=logo.svg
43
-
```
44
-
45
-
This [QField template plugin](https://github.com/opengisch/qfield-template-plugin) offers a simple skeleton from which you can build plugins from scratch.
46
-
47
-
## `iface` interface
48
-
49
-
Much like QGIS plugins, QField offers an `iface` object exposing a number of functionalities plugins can leverage.
50
-
The current invocable functions include:
51
-
52
-
-`iface.mainWindow()`: returns the QML ApplicationWindow instance, where plugins can parent their items via `iface.mainWindow().contentItem` and have access to functionality such as displaying toast messages using `iface.mainWindow().displayToast(text)`.
53
-
-`iface.mapCanvas()`: returns the map canvas item, which exposes crucial properties including `iface.mapCanvas().mapSettings` from which the extent, scale, etc. can be retrieved and modified.
54
-
-`iface.findItemByObjectName(string)`: returns a item living within the QField application window matching the object name `string`, such as `iface.findItemByObjectName("positionSource")` to reach the positioning item which controls the GNSS device and returns position details.
55
-
Additional items' object name strings can be found by viewing the [application window QML code](https://github.com/opengisch/QField/blob/master/src/qml/qgismobileapp.qml).
56
-
-`iface.addItemToPluginsToolbar(item)`, `iface.addItemToDashboardActionsToolbar(item)`, `iface.addItemToCanvasActionsToolbar(item)`: adds a given `item` in predefined containers within the QField application window.
57
-
Using these functions insure that items added by multiple plugins will happily co-exist.
58
-
59
-
## Utilities objects
60
-
61
-
QField ships with a number of utilities objects to manipulate features and geometries, access map layers, read and write project and map layer variables, and much more.
62
-
63
-
To familiarize yourself with these, visit QField’s source code’s [utilities directory](https://github.com/opengisch/QField/tree/master/src/core/utils) where .h\[eader\] files will provide documentation for all invocable functions.
64
-
65
-
## Plugin code snippets
66
-
67
-
### Search bar integration
68
-
69
-
The plugin framework empowers you to integrate custom searches into the QField search bar through the `QFieldLocatorFilter` item which can be added into a plugin's root item:
// prepareResult is the signal needed to pass on a result
126
-
// you can trigger the signal as many times as you need to pass on all available results
127
-
prepareResult(result_details);
128
-
}
129
-
}
130
-
```
131
-
132
-
This [QField OpenStreetMap Nomination plugin](https://github.com/opengisch/qfield-nominatim-locator) is a good example to learn more about search bar integration.
133
-
134
-
### Configuration button within the plugin manager
135
-
136
-
For plugins requiring user configuration, QField allows for these to add a configuration button within its plugin manager.
137
-
138
-
To do so, you can simply add a `function configure()` invocable function attached to the plugin's root item:
139
-
140
-
```qml
141
-
import QtQuick
142
-
import org.qfield
143
-
144
-
Item {
145
-
// ...
146
-
147
-
function configure()
148
-
{
149
-
optionDialog.open();
150
-
}
151
-
152
-
Dialog {
153
-
id: optionDialog
154
-
parent: iface.mainWindow().contentItem
155
-
visible: false
156
-
modal: true
157
-
title: "Configuration"
158
-
159
-
// ...
160
-
}
161
-
}
162
-
```
163
-
164
-
### Geometry highlighter canvas overlay
165
-
166
-
Plugins can make use of QField's geometry highlighter item to flash created or fetched geometries through the following code:
167
-
168
-
```qml
169
-
import QtQuick
170
-
import org.qfield
171
-
172
-
Item {
173
-
// ...
174
-
175
-
property var geometryHighlighter: iface.findItemByObjectName('geometryHighlighter')
176
-
177
-
function demo() {
178
-
// Flash Null Island geometry
179
-
let geom = GeometryUtils.createGeometryFromWkt("POINT(0 0)")
180
-
let crs = CoordinateReferenceSystemUtils.fromDescription("EPSG:4326")
0 commit comments