New icon sources for an item

Related to openhab/openhab-core#3052 Depends on the merge of PR openhab/openhab-core#3539 Signed-off-by: Laurent Garnier <[email protected]>
lolodomo · Apr 12, 2023 · 105e117 · 105e117
1 parent 57cfc39
commit 105e117
Showing 1 changed file with 41 additions and 2 deletions.
diff --git a/configuration/items.md b/configuration/items.md
@@ -296,6 +296,8 @@ In the example below, the "switch" icon has been selected:
 Switch Livingroom_Light "Livingroom Ceiling Light" <switch>
 ```
 
+#### Icons provided with openHAB
+
 openHAB provides a set of [classic icons](/docs/configuration/iconsets/classic/) by default.
 Users may add their own icons in either `png` or `svg` format in the openHAB icons configuration folder, `$OPENHAB_CONF/icons/classic/`.
 
@@ -310,14 +312,51 @@ The following guidelines apply to user-added icon files:
 
 **Bitmaps or Vector Graphics:**
 openHAB can work with either Bitmap (`png`) or Vector (`svg`) icon files.
-The format should match the display capabilities of the user interfaces in use (e.g. Basic UI).
+The format should match the display capabilities of the user interfaces in use.
 It is thereby important to decide on one format beforehand; vector graphics are recommended.
 The setting can be changed via UI for most user interfaces.
+Some user interfaces (e.g. Basic UI) don't have this setting because they support both formats transparently.
 Please check the user interface documentation if in doubt.
 Note that image files with the wrong file ending will be ignored.
 
 Users may substitute their own icon for an icon from the default icon set by placing a file in the `$OPENHAB_CONF/icons/classic/` folder with the same filename as the name of the icon being substituted.
 
+#### Icon sources
+
+Some user interfaces supports other icons than those provided by openHAB.
+Thus the most generic reference to an icon is composed of 3 segments separated by a semicolon:
+
+1. The first segment is the icon source
+
+2. The second segment is the icon set from this source
+
+3. The third segment is the name of an icon in this set
+
+As an example, "&lt;oh:classic:switch&gt;" references the "switch" icon from the openHAB classic icon set.
+
+If the value contains only two segments, the first segment is assumed to be the icon source and the second the icon name.
+In this case, the icon set is either undefined or the classic icon set if the source is openHAB.
+This is used in particular when the icon source only provides a single set of icons.
+As an example, "&lt;material:favorite&gt;" references the "favorite" icon from the Material icons.
+"&lt;oh:switch&gt;" references the "switch" icon from the openHAB classic icon set.
+
+If the value contains only one segment, it is assumed to be the name of an icon from the openHAB classic icon set.
+As an example, "&lt;switch&gt;" references the "switch" icon from the openHAB classic icon set.
+
+Here is the list of available icon sources and how they are supported by the major user interfaces.
+
+| Icon source                          | Main UI    | Basic UI      | Android app   | iOS app       |
+| ------------------------------------ | ---------- | ------------- | ------------- | ------------- |
+| openHAN icons (`oh`)                | Supported  | Supported     | Supported     | Supported     |
+| iconify icons (`if` or `iconify`) | Supported  | Supported     | Not supported | Not supported |
+| Material icons (`material`)        | Supported  | Supported     | Not supported | Not supported |
+| Framework7 icons (`f7`)             | Supported  | Not supported | Not supported | Not supported |
+
+You can have a list of all iconify icons [here](https://icon-sets.iconify.design/).
+Please note that they require an Internet access on devices running the user interface to render properly.
+
+You can have a list of all Material icons [here](https://fonts.google.com/icons).
+
 #### Dynamic Icons
 
 Some icons are dynamically selected by openHAB depending on the Item's state.
@@ -332,7 +371,7 @@ Dynamic icon filenames follow the pattern below:
 <name>-<state>.<extension>
 ```
 
-- `<name>` - the name of the icon set
+- `<name>` - the name of the icon
 - `-<state>` - the Item state the icon maps to in lowercase (e.g. "-on" or "-off", "-open" or "-closed")
 - `<extension>` - bitmap (`png`) or vector graphic (`svg`) icon file extension ([see above](#icons))