Projects/Plasma/Weather/Applets: Difference between revisions
(add some documentation how to use the utils.) |
Neverendingo (talk | contribs) m (Text replace - "</code>" to "</syntaxhighlight>") |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
== Introduction == | == Introduction == | ||
NOTE: This information has been changed for KDE 4.3. Conversion is done differently and cleaner. | |||
This page currently only includes some helpful things for applet developers. For the data format, see the [[Projects/Plasma/Weather/Ions|Ion development]] page. | This page currently only includes some helpful things for applet developers. For the data format, see the [[Projects/Plasma/Weather/Ions|Ion development]] page. | ||
== Helpful utils == | == Helpful utils == | ||
Namespace | Namespace WeatherUtils, which can be utilised by including ''Plasma/Weather/WeatherUtils'' inside your applet, provides some helpful functions for you to convert the data gotten from the ions. | ||
The functions related to handling units can use the following units: | The functions related to handling units can use the following units: | ||
* DegreeUnit | |||
* Celsius | * Celsius | ||
* Fahrenheit | * Fahrenheit | ||
| Line 22: | Line 25: | ||
* Knots | * Knots | ||
* Beaufort | * Beaufort | ||
These are packed inside | These are packed inside WeatherUtils::Unit enum and they are ready for you to use already. See the following sections for a small guide how they can be useful for you. | ||
=== convert() === | === convert() === | ||
==== Signature ==== | ==== Signature ==== | ||
< | <syntaxhighlight lang="text">float convert(float value, int srcUnit, int destUnit)</syntaxhighlight> | ||
''value'' is the value to be converted. | ''value'' is the value to be converted. | ||
''srcUnit'' is the unit from where to convert as | ''srcUnit'' is the unit from where to convert as WeatherUtils::Unit. | ||
''destUnit'' is the unit to where to convert as | ''destUnit'' is the unit to where to convert as WeatherUtils::Unit. | ||
==== Usage ==== | ==== Usage ==== | ||
| Line 39: | Line 42: | ||
For example the conversion of ''value'' from meters per second to miles per hour can be done like this: | For example the conversion of ''value'' from meters per second to miles per hour can be done like this: | ||
< | <syntaxhighlight lang="text">WeatherUtils::convert(value, WeatherUtils::MetersPerSecond, WeatherUtils::Miles);</syntaxhighlight> | ||
To make conversions even easier the ion developers are advised to use the same units when passing data to applets, so that one can pass an integer given by an ion directly to this function. | To make conversions even easier the ion developers are advised to use the same units when passing data to applets, so that one can pass an integer given by an ion directly to this function. | ||
| Line 46: | Line 49: | ||
=== getUnitString() === | === getUnitString() === | ||
==== Signature ==== | ==== Signature ==== | ||
< | <syntaxhighlight lang="text">QString getUnitString(int unit, bool plain=false)</syntaxhighlight> | ||
''unit'' being the unit as | ''unit'' being the unit as WeatherUtils::Unit. | ||
''plain'' being whether you want to have the unit in user presentable form or not. | ''plain'' being whether you want to have the unit in user presentable form or not. | ||
==== Usage ==== | ==== Usage ==== | ||
This function allows you as the developer to get a string based on the given | This function allows you as the developer to get a string based on the given WeatherUtils::Unit. This can be useful when you want to display a given format as a string in your user interface or you want to use it to decide which picture to display. | ||
To get a localized string to be used directly in the user interface you can just call it this way: | To get a localized string to be used directly in the user interface you can just call it this way: | ||
< | <syntaxhighlight lang="text">WeatherUtils::getUnitString(WeatherUtils::Beaufort);</syntaxhighlight> | ||
which gives you i18nized version of Bft. | which gives you i18nized version of Bft. | ||
To get a plain string, for example to use to load an image based on it, you just set ''plain'' to true: | To get a plain string, for example to use to load an image based on it, you just set ''plain'' to true: | ||
< | <syntaxhighlight lang="text">WeatherUtils::getUnitString(WeatherUtils::Beaufort, true);</syntaxhighlight> | ||
which returns "bft" to you. | which returns "bft" to you. | ||
| Line 66: | Line 69: | ||
=== degreesToCardinal() === | === degreesToCardinal() === | ||
==== Signature ==== | ==== Signature ==== | ||
< | <syntaxhighlight lang="text">QString degreesToCardinal(float degrees)</syntaxhighlight> | ||
''degrees'' being the degrees to be converted. | ''degrees'' being the degrees to be converted. | ||
| Line 74: | Line 77: | ||
Using this function is simple, just call: | Using this function is simple, just call: | ||
< | <syntaxhighlight lang="text">WeatherUtils::degreesToCardinal(degrees);</syntaxhighlight> | ||
and you will be provided by a cardinal value for the given degree. | and you will be provided by a cardinal value for the given degree. | ||
Latest revision as of 20:57, 29 June 2011
Introduction
NOTE: This information has been changed for KDE 4.3. Conversion is done differently and cleaner.
This page currently only includes some helpful things for applet developers. For the data format, see the Ion development page.
Helpful utils
Namespace WeatherUtils, which can be utilised by including Plasma/Weather/WeatherUtils inside your applet, provides some helpful functions for you to convert the data gotten from the ions.
The functions related to handling units can use the following units:
- DegreeUnit
- Celsius
- Fahrenheit
- Kelvin
- Kilometers
- MetersPerSecond
- Miles
- Kilopascals
- InchesHG
- Millibars
- Hectopascals
- Centimeters
- Millimeters
- Inches
- Knots
- Beaufort
These are packed inside WeatherUtils::Unit enum and they are ready for you to use already. See the following sections for a small guide how they can be useful for you.
convert()
Signature
float convert(float value, int srcUnit, int destUnit)
value is the value to be converted.
srcUnit is the unit from where to convert as WeatherUtils::Unit.
destUnit is the unit to where to convert as WeatherUtils::Unit.
Usage
Convert function can be used to convert the given value between different units. This makes it easy for applet developer to represent a value given by an ion in a selected format.
For example the conversion of value from meters per second to miles per hour can be done like this:
WeatherUtils::convert(value, WeatherUtils::MetersPerSecond, WeatherUtils::Miles);
To make conversions even easier the ion developers are advised to use the same units when passing data to applets, so that one can pass an integer given by an ion directly to this function.
getUnitString()
Signature
QString getUnitString(int unit, bool plain=false)
unit being the unit as WeatherUtils::Unit.
plain being whether you want to have the unit in user presentable form or not.
Usage
This function allows you as the developer to get a string based on the given WeatherUtils::Unit. This can be useful when you want to display a given format as a string in your user interface or you want to use it to decide which picture to display.
To get a localized string to be used directly in the user interface you can just call it this way:
WeatherUtils::getUnitString(WeatherUtils::Beaufort);
which gives you i18nized version of Bft.
To get a plain string, for example to use to load an image based on it, you just set plain to true:
WeatherUtils::getUnitString(WeatherUtils::Beaufort, true);
which returns "bft" to you.
degreesToCardinal()
Signature
QString degreesToCardinal(float degrees)
degrees being the degrees to be converted.
Usage
This function can be used to convert the wind and solar degrees to a cardinal value (like used in compasses). For example 32° converts to NNE.
Using this function is simple, just call:
WeatherUtils::degreesToCardinal(degrees);
and you will be provided by a cardinal value for the given degree.