ROX-CLib
========

A library for ROX applications written in C.

Installation
------------

Copy to a suitable place, such as ~/lib, and make sure it is on 
your $LIBDIRPATH.

Compile using ROX-CLib/AppRun --compile

Compiling and linking against the library
-----------------------------------------

Add the output of
   rox_run ROX-CLib --cflags
to your compile line, e.g.
   gcc `rox_run ROX-CLib --cflags` -c main.c 

Add the output of
   rox_run ROX-CLib --cflags
   rox_run ROX-CLib --libs
to your link line, e.g.
   gcc `rox_run ROX-CLib --cflags` -o main main.o `rox_run ROX-CLib --libs`

If you are using autoconf and building a ROX program then:
In src/configure.in add:
  if test -z "$ROX_RUN"; then
    AC_CHECK_PROG(ROX_RUN, rox_run, rox_run, "$APP_DIR/rox_run")
  fi
  AC_SUBST(ROX_RUN)

In src/Makefile.in add:
  ROX_CLIB = @ROX_RUN@ ROX-CLib
and to CFLAGS add: `${ROX_CLIB} --cflags`
and to LDFLAGS add: `${ROX_CLIB} --libs`

In AppRun and AppletRun ensure you have:
  APP_DIR=`cd $APP_DIR;pwd`; export APP_DIR

Finally put rox_run in the ROX app dir.

Brief listing of functions
--------------------------

Organized by header file.

rox.h
-----
Top level include.  It includes:
  choices.h
  error.h
  rox_debug.h
  rox_resources.h
  infowin.h

Two functions are declared:

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)".

choices.h
---------

Interface to the choices system and $CHOICESPATH.

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.

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.

infowin.h
---------

RISC OS style information window.

InfoWin is a GTK+ widget, derived from GtkDialog.

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 delclared.

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.

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.

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 (not yet implemented!).  udata
is passed to the handler routine.

void rox_dnd_register_uris(GtkWidget *widget,
				  guint flags,
				  rox_dnd_handle_uris uris,
				  gpointer udata)

Registers a widget with rox_dnd to handle any URI list drops on it.
There are no flags defined yet, so flags must be set to zero.  uris
handles URI list drops.  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 g_slist_free() after freeing data with g_free().

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.

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.  Note that using SOAP requires
libxml2. 

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);

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 eafname 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.

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

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

extern PanelLocation applet_get_panel_location(GtkWidget *plug);

Depreciated.

extern void applet_show_menu(GtkWidget *menu, GdkEventButton *evbut);

Depreciated.

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.

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.

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_delete(ROXSOAPServer *server);

Shutdown the server and release its memory.
