# ROX-CLib

A library for ROX applications written in C.

## For Users

### Installation

Copy to a suitable place such as `~/lib` or make sure it is on your `$LIBDIRPATH`. If you use Archive to extract it from then downloaded archive then make sure you rename it to `ROX-CLib`.

Compile using `ROX-CLib/AppRun --compile` or running ROX-CLib from the filer.

You will need GTK+ 2.x, libxml 2.4.x and GNU `make`. Linux users should already have GNU make installed `/usr/bin`. Other OS's may require you use a different directory (`/usr/bin/local) or program name (`gmake`). Set the environment variable MAKE to the correct value before compiling, e.g.`

    $ MAKE=gmake ROX-CLib/AppRun --compile

## For Programmers

### Compiling and linking against the library

Compile the library first

Copy the libdir script from `ROX-CLib/$PLATFORM/bin/libdir` into your app dir.

Add the output of

       ROX-CLib --cflags

to your compile line, e.g.

       ROX_CLIB="`$APP_DIR/libdir ROX-CLib`/AppRun"

       gcc `$ROX_CLIB --cflags` -c main.c

You should include the main file:

       #include <rox/rox.h>

and any of the others you need.

Add the output of

       ROX-CLib --cflags
       ROX-CLib --libs

to your link line, e.g.

       ROX_CLIB="`$APP_DIR/libdir ROX-CLib`/AppRun"

       gcc `$ROX_CLIB --cflags` -o main main.o `$ROX_CLIB --libs`

If you are using autoconf and building a ROX program then:

- Copy ROX-CLib/Help/aclocal.m4 to your programs src directory.
- In src/configure.in add:

      ROX_CLIB(2, 0, 0)

- In src/Makefile.in add:

        ROX_CLIB = @ROX_CLIB_PATH@/AppRun

  and to CFLAGS add: ``${ROX_CLIB} --cflags`` and to LDFLAGS add: ``${ROX_CLIB} --libs``
- In AppRun (and AppletRun if it is an applet) ensure you have:

         APP_DIR=`dirname $0`
         APP_DIR=`cd $APP_DIR;pwd`; export APP_DIR
         if [ -z "$LD_LIBRARY_PATH" ]; then
             LD_LIBRARY_PATH=`$APP_DIR/libdir ROX-CLib --runtime`
         else
             LD_LIBRARY_PATH=`$APP_DIR/libdir ROX-CLib --runtime`:$LD_LIBRARY_PATH
         fi
         export LD_LIBRARY_PATH

### Zero Install

To use ROX-CLib through Zero Install change the use of libdir to:

        ROX_CLIB="`$APP_DIR/libdir --0install www.kerofin.demon.co.uk ROX-CLib`/AppRun"

### Library reference

Organized by header file. Last updated for version 2.1.4. Use as e.g.

    #include <rox/rox.h>
    #include <rox/rox_soap.h>

- rox.h
- choices.h
- error.h
- gtksavebox.h
- infowin.h
- rox_debug.h
- rox_dnd.h
- rox_path.h
- rox_resources.h
- rox_soap.h
- rox_filer_action.h
- applet.h
- rox_soap_server.h
- options.h
- basedir.h
- mime.h
- appinfo.h
- mime_handler.h
- uri.h

#### rox.h

Top level include. It includes:

- choices.h
- options.h
- error.h
- rox_debug.h
- rox_resources.h
- infowin.h

Six functions are declared:

`void rox_init(const char *program, const char *domain, int *argc, char ***argv)`

  This handles the initialization of the library. It calls:

  - `gtk_init(argc, argv)`
  - `rox_debug_init(program)`
  - `choices_init()`
  - `options_init_with_domain(program, domain)` (if it detects an $APP_DIR/Options.xml file)
  - `rox_dnd_init()`
  - `mime_init()`

  domain is used to differentiate your program called "App" from every other program called "App". It is a domain name under the control of the program's author. If you do not have a unique domain, you can use your email address.

`void rox_init(const char *program, int *argc, char ***argv)`

  This handles the initialization of the library. It is equivalent to `rox_init_with_domain(program, NULL, argc, argv)`.

`const gchar *rox_get_program_name(void);`

  Returns the program name, as passed to rox_init(). If rox_init() was not called then it returns NULL.

`const gchar *rox_get_app_dir(void);`

  Returns the program's application directory, the environment variable APP_DIR. If APP_DIR is not defined then it returns NULL.

`GdkPixbuf *rox_get_program_icon(void);`

  Returns the program icon, loaded from the file .DirIcon in the application directory. If there is no icon then NULL is returned.

`int rox_clib_version_number(void)`

  Returns the version number of the library, so that 1.2.3 is encoded as 10203.

`const char *rox_clib_version_string(void)`

  Returns a string of the version number of the library, in the form "x.y.z (nth month year)" (actually the contents of the Version tag in the AppInfo.xml file).

`int rox_clib_gtk_version_number(void)`

  Returns the version number of the GTK+ library ROX-CLib is linked against, so that 1.2.3 is encoded as 10203.

`const char *rox_clib_gtk_version_string(void)`

  Returns a string of the version number of the GTK+ library ROX-CLib is linked against.

`void rox_add_window(GtkWidget *window)`

  Registers the window with the window counting system. When the window is destoyed it will automatically be de-registered.

`int rox_get_n_windows(void)`

  Returns the number of windows registered.

`void rox_main_loop(void)`

  This behaves as `gtk_main()`, except that it will return when the number of registered windows reaches zero. If there are no registered windows when called it will return immediately. (Opening an options window via `options_show()` registers a window).

`void rox_main_quit(void)`

  Exit from `rox_main_loop()` by calling `gtk_main_quit()`. The number of registered windows is ignored.

#### choices.h

Interface to the choices system and $CHOICESPATH. Originally by Thomas Leonard and taken from the ROX-Filer source.

`void choices_init(void)`

  Must be called before the other choices_* calls.

`GPtrArray *choices_list_dirs(const char *dir)`

  Returns an array of the directories in CHOICESPATH which contain a subdirectory called 'dir'. The result should be freed by passing it to `choices_free_list()`

`void choices_free_list(GPtrArray *list)`

  Frees the list returned by `choices_list_dirs()`

`gchar *choices_find_path_load(const char *leaf, const char *dir)`

  Get the pathname of a choices file to load. Eg: `choices_find_path_load("menus", "ROX-Filer")` -> `"/usr/local/share/Choices/ROX-Filer/menus"`.

  The return values may be NULL - use built-in defaults - otherwise `g_free()` the result.

`gchar *choices_find_path_save(const char *leaf, const char *dir, gboolean create)`

  Returns the pathname of a file to save to, or NULL if saving is disabled. If 'create' is TRUE then intermediate directories will be created (set this to FALSE if you just want to find out where a saved file would go without actually altering the filesystem).

  `g_free()` the result.

`gchar *rox_choices_load(const char *leaf, const char *dir, const char *domain)`

  Get the pathname of a choices file to load. Eg: `rox_choices_load("menus", "ROX-Filer", "rox.sourceforge.net")` -> `"/usr/local/share/Choices/ROX-Filer/menus"` (or `"/etc/xdg/rox.sourceforge.net/ROX-Filer/menus"` ).

  The return values may be NULL - use built-in defaults - otherwise `g_free()` the result.

  This uses the XDG base directories specification (used by basedir.h) to look up the file, falling back on the old $CHOICESPATH system. domain may be `NULL`.

`gchar *rox_choices_save(const char *leaf, const char *dir, const char *domain)`

  Returns the pathname of a file to save to, or NULL if saving is disabled.

  `g_free()` the result.

  This uses the XDG base directories specification (used by basedir.h) to look up the file, but it does not use the old $CHOICESPATH system. domain may be `NULL`.

#### error.h

Reporting errors.

`void rox_error(const char *fmt, ...)`

  Generates a string according to a printf style formatting string and supplied args, then displays the string in a dialog window with the title "Error!" and an OK button.

#### gtksavebox.h

Simple RISC OS style save box.

GtkSaveBox is a GTK+ widget, derived from GtkWindow. Originally by Thomas Leonard and taken from the ROX-Filer source.

Functions
  `GtkWidget* gtk_savebox_new(void)`

    Creates the GtkSaveBox widget.

  `void gtk_savebox_set_icon(GtkSavebox *savebox, GdkPixmap *pixmap, GdkPixmap *mask)`

    Sets the icon that may be dragged about.

  `void gtk_savebox_set_pathname(GtkSavebox *savebox, gchar *pathname)`

    Sets the pathname in the entry box.

Types
  `enum { GTK_XDS_SAVED, GTK_XDS_SAVE_ERROR, GTK_XDS_NO_HANDLER, }`

    Used by the `save_to_file` signal:

    GTK_XDS_SAVED | Done the save - no problem
    GTK_XDS_SAVE_ERROR | Error during save - reported
    GTK_XDS_NO_HANDLER | Used internally (sanity checking)

Signals
  `gint save_to_file(GtkSavebox *savebox, const gchar *pathname)`

    Save the data to disk using this pathname. Return `GTK_XDS_SAVED` on success, or `GTK_XDS_SAVE_ERROR` on failure (and report the error to the user somehow). DO NOT mark the data unmodified or change the pathname for the file - this might be a scrap file transfer.

  `void saved_to_uri(GtkSavebox *savebox, const gchar *uri)`

    The data is saved. If 'uri' is non-NULL, mark the file as unmodified and update the pathname/uri for the file to the one given.

#### infowin.h

RISC OS style information window.

ROXInfoWin is a GTK+ widget, derived from GtkDialog. Changed in ROX-CLib 2.1.2: InfoWin was renamed ROXInfoWin and the functions renamed accordingly. Functions remain available under the old names for binary compatability, but should not be used in new code.

Functions
  `GtkWidget* rox_info_win_new(const gchar *program, const gchar *purpose, const gchar *version, const gchar *author, const gchar *website)`

    Create a new ROXInfoWin object. The data in the window is taken from the function arguments. `rox_info_win_new_from_appinfo` is prefered.

  `GtkWidget* rox_info_win_new_from_appinfo(const gchar *program)`

    Create a new ROXInfoWin object. The data in the window is taken from the file $APP_DIR/AppInfo.xml, if it exists.

  `void rox_info_win_add_browser_command(ROXInfoWin *iw, const gchar *cmd)`

    Adds a command which will visit a named web site. The command will be called with a single argument, the URL passed in `rox_info_win_new()` or defined in $APP_DIR/AppInfo.xml.

    Deprecated, ROXInfoWin now uses rox_uri_launch() which relies on the handler for the text/x-uri MIME type.

  `GtkWidget* info_win_new(const gchar *program, const gchar *purpose, const gchar *version, const gchar *author, const gchar *website)`

    Deprecated. Use `rox_info_win_new_from_appinfo()` instead. This is the same as that, except that the new window is persistant: when closed it is hidden, not destroyed.

  `GtkWidget* info_win_new_from_appinfo(const gchar *program)`

    Deprecated. Use `rox_info_win_new_from_appinfo()` instead. This is the same as that, except that the new window is persistant: when closed it is hidden, not destroyed

  `void info_win_add_browser_command(ROXInfoWin *iw, const gchar *cmd)`

    Deprecated.

Signals

  None.

#### rox_debug.h

Utilities for generating debug output. Unless the pre-processor symbol `DEBUG` is defined and non-zero before rox_debug.h is included then nothing is declared.

`void rox_debug_init(const char *progname)`

  Initialises the debug system. progname is the name of the program which will prefix the output. Should be called at start, if not (or progname==NULL) then progname is assumed to be "ROX".

`void rox_debug_printf(int level, const char *format, ...)`

  Sends a debug message, using glib's `g_logv`. level is the level of severity and should be in the range 0-5, with 0 most severe. The user controls the amount of output by setting the environment PROGNAME_DEBUG_LEVEL to the maximum severity to display.

`#define dprintf rox_debug_printf`

  Aliases `dprintf` as `rox_debug_printf`

#### rox_dnd.h

Utilities to simplify the handling of drag and drop for the client. Based on the ROX-Filer code written by Thomas Leonard

`typedef gboolean (*rox_dnd_handle_uris)(GtkWidget *widget, GSList *uris, gpointer data, gpointer udata)`

  Type of function called when a widget registered with rox_dnd has a list of URIs dropped on it. It should return TRUE if handled successfully, FALSE otherwise.

`typedef gboolean (*rox_dnd_handle_xds)(GtkWidget *widget, const gchar *path, gpointer data, gpointer udata)`

  Type of function called when a widget registered with rox_dnd has a direct save on it. It should return TRUE if handled successfully, FALSE otherwise.

`void rox_dnd_init(void)`

  Called to initialise rox_dnd, before any other call.

`void rox_dnd_register_full(GtkWidget *widget, guint flags, rox_dnd_handle_uris uris, rox_dnd_handle_xds xds, gpointer udata)`

  Registers a widget with rox_dnd to handle any drops on it. There are no flags defined yet, so flags must be set to zero. uris handles URI list drops, xds handles the XDirectSave protocol. udata is passed to the handler routine.

`GSList *rox_dnd_filter_local(GSList *uris)`

  Scans list of URIs and picks out only those that refer to local files. Free result with rox_dnd_local_free().

`void rox_dnd_local_free(GSList *paths)`

  Frees the data returned by rox_dnd_filter_local().

#### rox_path.h

Utilities for handling the URIs used in the drag & drop protocol. All returned strings should be passed to `g_free()` when done.

`gchar *rox_path_get_local(const gchar *uri)`

  Returns the local path of the URI if it refers to a local file: path, otherwise it returns NULL.

`gchar *rox_path_get_server(const gchar *uri)`

  Returns the host part of the URI if it is a file: URI, otherwise it returns NULL.

`gchar *rox_path_get_path(const gchar *uri)`

  Returns the path part of a file: URI regardless of whether it is the local host or not.

`int rox_hostname_is_local(const gchar *hname)`

  Returns `TRUE` if the host name hname is one of the valid host names for the current machine.

#### rox_resources.h

Utility functions for finding resource files, which may be locale specific.

`gchar *rox_resources_find(const gchar *app_name, const gchar *leaf, const gchar *lang)`

  Search `$CHOICESPATH`, then `$APP_DIR` for a directory called `Resources` which contains the file `leaf`, whether in a sub-directory `lang` or directly. Returns the full path if found (pass to `g_free` when done) or `NULL` if not. lang may be `ROX_RESOURCES_NO_LANG` to not search for sub-directories, or `ROX_RESOURCES_DEFAULT_LANG` for the sub-directory appropriate for the selected language.

  If the language is set to `en_GB.ISO8859-1` then the sub-directories tried are:

  - {Choices}/app_name/en_GB.ISO8859-1/
  - {Choices}/app_name/en.ISO8859-1/
  - {Choices}/app_name/en_GB/
  - {Choices}/app_name/en/
  - {Choices}/app_name/
  in that order.

#### rox_soap.h

Communicating with the filer via SOAP. Based on the ROX-Filer code written by Thomas Leonard

`typedef struct rox_soap_filer ROXSOAP;`

  This is an opaque type representing the connection to an instance of the filer.

`typedef void (*rox_soap_callback)(ROXSOAP *filer, gboolean status, xmlDocPtr reply, gpointer udata)`

  Defines the function called when the SOAP call completes. If status is `FALSE` then the call failed and reply is `NULL`. If status is not `FALSE` then the call succeeded and reply contains the result (may still be `NULL`).

`void rox_soap_init(void);` =09

  Initializes the data.

`void rox_soap_define_program(const char *name, const char *atom_fmt, const char *command);`

  Define how to connect to the named program.

  name | name of program as passed to rox_soap_connect
  atom_fmt | format of atom name to use to connect, %e is effective UID, %h is FQDN of display
  command | command that may be fed the SOAP document on stdin if connecting via the atom fails, may be NULL

  An entry for ROX-Filer is pre-defined. (`"ROX-Filer"`, `"_ROX_FILER_%e_%h"`, `"rox -R"`).

`char *rox_soap_atom_name_for_program(const char * name);`

  Returns the name of the atom which will be used to locate the given program. It uses the format given in the `rox_soap_define_program()` call, with the defined substitutions. Pass to `g_free()` when done.

`gboolean rox_soap_ping(const char *prog);`

  Returns `TRUE` if the named program is contactable via SOAP.

`ROXSOAP *rox_soap_connect(const char *prog_name);`

  Initialise the connection to the named program.

`ROXSOAP *rox_soap_connect_to_filer(void);`

  Initialise the connection to the filer.

`gboolean rox_soap_send(ROXSOAP *program, xmlDocPtr doc, gboolean run_prog, rox_soap_callback callback, gpointer udata);`

  Send the XML document to program using SOAP. If run_prog is `TRUE` and there is no program to talk to, use `rox_soap_send_via_pipe()`. Returns `TRUE` if comms succeeded, when complete callback is called with the status and reply.

`gboolean rox_soap_send_via_pipe(ROXSOAP *filer, xmlDocPtr doc, rox_soap_callback callback, gpointer udata);`

  Send the XML document to the program, using the command defined by `rox_soap_define_program()`. When complete callback is called with the status and reply.

`void rox_soap_set_timeout(ROXSOAP *filer, guint ms);`

  Set the timeout when contacting ROX-Filer (in ms, defaults to 10000). If filer is `NULL` it sets the timeout for all new connections.

`xmlDocPtr rox_soap_build_xml(const char *action, const char *ns_url, xmlNodePtr *act);`

  Build part of XML document to send. The action to perform is in name space ns_url. Add arguments to the node act, then call `rox_soap_send()` with the return value.

`const char *rox_soap_get_last_error(void);`

  Returns the text of the last error raised. This may be `"No error"` if no error has occured, or `rox_soap_clear_error()` has been called.

`void rox_soap_clear_error(void);`

  Clears the error text.

`void rox_soap_close(ROXSOAP *filer);`

  Close connection.

#### rox_filer_action.h

These functions drive ROX-Filer via the rox_soap.h interface above.

`typedef enum panel_side { ROXPS_TOP,ROXPS_BOTTOM,ROXPS_LEFT,ROXPS_RIGHT } ROXPanelSide;`

  The four possible places for a panel, used in rox_filer_panel().

`#define ROX_FILER_DEFAULT (-1)`

  This value means "use value user has selected in options".

`char *rox_filer_version(void);`

  Return the version string for the current filer. Return value should be passed to g_free when done.

`void rox_filer_open_dir(const char *filename);`

  Open a viewer for the given directory.

`void rox_filer_close_dir(const char *filename);`

  Close all viewers for the given directory and any subdirectories.

`void rox_filer_examine(const char *filename);`

  Re-fresh the viewer for the given directory.

`void rox_filer_panel(const char *name, ROXPanelSide side);`

  Open a panel with the given name on the specfied side. If name is "" then the panel on that side is closed instead.

`void rox_filer_panel_add(ROXPanelSide side, const char *path, int after);`

  Add an object to the panel on the specfied side. If after is `FALSE` then the object is placed on the left (top or bottom panels) or top (left or right panels), otherwise the other end.

`void rox_filer_pinboard(const char *name);`

  Display pinboard name on the desktop background. Name can be a name in Choices (eg, `MyPinboard') or a full pathname.

`void rox_filer_pinboard_add(const char *path, int x, int y);`

  Add an object to the pinboard at the specfied co-ordinates.

`void rox_filer_run(const char *filename);`

  Run filename as if it was clicked on in the filer.

`void rox_filer_show(const char *directory, const char *leafname);`

  Open directory and flash the file leafname inside it.

`void rox_filer_copy(const char *from, const char *to, const char *leafname, int quiet);`

  Copy the object from into the directory to. If leafname is not `NULL` then use it as the new name of the file. If quiet is `FALSE` then prompt the user before copying.

`void rox_filer_move(const char *from, const char *to, const char *leafname, int quiet);`

  Move the object from into the directory to. If leafname is not `NULL` then use it as the new name of the file. If quiet is `FALSE` then prompt the user before moving.

`void rox_filer_link(const char *from, const char *to, const char *leafname);`

  Symbolically link the object from into the directory to. If leafname is not `NULL` then use it as the new name of the file.

`void rox_filer_mount(const char *mountpoint, int quiet, int opendir);`

  Attempt to mount on the directory mountpoint (which should be in `/etc/fstab` or similar). If quiet is `FALSE` then prompt the user before mounting. If opendir is not `FALSE` then open a viewer for the new directory if succesfully mounted. The ability to mount is normally restricted.

`char *rox_filer_file_type(const char *file);`

  Return a string describing the MIME type of the given file (which need not exist!). Return value should be passed to `g_free` when done. If `NULL` is returned then there was an error in communication.

`int rox_filer_have_error(void);`

  Returns non-zero if an error message is available.

`const char *rox_filer_get_last_error(void);`

  Returns the text of the last error raised. This may be `"No error"` if no error has occured, or `rox_filer_clear_error()` has been called.

`void rox_filer_clear_error(void);`

  Clears the error text.

#### applet.h

Utilities for developing ROX applets.

`typedef enum panel_location { PANEL_TOP, PANEL_BOTTOM, PANEL_LEFT, PANEL_RIGHT, PANEL_UNKNOWN } PanelLocation;`

  Defines the four possible locations for the panel containing the applet, plus an error condition.

`extern void applet_popup_menu(GtkWidget *plug, GtkWidget *menu, GdkEventButton *evbut);`

  Shows a pop-up menu in a suitable place for the applet. It is assumed that this will be called in a `button_press` handler which is passed a `GdkEventButton *`. plug is the GtkPlug object which is the applets window.

#### rox_soap_server.h

Provides a ROX-Filer like SOAP server. Based on the ROX-Filer code written by Thomas Leonard

`typedef struct rox_soap_server ROXSOAPServer;`

  This is an opaque object representing the server.

`typedef xmlNodePtr (*rox_soap_server_action)(ROXSOAPServer *server, const char *action_name, GList *args, gpointer udata);`

  This represents the type of the function called when a SOAP method is executed. Any reply should be returned as an XML node. args is a list of the arguments passed as XML nodes, in the order they were defined in `rox_soap_server_add_action()` (required, then optional). Optional arguments may be `NULL`.

`typedef struct rox_soap_server_actions ROXSOAPServerActions;`

  This type is used for an array of SOAP server actions to be passed to `rox_soap_server_add_actions()`. It is defined as:

  `

      typedef struct rox_soap_server_actions {
        const char *action_name;
        const char *args;
        const char *optional_args;
        rox_soap_server_action action;
        gpointer udata;
      } ROXSOAPServerActions;

  `
`void rox_soap_server_init(void);`

  Initialise the server routines.

`ROXSOAPServer *rox_soap_server_new( const char *program_name, const char *ns_url);`

  Create a new server object and advertise it via the root window. program_name is the name of the program (see `rox_soap_define_program()`). ns_url is the name space URL.

`void rox_soap_server_add_action( ROXSOAPServer *server, const char *action_name, const char *args, const char *optional_args, rox_soap_server_action action, gpointer udata);`

  Define a new method (or action) supported by this server. action_name is the name of the action. args is a string of a comma seperated list of arguments, or `NULL` if there are no required arguments. optional_args is a string of a comma seperated list of arguments, or `NULL` if there are no optional arguments. action is the function to call when a correctly formatted SOAP message is received.

`void rox_soap_server_add_action( ROXSOAPServer *server, ROXSOAPServerActions *actiona);`

  Define a group of new methods (or actions) supported by this server. actions is the array of action definitions, terminated by an entry with a `NULL` action_name.

`void rox_soap_server_delete( ROXSOAPServer *server);`

  Shutdown the server and release its memory.

#### options.h

Options system for configuring your program, similar to ROX-Filer's options. Based on the ROX-Filer code written by Thomas Leonard

`typedef struct _Option Option;`

  Object used to store an option. The following members are used to access the values:

  `gchar *value`

    Value of the option, as a string

  `long int_value`

    Value of the option, as a number

  `gboolean has_changed`

    Non-zero if the option has changed (valid in the OptionNotify callback).

  `gchar *backup;`

    Copy of value to Revert to

  The other members are used when implementing new widget types.

  `GtkWidget *widget;`

    Widget that stores the value

  `void (*update_widget)(Option *option);`

    Call to set value

  `gchar *(*read_widget)(Option *option);`

    Call to read value

`typedef void OptionNotify(void);`

  Type of function called when options changed (see option_add_notify() below).

`typedef GList * (*OptionBuildFn)(Option *option, xmlNode *node, gchar *label);`

  Type of function used to build widgets (see option_register_widget() below) for the options window. option is the option for which the widget is used. node is the XML node from the Options.xml file describing the widget. label is the label property from the element, to be used as a label. Returns a list of widgets to be added to the window.

`void options_init_with_domain(const char *project, const char *domain);`

  Called to initialize options system. Must be called after choices_init(), but before any other function in the options system. project is the name of the project and is passed to choices functions. domain is also passed to the choices functions and may be `NULL`.

`void options_init(const char *project);`

  Equivalent to `options_init_with_domain(project, NULL)`.

`void option_register_widget(char *name, OptionBuildFn builder);`

  Registers a new widget type. name is the name of the XML element in the Options.xml file. builder is the function used to build the widget. Pre-defined widget types include:

  - label
  - spacer
  - frame
  - toggle
  - slider
  - entry
  - numentry
  - radio-group
  - colour
  - menu
  - font
`void option_check_widget(Option *option);`

  This is called when the widget's value is modified by the user. Reads the new value of the widget into the option and calls the notify callbacks.

`void option_add_int(Option *option, const gchar *key, int value);`

  Adds a new option to hold integer values.

`void option_add_string(Option *option, const gchar *key, const gchar *value);`

  Adds a new option to hold string values, including fonts and colours.

`void options_notify(void);`

  Inform watching functions that options have changed.

`void option_add_notify(OptionNotify *callback);`

  Add a callback to be called when options have changed.

`GtkWidget *options_show(void);`

  Show options window. Returns the window widget (you don't normally need this), NULL if already open. This causes the $APP_DIR/Options.xml file to be parsed. This is an XML file containing an 'options' element. This in turn contains 1 or more 'section' element, each with a 'title' property and containing one or more widgets to be built. The 'section' elements can be nested.

  Widgets available by default (see option_register_widget() for more) are:

  `label help=int`

    A label

  `hbox [label=str]`
  `vbox [label=str]`
  `spacer`
  `frame label=str`

    Container for other objects

  `section title=str`

    Groups options, can be nested.

  `toggle name=str label=str`

    Simple on/off switch

  `slider name=str label=str min=int max=int fixed=bool showvalue=bool [end=str]`

    Range of ints. fixed is fixed width. If showvalue then current value shown. end is label after slider widget

  `entry name=str label=str`

    Text entry

  `numentry name=str label=str min=int max=int step=int width=int [unit=str]`

    Numeric entry. width is number of digits. unit is text to right of widget (units indicator).

  `radio-group name=str label=str [columns=int]`

    List of exclusive options. Must contain radio elements

  `radio label=str value=str`

    Option for a radio group

  `colour name=str label=str`

    Button for colour selector

  `menu name=str label=str`

    Option menu. Must contain 'item' elements.

  `item label=str value=str`

    Option for an option menu

  `font name=str label=str override=int`

    Button for font selector. If override, adds a checkbox to enable the font.

  The new window is registered using `rox_add_window()`

#### basedir.h

Interface to the XDG Base directory system.

`gchar *basedir_save_config_path(const char *resource, const char *leaf)`

  Returns the pathname of a configuration file to save. This will be in the directory `$XDG_CONFIG_HOME` (defaulting to `$HOME/.config`). Eg: `basedir_save_config_path("MyApp", "options.dat")` -> `"/home/myuser/.config/MyApp/options.dat"`.

  The directory `$XDG_CONFIG_HOME` and the sub-directory resource are created by this call if required.

  The parameter leaf may be `NULL`. If so just the directory part is returned.

  `basedir_save_config_path("MyApp", NULL)` -> `"/home/myuser/.config/MyApp"`.

  The return value may be NULL - saving is disabled - otherwise `g_free()` the result.

`gchar *basedir_save_data_path(const char *resource, const char *leaf)`

  Returns the pathname of a data file to save. This will be in the directory `$XDG_DATA_HOME` (defaulting to `$HOME/.local/share`). Eg: `basedir_save_data_path("MyApp", "data.dat")` -> `"/home/myuser/.local/share/MyApp/data.dat"`.

  The directory `$XDG_DATA_HOME` and the sub-directory resource are created by this call if required.

  The parameter leaf may be `NULL`. If so just the directory part is returned.

  `basedir_save_data_path("MyApp", NULL)` -> `"/home/myuser/.local/share/MyApp"`.

  The return value may be NULL - saving is disabled - otherwise `g_free()` the result.

`gchar *basedir_load_config_path(const char *resource, const char *leaf)`

  Returns the pathname of a configuration file to load. This will be in the directory `$XDG_CONFIG_HOME` (defaulting to `$HOME/.config`) or a directory named in `$XDG_CONFIG_DIRS` (defaulting to `/etc/xdg`). Eg: `basedir_load_config_path("MyApp", "options.dat")` -> `"/home/myuser/.config/MyApp/options.dat"`.

  The return value may be NULL - meaning the file was not found - otherwise `g_free()` the result.

`gchar *basedir_load_data_path(const char *resource, const char *leaf)`

  Returns the pathname of a data file to load. This will be in the directory `$XDG_DATA_HOME` (defaulting to `$HOME/.local/share`) or a directory named in `$XDG_DATA_DIRS` (defaulting to `/usr/local/share:/usr/share`). Eg: `basedir_load_data_path("MyApp", "data.dat")` -> `"/usr/local/share/MyApp/data.dat"`.

  The return value may be NULL - meaning the file was not found - otherwise `g_free()` the result.

`GList *basedir_load_config_paths(const char *resource, const char *leaf)`

  Returns a list of all the pathnames of existing configuration files to load. This includes the directories `$XDG_CONFIG_HOME` (defaulting to `$HOME/.config`) and `$XDG_CONFIG_DIRS` (defaulting to `/etc/xdg`).

  If leaf is `NULL` then just the existing configuration directories for resource are returned. If resource is `NULL` then the existing configuration directories are returned.

  The return value may be NULL if no config directories or config files could be found. Otherwise `g_free()` each list item and `g_list_free()` the whole list.

`GList *basedir_load_data_paths(const char *resource, const char *leaf)`

  Returns a list of all the pathnames of existing data files to load. This includes the directories `$XDG_DATA_HOME` (defaulting to `$HOME/.local/share`) and `$XDG_DATA_DIRS` (defaulting to `/usr/local/share:/usr/share`).

  If leaf is `NULL` then just the existing data directories for resource are returned. If resource is `NULL` then the existing data directories are returned.

  The return value may be NULL if no data directories or data files could be found. Otherwise `g_free()` each list item and `g_list_free()` the whole list.

#### mime.h

Interface to the Shared MIME database system.

`typedef struct mime_type MIMEType;`

  This type represents a MIME type. It has a number of members, two of which are public but read-only:

  - `const char *media;`
  - `const char *subtype;`

  These are the two parts of the MIME type media/subtype (e.g. `text/plain`).

`extern MIMEType *text_plain;`

  MIME type representing `text/plain` files. This is the default for a file under *nix.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *application_executable;`

  MIME type representing `application/x-executable` files. This represents an executable file.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *application_octet_stream;`

  MIME type representing `application/octet-stream` files. This represents a non-text binary file.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_directory;`

  MIME type representing `inode/directory` files. This represents a directory.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_mountpoint;`

  MIME type representing `inode/mountpoint` files. This represents a directory on which a file system is mounted, or may be mounted according to /etc/fstab. ROX-CLib does not yet recognize such objects.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_pipe;`

  MIME type representing `inode/fifo` files. This represents a pipe or FIFO object.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_socket;`

  MIME type representing `inode/socket` files. This represents a socket object.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_block;`

  MIME type representing `inode/blockdevice` files. This represents a block device object.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_char;`

  MIME type representing `inode/char` files. This represents a character device object.

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_door;`

  MIME type representing `inode/door` files. This represents a door object (Solaris only).

  This is not valid until `mime_init()` has been called.

`extern MIMEType *inode_unknwon;`

  MIME type representing `inode/unknown` files. This represents an object which could not be identified (probably missing).

  This is not valid until `mime_init()` has been called.

`extern void mime_init(void)`

  Initializes the MIME system, defines the default types, and loads the lookup database.

`extern MIMEType *mime_lookup(const char *path)`

  Returns the MIME type of the given file. If the file exists then it is first checked for being a non-regular file. If it is regular and by content lookups are enabled the contents of the file is checked. If none of the above identifies the file then the file is identified by its name.

  In future a check may be made using extended attributes for a user-defined MIME type. This check will be made on regular files before contents are checked.

  The object returned is maintained by the MIME system and should not be freed or modified.

`extern MIMEType *mime_lookup_by_name(const char *name)`

  Returns the MIME type object for the named type. name should be in the form `media/subtype`.

  The object returned is maintained by the MIME system and should not be freed or modified.

`extern char *mime_type_name(const MIMEType *type)`

  Returns the name of the MIME type in the form `text/plain`. The returned string must be passed to `g_free()` when done.

`extern const char *mime_type_comment(MIMEType *type)`

  Returns the comment field of the MIME type. This is the human readable name of the type, such as `C headers` for `text/x-chdr`. Unlike `mime_type_lookup()` this call reads one or more files, including `/uri/0install/zero-install.sourceforge.net/share` and may take some time to complete.

  The string returned is maintained by the MIME system and should not be freed or modified.

`extern void mime_set_ignore_exec_bit(int ignore)`

  If ignore is non-zero then `mime_type_lookup()` will check the name of executable files for determining type and only return `application/x-executable` if that fails. Otherwise `application/x-executable` is always returned for files with an executable bit set.

`extern int mime_get_ignore_exec_bit(void)`

  Returns the ignore executable bit flag.

`extern void mime_set_by_content(int content)`

  If content is zero then `mime_type_lookup()` will not check the contents of the file to determine the type. This is the default.

  Currently ignored as by-content lookups are not enabled.

`extern int mime_get_by_content(void)`

  Returns the by content flag.

#### appinfo.h

An object representing a parsed AppInfo.xml file.

`typedef struct _ROXAppInfo ROXAppInfo;`

  This type represents an AppInfo.xml. It is derived from GObject.

`GObject *rox_appinfo_new(void)`

  This parses the current app's AppInfo.xml file and returns a pointer to a `ROXAppInfo` object. If $APP_DIR is unset, $APP_DIR/AppInfo.xml is missing or not valid XML then `NULL` is returned.

  You should call `g_object_unref()` to free this object when done.

`GObject *rox_appinfo_new_from_path(const gchar *path)`

  This parses the named AppInfo.xml file and returns a pointer to a `ROXAppInfo` object. If path is missing or not valid XML then `NULL` is returned.

  You should call `g_object_unref()` to free this object when done.

`void rox_appinfo_set_language(ROXAppInfo *ai, const gchar *lang)`

  Set the language used when parsing the AppInfo data. If lang is `NULL` then the data returned will be that with no language set, otherwise the appropriate elements for the set language will be returned, falling back to the no language elements if the specific language is not found.

`const char *rox_appinfo_get_language(ROXAppInfo *ai)`

  Return the language code used when parsing the AppInfo data. This may be `NULL` for no language set.

`const char *rox_appinfo_get_summary(ROXAppInfo *ai)`

  Return the contents of the Summary element.

`char *rox_appinfo_get_about(ROXAppInfo *ai, const gchar *element)`

  Return the contents of the named element in the About element. Pass the return value to `g_free()` when done.

`char *rox_appinfo_get_label(ROXAppInfo *ai, const gchar *element)`

  Return the label for the named element in the About element in the current language. If this is not set or is empty then a copy of element is returned. Pass the return value to `g_free()` when done.

`const xmlNodePtr rox_appinfo_get_element(ROXAppInfo *ai, const gchar *element)`

  Return the `xmlNode` object for the named element. Only child elements of the root AppInfo element are searched, no recursive search is performed. `NULL` is returned if no element was found, otherwise just the first matching entry is returned. Language is not checked.

  `xmlNodePtr` is part of libxml.

`GList *rox_appinfo_get_mime_type_list(ROXAppInfo *ai, const gchar *element)`

  Returns a list of `MIMEType *` objects. The mime types are listed in <MimeType> elements in the top level element element (found by `rox_appinfo_get_element()`). See the AppInfo.xml file for VideoThumbnail for an example.

`void rox_appinfo_free_mime_type_list( GList *list)`

  Free a list of `MIMEType *` objects, as returned by `rox_appinfo_get_mime_type_list()`.

`GList *rox_appinfo_get_can_run_list(ROXAppInfo *ai)`

  Returns a list of `MIMEType *` objects declared in the <CanRun> element. This is equivalent to `rox_appinfo_get_mime_type_list(ai, "CanRun").`

`GList *rox_appinfo_get_can_thumbnail_list(ROXAppInfo *ai)`

  Returns a list of `MIMEType *` objects declared in the <CanThumbnail> element. This is equivalent to `rox_appinfo_get_mime_type_list(ai, "CanThumbnail"). See the AppInfo.xml file for VideoThumbnail for an example.`

#### mime_handler.h

Install handlers for MIME types.

`void rox_mime_install_from_appinfo(void)`

  This offers the user a chance to install the current application as the handler for those types given in the application's AppInfo.xml file. Types given in the <CanRun> element are offered as run actions and SendTo, those in the <CanThumbnail> element are offered as the thumbnail handler.

#### uri.h

Utilities for uri handling and launching.

`gchar *rox_unescape_uri(const gchar *uri)`

  Converts all %xx escape sequences in uri back into characters.

`gchar *rox_escape_uri_path(const gchar *path)`

  Converts all problematic characters in path into %xx escape sequences.

`gchar *rox_encode_path_as_uri(const gchar *uri)`

  Converts all problematic characters in path into %xx escape sequences and adds a `file://hostname` prefix. hostname is as returned from `rox_hostname`

`int rox_uri_launch(const char *uri)`

  Attempt to launch uri by passing to the handler for the mime type text/x-uri. If no handler is defined attempt to open it in mozilla or netscape. The return value is the exit status of the command used to launch.

`const char *rox_hostname(const gchar *uri)`

  Returns the hostname which will be used in drag and drop operations.

Last modified: Sat Oct 23 15:04:48 BST 2004