Next: , Previous: , 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: , Previous: , Up: Positioner Object   [Contents][Index]