A library for ROX applications written in C.
Copy to a suitable place, such as ~/lib, and make sure it is on your $LIBDIRPATH.
Compile using ROX-CLib/AppRun --compile
Add the output of
rox_run ROX-CLib --cflagsto 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 --libsto 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-CLiband to CFLAGS add: `${ROX_CLIB} --cflags` and to LDFLAGS add: `${ROX_CLIB} --libs`
In AppRun and AppletRun 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/rox_run ROX-CLib --runtime`
else
LD_LIBRARY_PATH=`$APP_DIR/rox_run ROX-CLib --runtime`:$LD_LIBRARY_PATH
fi
export LD_LIBRARY_PATH
Finally put rox_run in your application directory.
Organized by header file.
Top level include. It includes:
Six functions are declared:
void rox_init(const char *program, 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(program) (if it detects an
$APP_DIR/Options.xml file)
rox_dnd_init()
Returns the program name, as passed to rox_init(). If
rox_init() was not
called then it returns NULL.
-
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)".
-
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.
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.
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.
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.
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.
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) |
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.
RISC OS style information window.
InfoWin is a GTK+ widget, derived from GtkDialog.
GtkWidget* info_win_new(const gchar *program,
const gchar *purpose,
const gchar *version, const gchar *author,
const gchar *website)
Create a new InfoWin object. The data in the window is taken from the function arguments.
GtkWidget* info_win_new_from_appinfo(const gchar *program)
Create a new InfoWin object. The data in the window is taken from the file $APP_DIR/AppInfo.xml, if it exists.
void info_win_add_browser_command(InfoWin *iw,
const gchar *cmd)
Adds a command which will visit a named web site.
The command will be called with a single argument, then
URL passed in info_new_win().
None.
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
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().
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.
gchar *unescape_uri(const gchar *uri)
Converts all %xx escape sequences in uri back into characters.
gchar *escape_uri_path(const gchar *path)
Converts all problematic characters in path into %xx escape sequences.
gchar *encode_path_as_uri(const gchar *uri)
Converts all problematic characters in path
into %xx escape sequences and adds a
file://hostname prefix.
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:
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.
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.
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.
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.
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.
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(const char *project);
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.
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:
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.