aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Vrátil <dvratil@kde.org>2016-08-05 00:49:40 (GMT)
committerDaniel Vrátil <dvratil@kde.org>2016-08-05 00:49:40 (GMT)
commit73bd97b75d76e06fe758e590ddeaa778f03c994f (patch)
treed99390d8e0dd8c987602313d675df9672b6d6d04
parent5614e65eb6217e5aa9d29dbb86d752b660b8eac6 (diff)
Enable docs generation on api.kde.org, add tags documentation
Enable GrantleeTheme docs to be on api.kde.org and add syntax documentation for the {% icon } Grantlee tag provided by the plugin from GrantleeTheme.
-rw-r--r--README.md23
-rw-r--r--docs/plugins_icon.md42
-rw-r--r--metainfo.yaml6
3 files changed, 70 insertions, 1 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..191a3e0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+# GrantleeTheme
+
+GrantleeTheme library provides a class for loading theme packages containing
+set of templates.
+
+## Template syntax
+
+The library provides a KDE-specific Grantlee plugins that introduce
+new tags into the Grantlee theme syntax:
+
+* [Icons](@ref plugins_icon)
+
+## Localization
+
+The library provides GrantleeKI18nLocalizer, a Grantlee::AbstractLocalizer
+subclass that integrates with Ki18n (the KDE localization framework) instead
+of the Qt localization system.
+
+## Qt Resource System support
+
+Grantlee only supports loading templates from files on disk currently.
+The GrantleeTheme library provides QtResourceTemplateLoader, which
+allows loading Grantlee templates from the Qt Resource System.
diff --git a/docs/plugins_icon.md b/docs/plugins_icon.md
new file mode 100644
index 0000000..0041c7d
--- /dev/null
+++ b/docs/plugins_icon.md
@@ -0,0 +1,42 @@
+# Plugins: icon {#plugins_icon}
+
+This plugin introduces a new template tag `icon`. The tag allows easilly displaying
+standard icons in the templates by using XDG icon names. The behaviour is identical
+to resolving icon path via KIconLoader::iconPath() and passing the path to the
+template as a string.
+
+The `icon` tag supports up to three arguments:
+
+ {% icon ICON_NAME [SIZE_OR_GROUP] [ALT_TEXT] %}
+
+* *ICON_NAME* is the name of the icon you would normally pass to QIcon::fromTheme()
+ to get the icon. The name can be a string or a name of a context variable holding
+ the string. This argument is mandatory.
+* *SIZE_OR_GROUP* can either be requested icon size in pixels, or one of the keywords
+ `desktop`, `toolbar`, `maintoolbar`, `small`, `panel`, `dialog`, `sizesmall`, `sizesmallmedium`,
+ `sizemedium`, `sizelarge`, `sizehuge` or `sizeenormous`. Those strings map to values
+ in KIconLoader::Group and KIconLoader::StdSizes enumerators. This argument is optional,
+ the default value is `small`.
+* *ALT_TEXT* A string to be used as an alt text for the image in the generated HTML code.
+ The string must be wrapped in localizer function (`_("Some string")`) or can be
+ a name of a context variable holding the string. This argument is optional.
+
+## Examples
+
+Show an icon called "kontact", size medium, no alt text:
+
+ {% icon kontact }
+
+Show an icon called "kontact", size small, alt text in variable `kontact_icon_alt`:
+
+ {% icon kontact kontact_icon_alt }
+
+Show an icon called "edit-redo", size medium, alt text "Redo" (localized):
+
+ {% icon edit-redo medium _("Redo") }
+
+Show an icon as specified in `button.icon` context variable, size small, alt test specified in
+`button.label` context variable:
+
+ {% icon button.icon small button.label }
+
diff --git a/metainfo.yaml b/metainfo.yaml
index cfe87e3..6666630 100644
--- a/metainfo.yaml
+++ b/metainfo.yaml
@@ -1,5 +1,5 @@
maintainer: mlaurent
-description: kdepim grantlee theme support library
+description: KDE PIM Grantlee theme support library
tier: 3
type: functional
platforms:
@@ -12,3 +12,7 @@ libraries:
cmake: "KF5::GrantleeTheme"
cmakename: KF5GrantleeTheme
+public_lib: true
+group: kdepim
+platforms:
+ - name: Linux