The Routine fl_add_NEW() (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Up: Part IV Global Structure [Contents][Index]

### 25.1 The Routine `fl_add_NEW()`

`fl_add_NEW()` has to add a new object to the form and bind its handle routine to it. To make it consistent with other object classes and also more flexible, there should in fact be two routines: `fl_create_NEW()` that creates the object and `fl_add_NEW()` that actually adds it to the form. They normally look as follows:

    typedef struct {
         /* instance specific record */
    } SPEC;

    FL_OBJECT *fl_create_NEW(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label) {
        FL_OBJECT *obj;

        /* create a generic object */
        obj = fl_make_object(FL_COLBOX, type, x, y, w, h, label,
                             handle_NEW);

        /* fill in defaults */
        obj->boxtype = FL_UP_BOX;

        /* allocate instance-specific storage and fill it with defaults */
        obj->spec_size = sizeof SPEC;
        obj->spec = fl_calloc(1, obj->spec_size);
        return obj;
    }

The constant `FL_NEW` will indicate the object class. It should be an integer. The numbers 0 to `FL_USER_CLASS_START - 1` (1000) and `FL_BEGIN_GROUP` (10000) and higher are reserved for the system and should not be used. Also it is preferable to use `fl_malloc()`, `fl_calloc()`, `fl_realloc()` and `fl_free()` to allocate/free the memory for the instance specific structures. These routines have the same prototypes and work the same way as those in the standard library and may offer additional debugging capabilities in future versions of the Forms Library. Also note that these functions are actually function pointers, and if desired, the application is free to assign these pointers to its own memory allocation routines.

There’s also a version equivalent to the `strdup()` POSIX function which used `fl_malloc()`:

    char * fl_strdup(const char *s);

The object pointer returned by `fl_make_object()` will have all of its fields set to some defaults (see The Type `FL_OBJECT`). In other words, the newly created object inherits many attributes of a generic one. Any class specific defaults that are different from the generic one can be changed after `fl_make_object()`. Conversion of units, if different from the default pixel, is performed within `fl_make_object()` and a class module never needs to know what the prevailing unit is. After the object is created, it has to be added to a form:

    FL_OBJECT *fl_add_NEW(int type, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h, const char *label) {
         FL_OBJECT *obj;
         obj = fl_create_NEW(type, x, y, w, h, label);
         fl_add_object(fl_current_form, obj);
         return obj;
    }

Up: Part IV Global Structure [Contents][Index]