A library for ROX applications written in C.
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
Compile the library first
Copy the libdir script from ROX-CLib/$PLATFORM/bin/libdir into your app dir.
Add the output of
ROX-CLib --cflagsto 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 --libsto 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:
ROX_CLIB(2, 0, 0)
ROX_CLIB = @ROX_CLIB_PATH@/AppRunand to CFLAGS add: `${ROX_CLIB} --cflags` and to LDFLAGS add: `${ROX_CLIB} --libs`
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
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"
Organized by header file. Last updated for version 2.1.4. Use as e.g.
#include <rox/rox.h> #include <rox/rox_soap.h>
Top level include. It includes:
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.
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
.
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.
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.
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.
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.
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.
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
.
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 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:
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()
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.
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.
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.
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.
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.