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

Next: Doing Interaction, Previous: Creating Forms, Up: Part V Overview of Main Functions [Contents][Index]

### 32.4 Object Attributes

A number of general routines are available for setting and querying attributes. Unless stated otherwise, all attributes altering routines affect the appearance or geometry of the object immediately if the object is visible.

Since the object class and type of an object can’t be changed anymore once an object has been created there are only functions for querying these attributes:

    int fl_get_object_objclass(FL_OBJECT *obj);
    int fl_get_object_type(FL_OBJECT *obj);

Receiving a negative value indicates that a `NULL` pointer was passed to the functions.

To set the two colors that influence the appearance of the object use

    void fl_set_object_color(FL_OBJECT *obj, FL_COLOR col1, FL_COLOR col2);

and to find out about the colors of an object use

    void fl_get_object_color(FL_OBJECT *obj,
                             FL_COLOR *col1, FL_COLOR *col2);

    void fl_set_object_boxtype(FL_OBJECT *obj, int boxtype);

Changes the shape of the box of the object. Please note that not all possible boxtypes are suitable for all types of objects, see the documentation for the different objects for limitations.

To find out the current boxtype of an object use

    int fl_get_object_boxtype(FL_OBJECT *obj);

Receiving a negative value indicates that a `NULL` pointer was passed to the function.

There are also functions to change or query the border width of an object:

    void fl_set_object_bw(FL_OBJECT *obj, int bw);
    void fl_get_object_bw(FL_OBJECT *obj, int *bw);

If the requested border width is 0, -1 is used.

To change or inquire the objects position (relative to the form it belongs to) the functions

    void fl_set_object_position(FL_OBJECT *obj, FL_Coord x, FL_Coord y);
    void fl_get_object_position(FL_OBJECT *obj, FL_Coord *x, FL_Coord *y);

exist. If the object is visible it’s redrawn at the new position.

An object can also be moved relative to its current position using the function

    void fl_move_object(FL_OBJECT *obj, FL_Coord dx, FL_Coord dy);

where `dx` and `dy` are the amounts by which the object is moved to the right and down.

To change or inquire about the size of an object use

    void fl_set_object_size(FL_OBJECT *obj, FL_Coord w, FL_Coord h);
    void fl_get_object_size(FL_OBJECT *obj, FL_Coord *w, FL_Coord *h);

When changing the size of the object the position of its upper left hand corner remains unchanged.

To set or query both the position and the size of an object the functions

    void fl_set_object_geometry(FL_OBJECT *obj, FL_Coord x, FL_Coord y,
                                FL_Coord w, FL_Coord h);
    void fl_get_object_geometry(FL_OBJECT *obj, FL_Coord *x, FL_Coord *y,
                                FL_Coord (*w, FL_Coord *h);

can be used.

Please note: always use one of the above functions to change the position and/or size of an object and don’t try to change the information stored in the object directly. There’s some double bookkeeping going on under the hood that makes sure that the objects position and size won’t change due to rounding errors when the whole form gets resized and changing the internal information kept in the objects structure would interfere with this.

There’s a second function for calculation an objects geometry:

    void fl_get_object_bbox(FL_OBJECT *obj, FL_Coord *x, FL_Coord *y,
                            FL_Coord *w, FL_Coord *h);

The difference between this functions and `fl_get_object_geometry()` is that `fl_get_object_bbox()` returns the bounding box size that has the label, which could be drawn outside of the object figured in.

Some objects in the library are composite objects that consist of other objects. For example, the scrollbar object is made of a slider and two scroll buttons. To get a handle to one of the components of the composite object, the following routine is available:

    FL_OBJECT *fl_get_object_component(FL_OBJECT *obj, int objclass,
                                       int type, int number);

where `obj` is the composite object, `objclass` and `type` are the component object’s class ID and type; and `number` is the sequence number of the desired object in case the composite has more than one object of the same class and type. You can use a constant -1 for `type` to indicate any type of class `objclass`. The function returns the object handle if the requested object is found, otherwise `NULL`. For example to obtain the object handle to the horizontal scrollbar in a browser, code similiar to the following can be used

    hscrollbar = fl_get_object_component(browser, FL_SCROLLBAR,
                                         FL_HOR_THIN_SCROLLBAR, 0)

To influence change the color, font size, font style, alignment and text of the label of an object use

    void fl_set_object_lcolor(FL_OBJECT *obj, FL_COLOR lcol);
    void fl_set_object_lsize(FL_OBJECT *obj, int lsize);
    void fl_set_object_lstyle(FL_OBJECT *obj, int lstyle);
    void fl_set_object_lalign(FL_OBJECT *obj, int align);
    void fl_set_object_label(FL_OBJECT *obj, const char *label);
    void fl_set_object_label(FL_OBJECT *obj, const char *fmt, ...);

To find out about the object labels color, font size, style, alignment and the string itself use

    FL_COLOR fl_get_object_lcolor(FL_OBJECT *obj);
    int fl_get_object_lsize(FL_OBJECT *obj);
    int fl_get_object_lstyle(FL_OBJECT *obj);
    int fl_get_object_lalign(FL_OBJECT *obj);
    const char * fl_get_object_label(FL_OBJECT *obj);

To set a tool-tip text for an object use the following routines

    void fl_set_object_helper(FL_OBJECT *obj, const char *helpmsg);
    void fl_set_object_helper_f(FL_OBJECT *obj, const char *fmt, ...);

where `helpmsg` is a text string (with possible embedded newlines in it) that will be shown when the mouse hovers over the object for nore than about 600 msec. A copy of the string is made internally. The second functions accepts instead of a simple string a format string just as it’s used for `printf()` etc., followed by as many further arguments as the format string contains format specifiers.

The boxtype, color and font for the tool-tip message displayed can be customized further using the following routines:

    void fl_set_tooltip_boxtype(int boxtype);
    void fl_set_tooltip_color(FL_COLOR textcolor, FL_COLOR background);
    void fl_set_tooltip_font(int style, int size);

where `boxtype` is the backface of the form that displays the text. The default is `FL_BORDER_BOX`. `textcolor` and `background` specify the color of the text and the color of the backface. The defaults for these are `FL_BLACK` and `FL_YELLOW`. `style` and `size` are the font style and size of the text.

There are four function for controlling how an object reacts to resizing the form it belongs to or to find out what its current settings are:

    void fl_set_object_resize(FL_OBJECT *obj, unsigned int howresize);
    void fl_get_object_resize(FL_OBJECT *obj, unsigned int *howresize);
    void fl_set_object_gravity(FL_OBJECT *obj, unsigned int NWgravity,
                               unsigned int SEgravity);
    void fl_get_object_gravity(FL_OBJECT *obj, unsigned int *NWgravity,
                               unsigned int *SEgravity);

See Doing Interaction, for more details on the resizing behaviour of objects.

If you change many attributes of a single object or many objects in a visible form the changed object is redrawn after each change. To avoid this put the changes between calls of the two functions

    void fl_freeze_form(FL_FORM *form);
    void fl_unfreeze_form(FL_FORM *form);

The form is automatically redrawn once it is "unfrozen", so a call of `fl_redraw_form()` isn’t required (and, while the form is "frozen", calling this function as well as `fl_redraw_object()` has no effects).

You may also freeze and unfreeze all forms at once by using

    void fl_freeze_all_forms(void);
    void fl_unfreeze_all_forms(void);

There are also routines that influence the way events are dispatched. These routines are provided mainly to facilitate the development of (unusual) new objects where attributes need to be changed on the fly. These routines should not be used on the built-in ones.

To enable or disable an object to receive the `FL_STEP` event, use the following routine

    void fl_set_object_automatic(FL_OBJECT *obj, int yes_no);

To determine if an object receives `FL_STEP` events use

    int fl_object_is_automatic(FL_OBJECT *obj);

To enable or disable an object to receive the `FL_DBLCLICK` event use the following routine

    void fl_set_object_dblclick(FL_OBJECT *obj, unsigned long timeout);

where `timeout` specifies the maximum time interval (in msec) between two clicks for them to be considered a double-click (using 0 disables double-click detection). To determine the current setting of the timeout use

    unsigned fl_get_object_dblclick(FL_OBJECT *obj);

To make an object or a group invisible or visible use the following two functions

    void fl_hide_object(FL_OBJECT *obj);
    void fl_show_object(FL_OBJECT *obj);

`obj` can be the pseudo-object returned by `fl_bgn_group()` and then allows to hide or show whole groups of objects.

To determine if an object is visible (given that the form it belongs to is also visible) use

    int fl_object_is_visible(FL_OBJECT *obj);

    void fl_trigger_object(FL_OBJECT *obj);

returns `obj` to the application program after calling its callback if one exists.

    void fl_set_focus_object(FL_FORM *form, FL_OBJECT *obj);

sets the input focus in form `form` to object `obj`. Note however, if this routine is used as a response to an `FL_UNFOCUS` event, i.e., as an attempt to override the focus assignment by the main loop from within an objects event handler, this routine will not work as the main loop assigns a new focus object upon return from the object event handler, which undoes the focus change inside the event handler. To override the `FL_UNFOCUS` event the following routine should be used:

    void fl_reset_focus_object(FL_OBJECT *obj);

Use the following routine to obtain the object that has the focus on a form

    FL_OBJECT *fl_get_focus_object(FL_FORM *form);

The routine

    void fl_set_object_callback(FL_OBJECT *obj,
                                void (*callback)(FL_OBJECT *, long),
                                long argument);

binds a callback routine to an object.

To invoke the callback manually (as opposed to invocation by the main loop), use the following function

    void fl_call_object_callback(FL_OBJECT *obj);

If the object `obj` does not have a callback associated with it, this call has not effect.

    void fl_set_form_callback(FL_FORM *form,
                              void (*callback)(FL_OBJECT *, void *),
                              void *data);

binds a callback routine to an entire form.

It is sometimes useful to obtain the last X event from within a callback function, e.g., to implement different functionalities depending on which button triggers the callback. For this, the following routine can be used from within a callback function.

    const XEvent *fl_last_event(void);

In other rare circumstances one might not be interested not in the X event but instead the internal XForms event resulting in the invocation of an object or form callback. This information can be obtained by calling

    int fl_current_event(void);

A callback invocation resulting from a call of `fl_call_object_callback()` will return `FL_TRIGGER`. For other possible return value see the chapter about XForms internal events. Calling this function is only useful while within an object or form callback, at all other times it returns just `FL_NOEVENT`.

Also in objects callback it might be of interest to find out if the mouse is on top of a certain letter of the (inside) label (one trivial use of this can be found in the program `demo/strange_button.c`. To find out about this use

    int fl_get_label_char_at_mouse(FL_OBJECT *obj);

The function returns the index of the character in the label of the object the mouse is on or `-1` if it’s not over the label. Note that this function has some limitations: it can only be used on labels inside of the object and the label string may not contain underline characters (and the label can’t be a symbol) - if you try to use it on labels that don’t satisfy these requirements `-1` is returned.

Sometimes, it may be desirable to obtain hardcopies of some objects in a what-you-see-is-what-you-get (WYSISYG) way, especially those that are dynamic and of vector-graphics in nature. To this end, the following routine exists:

    int fl_object_ps_dump(FL_OBJECT *obj, const char *fname);

The function will output the specified object in PostScript. If `fname` is `NULL`, a file selector will be shown to ask the user for a file name. The function returns a negative number if no output is generated due to errors. At the moment, only the `FL_XYPLOT` object is supported. Nothe that this function isn’t part of the statndard XForms library (`libforms`) but the XForms image library (`libflimage` discussed in Part VI Images.

The object must be visible at the time of the function call. The hardcopy should mostly be WYSIWYG and centered on the printed page. The orientation is determined such that a balanced margin results, i.e., if the width of the object is larger than the height, landscape mode will be used. Further, if the object is too big to fit on the printed page, a scale factor will be applied so the object fits. The box underneath the object is by default not drawn and in the default black&white mode, all curves are drawn in black. See demo program `xyplotover.c` for an example output.

It is possible to customize the output by changing the PostScript output control parameters via the function

    FLPS_CONTROL *flps_init(void);

A typical use is to call this routine to obtain a handle to the PostScript output control structure and change the control structure members to suit your needs before calling `fl_object_ps_dump()`. You should not free the returned buffer.

The control structure has the following members

`int ps_color`

  The choices are full color (`FLPS_COLOR`), grayscale (`FLPS_GRAYSCALE`) and black&white (`FLPS_BW`). The default for xyplot is black and white. In this mode, all drawings are black, on a white background. If `drawbox` (see below) is true, the drawing color can be either white or black depending on the specified color.

`int orientation`

  Valid choices are `FLPS_AUTO`, `FLPS_PORTRAIT` and `FLPS_LANDSCAPE`. The default is `FLPS_AUTO`.

`auto_fit`

  By default, this is true so the object always fits the printed page. Set it to false (0) to turn off auto-scaling.

`int eps`

  Set this to 1 if output in EPS format is required.

`int drawbox`

  Set this to 1 if the box of the object is to be drawn.

`float xdpi, ydpi`

  These two are the screen resolution. The default is to use the actual resolution of the display. Note by setting a dpi number smaller or larger than the actual resolution, the output object is in effect being enlarged or shrunken.

`float paper_w`

  The paper width in inches. The default is 8.5 in.

`float paper_h`

  The paper height in inches. The default is 11 in.

To generate a PostScript output of a form or forms, use the `fd2ps` program documented in Part II Generating Hardcopies.

Next: Doing Interaction, Previous: Creating Forms, Up: Part V Overview of Main Functions [Contents][Index]