|FLTK Apps FLTK Library Forums Links Login|
|[ Home | Articles & FAQs | Bugs & Features | Documentation | Download ]|
Returns non-zero if any of the rectangle intersects the current clip region. If this returns 0 you don't have to draw the object.
Intersect the rectangle x,y,w,h with the current clip region and returns the bounding box of the result in X,Y,W,H. Returns non-zero if the resulting rectangle is different than the original. This can be used to limit the necessary drawing to a rectangle. W and H are set to zero if the rectangle is completely outside the region.
Replace the top of the clip stack with a clipping region of any shape. Fl_Region is an operating system specific type. The second form returns the current clipping region.
FLTK manages colors as 32-bit unsigned integers. Values from 0 to 255 represent colors from the FLTK 1.0.x standard colormap and are allocated as needed on screens without TrueColor support. The Fl_Color enumeration type defines the standard colors and color cube for the first 256 colors. All of these are named with symbols in <FL/Enumerations.H>.
Color values greater than 255 are treated as 24-bit RGB values. These are mapped to the closest color supported by the screen, either from one of the 256 colors in the FLTK 1.0.x colormap or a direct RGB value on TrueColor screens. You can generate 24-bit RGB color values using the fl_rgb_color() function.
Sets the color for all subsequent drawing operations.
For colormapped displays, a color cell will be allocated out of fl_colormap the first time you use a color. If the colormap fills up then a least-squares algorithm is used to find the closest color.
Returns the last fl_color() that was set. This can be used for state save/restore.
void fl_color(uchar r, uchar g, uchar b)
Set the color for all subsequent drawing operations. The closest possible match to the RGB color is used. The RGB color is used directly on TrueColor displays. For colormap visuals the nearest index in the gray ramp or color cube is used.
FLTK supports drawing of lines with different styles and widths. Full functionality is not available under Windows 95, 98, and Me due to the reduced drawing functionality these operating systems provide.
Set how to draw lines (the "pen"). If you change this it is your responsibility to set it back to the default with fl_line_style(0).
style is a bitmask which is a bitwise-OR of the following values. If you don't specify a dash type you will get a solid line. If you don't specify a cap or join type you will get a system-defined default of whatever value is fastest.
width is the number of pixels thick to draw the lines. Zero results in the system-defined default, which on both X and Windows is somewhat different and nicer than 1.
dashes is a pointer to an array of dash lengths, measured in pixels. The first location is how long to draw a solid portion, the next is how long to draw the gap, then the solid, etc. It is terminated with a zero-length entry. A NULL pointer or a zero-length array results in a solid line. Odd array sizes are not supported and result in undefined behavior.
These functions are used to draw almost all the FLTK widgets. They draw on exact pixel boundaries and are as fast as possible. Their behavior is duplicated exactly on all platforms FLTK is ported. It is undefined whether these are affected by the transformation matrix, so you should only call these while the matrix is set to the identity matrix (the default).
Draw a single pixel at the given coordinates.
Color a rectangle that exactly fills the given bounding box.
void fl_rectf(int x, int y, int w, int h, uchar r, uchar g, uchar b)
Color a rectangle with "exactly" the passed r,g,b color. On screens with less than 24 bits of color this is done by drawing a solid-colored block using fl_draw_image() so that the correct color shade is produced.
Draw a 1-pixel border inside this bounding box.
void fl_line(int x, int y, int x1, int y1)
For portability, you should only draw polygons that appear the same whether "even/odd" or "non-zero" winding rules are used to fill them. Holes should be drawn in the opposite direction of the outside loop.
fl_gap() should only be called between fl_begin_complex_polygon() and fl_end_complex_polygon(). To outline the polygon, use fl_begin_loop() and replace each fl_gap() with fl_end_loop();fl_begin_loop().
Add a series of points on a Bezier curve to the path. The curve ends (and two of the points) are at x,y and x3,y3.
Add a series of points to the current path on the arc of a circle; you can get elliptical paths by using scale and rotate before calling fl_arc(). x,y are the center of the circle, and r is its radius. fl_arc() takes start and end angles that are measured in degrees counter-clockwise from 3 o'clock. If end is less than start then it draws the arc in a clockwise direction.
fl_circle() is equivalent to fl_arc(...,0,360) but may be faster. It must be the only thing in the path: if you want a circle as part of a complex polygon you must use fl_arc().
fl_circle() draws incorrectly if the transformation is both rotated and non-square scaled.
All text is drawn in the current font. It is undefined whether this location or the characters are modified by the current transformation.
Draw a nul-terminated string or an array of n characters starting at the given location. Text is aligned to the left and to the baseline of the font. To align to the bottom, subtract fl_descent() from y. To align to the top, subtract fl_descent() and add fl_height(). This version of fl_draw provides direct access to the text drawing function of the underlying OS. It does not apply any special handling to control characters.
Fancy string drawing function which is used to draw all the labels. The string is formatted and aligned inside the passed box. Handles '\t' and '\n', expands all other control characters to ^X, and aligns inside or against the edges of the box described by x, y, w and h. See Fl_Widget::align() for values for align. The value FL_ALIGN_INSIDE is ignored, as this function always prints inside the box.
If img is provided and is not NULL, the image is drawn above or below the text as specified by the align value.
The draw_symbols argument specifies whether or not to look for symbol names starting with the "@" character.
The text length is limited to 1024 caracters per line.
Measure how wide and tall the string will be when printed by the fl_draw(...align) function. If the incoming w is non-zero it will wrap to that width.
Recommended minimum line spacing for the current font. You can also just use the value of size passed to fl_font().
Recommended distance above the bottom of a fl_height() tall box to draw the text at so it looks centered vertically in that box.
Return the pixel width of a nul-terminated string, a sequence of n characters, or a single character in the current font.
Unparse a shortcut value as used by Fl_Button or Fl_Menu_Item into a human-readable string like "Alt+N". This only works if the shortcut is a character key or a numbered function key. If the shortcut is zero an empty string is returned. The return value points at a static buffer that is overwritten with each call.
FLTK supports a set of standard fonts based on the Times, Helvetica/Arial, Courier, and Symbol typefaces, as well as custom fonts that your application may load. Each font is accessed by an index into a font table.
Initially only the first 16 faces are filled in. There are symbolic names for them: FL_HELVETICA, FL_TIMES, FL_COURIER, and modifier values FL_BOLD and FL_ITALIC which can be added to these, and FL_SYMBOL and FL_ZAPF_DINGBATS. Faces greater than 255 cannot be used in Fl_Widget labels, since Fl_Widget stores the index as a byte.
Set the current font, which is then used by the routines described above. You may call this outside a draw context if necessary to call fl_width(), but on X this will open the display.
The font is identified by a face and a size. The size of the font is measured in pixels and not "points". Lines should be spaced size pixels apart or more.
Returns the face and size set by the most recent call to fl_font(a,b). This can be used to save/restore the font.
FLTK 1 supports western character sets using the eight bit encoding of the user-selected global code page. For MS Windows and X11, the code page is assumed to be Windows-1252/Latin1, a superset to ISO 8859-1. On Mac OS X, we assume MacRoman.
FLTK provides the functions fl_latin1_to_local, fl_local_to_latin1, fl_mac_roman_to_local, and fl_local_to_mac_roman to convert strings between both encodings. These functions are only required if your source code contains "C"-strings with international characters and if this source will be compiled on multiple platforms.
Assuming that the following source code was written on MS Windows, this example will output the correct label on OS X and X11 as well. Without the conversion call, the label on OS X would read Fahrvergn¸gen with a deformed umlaut u.
btn = new Fl_Button(10, 10, 300, 25); btn->copy_label(fl_latin1_to_local("Fahrvergnügen"));
If your application uses characters that are not part of both encodings, or it will be used in areas that commonly use different code pages, yoou might consider upgrading to FLTK 2 which supports UTF-8 encoding.
These functions allow you to draw interactive selection rectangles without using the overlay hardware. FLTK will XOR a single rectangle outline over a window.
fl_overlay_rect() draws a selection rectangle, erasing any previous rectangle by XOR'ing it first. fl_overlay_clear() will erase the rectangle without drawing a new one.
Using these functions is tricky. You should make a widget with both a handle() and draw() method. draw() should call fl_overlay_clear() before doing anything else. Your handle() method should call window()->make_current() and then fl_overlay_rect() after FL_DRAG events, and should call fl_overlay_clear() after a FL_RELEASE event.
To draw images, you can either do it directly from data in your memory, or you can create a Fl_Image object. The advantage of drawing directly is that it is more intuitive, and it is faster if the image data changes more often than it is redrawn. The advantage of using the object is that FLTK will cache translated forms of the image (on X it uses a server pixmap) and thus redrawing is much faster.
The behavior when drawing images when the current transformation matrix is not the identity is not defined, so you should only draw images when the matrix is set to the identity.
Draw an 8-bit per color RGB or luminance image. The pointer points at the "r" data of the top-left pixel. Color data must be in r,g,b order. X,Y are where to put the top-left corner. W and H define the size of the image. D is the delta to add to the pointer between pixels, it may be any value greater or equal to 3, or it can be negative to flip the image horizontally. LD is the delta to add to the pointer between lines (if 0 is passed it uses W * D), and may be larger than W * D to crop data, or negative to flip the image vertically.
It is highly recommended that you put the following code before the first show() of any window in your program to get rid of the dithering if possible:
Gray scale (1-channel) images may be drawn. This is done if abs(D) is less than 3, or by calling fl_draw_image_mono(). Only one 8-bit sample is used for each pixel, and on screens with different numbers of bits for red, green, and blue only gray colors are used. Setting D greater than 1 will let you display one channel of a color image.
The X version does not support all possible visuals. If FLTK cannot draw the image in the current visual it will abort. FLTK supports any visual of 8 bits or less, and all common TrueColor visuals up to 32 bits.
Call the passed function to provide each scan line of the image. This lets you generate the image as it is being drawn, or do arbitrary decompression of stored data, provided it can be decompressed to individual scan lines easily.
The callback is called with the void * user data pointer which can be used to point at a structure of information about the image, and the x, y, and w of the scan line desired from the image. 0,0 is the upper-left corner of the image, not X,Y. A pointer to a buffer to put the data into is passed. You must copy w pixels from scanline y, starting at pixel x, to this buffer.
Due to cropping, less than the whole image may be requested. So x may be greater than zero, the first y may be greater than zero, and w may be less than W. The buffer is long enough to store the entire W * D pixels, this is for convenience with some decompression schemes where you must decompress the entire line at once: decompress it into the buffer, and then if x is not zero, copy the data over so the x'th pixel is at the start of the buffer.
You can assume the y's will be consecutive, except the first one may be greater than zero.
If D is 4 or more, you must fill in the unused bytes with zero.
Draws XPM image data, with the top-left corner at the given position. The image is dithered on 8-bit displays so you won't lose color space for programs displaying both images and pixmaps. This function returns zero if there was any error decoding the XPM data.
To use an XPM, do:
#include "foo.xpm" ... fl_draw_pixmap(foo, X, Y);
Transparent colors are replaced by the optional Fl_Color argument. To draw with true transparency you must use the Fl_Pixmap class.
An XPM image contains the dimensions in its data. This function finds and returns the width and height. The return value is non-zero if the dimensions were parsed ok and zero if there was any problem.
FLTK provides a single function for reading from the current window or off-screen buffer into a RGB(A) image buffer.
Read a RGB(A) image from the current window or off-screen buffer. The p argument points to a buffer that can hold the image and must be at least W*H*3 bytes when reading RGB images and W*H*4 bytes when reading RGBA images. If NULL, fl_read_image() will create an array of the proper size which can be freed using delete.
The alpha parameter controls whether an alpha channel is created and the value that is placed in the alpha channel. If 0, no alpha channel is generated.
FLTK provides a base image class called Fl_Image which supports creating, copying, and drawing images of various kinds, along with some basic color operations. Images can be used as labels for widgets using the image() and deimage() methods or drawn directly.
The Fl_Image class does almost nothing by itself, but is instead supported by three basic image types:
The Fl_Bitmap class encapsulates a mono-color bitmap image. The draw() method draws the image using the current drawing color.
The Fl_Pixmap class encapsulates a colormapped image. The draw() method draws the image using the colors in the file, and masks off any transparent colors automatically.
The Fl_RGB_Image class encapsulates a full-color (or grayscale) image with 1 to 4 color components. Images with an even number of components are assumed to contain an alpha channel that is used for transparency. The transparency provided by the draw() method is either a 24-bit blend against the existing window contents or a "screen door" transparency mask, depending on the platform and screen color depth.
fl_can_do_alpha_blending() will return 1, if your platform supports true alpha blending for RGBA images, or 0, if FLTK will use screen door transparency.
FLTK also provides several image classes based on the three standard image types for common file formats:
Each of these image classes load a named file of the corresponding format. The Fl_Shared_Image class can be used to load any type of image file - the class examines the file and constructs an image of the appropriate type.
Finally, FLTK provides a special image class called Fl_Tiled_Image to tile another image object in the specified area. This class can be used to tile a background image in a Fl_Group widget, for example.
The copy() method creates a copy of the image. The second form specifies the new size of the image - the image is resized using the nearest-neighbor algorithm.
The draw() method draws the image object. x,y,w,h indicates a destination rectangle. ox,oy,w,h is a source rectangle. This source rectangle is copied to the destination. The source rectangle may extend outside the image, i.e. ox and oy may be negative and w and h may be bigger than the image, and this area is left unchanged.
Draws the image with the upper-left corner at x,y. This is the same as doing draw(x,y,img->w(),img->h(),0,0).
Create an RGB offscreen buffer with w*h pixels.
Delete a previously created offscreen buffer. All drawings are lost.
Send all subsequent drawing commands to this offscreen buffer. FLTK can draw into a buffer at any time. There is no need to wait for an Fl_Widget::draw() to occur.
Quit sending drawing commands to this offscreen buffer.
Copy a rectangular area of the size w*h from srcx, srcy in the offscreen buffer into the current buffer at x, y.
This tells how to set the font face and size, but does NOT tell what the default values are (face = 0 = helvetica and size = 14). That would be a helpful addition.
[ Reply ]
It might be useful to know that on my platform (Ubuntu 8.10 x86-64/gnome, libfltk1.1-dev from Ubuntu repos, gcc 4.3), the default font face and size are 'segfault'! It appears that for portable code, you should not rely on the defaults here.
[ Reply ]
Another bad link:
In the "Drawing Images" section, on the first line, there is a link supposedly to class Fl_Image. But this link just points back to the same page you are already on, rather than the correct location:
[ Reply ]
Bad link on the page.
In the section titled "FLTK Drawing Functions", there is a link to "Images". This incorrectly points to a Fluid topic rather than to the "Drawing Images" section of chapter 5.
[ Reply ]