Next: Doing Interaction, Previous: Creating Forms, Up: Part V Overview of Main Functions [Contents][Index]
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);
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]