libfoXdesktop is foXdesktop's core library, i.e. every foXdesktop application uses it.
It extends FOX (foXdesktop's widget set)
with additional classes, icons and registry entries.
There are certain standards for all foXdesktop applications.
Since not everything is described here yet have a look at e.g. foXman.
for an example implementation.
Each foXdesktop application uses GNU automake/autoconf (not yet documented).
Make sure you use libfoXdesktop's FDApp instead of FXApp for using
icon files instead of harwired icons (see below) and having an easy
way to invoke your program's help (see below).
If your application provides a preferences dialogue you are recommended
to make it a foXdesktop component so that it appears in foXcontrol too.
(not yet documented).
Icons are an important thing for every graphical application.
An icon can theoretically have every size but FOX's widgets
traditionally use normal-sized (32x32 pixels) and mini (16x16) icons.
FOX originally uses hard-wired icons. With the FOX distribution comes a tool
called reswap you can turn icons into C arrays with. As a result those
generated icon source files can regularily be included and compiled.
Hardwired icons may be good for binary-only commercial software.
But of course there are serveral disadvantages with this approach:
Sharing icons between different applications is not impossible but unnecessarily
difficult. And without some tricks you have to recompile your program
everytime you want to change one of its icons.
In contrast foXdesktop prefers normal xpm files loaded at runtime.
Although this is not the "native" FOX way (except for special cases like mime types)
you can relatively easily do it.
FOX's class FXIconDict handles everything regarding loading (and caching) icons.
You just have to tell it the name of the icon you want to have loaded
(using FXIconDict's "insert" method), e.g. "foo/bar.xpm" and you get an
appropriative pointer. FXIconDict parses a colon-separated string (a number of directories)
you have to set in order to locate the directory the requested icon files are relative to.
For your convenience FDApp (which you are recommended to use instead of FXApp)
already has an FXIconDict variable you can get using FDApp::ico()
and reads its icon path from the registry (section SETTINGS, key iconpath).
The registry file "Desktop" supplied with libfoXdesktop sets iconpath to:
"~/.foxicons:/usr/local/share/icons:/usr/share/icons".
When you FXIconDict::insert an icon the first valid full icon path matches,
so if you have e.g. two icons with the same name in both /foo and /bar
and your iconpath is "/foo:/bar" you'll get the icon in /foo.
Install all icons shipped with your application in $(datadir)/icons and/or its subdirs.
$(datadir) is defined as $(prefix)/share and $(prefix) defaults to /usr/local.
It is very unlikely that someone uses another directory than /usr or /usr/local
as his $(prefix). In that case your user knows what he does and will likely
add his special $(datadir)/icons to iconpath for foXdesktop applications to find those icons.
Remember: iconpath is a FOX registry entry so each user can overwrite it
in her local registry files.
You have to distinguish two types of icons: Icons solely used by your application
and those useful for other purposes too. The latter icons (including your application's
identifier icon(s) - they can be useful for other things too, imagine e.g. a taskbar)
are meant to be installed directly in $(datadir)/icons respectively $(datadir)/icons/mini
(the normal-sized icon and its mini counterpart should share the same name).
Application-specific icons are better located in their own subdirectories, called after
your application's name, $(datadir)/icons/$(app name) and $(datadir)/icons/mini/$(app name).
For preventing name clashes with existing icons in $(datadir)/icons (you do not want
to be overwritten) I recommend you to make every icon/subdir start with "foX".
Having some documentation is generally a good idea for even
the smallest and most simple piece of software.
Traditionally Unix-based systems provide man pages (you can view
using man or as an alternative foXman) and info pages as the
most important sources of information.
Especially (but not only) for modern desktop systems however
HTML-based documentation has evolved as a pseudo standard
because HTML is far superiour concerning layout and formatting
and provides hyperlinks (this is also true for info pages
which were thought to be a replacement for man pages but came too late).
As a result all parts of foXdesktop are documentated in HTML as well.
libfoXdesktop defines standard locations for the HTML files and APIs
for its applications to easily access them.
Similar to iconpath (see the previous section) there is another
registry entry containing a list of directories below which any requested
HTML-pages are searched: It is called docpath and defaults to
"/usr/local/share/doc:/usr/share/doc". Just use $(datadir)/doc in your
application's Makefiles and install all documentation files (*.html, *.jpg...)
in $(datadir)/doc/HTML/ll/app with app being the application's name and
ll identifiying the language of your documentation. A valid documentation path
is e.g. $(datadir)/doc/HTML/en/foXman.
Within your application's help routine the easiest way to show the corresponding
help is to invoke FDApp::showHelp ().
Remember, using FDApp instead of FXApp is generally a good idea :-)
showHelp takes two arguments: app and file. Again app is the application's name
for identifying the directory below $(datadir)/doc/HTML/ll.
Please note that at the moment showHelp always uses "en" for "ll" so possibly
available documentation in languages other than English is not considered.
file can be omitted and defaults to index.html.
There is no built-in browser capability or similar in libfoXdesktop or in libFOX
so showHelp just invokes an external browser with the detected file name.
It reads section "PROGRAM ALIASES", key "xbrowser" from the registry
and uses "xterm -e lynx" if nothing can be found.
libfoXdesktop uses the same versioning system as the Linux kernel,
i.e. versions with an even minor number (0.2.7, 0.4...) are (considered) stable.
Every (stable) release is backwards compatible with all previous ones with the
same (even) minor number (e.g. libfoXdesktop 0.2.4 is compatible with libfoXdesktop 0.2.1).
Versions with an odd minor number (0.3, 0.5.2...) are unstable.
They are recommended for programmers and very interested users only.
libfoXdesktop is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
See the AUTHORS file in the libfoXdesktop distribution for all copyright holders.
http://foxdesktop.sourceforge.net
Mailing list:
foxdesktop-devel@lists.sourceforge.net
Mailing list subscription page:
http://lists.sourceforge.net/lists/listinfo/foxdesktop-devel