[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 15. Static Objects

## 15.1 Box Object

Boxes are simply used to give the dialogue forms a nicer appearance. They can be used to visually group other objects together. The bottom of each form is a box.

### 15.1.1 Adding Box Objects

To add a box to a form you use the routine

    FL_OBJECT *fl_add_box(int type, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h, const char *label);

The meaning of the parameters is as usual. The label is per default placed in the center of the box.

### 15.1.2 Box Types

The following types are available:

`FL_UP_BOX`

  A box that comes out of the screen.

``FL_DOWN_BOX``

  A box that goes down into the screen.

`FL_FLAT_BOX`

  A flat box without a border.

`FL_BORDER_BOX`

  A flat box with just a border.

`FL_FRAME_BOX`

  A flat box with an engraved frame.

`FL_SHADOW_BOX`

  A flat box with a shadow.

`FL_ROUNDED_BOX`

  A rounded box.

`FL_RFLAT_BOX`

  A rounded box without a border.

`FL_RSHADOW_BOX`

  A rounded box with a shadow.

`FL_OVAL_BOX`

  An elliptic box.

`FL_NO_BOX`

  No box at all, only a centered label.

### 15.1.3 Box Attributes

The first color argument (`col1`) to `fl_set_object_color()` controls the color of the box, the second (`col2`) is not used.

### 15.1.4 Remarks

No interaction takes place with boxes.

Do not use `FL_NO_BOX` type if the label is to change during the execution of the program.

## 15.2 Frame Object

Frames are simply used to give the dialogue forms a nicer appearance. They can be used to visually group other objects together. Frames are almost the same as a box, except that the interior of the bounding box is not filled. Use of frames can speed up drawing in certain situations. For example, to place a group of radio buttons within an `FL_ENGRAVED_FRAME`. If we were to use an `FL_FRAME_BOX` to group the buttons, visually they would look the same. However, the latter is faster as we don't have to fill the interior of the bounding box and can also reduce flicker. Frames are useful in decorating free objects and canvases.

### 15.2.1 Adding Frame Objects

To add a frame to a form you use the routine

    FL_OBJECT *fl_add_frame(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, const char *label);

The meaning of the parameters is as usual except that the frame is drawn outside of the bounding box (so a flat box of the same size just fills the inside of the frame without any gaps). The label is by default placed centered inside the frame.

### 15.2.2 Frame Types

The following types are available:

`FL_NO_FRAME`

  Nothing is drawn.

`FL_UP_FRAME`

  A frame appears coming out of the screen.

`FL_DOWN_FRAME`

  A frame that goes down into the screen.

`FL_BORDER_FRAME`

  A frame with a simple outline.

`FL_ENGRAVED_FRAME`

  A frame appears to be engraved.

`FL_EMBOSSED_FRAME`

  A frame appears embossed.

`FL_ROUNDED_FRAME`

  A rounded frame.

`FL_OVAL_FRAME`

  An elliptic box.

### 15.2.3 Frame Attributes

The first color argument (`col1`) of `fl_set_object_color()` controls the color of the frame if applicable, the second (`col2`) is not used. The boxtype attribute does not apply to the frame class.

### 15.2.4 Remarks

No interaction takes place with frames.

It may be faster to use frames instead of boxes for text that is truly static. See ``freedraw.c`' for an example use of frame objects.

## 15.3 LabelFrame Object

A label frame is almost the same as a frame except that the label is placed on the frame (See Fig. 15.1) instead of inside or outside of the bounding box as in a regular frame.

### 15.3.1 Adding LabelFrame Objects

To add a labelframe to a form you use the routine

    FL_OBJECT *fl_add_labelframe(int type, FL_Coord x, FL_Coord y,
                                 FL_Coord w, FL_Coord h, const char *label);

The meaning of the parameters is as usual except that the frame is drawn outside of the bounding box (so a flat box of the same size just fills the inside of the frame without any gaps). The label is by default placed on the upper left hand part of the frame. Its position can changed (within limits) via calls of `fl_set_object_lalign()`.

### 15.3.2 LabelFrame Types

The following types are available:

`FL_NO_FRAME`

  Nothing is drawn.

`FL_UP_FRAME`

  A frame appears coming out of the screen.

`FL_DOWN_FRAME`

  A frame that goes down into the screen.

`FL_BORDER_FRAME`

  A frame with a simple outline.

`FL_ENGRAVED_FRAME`

  A frame appears to be engraved.

`FL_EMBOSSED_FRAME`

  A frame appears embossed.

`FL_ROUNDED_FRAME`

  A rounded frame.

`FL_OVAL_FRAME`

  An elliptic box.

### 15.3.3 Attributes

The first color in the call of `fl_set_object_color()` controls the color of the frame if applicable. The second color controls the background color of the label. Boxtype attribute does not apply to the labelframe class

### 15.3.4 Remarks

No interaction takes place with labelframes.

You can not draw a label inside or outside of the frame box. If you try, say, by requesting `FL_ALIGN_CENTER`, the label is drawn using `FL_ALIGN_TOP_LEFT`.

## 15.4 Text Object

Text objects simply consist of a label possibly placed in a box.

### 15.4.1 Adding Text Objects

To add a text to a form you use the routine

    FL_OBJECT *fl_add_text(int type, FL_Coord x, FL_Coord y,
                           FL_Coord w, FL_Coord h, const char *label);

The meaning of the parameters is as usual. The label is by default placed flushed left in the bounding box.

### 15.4.2 Text Types

Only one type of text exists: `FL_NORMAL_TEXT`.

### 15.4.3 Text Attributes

To set or change the text shown, use `fl_set_object_label()` or `fl_set_object_label_f()`.

Any boxtype can be used for text.

The first color argument (`col1`) of `fl_set_object_color()` controls the color of the box the text is placed into, the second (`col2`) is not used. The color of the text itself is controlled by calls of `fl_set_object_lcolor()` as usual.

If the text is to change dynamically, boxtype `NO_BOX` should not be used for the object.

### 15.4.4 Remarks

No interaction takes place with text objects.

Don't use boxtype `FL_NO_BOX` if the text is to change dynamically. Note that there is almost no difference between a box with a label and a text. The only difference lies in the position where the text is placed and the fact that text is clipped to the bounding box. Text is normally placed inside the box at the left side. This helps you putting different lines of text below each other. Labels inside boxes are default centered in the box. You can change the position of the text inside the box using the routine `fl_set_object_lalign()`. In contrast to boxes different alignments for text always place the text inside the box rather than outside the box.

## 15.5 Bitmap Object

A bitmap is a simple bitmap shown on a form.

### 15.5.1 Adding Bitmap Objects

To add a bitmap to a form you use the routine

    FL_OBJECT *fl_add_bitmap(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label);

The meaning of the parameters is as usual. The label is by default placed below the bitmap. The bitmap is empty on creation.

### 15.5.2 Bitmap Types

Only the type `FL_NORMAL_BITMAP` is available.

### 15.5.3 Bitmap Interaction

No interaction takes place with a bitmap. For bitmaps that interact see Adding Button Objects, on how to create a button with a bitmap on top of it. (You can also place a hidden button over it if you want something to happen when pressing the mouse on a static bitmap.)

### 15.5.4 Other Bitmap Routines

To set the actual bitmap being displayed use

    void fl_set_bitmap_data(FL_OBJECT *obj, int w, int h,
                             unsigned char *bits);
    void fl_set_bitmap_file(FL_OBJECT *obj, const char *file);

`bits` contains the bitmap data as a character string. `file` is the name of the file that contains the bitmap data. A number of bitmaps can be found in ``/usr/include/X11/bitmaps`' or similar places. The X program `bitmap` can be used to create bitmaps.

Two additional routines are provided to make a Bitmap from a bitmap file or data

    Pixmap fl_read_bitmapfile(Window win, const char *filename,
                              unsigned *width, unsigned *height,
                              int *hotx, int *hoty)
    Pixmap fl_create_from_bitmapdata(Window win, const char *data,
                                     int width, int height);

where `win` is any window ID in your application and the other parameters have the obvious meanings. If there is no window created yet, the return value of `fl_default_window()` may be used.

Note: bitmaps created by the above routines have a depth of 1 and should be displayed using `XCopyPlane()`.

### 15.5.5 Bitmap Attributes

The label color as set by `fl_set_object_lcolor()` controls both the foreground color of the bitmap and the color of the label (i.e., they are always identical).

The first color argument (`col1`) to `fl_set_object_color()` sets the background color of the bitmap (and the color of the box), the second (`col2`) is not used.

### 15.5.6 Remarks

See ``demo33.c`' for a demo of a bitmap.

## 15.6 Pixmap Object

A pixmap is a simple pixmap (color icon) shown on a form.

### 15.6.1 Adding Pixmap Objects

To add a pixmap to a form use the routine

    FL_OBJECT *fl_add_pixmap(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label)

The meaning of the parameters is as usual. The label is by default placed below the pixmap. The pixmap is empty on creation.

### 15.6.2 Pixmap Types

Only the type `FL_NORMAL_PIXMAP` is available.

### 15.6.3 Pixmap Interaction

No interaction takes place with a pixmap. For pixmap that interacts see Adding Button Objects, on how to create a button with a pixmap on top of it. (You can also place a hidden button over it if you want something to happen when pressing the mouse on a static pixmap.)

### 15.6.4 Other Pixmap Routines

A pixmap file (usually with extension `.xpm`) is an ASCII file that contains the definition of the pixmap as a `char` pointer array that can be included directly into a C (or C++) source file.

To set the actual pixmap being displayed, use one of the following routines:

    void fl_set_pixmap_file(FL_OBJECT *obj, const char *file);
    void fl_set_pixmap_data(FL_OBJECT *obj, char **data);

In the first routine, you specify the pixmap by the filename `file` that contains it. In the second routine, you `#include` the pixmap at compile time and use the pixmap data (an array of `char` pointers) directly. Note that both of these functions do not free the old pixmaps associated with the object. If you're writing a pixmap browser type applications, be sure to free the old pixmaps by calling

    void fl_free_pixmap_pixmap(FL_OBJECT *obj);

on the pixmap object prior to calling these two routines. This function, in addition to freeing the pixmap and the mask, also frees the colors the pixmap allocated.

To obtain the pixmap ID currently being displayed, the following routine can be used

    Pixmap fl_get_pixmap_pixmap(FL_OBJECT *obj, Pixmap *id,
                                Pixmap *mask);

In some situations, you might already have a pixmap resource ID, e.g., from `fl_read_pixmapfile()` (see below in the "Remarks" subsection). Then you can use the following routine to change the the pixmap

    void fl_set_pixmap_pixmap(FL_OBJECT *obj, Pixmap id,
                              Pixmap mask);

where `mask` is used for transparency (see `fl_read_pixmapfile()`). Use 0 for mask if no special clipping attributes are desired.

This routine does not free the pixmap ID nor the mask already associated with the object. Thus if you no longer need the old pixmaps, they should be freed prior to changing the pixmaps using the function `fl_free_pixmap_pixmap()`.

Pixmaps are by default displayed centered inside the bounding box. However, this can be changed using the following routine

    void fl_set_pixmap_align(FL_OBJECT *obj, int align,
                             int dx, int dy);

where `align` is the same as that used for labels, see section Label Attributes and Fonts for a list. `dx` and `dy` are extra margins to leave in addition to the object border width. By default, `dx` and `dy` are set to 3. Note that although you can place a pixmap outside of the bounding box, it probably is not a good idea.

### 15.6.5 Pixmap Attributes

By default if a pixmap has more colors than that available in the colormap, the library will use substitute colors that are judged "close enough". This closeness is defined as the difference between the requested color and the color found being smaller than some pre-set threshold values between 0 and 65535 (0 means exact match). The default thresholds are 40000 for red, 30000 for green and 50000 for blue. To change these defaults, use the following routine

    void fl_set_pixmap_colorcloseness(int red, int green, int blue);

### 15.6.6 Remarks

The following routines may be handy for reading a pixmap file into a pixmap

    Pixmap fl_read_pixmapfile(Window win, const char *filename,
                              unsigned *width, unsigned *height,
                              Pixmap *shape_mask, int *hotx, int *hoty,
                              FL_COLOR tran);

where `win` is the window in which the pixmap is to be displayed. If the window is yet to be created, you can use the default window, returned by a call of `fl_default_window()`. Parameter `shape_mask` is a pointer to an already existing `Pixmap`, which, if not `NULL`, is used as a clipping mask to achieve transparency. `hotx` and `hoty` are the center of the pixmap (useful if the pixmap is to be used as a cursor). Parameter `tran` is currently not used.

If you already have the pixmap data in memory, the following routine can be used

    Pixmap fl_create_from_pixmapdata(Window win, char **data,
                                     unsigned *width, unsigned *height,
                                     Pixmap *shape_mask, int *hotx,
                                     int *hoty, FL_COLOR tran);

All parameters have the same meaning as for `fl_read_pixmapfile`.

Note that the Forms Library handles transparency, if specified in the pixmap file or data, for pixmap and pixmapbutton objects. However, when using `fl_read_pixmapfile()` or `fl_create_from_pixmapdata()`, the application programmer is responsible to set the clip mask in an appropriate GC.

Finally there is a routine that can be used to free a Pixmap

    void fl_free_pixmap(Pixmap id);

You will need the XPM library (version 3.4c or later)m developed by Arnaud Le Hors and Groupe Bull, to use pixmaps. The XPM library is avalialble as a package for most distributions, but can also be obtained from many X mirror sites, e.g., via anonymous FTP from (ftp://ftp.x.org/contrib/libraries/. Its home page is http://old.koalateam.com/lehors/xpm.html.

## 15.7 Clock Object

A clock object simply displays a clock on the form

### 15.7.1 Adding Clock Objects

To add a clock to a form you use the routine

    FL_OBJECT *fl_add_clock(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, char label[])

The meaning of the parameters is as usual. The label is placed below the clock by default.

### 15.7.2 Clock Types

The following types are available:

`FL_ANALOG_CLOCK`

  An analog clock complete with the second hand.

`FL_DIGITAL_CLOCK`

  A digital clock.

### 15.7.3 Clock Interaction

No interaction takes place with clocks.

### 15.7.4 Other Clock Routines

To get the displayed time (local time as modified by the adjustment described below) use the following routine

    void fl_get_clock(FL_OBJECT *obj, int *h, int *m, int *s);

Upon function return the parameters are set as follows: `h` is between 0-23, indicating the hour, `m` is between 0-59, indicating the minutes, and `s` is between 0-59, indicating the seconds.

To display a time other than the local time, use the following routine

    long fl_set_clock_adjustment(FL_OBJECT *obj, long adj);

where `adj` is in seconds. For example, to display a time that is one hour behind the local time, an adjustment of `3600` can be used. The function returns the old adjustment value.

By default, the digital clock uses 24hr system. You can switch the display to 12hr system (am-pm) by using the following routine

    void fl_set_clock_ampm(FL_OBJECT *obj, int yes_no)

### 15.7.5 Clock Attributes

Never use `FL_NO_BOX` as the boxtype for a digital clock.

The first color argument (`col1`) of `fl_set_object_color()` controls the color of the background, the second (`col2`) is the color of the hands.

### 15.7.6 Remarks

See ``flclock.c`' for an example of the use of clocks. See section Misc. Functions, for other time related routines.

## 15.8 Chart Object

The chart object gives you an easy way to display a number of different types of charts like bar-charts, pie-charts, line-charts etc. They can either be used to display some fixed chart or a changing chart (e.g., a strip-chart). Values in the chart can be changed and new values can be added which makes the chart move to the left, i.e., new entries appear at the right and old entries disappear at the left. This can be used to e.g., monitor processes.

### 15.8.1 Adding Chart Objects

To add a chart object to a form use the routine

    FL_OBJECT *fl_add_chart(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, const char *label);

It shows an empty box on the screen with the label below it.

### 15.8.2 Chart Types

The following types are available:

`FL_BAR_CHART`

  A bar-chart

`FL_HORBAR_CHART`

  A horizontal bar-chart

`FL_LINE_CHART`

  A line-chart

`FL_FILLED_CHART`

  A line-chart but the area below curve is filled

`FL_SPIKE_CHART`

  A chart with a vertical spike for each value

`FL_PIE_CHART`

  A pie-chart

`FL_SPECIALPIE_CHART`

  A pie-chart with displaced first item

All charts except pie-charts can display positive and negative data. Pie-charts will ignore values that are less then or equal to 0. The maximum number of values displayed in the chart can be set using the routine `fl_set_chart_maxnumb()`. The argument must be not larger than `FL_CHART_MAX` which currently is 512. Switching between different types can be done without any complications.

### 15.8.3 Chart Interaction

No interaction takes place with charts.

### 15.8.4 Other Chart Routines

There are a number of routines to change the values in the chart and to change its behavior. To clear a chart use the routine

    void fl_clear_chart(FL_OBJECT *obj);

To add an item to a chart use

    void fl_add_chart_value(FL_OBJECT *obj, double val,
                            const char *text, FL_COLOR col);

Here `val` is the value of the item, `text` is the label to be associated with the item (can be empty) and `col` is an index into the colormap (`FL_RED` etc.) that is the color of this item. The chart will be redrawn each time you add an item. This might not be appropriate if you are filling a chart with values. In this case put the calls between calls of `fl_freeze_form()` and `fl_unfreeze_form()`.

By default, the label is drawn in a tiny font in black. You can change the font style, size or color using the following routine

    void fl_set_chart_lstyle(FL_OBJECT *obj, int fontstyle);
    void fl_set_chart_lsize(FL_OBJECT *obj, int fontsize);
    void fl_set_chart_lcolor(FL_OBJECT *obj, FL_COLOR color);

Note that `fl_set_chart_lcolor()` only affects the label color of subsequent items, not the items already created.

You can also insert a new value at a particular place using

    void fl_insert_chart_value(FL_OBJECT *obj, int index,
                               double val, const char *text,
                               FL_COLOR col);

`index` is the index before which the new item should be inserted. The first item is number 1. So, for example, to make a strip-chart where the new value appears at the left, each time insert the new value before index 1.

To replace the value of a particular item use the routine

    void fl_replace_chart_value(FL_OBJECT *obj, int index,
                                double val, const char *text,
                                FL_COLOR col);

Here `index` is the index of the value to be replaced. The first value has an index of 1, etc.

Normally, bar-charts and line-charts are automatically scaled in the vertical direction such that all values can be displayed. This is often not wanted when new values are added from time to time. To set the minimal and maximal value displayed use the routine

    void fl_set_chart_bounds(FL_OBJECT *obj, double min, double max)'

To return to automatic scaling call it with both `min` and `max` being set to `0.0`. To obtain the current bounds, use the following routine

    void fl_get_chart_bounds(FL_OBJECT *obj, double *min, double *max)'

Also the width of the bars and distance between the points in a line-chart are normally scaled. To change this use

    void fl_set_chart_autosize(FL_OBJECT *obj, int autosize);

with `autosize` being set to false (0). In this case the width of the bars will be such that the maximum number of items fits in the box. This maximal number (defaults to `FL_CHART_MAX`) can be changed using

    void fl_set_chart_maxnumb(FL_OBJECT *obj, int maxnumb);

where `maxnumb` is the maximal number of items to be displayed, which may not be larger than `FL_CHART_MAX`.

### 15.8.5 Chart Attributes

Don't use boxtype `FL_NO_BOX` for a chart object if it changes value.

Normally, for bar and line chart a baseline is drawn at 0. This can be switched on and off by the function

    void fl_set_chart_baseline(FL_OBJECT *ob, int yes_no);

The first color argument (`col1`) to `fl_set_object_color()` controls the (background) color of the box, the second (`col2`) the color of the baseline.

### 15.8.6 Remarks

See ``chartall.c`' and ``chartstrip.c`' for examples of the use of chart objects.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Jens Thoms Toerring on January 5, 2014 using texi2html 1.82.