Registering a Piece of Data

To register data several things need to be known; the contig number, the callback function, the client_data (typically the address of the data to register), the list of notifications to respond to, an indentifier, and the "type" of this data (one of the REG_TYPE_ macros).

If the data needs updating when more than one specific contig changes, then the data should be registered with more than one contig.

Use the contig_register function to register an item. The prototype is:

#include <io-reg.h>

int contig_register(
        GapIO  *io,
        int     contig,
        void  (*func)(
                      GapIO     *io,
                      int        contig,
                      void      *fdata,
                      reg_data  *jdata),
        void   *fdata,
        int     id,
        int     flags,
        int     type);

contig is a contig number in the C sense (1 to NumContigs(io)), not a gel reading number.

The fdata (the client_data mentioned before) can be anything you wish. It will be passed back to the callback function func when a notification is made. Typically it's best to simply pass the address of your data that you wish to keep up to date. If your data is not a single pointer then turn it into one by creating a structure containing all the relevant pointers.

The id number is usually unique for each time an option it ran, but common to all registrations of this particular piece of data. This is not a hard and fast rule -- it depends on how you wish to interact with this data. For instance, the contig selector window registers with all contigs so that it can be notified when any contig changes. The same id is used for each of these registrations as it is the collection of registrations as a whole which is required for the display.

"Flags" is used to request which notifications should be sent to this callback function. Each notification has a name which is actually a #define for a number. This names can be ORed together to generate a bit field of acknowledged requests. There are some predefined bitfields (for shortening the function call) that can themselves be ORed together. See section The Notifications Available. Finally, one special flag can be ORed on to request that this function does not appear in the results manager window. This flag is REG_FLAG_INVIS: see the contig selector code for an example.

An example of using contig_register can be seen in the stop codon plot. Our stop codon results are all held within a structure of type mobj_stop. The general outline of our stop codon code is as follows:

mobj_stop *s;
int id;

if (NULL == (s = (mobj_stop *)xmalloc(sizeof(mobj_stop)))) {
    return 0;
}

[ Fill in our 's' structure with our results ]

DrawStopCodons(s);
id = register_id();
contig_register(io, contig_number, stop_codon_callback, (void *)s, id,
                REG_REQUIRED | REG_DATA_CHANGE | REG_OPS | REG_GENERIC
                | REG_NUMBER_CHANGE | REG_REGISTERS | REG_CURSOR_NOTIFY,
                REG_TYPE_STOPCODON);

Here we've requested that the result s, of type REG_TYPE_STOPCODON, should be passed to the stop_codon_callback function whenever a notification of type REG_REQUIRED, REG_DATA_CHANGE, REG_OPS, REG_GENERIC, REG_NUMBER_CHANGE, REG_REGISTERS or REG_CURSOR_NOTIFY occurs. These notification types are actually combinations of types, but more on this later.