From Pandora Wiki
Revision as of 05:39, 24 November 2008 by Chip (talk | contribs) (wikification of reference PDF)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Pandora XML (PXML) File structure v1.2

A *.PXML-File should be included with every Pandora application. The name can be anything you like, as long as it uses a .PXML suffix. Basically it's an XML file (and follows the XML standards), but as some apps might use .XML files themselves, it has been named to PXML.

It includes various information about the program as well as can be used to save configuration options from different GUIs (by adding their own config sections). Every GUI should crawl through the directories in the default app path on the SD Cards and on the NAND to find all the PXML-Files which include everything needed to run apps and sort them into categories / subcategories. ![CDATA[ can be used in all fields.

Everything within are the general information which should be used by every GUI.i The PATH is ALWAYS relative to the location of the PXML file. The root name has to be <PXML>, the encoding is UTF-8.

A second file (custconf.pxml) can reside in the same directory. It includes all users settings (i.e. Different categories) and custom GUI configs. It overrides any settings that conflict with the default *.PXML, it always overrides the complete categories section if it exists.

A third file (catlangs.pxml) will be included within the standard firmware and includes translated names of categories (for multilingual menus). It will be updated when new categories are needed. The GUIs should read it and – if they have a language setting – use the localized name for a category name if it is included in that file (ISO code again).

Discription of PXML File Entries

Entry Description Mandatory?
<title> </title> The application name. Can be used by the GUI to show the correct name. Yes
<title lang='ISO'> </title> Multilingual names for the title entries. Replace ISO with the ISO­Code of the country (i.e. <title lang='DE'> for German title) No
<description> </description> The description of the application. Standard BB­Code tags can be used to style the text. Yes
<description lang='ISO'> </description> Multilangual names for the description entries. Replace ISO with the ISO­Code of the country. No
<standalone> </standalone> Set to "Yes" if the program can be run as standalone or "No" if it needs parameters to run. Yes
<icon> </icon> The path and name to the icon to be shown. No
<preview> </preview> One or more preview pictures of the program (each picture is between <previewitem> </previewitem>) No
<author name='x' website='x' email='x' /> The name, website and email address of the author. Pretty cool with direct internet access from the Pandora :) No
<version major='number' minor='number' release=number build='number' /> The version numbers. Can be used to check for updates. Yes
<exec> </exec> The name of the executable to be started. Yes
<category> </category> The category / subcategories where it will be listed within the menu. If you use a default category (see list below), you only need to use the English name and it will be translated automatically. If you use your own categories, you can define translated names within this file. Use <subcategory> for subcategories (as many as you want). A program can be listed in multiple categories by simply including more <category></category>­ sections. One category is needed, the rest is optional.
<osversion major='number' minor='number' release='number' build='number' /> If an app needs at least OS Version x.x.x of the Pandora OS, it can be stated here. No
    <name> </name>
    <filetype> </filetype>
    <parameter> </parameter>
    <compresspath> </compresspath>
Associates the program with one or more filetypes (can be used by file explorers). Delimit each filetype with "," If filetypes need special start parameters, they can also be defined here. You can also associate the same filetype with multiple programs – the explorer should then show <name> </name> and let the user select what to do. If compressed files which are in a certain directory should also be associated with that program, include the path (absolute or relative) within <compresspath> </compresspath>. Multiple associations with different parameters can be defined by simply including more <associatonitem> </associationitem>­ sections. Optional when <standalone> is set to "yes". Otherwise at least one <association> is required.
<clockspeed> </clockspeed> The clock speed the app will be started with. Doesn't change clock speed if undefined. No
<background> </background> Defines if program should start in background (set to "Yes") or foreground (set to "No"). Defaults to "No" if undefined. The GUI should have some kind of wrapper which automatically restarts it after the program quits after running in foreground mode. No
<startdir> </startdir> Change the current path to a different (relative to the PXML file) path and start the program afterward. The current path will always set to the path of the PXML­ file if undefined. No

Example PXML File

Everything printed in bold is mandatory. The rest is optional.

<?xml version="1.0" encoding="UTF­8" standalone="yes"?>
  <title>Program Title</title>
  <title lang='de'>Program Title in German Language</title>
  <title lang='it'>Program Title in Italian Language</title>
This is the [b]English Description[/b] of the file.
Can use [i]multiple lines[/i] and BBCode.
  <description lang='de'>The German Description</description>
  <description lang='it'>The Italian Description</description>
  <author name = 'EvilDragon' website='http://www.openpandora.org' />
  <version major='1' minor='1' release='1' build='2' />
  <category>Main category
<subcategory>Subcategory 1</subcategory>
<subcategory>Subcategory 2</subcategory>
  <category>Alternate category
<subcategory>Alternate subcategory</subcategory>
  <osversion major='1' minor='1' release='1' build='2' />
<name>View this Picture</name>
<name>Convert this Picture</name>
<name>Watch This Movie</name>

Example of catlangs.pxml

<?xml version="1.0" encoding="UTF­8" standalone="yes"?>
<category = 'Games'>
<category = 'Application'>

External Links

PXML Reference PDF