-
Notifications
You must be signed in to change notification settings - Fork 7
Mirror repository, PRs are not watched, please use Xfce's GitLab
License
xfce-mirror/xfce4-weather-plugin
Folders and files
Name | Name | Last commit message | Last commit date | |
---|---|---|---|---|
Repository files navigation
XFCE4-WEATHER-PLUGIN ========================================================================== You can always find up-to-date information at the plugin homepage: https://docs.xfce.org/panel-plugins/xfce4-weather-plugin CONTENTS ========================================================================== * ABOUT * USAGE * INFORMATION FOR PACKAGE MAINTAINERS AND DISTRIBUTORS * MET.NO API DOCUMENTATION * DEBUGGING AND REPORTING BUGS * REQUIREMENTS AND DEPENDENCIES * EASY BUILD INSTRUCTIONS * TRANSLATING THE PLUGIN FOR YOUR LANGUAGE * ICON THEMES * CACHING * HIDDEN OPTIONS ABOUT ========================================================================== Originally written by Bob Schlärmann, this panel plugin shows information about your local weather in the panel, using forecast data provided by met.no. USAGE ========================================================================== The first time you open the configuration dialog, the weather plugin automatically configures itself to fetch weather data from a place which should be near you - based on your IP address. It will also try to guess and setup your unit system according to the country code. You can change this location using the Change... button, and searching for the city, country, address, monument etc. you're interested in. Only latitude, longitude and altitude (the latter only matters outside of Norway) will be used for the data requests, so you can edit the location name to anything you like. Besides location parameters, the configuration dialog boasts a variety of other configuration options to alter the appearance of icons, tooltips and parts of the summary window. On the scrollbox tab you can choose and rearrange the values presented by the scrollbox. Middle-click on the font or color button unsets a previously set font or color. Tooltips give detailed information about nearly every widget of the configuration dialog and will tell you what a certain value (temperature, apparent temperature, wind,...) does and how it can be interpreted. On the panel icon, a middle click forces an update, left click brings up the so-called summary window with a forecast page that shows forecasts for the next few days and a details page with more information on the current and plugin data. Right-clicking opens the contextual menu with more actions. INFORMATION FOR PACKAGE MAINTAINERS AND DISTRIBUTORS ========================================================================== If you're going to distribute this package, and legal concerns and principles allow you to do it, please be so kind and set the GEONAMES_USERNAME configure option for the GeoNames web service which is used for altitude and timezone detection. GeoNames requires one to register an account and limits requests on a per-hour and per-day basis to prevent misuse of their service. There are no other restrictions and registration is free, uncomplicated and takes less than a minute (https://www.geonames.org/export/web-services.html). Performing these steps will ensure automatic altitude and timezone detection are kept operational for all users of the plugin. Currently, it is no big deal and only a precaution, as there are likely not that many users setting up the plugin within the same hour and exhausting the credits. Still, if it is ok with you to register a username yourself for the users of your package, then it would certainly help should that unlikely case become true. While the user can also set this via a hidden option, the developer/maintainer of the plugin thinks the user should not be bothered with it, as every user would need to do it by default, and that would hurt user experience. MET.NO API DOCUMENTATION ========================================================================== To get a quick overview, please consolidate the met.no API weather documentation and especially their FAQ, which answers some questions left open by the former: * General documentation and data licensing https://api.met.no/weatherapi/documentation https://api.met.no/faq.html https://api.met.no/license_data.html * Service-specific documentation https://api.met.no/weatherapi/locationforecast/2.0/documentation https://api.met.no/weatherapi/sunrise/2.0/documentation For more technical details you might need to study the XML schema corresponding to the document in question. DEBUGGING AND REPORTING BUGS ========================================================================== Before reporting bugs or asking for new features, please open an issue on https://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin/ and check the TODO file, because your issue or request might have been reported already or be in planning. However, feel free to add any information not yet mentioned that you find useful. First, if you're having trouble with downloading data, then you might look at the warnings in the panel output. In case of an error, the HTTP status code will be reported, along with a short text given the reason, as a result of a download request. It is easy to look up this code on the web to find more detailed information. Although if it is a download problem and your connection is ok, then most probably the service isn't available at the moment due to maintenance or a similar reason, so just wait some time and try later. Please do not report bugs about such problems. If you encounter problems like crashes or weird behaviour, it might prove insightful to enable panel debugging as follows: 1) Quit the current running panel instance using 'xfce4-panel -q'. 2) Set the PANEL_DEBUG environment variable to 'weather' or 'all': export PANEL_DEBUG=weather 3) Start the panel and let it write its output to a file, e.g.: xfce4-panel > panel.log 2>&1 & disown 4) Watch output using tail -f or less or whatever you like: tail -f panel.log This will make the plugin explain what it's currently doing and dump data it downloaded from the various sources. More information about debugging panel plugins can be obtained from several pages of the Xfce Wiki at https://docs.xfce.org/xfce/xfce4-panel/debugging. It's also relatively easy and often very helpful to create a backtrace using gdb or any other debugger should the plugin crash: 1) Find the process ID of the weather plugin with something like 'pgrep -f libweather.so'. Let's assume the resulting PID is 1234. 2) Attach the GNU debugger to that process: 'gdb attach 1234'. 3) The plugin will be frozen now. Tell the debugger to let it continue with the 'cont' command. 4) Produce the crash if possible, or wait until it crashes. 5) GDB will detect the crash and freeze the plugin again. Use 'bt' to print a nice backtrace. Report the issue to the Xfce bugtracker at https://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin, providing the backtrace. 6) 'quit' exits the debugger. BUILD REQUIREMENTS AND DEPENDENCIES ========================================================================== To be able to build the plugin, the following requirements have to be met in addition to those of XFCE-4.16: * >=libxml-2.4.0 * >=libsoup-3.0.0 * >=upower-0.9.0 (optional) You might also need developer libraries necessary for building other parts of XFCE. Usually autogen.sh / configure will tell you, otherwise look at the XFCE build instructions https://docs.xfce.org/xfce/building and the release information https://wiki.xfce.org/releng/4.14/roadmap. EASY BUILD INSTRUCTIONS ========================================================================== If you're interesting in building the plugin yourself, these instructions provided here will work for most users. If not, please look at the INSTALL file or ask at a forum for your linux distribution or try the methods explained on https://www.xfce.org/community. Make sure you have installed the needed dependencies (see previous section BUILD REQUIREMENTS AND DEPENDENCIES). For the panel being able to find the plugin, it is important to set the proper prefix. The prefix is the place in the filesystem where the plugin files gets installed. It has to match the prefix used for building the panel. There's nothing the plugin can do about that requirement. When you're using the panel provided by the package management system of your distribution, then the prefix is in most cases /usr, otherwise the default prefix is /usr/local. If you want to install the current version from git, execute the following command in the weather plugin project directory (make sure you have GNU automake installed!): 1a) ./autogen.sh --prefix=/usr Otherwise, if you've downloaded the tarball from e.g. https://archive.xfce.org/, issue the following command: 1b) ./configure --prefix=/usr If 1a) or 1b) fail, you should receive an error message telling you the cause for the failure (e.g. missings libraries). If you're missing a dependency you need to install it using the package management system of your distribution. Distributions commonly have two versions of a software package: One containing the supplementary files needed for compiling other packages (usually called "dev"-packages), and the other one providing the runtime libraries etc. While the latter is usually installed, the former often is not, so better check this. Note: To solve distribution-specific problems the most efficient way is to ask at a forum for your distribution, not on a general forum. Then for both cases: 2) make If this fails, file a bug on https://gitlab.xfce.org/panel-plugins/xfce4-weather-plugin, or send a mail to the xfce mailing list and provide make output. Finally, and usually as root: 3) make install Note: Depending on your prefix, this might overwrite an existing version of the plugin. You can later uninstall the plugin (as root) with 4) make uninstall The panel should then recognize the new plugin, if it doesn't try to restart it using xfce4-panel -r. If it still doesn't work after that try to ask for help somewhere (forums, mailing lists, #xfce on IRC). Please do not report such problems on the bug tracker. TRANSLATING THE PLUGIN FOR YOUR LANGUAGE ========================================================================== If you need help getting started with translating the weather plugin into your language, please visit https://translations.xfce.org/ and absorb the information that is there, especially on the *Help* page! There is other useful documentation available on this topic, try this wiki page for a start: https://wiki.xfce.org/translations/translation_guidance_in_xfce TRANSLATORS, PLEASE MAKE SURE YOU CHECK YOUR FILE FOR ERRORS BEFORE UPLOADING IT! Otherwise, it will break compilation of the plugin. It is easy to do this with the following command (where file.po is the po file of your language): msgfmt -c --check-accelerators=_ -v -o /dev/null <file.po> This plugin provides a lot of descriptions via the tooltips in the config dialog. These aim to give short, but interesting explanations for the various units and available values. While the conventions should be followed for most of the widgets - you might look up such agreements and recommendations on the Xfce wiki or ask your translation team about them -, the descriptions should be translated in a way that they are understandable and comfortable to read in your own language, which means that they don't have to be translated literally. On the contrary, it is recommended that you use your own words and phrases to get the best results. The author believes this will make translation much easier and more fun, without denying it can be quite tedious sometimes. If your po file is out of date and doesn't contain all strings that appear in the plugin source code, you can use the build system to update it for you. See the previous section EASY BUILD INSTRUCTIONS for setting up the build system and perform step 1a to clone the repository and generate the make files using automake. If this succeeds, simply change to the po subdirectory and execute the command "make update-po". This will regenerate all po files in the po directory and mark changed strings as fuzzy or obsolete, and add new strings as untranslated. You can then work on it as usual. However, if you need to start with a translation completely from scratch (the po file doesn't exist and isn't listed in transifex), then please write a mail to [email protected] or [email protected] or use the bug tracker and ask for such a file being added to the project. Currently, only the package maintainer or developer of the plugin can add this new file and include it in the automake files in the git repository so that it is integrated into the build process and packaged properly. Korean translator Seong-ho Cho also recommended the following command - to be executed in the project's root directory - for creating a fresh pot file: xgettext --keyword=_ --keyword=d_:1 --keyword=P_:1,2 --keyword=P_:1,2 --keyword=N_ --keyword=NP_:1,2 --from-code=UTF-8 --foreign-user --output=xfce4-weather-plugin.master.untitled.pot panel-plugin/*.[ch] This gives a po-template file with untranslated strings, with the advantage being that this only requires the gettext package to be installed. Of course, you can always simply ask the developer/package maintainer to generate and add a new po file for your language, so that you can download it using transifex. ICON THEMES ========================================================================== 1) Icon theme support -------------------------------------------------------------------------- As of 0.8.3, xfce4-weather-plugin supports icon themes. This requires a specific icon naming scheme that corresponds to the met.no API symbols definition. Icon sets following the freedesktop.org standardized naming scheme are not supported because they lack too many icons the plugin would need for the various weather conditions provided by met.no, so adhereing to the standard wouldn't make much sense (see the next section 2) for more information). If you want to design your own set, please have a look at the default Liquid theme that is included in this package to get an idea what the icons should look like and at the source file weather-translate.c, where you will find references and explanations for the weather symbols. The plugin searches for icon themes in the following directories, in this particular order (this very same order will be used for listing the themes in the configuration dialog): $XDG_CONFIG_HOME/xfce/weather/icons $(datadir)/icons Where * $XDG_CONFIG_HOME is usually /home/user/.config * $(datadir) is whatever you configured it to be on build-time, like /usr/local/share/xfce4/weather/icons or /usr/share/xfce4/weather/icons In these directories the plugin shall find subdirectories that contain the icon themes. Let's look at the structure by example of the Liquid theme (files or directories in brackets [] are optional): Liquid |--22 |--48 |--128 \--theme.info The theme.info file needs to be present, or the plugin will not consider the directory a valid icon theme. This file may contain the following entries: ------------------------------- theme.info ------------------------------- Name=Liquid Author=Unknown Description=Modified icon theme originating from the Superkaramaba Liquid Weather plugin License=GPL-2 -------------------------- theme.info ends here -------------------------- Make sure that each entry is on one line. Entries may not span multiple lines, all additional lines will be ignored. You can use \n for newlines, though. These values will be shown in the tooltip of the theme selection combo box in the configuration dialog. You might want to put an extra LICENSE file into your theme directory. Directories 22, 48 and 128 shall contain the icons in PNG format (or at least with a PNG extension) at approximately the size the directory names suggest. Icon sizes for the panel icon will be chosen depending on the panel size. For the tooltip, the icon will be taken from the 128 directory, and medium sized icons (48) for the forecast window and similar places. Here is a list showing which icon sizes are recommended for the various panel sizes: Directory Panel size Recommended icon sizes 22 16-23 22, 24, 16 48 24-48 48, 24, 32 128 49-128 128, 96, 80, 64 To be found by the plugin, the icons need to be named exactly as follows (listed in alphabetical order): * cloud.png * fog.png * lightcloud.png * lightrain.png * lightrainsun.png * lightrainthunder.png * lightrainthundersun.png * nodata.png * partlycloud.png * rain.png * rainthunder.png * sleet.png * sleetsun.png * sleetsunthunder.png * sleetthunder.png * snow.png * snowsun.png * snowsunthunder.png * snowthunder.png * sun.png At night time, the plugin will first look for icons having a "-night" suffix, e.g. partlycloud-night.png, lightrainsun-night.png etc. The rest of the filename needs to be the same as for the day icon, and the icons should probably look similar, however with brother sun replaced by sister moon. Of course, the latter is rather a design decision than a technical necessity. If no night variant is provided, the plugin will fallback to using the day icon. Note that not all symbols are expected to have icons for night time. For example, the CLOUD symbol is used when there is 100% cloudiness and the sun or moon cannot be seen. However, the plugin will still look for such night icons, in case the designer has another idea how to indicate night time without creating confusion. The only exception to this is the icon for NODATA, which has no night variant. This icon will only be shown when the plugin has not been configured yet - but then more likely only the NODATA icon of the default theme will appear and not that of your theme -, or when there is no data available, for example in case of a network error. It also serves as the fallback icon for all missing day icons. Finally, if you do not provide a NODATA icon for your theme, then the one of the default theme will be used which is assumed to always be present. If the plugin can't find a specific icon, it will remember that it is missing and not try to read it again until you restart the panel for change the theme. Also, icons for the panel and for the tooltip will be cached. These are measures to minimize disk access. Just keep that in mind when you work on your icons when the plugin is running. All icon sets included and distributed in the xfce4-weather-plugin package are under GPL by default. 2) Freedesktop standardized naming scheme -------------------------------------------------------------------------- It was suggested (https://mail.xfce.org/pipermail/xfce/2012-August/031180.html) to make use of icon themes implementing the freedesktop standardized naming scheme, like some KDE and GNOME application do, for reference please see https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html. This might not be such a good idea, however, because * the standard only provides a limited set of weather icons which will not be enough to represent all possible conditions the weather plugin can show, * it is unclear what to do when those icons are missing, and solving this in a good manner will make things unnecessarily complicated for the plugin, * with the Liquid icon set there already is a good default icon set that suits most users, * the deficiences of the Liquid theme can be solved more easily with proper theming support and a bit of editing (providing an alternative Liquid theme for dark panels). Of course, you might take any such freedesktop compliant theme as the basis for your personal new icon set, so you only have to design or assemble the remaining few icons. And finally, with a bit of searching you can find lots of free-to-use icons and icon sets on the web! 3) The "Liquid" icon theme and its license -------------------------------------------------------------------------- In August 2012 a question was raised about the license of the Liquid icon theme (see https://mail.xfce.org/pipermail/xfce/2012-August/031178.html and https://mail.xfce.org/pipermail/xfce/2012-August/031188.html for further discussion), so let's elaborate a bit on that. According to original author of the plugin, Bob Schlärmann, the "Liquid" icon theme originates from the now abandoned "Liquid Weather" package for KDE Superkaramba and has been part of the weather plugin since around 2004. While this is not 100% certain, it is supposed to be licensed under GPL-2, as is the "Liquid Weather" script. Unfortunately, the Liquid Weather website at liquidweather.net is no more, and so obtaining the script package is a bit difficult and requires searching for mirrors. A link that still works at the time of this writing is: ftp://ftp.wanadoo.nl/pub/mirrors/FreeBSD/ports/distfiles/lwp-15.0.skz However, trying to contact the developers of Liquid Weather in September 2012 for verification about this issue did not yield any response. An archived version of the website which contains information about the previously available icon sets and the license is still available at https://web.archive.org/web/20100724155753/http://liquidweather.net/icons.php: "On this page, you'll find additional iconsets and backgrounds for liquid weather ++ - please note that the backgrounds are not easily installable with versions earlier than v9.0. With the exception of the weather.com, Beginning and Um icons, I believe that these iconsets are either GPL or available for redistribution. If I am wrong, please let me know and I'll remove them. Please note that the weather.com icons are used with permission of the weather.com website, and the Beginning and Grzanka icons are used with the permission of their authors. This means that these iconsets may not be copied, modified or redistributed without permission. The same applies to the Umicons included in the core liquid weather tarball." A further look at http://kde-look.org/content/show.php?content=6384, brings forth this bit of information: "License: Everything is GPL, EXCEPT FOR some of the icon sets, which are distributed with the permission of their authors." Looking at the archived web page above, the Liquid weather icon set is not to be found in the exceptions list, so according to that it should be GPL. Besides, the similarity of the name of both the icon set and its containing package also hints to that licensing. To sum it all up, the icon theme is considered licensed under GPL too, though its original author remains unknown. If someone can resolve this, please send a mail to the current maintainer of the weather plugin, and he/she will give proper credit. CACHING ========================================================================== As of 0.8.3, xfce4-weather-plugin caches downloaded weather and astronomical data. Per plugin instance, one file containing that cached data is created in the user cache directory, typically in $HOME/.cache/xfce4/weather. This file will be generated or overwritten on every weather data download and read before any location data change. Cached data has a certain expiry date and will not be used if it is older than that. There is an option not exposed by the UI to change the maximum age; This parameter is called "cache_file_max_age" and can be found in the plugin configuration file usually located in ~/.config/xfce4/panel. It is set to the maximum age in seconds and defaults to 48 hours (172800 seconds). By using caching, some deficiencies of data provided by met.no can be worked around: First, their location forecast service wasn't really meant to provide data for the current weather, which the plugin tries to convey. However, the forecasts for the next few hours (typically the next 3 hours or sometimes even the next hour for cities, in any case at max 6 hours for all locations) are in most cases good enough to fake current conditions using interpolation. Note that other weather providers often present values for current weather that have been measured half an hour or even more ago, so in most cases it won't make a big difference. Second, caching reduces network traffic. Data will only be downloaded after the download interval time has expired. Information about download times can be seen in the details page of the summary window. Third, caching data enables the plugin to work without internet connection for some time (see the previous paragraph about cache_file_max_age for information about configuring this expiry time). Note that refreshing data by middle-clicking the icon or by clicking on the appropriate context menu entry does not clear the cache. However, data that has been downloaded will always overwrite any existing data. HIDDEN OPTIONS ========================================================================== Further options are available which are not exposed via the UI because they are usually not needed. To add or edit these, quit the panel with "xfce4-panel -q", make the desired modifications to the appropriate config file in $HOME/.config/xfce4/panel, then restart the panel with "xfce4-panel &". * cache_file_max_age: Maximum allowed age of the cache file in seconds. See the previous section CACHING for an explanation. * geonames_username: The GeoNames webservices are credit-based, and although the plugin uses them only for setting up its configuration, the credits could get exhausted if many users use the plugin. This configuration option gives the user the chance to set a registered GeoNames username manually (see INFORMATION FOR PACKAGE MAINTAINERS AND DISTRIBUTORS on how to register). Delete this option completely to use the default GeoNames username set at build time. * power_saving: If the plugin has been compiled with support for upower, it will try to extend battery life by taking the following measures: If the machine is on battery, - decrease the regular update interval to 30 seconds, - stop the scrollbox animation and - update the summary window clock only every minute. Setting this value to false will deactivate power saving. If upower support has not been compiled in, then this setting will have no effect.
About
Mirror repository, PRs are not watched, please use Xfce's GitLab
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published