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

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

#### 21.3.4 Other Canvas Routines

Upon canvas creation, all its window related attributes, e.g., visual, depth and colormap etc., are inherited from its parent (i.e., the window of the form the canvas belongs to). To modify any attributes of the canvas, use the following routine

    void fl_set_canvas_attributes(FL_OBJECT *obj, unsigned mask,
                                  XSetWindowAttributes *xswa);

See `XSetWindowAttributes()` for the definition of the structure members. Note that this routine should not be used to manipulate events.

Other functions exists that can be used to modify the color/visual property of a canvas:

    void fl_set_canvas_colormap(FL_OBJECT *obj, Colormap map);
    Colormap fl_get_canvas_colormap(FL_OBJECT *obj);
    void fl_set_canvas_visual(FL_OBJECT *obj, Visual *vi);
    void fl_set_canvas_depth(FL_OBJECT *obj, int depth);
    int fl_get_canvas_depth(FL_OBJECT *obj);

Note that changing visual or depth does not generally make sense once the canvas window is created (which happens when the parent form is shown). Also, typically if you change the canvas visual, you probably should also change the canvas depth to match the visual.

Caution should also applied when using `fl_set_canvas_colormap()`: when the canvas window goes away, e.g., as a result of a call of `fl_hide_form()`, the colormap associated with the canvas is freed (destroyed). This likely will cause problems if a single colormap is used for multiple canvases as each canvas will attempt to free the same colormap, resulting in an X error. If your application works this way, i.e., the same colormap is used on multiple canvases (via `fl_set_canvas_colormap()`), you should use the following routine to prevent the canvas from freeing the colormap:

    void fl_share_canvas_colormap(FL_OBJECT *obj, Colormap colormap);

This function works the same way as `fl_set_canvas_colormap()` except that it also sets a internal flag so the colormap isn’t freed when the canvas goes away.

By default, canvases are decorated with an `FL_DOWN_FRAME`. To change the decoration, change the the boxtype of the canvas and the boxtype will be translated into a frame that best approximates the appearance of the request boxtype (e.g., a `FL_DOWN_BOX` is translated into a `FL_DOWN_FRAME` etc). Note that not all frame types are appropriate for decorations.

The following routine is provided to facilitate the creation of a colormap appropriate for a given visual to be used with a canvas:

    Colormap fl_create_colormap(XVisualInfo *xvinfo, int n_colors);

where `n_colors` indicates how many colors in the newly created colormap should be filled with XForms’ default colors (to avoid flashing effects). Note however, that the colormap entry 0 is allocated with either black or white even if you specify 0 for `n_colors`. To prevent this from happening (so you get a completely empty colormap), set `n_colors` to -1. See Drawing Objects, on how to obtain the `XVisualInfo` for the window. Depending on the window manager, a colormap other than the default may not get installed correctly. If you’re working with such a window manager, you may have to install the colormap yourself when the mouse pointer enters the canvas using `XInstallColormap()`.

By default, objects with shortcuts appearing on the same form as the canvas will "steal" keyboard inputs if they match the shortcuts. To disable this feature, use the following routine with a false (0) value for `yes_no`:

    void fl_canvas_yield_to_shortcut(FL_OBJECT *obj, int yes_no);

To clear the canvas use

    void fl_clear_canvas(FL_OBJECT *obj);

If `fl_set_object_color()` gas been called on the object the first color passed to the function will be used to draw the background of the color, otherwise it’s drawn in black.

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