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
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:
- Name[de_DE]
- Name[de]
- Name
Sample Desktop file using i18n support
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:
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.
