Libpnd hub

libpnd - the Pandora Library

Design considerations

The library is of course broken into parts:

include - include these files to make use of the lib lib - the code that produces the lib test - mini tools to test various pieces of the lib in isolation bin - test tools testdata/ - for testing /etc/pandora; will contain 'conf' dir, for example

Once we get it near being useful or done, perhaps some documentation will be in order ;) For now though, here are a couple notes about the design.

- it is straight C code, to be maximumly re-usable (perhaps C++ and other language bindings will tie back to it)

- we do pretend to follow some OO principles; data hiding, encapsulation...

- Since much is subject to change (especially during development of the lib) I want the internals hidden; this also protects the user down the road.. if we change the internals (likely!), it should not break the users code too much.. API should be changing less frequently than the internals

- As a result of that decision, 'handles' are used; a handle is a 'black box' type, something you cannot just use 'handle h; h -> foo = 5' type code for. Instead, internally the library will cast the handle to the actual useful type (which may involve pointer arith etc). This way the user can be returned a handle, and pass the handle to various access functions to get useful data/operations.. but the user is not encouraged to look inside the data objects himself

- As another implication, access functions are available aplenty; it is a little unwieldy perhaps, but its all about keeping the API good without the user peeking inside and risking being broken down the road. (By example, consider.. you use ftell() on a FILE object; you don't go looking in FILE for the 'position' member, since it might be platform specific, etc.)

Opportunities for improvement

Certainly nothing is perfect, especially when chasing moving targets. Some aspects of the library are less efficient, or missing, or buggy, and a few things are noted here should someone have time. The API was designed to be pretty stable so the internal code could be altered without breaking the API interface.

- better iso lang handling .. due to shift from original PXML spec to new PXML spec with better lang support I've not updated some of the internal code, API uses etc to handle it. (even .desktop files could include all iso-lang titles, and let the WM pick through as the spec suggests.)

Obtaining the library

libpnd is in the Official Pandora GIT repo.

You can do a pull as follows:

mkdir libpnd cd libpnd git init git remote add libpnd ssh://skeezixgit@git.openpandora.org/srv/git/pandora-libraries.git git pull libpnd master

Integration with FreeDesktop .desktop systems

Icons

There are some rules for Icons in PXML.xml and pnd/directory bundles

- An Icon should be in the root of the directory or .pnd bundle

- An Icon must be specified in the PXML.xml if you expect it to work

- As the PXML.xml is parsed, the icon is sought; if the icon is specified, but not found, it is assumed to be a system default icon and the filename will be placed into the .desktop Icon= line verbatim (ex: Icon=foo.png), and the window manager presumably will know how to locate it. If the icon is specified, and is found, then it will be copied into the configured IconPath, and the full path to it will be used for the Icon= line in the .desktop file ex: Icon=/tmp/myicon.png). If no icon is specified in the PXML file, then no Icon= line will be entered into the .desktop and the WM will presumably apply a default icon based on category or whatever.