Configuration Files

The gnome-config routines provide an easy way to store configuration info in files. To see a full list of the routines, look in the libgnome/gnome-config.h header file.

Do note however that these routines are marked deprecated for GNOME 2.0. The reason is that there is now a much better library for storing configuration data called GConf. GConf will also be a part of the GNOME 1.4 release so you can start using it for stable applications at that time.

The routines all working with a path. The path is a Unix like path, but the root is set to the ~/.gnome/ directory. So /some/config/path/file/sectionA/keyB, refers to the file ~/.gnome/some/config/path/file, and inside the file using section sectionA and key keyB.

int counter;
char *text;
gboolean def;
...
counter = gnome_config_get_int_with_default("/example/section/counter=1",
                                            &def);
if(def) g_print("Default used for counter!\n");
text = gnome_config_get_string("/example/section/text=TEXT");
...
g_free(text);

char *text;
int counter;
...
/*after we have set text and counter to some values we can
  write them to our config location*/
gnome_config_set_int("/example/section/counter", counter);
gnome_config_set_string("/example/section/text", text);
gnome_config_sync();

char buf[256];
...
/*write some bogus data to a temporary file*/
g_snprintf(buf,256,"=%s=/section/key",tmpnam(tmpnam));
gnome_config_set_int(buf,999);
gnome_config_sync();

gnome_config_push_prefix("/file/section/");
gnome_config_set_int("key1",1);
gnome_config_set_int("key2",2);
gnome_config_set_int("key3",-88);
gnome_config_pop_prefix();

.desktop Files

The .desktop files are the files that contain information about programs. The files are in the gnome-config format and are internally read using gnome-config. Your app definitely needs one of these files installed in the system menu paths if it wants to be added to the menu.

You can use gnome_desktop_entry_* functions to manipulate these files. These functions work with a structure called GnomeDesktopEntry and you should look at the libgnome/gnome-dentry.h header file for the format of this structure.

The basic functions that you use to manipulate these files are gnome_desktop_entry_load which returns a newly allocated GnomeDesktopEntry structure, gnome_desktop_entry_launch which takes the GnomeDesktopEntry structure as an argument and launches the program it describes and gnome_desktop_entry_free which frees the allocated memory with the structure.

An example .desktop file for your app might look like:

[Desktop Entry]
Name=Clock
Name[cz]=Hodiny
Comment=Digital Clock
Comment[cz]=Digitalni Hodiny
Exec=digital-clock
Icon=clock.png
Terminal=0
Type=Application

You will notice that there are translations for Name and Comment fields in Czech. For gnome programs to notice your .desktop file, it is usually located somewhere under <prefix>/share/apps/, which contains the hierarchy of the system menus. For the system to find your icon, your icon should be placed inside the <prefix>/share/pixmaps directory. Note that the prefix refers to the location where GNOME was installed. 

Utility and Files

char *name;
...
name = gnome_pixmap_file("gnome-help.png");
if(!name) {
        g_warning("gnome-help.png doesn't exist!");
} else {
        /*here we use the file*/
        ...
        g_free(name);
}

Mime Types

Sometimes it's useful to know the mime-type of a file. You can do this by using the gnome_mime_type_or_default function, which takes two arguments, the filename and a default mime-type string which it will return if it can't figure out the mime type from the filename. This call doesn't actually look into the file, it tries to guess the type by looking at the filename itself. Also the string it returns is a pointer to it's internal database and you should not free it as that would likely result in a segfault later on. You can also use gnome_mime_type which will return NULL if it can't guess the mime-type.

It is also possible to work with URI lists, such as the ones used sometimes in Drag and Drop. Usually from an URI list you want to extract a list of filenames that you just received. For that you use the gnome_uri_list_extract_filenames function, which takes the URI list as a string argument, and returns a GList * of newly allocated strings. Once you are done with the files, you should free the strings and the list. You can use the utility routine gnome_uri_list_free_strings to do this for you.

In the following example I write a drag and drop handler that takes the files and finds out their mime information, then you could just write code that can do things based on the mime type of the files.

/*this is the handler for the drag_data_receive signal, assuming our
  widget only accepts the "text/uri-list" mime type of data, drag and
  drop is a more complicated topic and you should read up on GTK+
  documentation for better treatment*/
static void
dnd_drop_internal (GtkWidget        *widget,
                   GdkDragContext   *context,
                   gint              x,
                   gint              y,
                   GtkSelectionData *selection_data,
                   guint             info,
                   guint             time)
{
        GList *files, *li;

        /*here we extract the filenames from the URI-list we received*/
        files = gnome_uri_list_extract_filenames(selection_data->data);

        /*here we loop though the files and get their mime-type*/
        for(li = files; li!=NULL ; li = g_list_next(li)) {
                  char *mimetype;
                  char *filename = li->data;

                  /*guess the mime type of the file*/
                  mimetype = gnome_mime_type(filename);

                  /*if we can't guess it, just loop to the
                    next filename*/
                  if(!mimetype) continue;

                  /*here comes code that can actually do something
                    based on the mime-type of the file we received*/
                  ...
        }
        /*free the list of files we got*/
        gnome_uri_list_free_strings (files);
}

Note how easy it is to find out what files you got, and what type they are. You would just need to add some code instead of the three dots that actually compares the mime strings you got to some you have to figure out what you can do with the files. 

Meta Data

Sometimes it is useful to store some information along with a filename, this can be done easily with the gnome-metadata. It is a set of functions to manage this data. Since Unix doesn't natively support meta-data, you have to help it yourself. For example if your app copies, renames or deletes files, use the following functions.

These functions don't actually do the operations on the files, they just change the meta-data accordingly. So if your app does any of these operations, it is nicer towards other apps, that it notifies the meta-data database of the changes. You shouldn't rely on the data being stored. Only non-critical data should be stored in the meta-data, since apps that do not notify the database with these functions will make you loose your data for the file. These functions will return 0 or GNOME_METADATA_OK if there was no error, or an error-code (described above).

Now if you actually want to use the meta-data to store information about files, you will most likely use the functions gnome_metadata_set, gnome_metadata_remove and gnome_metadata_get. Again these functions return an integer, which is GNOME_METADATA_OK in case there was no error, or they use the same error codes as the previous functions.

The functions work with a a key string for which they store a piece of data. The data is represented by a size integer and a character pointer. gnome_metadata_set takes the filename as the first argument, the name or key of the data as the second argument, the size as the third and the pointer to the actual data as the forth argument. This function just sets that data for that file and key. gnome_metadata_remove will clear a particular data item on a file, so it takes a file and then the key name as the second argument. gnome_metadata_get takes the filename as the first argument and the key name as the second, then it returns data size though an integer pointer you pass though the third argument and the actual data though a pointer to a pointer you pass as the fourth argument. The data returned is newly allocated and should be freed after use. Small example follows (in real life you should also check the return of the functions for errors):

int size;
char *data;
...
/*set some bogus data on a file*/
gnome_metadata_set("/some/file/name","bogus",5,"BLAH");
...
/*retrieve the data back*/
gnome_metadata_get("/some/file/name","bogus",&size,&data);