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

Next: Getting the Size, Previous: Mouse Handling, Up: Part IV Drawing Objects [Contents][Index]

### 28.4 Clipping

To avoid drawing outside a box the following routine exists:

    void fl_set_clipping(FL_Coord x, FL_Coord y, FL_Coord w, FL_Coord h);

It sets a clipping region in the Forms Library’s default `GC` used for drawing (but not for output of text, see below). `x`, `y`, `w` and `h` define the area drawing is to restrict to and are relative to the window/form that will be drawn to. In this way you can prevent drawing over other objects.

Under some circumstances XForms also does it’s own clipping, i.e., while drawing due to a exposure event. This is called "global clipping". Thus the clipping area you have set via a call of `fl_set_clipping()` may get restricted even further due this global clipping.

You can check if there’s clipping set for the default `GC` using the function

    int fl_is_clipped(int include_global);

which returns `1` if clipping is switched on and `0` otherwise. The `include_global` argument tells the function if global clipping is to be included in the answer or not (i.e., if the argument is `0` only clipping set via `fl_set_clipping()` is reported).

The area currently clipped to is returned by the function

    int fl_get_clipping(int include_global, FL_Coord *x,FL_Coord *y,
                            FL_Coord *width, FL_Coord *height);

On return the four pointer arguments are set to the position and size of the clipping rectangle (at least if clipping is switched on) and the qreturn value of this function is the same as that of `fl_is_clipped()`. The `include_global` argument has the same meaning as for `fl_is_clipped()`, i.e., it controls if the effects of global clipping is included in the results.

When finished with drawing always use

    void fl_unset_clipping(void);

to switch clipping of again.

You also can check and obtain the current settings for global clipping using the functions

    int fl_is_global_clipped(void);
    int fl_get_global_clipping(FL_Coord *x,FL_Coord *y,
                               FL_Coord *width, FL_Coord *height);

Clipping for text is controlled via a different `GC` and thus needs to be set, tested for and unset using a different set of functions:

    void fl_set_text_clipping(FL_Coord x,FL_Coord y,FL_Coord w,FL_Coord h);
    int fl_is_text_clipped(int include_global);
    int fl_get_text_clipping(int include_global, FL_Coord *x,FL_Coord *y,
                             FL_Coord *width, FL_Coord *height);
    void fl_unset_text_clipping(void);

Finally, there are functions to set and unset the clipping for a specific `GC`:

    void fl_set_gc_clipping(GC gc, FL_Coord x, FL_Coord y,
                            FL_Coord width, FL_Coord height);
    void fl_unset_gc_clipping(GC gc);

Please note that setting clipping for a `GC` will always further restrict the region to the region of global clipping (if it is on at the moment the function is called) and unsetting clipping will still retain global clipping if this is on at the moment the second function is invoked (if it is currently on can be checked using the `fl_is_global_clipped()`).

Next: Getting the Size, Previous: Mouse Handling, Up: Part IV Drawing Objects [Contents][Index]