Projects/Plasma/Weather/Applets: Difference between revisions

From KDE TechBase
(add some documentation how to use the utils.)
 
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 WeatherFormula, which can be utilised by including plasma/weather/formulas.h inside your applet, provides some helpful functions for you to convert the data gotten from the ions.
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 WeatherFormula::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.
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 ====
<code>float convert(float value, int srcUnit, int destUnit)</code>
<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 WeatherFormula::Unit.
''srcUnit'' is the unit from where to convert as WeatherUtils::Unit.


''destUnit'' is the unit to where to convert as WeatherFormula::Unit.
''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:
<code>WeatherFormula::convert(value, WeatherFormula::MetersPerSecond, WeatherFormula::Miles);</code>
<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 ====
<code>QString getUnitString(int unit, bool plain=false)</code>
<syntaxhighlight lang="text">QString getUnitString(int unit, bool plain=false)</syntaxhighlight>


''unit'' being the unit as WeatherFormula::Unit.
''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 WeatherFormula::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.
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:
<code>WeatherFormula::getUnitString(WeatherFormula::Beaufort);</code>
<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:
<code>WeatherFormula::getUnitString(WeatherFormula::Beaufort, true);</code>
<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 ====
<code>QString degreesToCardinal(float degrees)</code>
<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:
<code>WeatherFormula::degreesToCardinal(degrees);</code>
<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.