Static Widgets

Static widgets implement quite basic functionality. A static widget is either a bookmark to a web url or a launcher for a preinstalled native application. It is added to the pinboard via the automatic installation from WeTab Market or the Widget Creator app (Category Tools & Utilities).

A bookmark widget points to a web url and when clicked, it opens up the WeTab Browser displaying the specified url. There are a number of bookmark widgets available in the WeTab Market, however users can also add bookmarks using the WeTab Browser”™s bookmark function. The bookmark widgets installed from the market have a graphical icon, whereas the user created bookmarks show a partly screenshot of the web page.

An application launcher is similar to a desktop shortcut in modern operating systems, when clicked it runs an executable to start a native application, which has to be already installed on the system. (e.g. Video player) When creating application launchers developers have to define RPM dependencies to the actual native application to make sure that the required software is also being installed with the widget.

Technical structure

A static widget consists of a desktop entry file (.desktop) and an optional icon. The desktop entry files (.desktop) used by the pinboard partially implement the FreeDesktop”™s Desktop Entry specification (see http://standards.freedesktop.org/desktop-entry-spec/latest/) However developers should be aware that not all of the keys mentioned in the specification are evaluated. See the table below for supported keys and possible values.

Sample “.desktop” file for an application launcher

[Desktop Entry]
Type=Application
Name=File Browser
Icon=Widget-DateiBrowser.png
Exec=/usr/bin/tiitoo-file-browser
X-tiitoo-permanent=true

Definition of valid keys and values

Key Description Values Optional i18n
Type Defines type of the static widget.
Application | Link No No
Name Title to be displayed on the widget Any string Yes Yes
Icon The PNG image file to be displayed as the widget background. If not provided a generic background image will be used. PNG image file name located in <BOOKMARKS_HOME> Yes Yes
Exec Required and valid only for “Application” type. The full path to the binary executable to start the native application. Program arguments can be passed as regular (space separated). Any spaces in executable path must be escaped using double backslashes. e.g. /opt/Awesome\\\\ App/bin/awesomeness String No Yes
URL Required and valid only for “Link” type. A regular world wide web link String No Yes
X-tiitoo-permanent Prevents users to remove the wiget from the pinboard in configuration mode. The remove button on top left of the widget will be hidden. true | false Yes No
X-tiitoo-desiredPos Recommended position on the pinboard. If set pinboard will try to position this widget in this position, if its not already allocated by another widget. Position in widget space as QPoint e.g. @Point(0 1) Yes No
X-tiitoo-kiosk Valid only for “Link” type. Opens up the WeTab Browser Kiosk Mode (without adressbar and the leftbar) true | false Yes No

Internationalization (i18n)

Name, Icon, Exec and URL fields can be localized using the standard i18n structure of desktop entries. For example, for the field “Name” and the user locale “de_DE” pinboard will search for a value in the following order:

  1. Name[de_DE]
  2. Name[de]
  3. Name

Sample Desktop file using i18n support

[Desktop Entry]
Type=Application
Name=File Browser (Default value – usually in English)
Name[de]=Datei Browser (German value)
Name[en]=File Browser (English value)
Icon=Widget-FileBrowser.png
Icon[de]=Widget-DateiBrowser.png
Exec=/usr/bin/tiitoo-file-browser

Developers should always provide a default value (i.e. a key/value pair without locale extension) as a fallback. Default value should be provided in English language.

Installation

Manual installation

The .desktop entry and the optional icon file have to be placed in a specific folder in user”™s HOME, which is referenced above in the table as BOOKMARKS_HOME:

~/.appData/tiitoo-pinnwand/tiitoo-localbookmarks/

At each start up the pinboard application scans this folder and register newly created .desktop entries as static widgets in its internal database. Once a .desktop entry is recognized as a static widget, pinboard places it automatically to the next available position (if the X-tiitoo-desiredPos is set, the specified position will be tried as first option). For each registered static widget there is also a .pprop file in BOOKMARKS_HOME folder, which is generated by the pinboard. Pprop files are managed by the pinboard and they must never be edited manually.

Installation from the WeTab Market

If a static widget has been submitted to the WeTab Market, the installation procedure will be done by the pinboard.