Other Positioner Routines (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Positioner Attributes, Previous: Positioner Interaction, Up: Positioner Object [Contents][Index]

#### 17.4.4 Other Positioner Routines

Usually, a positioner of type `FL_OVERLAY_POSITIONER` is used on top if another object, e.g., a pixmap object. If the object below the positioner is changed, e.g., by setting a new pixmap for the pixmap object, tis may lead to visual artefacts since the postioner isn’t aware of the changes of the underlying object. To avoid this call the function

    void fl_reset_positioner(FL_OBJECT *obj);

before each change to an object below it.

Per defauly the range that the `x` and `y` values of a positioner can assume are controlled via minimum and maximum values for both directions. These boundary values can be set by using the functions the routines:

    void fl_set_positioner_xbounds(FL_OBJECT *obj, double min, double max);
    int fl_set_positioner_ybounds(FL_OBJECT *obj, double min, double max);

When a new positioner object is created the minimum values are 0.0 and the maximum values are 1.0. For boundaries in x-direction `min` and `max` should be taken to mean the left- and right-most position, respectively, and for the y-boundaries `min` and `max` should be taken to mean the value at the bottom and value at the top of the positioner, respectively.

Note that the posituoners value may be changed automatically when setting new boundaries to make them satisfy the new conditions.

For more complicated situations, i.e., when only a subset of the positioners value range may be used, a validation function can be installed (see the `positioner_overlay` demo program for an example):

    typedef int (*FL_POSITIONER_VALIDATOR (FL_OBJECT * obj,
    									   double x, double y,
    									   double *x_repl, double *y_repl);

    FL_POSITIONER_VALIDATOR
    fl_set_positioner_validator(FL_OBJECT               * obj,
    							FL_POSITIONER_VALIDATOR   validator);

If a non-`NULL` pointer is passed to the function each time a new position is set the validation function is invoked. It can return either `FL_POSITIONER_INVALID` to indicate that the new valuea aren’t acceptable, in which case the position remains unchanged. It may also return `FL_POSITIONER_VALID` if the values are acceptable. Finally, the function may also return modified values via the `x_repl` and `y_repl` pointers and return `FL_POSITIONER_REPLACED`. In this case the values returned are used. It’s the responsibility of the validation function to make sure that the `x` and `y` values satisfy the boundary restrictions etc. If it doesn’t the results are unpredictable.

To switch off validation pass the function a `NULL` pointer. The function returns a pointer to the previously active validation function (or `NULL` if non had been set). Note that if a new validation function is set it is immediately called to check that the current position is still compatible with the new requirements. If the validation function returns `FL_POSITIONER_INVALID` in this case the position can’t be corrected to fit the new conditions. Thus if you write your validation function in a way that it may return this value it is advisable to set compilant values for the positions before installing the validation function.

To programatically change the `x` and `y` position use

    int fl_set_positioner_values(FL_OBJECT *obj, double xval, double yval);
    int fl_set_positioner_xvalue(FL_OBJECT *obj, double val);
    int fl_set_positioner_yvalue(FL_OBJECT *obj, double val);

These functions return either `FL_POSITIONER_VALID` if the new position was acceptable or `FL_POSITIONER_REPLACED` if the value passed to the function had to be modified due to constraints imposed by the boundaries the step sizes or a validation routine. If a validation routine is set the functions also may return `FL_POSITIONER_INVALID` if that routine returned this value.

To obtain the current values of the positioner and the bounds use

    double fl_get_positioner_xvalue(FL_OBJECT *obj);
    double fl_get_positioner_yvalue(FL_OBJECT *obj);
    void fl_get_positioner_xbounds(FL_OBJECT *obj, double *min, double *max);
    void fl_get_positioner_ybounds(FL_OBJECT *obj, double *min, double *max);

In a number of situations you might like positioner values to be rounded to some values, e.g., to integer values. To this end use the routines

    void fl_set_positioner_xstep(FL_OBJECT *obj, double step);
    void fl_set_positioner_ystep(FL_OBJECT *obj, double step);

After these calls positioner values will be rounded to multiples of `step`. Use a value of 0 for `step` to switch off rounding.

The functions

    void fl_get_positioner_xstep(FL_OBJECT *obj);
    void fl_get_positioner_ystep(FL_OBJECT *obj);

return the current settings for the `x` and `y` step size.

Sometimes, it makes more sense for a positioner to have an icon/pixmap as the background that represents a minified version of the area where the positioner’s values apply. Type `FL_OVERLAY_POSITIONER` is specifically designed for this by drawing the moving cross-hair in XOR mode as not to erase the background. A typical creation procedure might look something like the following

    obj = fl_add_pixmap(FL_NORMAL_PIXMAP, x, y, w, h, label);
    fl_set_pixmap_file(obj, iconfile);
    pos = fl_add_positioner(FL_OVERLAY_POSITIONER, x, y, w, h, label);

Of course, you can overlay this type of positioner on objects other than a pixmap. See the demo program `positionerXOR.c` for an example.

Next: Positioner Attributes, Previous: Positioner Interaction, Up: Positioner Object [Contents][Index]