diff options
Diffstat (limited to 'documentation/src/drawing.dox')
| -rw-r--r-- | documentation/src/drawing.dox | 1013 |
1 files changed, 1013 insertions, 0 deletions
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox new file mode 100644 index 000000000..ea47d8fe2 --- /dev/null +++ b/documentation/src/drawing.dox @@ -0,0 +1,1013 @@ +/** + + \page drawing 5 - Drawing Things in FLTK + +This chapter covers the drawing functions that are provided with FLTK. + +\section sect_WhenCanYouDraw When Can You Draw Things in FLTK? + +There are only certain places you can execute drawing code in FLTK. +Calling these functions at other places will result in undefined behavior! + +\li The most common place is inside the virtual Fl_Widget::draw() method. + To write code here, you must subclass one of the existing Fl_Widget + classes and implement your own version of draw(). + +\li The most common place is inside the virtual method + <A href="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A>. + To write code here, you must subclass one of the existing Fl_Widget + classes and implement your own version of draw(). + +\li You can also write <A href="common.html#boxtypes">boxtypes</A> and + <A href="common.html#labeltypes">labeltypes</A>. These are small + procedures that can be called by existing + <A HREF="subclassing.html#draw"><tt>Fl_Widget::draw()</tt></A> + methods. These "types" are identified by an 8-bit index that is stored + in the widget's box(), labeltype(), and possibly other properties. + +\li You can call Fl_Window::make_current() to do incremental update of a + widget. Use Fl_Widget::window() to find the window. + + +\section sect_DrawingFunctions Drawing Functions + +To use the drawing functions you must first include the <FL/fl_draw.H> +header file. FLTK provides the following types of drawing functions: + +\li \ref ssect_Boxes +\li \ref ssect_Clipping +\li \ref drawing_colors +\li \ref ssect_Lines +\li \ref ssect_Fast +\li \ref ssect_Complex +\li \ref ssect_Text +\li \ref ssect_Fl_Image +\li \ref ssect_Overlay +\li \ref ssect_Offscreen + +<A name="boxdraw"></A> <!-- For old HTML links only ! --> +\subsection ssect_Boxes Boxes + +FLTK provides three functions that can be used to draw boxes for buttons +and other UI controls. Each function uses the supplied upper-lefthand corner +and width and height to determine where to draw the box. + +<A NAME="fl_draw_box"> </A> <!-- For old HTML links only ! --> +void fl_draw_box(Fl_Boxtype b, int x, int y, int w, int h, Fl_Color c); + +\par +The first box drawing function is fl_draw_box() +which draws a standard boxtype \a b in the specified color \a c . + +<A NAME="fl_frame"></A> <!-- For old HTML links only ! --> +void fl_frame(const char *s, int x, int y, int w, int h) + +\par +The fl_frame() function draws a series of line segments around the +given box. The string \a s must contain groups of 4 letters which specify +one of 24 standard grayscale values, where 'A' is black and 'X' is white. +The order of each set of 4 characters is: top, left, bottom, right. The +results of calling fl_frame() with a string that is not a multiple +of 4 characters in length are undefined. + +\par +The only difference between this function and fl_frame2() is the +order of the line segments. + +\par +See also: <A HREF="common.html#fl_frame">fl_frame boxtype</A>. + +<A NAME="fl_frame2"></A> <!-- For old HTML links only ! --> +void fl_frame2(const char *s, int x, int y, int w, int h); + +\par +The fl_frame2() function draws a series of line segments around +the given box. The string \a s must contain groups of 4 letters which +specify one of 24 standard grayscale values, where 'A' is black and 'X' is +white. The order of each set of 4 characters is: bottom, right, top, left. +The results of calling fl_frame2() with a string that is +not a multiple of 4 characters in length are undefined. + +\par +The only difference between this function and fl_frame() +is the order of the line segments. + +<A name="clipping"></A> <!-- For old HTML links only ! --> +\subsection ssect_Clipping Clipping + +You can limit all your drawing to a rectangular region by calling +fl_push_clip(), and put the drawings back by using fl_pop_clip(). +This rectangle is measured in pixels and is unaffected by the current +transformation matrix. + +In addition, the system may provide clipping when updating windows +which may be more complex than a simple rectangle. + +<A name="fl_push_clip"></A> <!-- For old HTML links only ! --> +void fl_clip(int x, int y, int w, int h) <br> +void fl_push_clip(int x, int y, int w, int h) + +\par +Intersect the current clip region with a rectangle and push this new +region onto the stack. The fl_clip() name is deprecated and +will be removed from future releases. + +<A NAME="fl_push_no_clip"></A> <!-- For old HTML links only ! --> +void fl_push_no_clip() + +\par +Pushes an empty clip region on the stack so nothing will be clipped. + +<A NAME="fl_pop_clip"></A> <!-- For old HTML links only ! --> +void fl_pop_clip() + +\par +Restore the previous clip region. + +\par +\b Note: +You must call fl_pop_clip() once for every time you call fl_push_clip(). +If you return to FLTK with the clip stack not empty unpredictable results +occur. + +<A NAME="fl_not_clipped"></A> <!-- For old HTML links only ! --> +int fl_not_clipped(int x, int y, int w, int h) + +\par +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. + +\par +\b Note: +Under X this returns 2 if the rectangle is partially clipped, +and 1 if it is entirely inside the clip region. + +<A NAME="fl_clip_box"></A> <!-- For old HTML links only ! --> +int fl_clip_box(int x, int y, int w, int h, int &X, int &Y, int &W, int &H) + +\par +Intersect the rectangle <tt>x,y,w,h</tt> with the current +clip region and returns the bounding box of the result in +<tt>X,Y,W,H</tt>. Returns non-zero if the resulting rectangle is +different than the original. This can be used to limit the +necessary drawing to a rectangle. \c W and \c H are +set to zero if the rectangle is completely outside the region. + +<A NAME="fl_clip_region"></A> <!-- For old HTML links only ! --> +void fl_clip_region(Fl_Region r) <br> +Fl_Region fl_clip_region() + +\par +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. + + +<A NAME="colors"></A> <!-- For old HTML links only ! --> +\section drawing_colors Colors + +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 +<A href="enumerations.html#colors"><tt><FL/Enumerations.H></tt></A>. + +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 +<A HREF="functions.html#fl_rgb_color"><tt>fl_rgb_color()</tt></A> +function. + +<A name="fl_color"></A> <!-- For old HTML links only ! --> +void fl_color(Fl_Color) + +\par +Sets the color for all subsequent drawing operations. + +\par +For colormapped displays, a color cell will be allocated out +of <tt>fl_colormap</tt> the first time you use a color. If the +colormap fills up then a least-squares algorithm is used to find +the closest color. + +Fl_Color fl_color() + +\par +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) + +\par +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. + +<A name="lines"></A> <!-- For old HTML links only ! --> +\subsection ssect_Lines Line Dashes and Thickness + +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. + +<A NAME="fl_line_style"></A> <!-- For old HTML links only ! --> +void fl_line_style(int style, int width=0, char* dashes=0) + +\par +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). + +\par +\b Note: +Because of how line styles are implemented on WIN32 systems, you <I>must</I> +set the line style <I>after</I> setting the drawing color. If you set the +color after the line style you will lose the line style settings! + +<i>style</i> 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. + +\li <tt>FL_SOLID -------</tt> +\li <tt>FL_DASH - - - -</tt> +\li <tt>FL_DOT .......</tt> +\li <tt>FL_DASHDOT - . - .</tt> +\li <tt>FL_DASHDOTDOT - .. -</tt> +\li <tt>FL_CAP_FLAT</tt> +\li <tt>FL_CAP_ROUND</tt> +\li <tt>FL_CAP_SQUARE</tt> (extends past end point 1/2 line width) +\li <tt>FL_JOIN_MITER</tt> (pointed) +\li <tt>FL_JOIN_ROUND</tt> +\li <tt>FL_JOIN_BEVEL</tt> (flat) + +<i>width</i> 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. + +<!-- NEED 4in --> + +<i>dashes</i> 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 <tt>NULL</tt> pointer or a zero-length +array results in a solid line. Odd array sizes are not supported and +result in undefined behavior. + +\note +The dashes array does not work under Windows 95, 98, or Me, since those +operating systems do not support complex line styles. + +<A name="fast"></A> <!-- For old HTML links only ! --> +\subsection ssect_Fast Drawing Fast Shapes + +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 +<A href="#complex">transformation matrix</A>, +so you should only call these while the matrix is set to the +identity matrix (the default). + +<A NAME="fl_point"></A> <!-- For old HTML links only ! --> +void fl_point(int x, int y) + +\par +Draw a single pixel at the given coordinates. + +<A NAME="fl_rectf"></A> <!-- For old HTML links only ! --> +void fl_rectf(int x, int y, int w, int h) <br> +void fl_rectf(int x, int y, int w, int h) + +\par +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) + +\par +Color a rectangle with "exactly" the passed +<tt>r,g,b</tt> color. On screens with less than 24 bits of +color this is done by drawing a solid-colored block using +<A href="#fl_draw_image"><tt>fl_draw_image()</tt></A> +so that the correct color shade is produced. + +<A NAME="fl_rect"></A> <!-- For old HTML links only ! --> +void fl_rect(int x, int y, int w, int h) <br> +void fl_rect(int x, int y, int w, int h, Fl_Color c) + +\par +Draw a 1-pixel border <I>inside</I> this bounding box. + +<A NAME="fl_line"></A> <!-- For old HTML links only ! --> +void fl_line(int x, int y, int x1, int y1) <br> +void fl_line(int x, int y, int x1, int y1, int x2, int y2) + +\par +Draw one or two lines between the given points. + +<A NAME="fl_loop"></A> <!-- For old HTML links only ! --> +void fl_loop(int x, int y, int x1, int y1, int x2, int y2) <br> +void fl_loop(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) + +\par +Outline a 3 or 4-sided polygon with lines. + +<A NAME="fl_polygon"></A> <!-- For old HTML links only ! --> +void fl_polygon(int x, int y, int x1, int y1, int x2, int y2) <br> +void fl_polygon(int x, int y, int x1, int y1, int x2, int y2, int x3, int y3) + +\par +Fill a 3 or 4-sided polygon. The polygon must be convex. + +<A NAME="fl_xyline"></A> <!-- For old HTML links only ! --> +void fl_xyline(int x, int y, int x1) <br> +void fl_xyline(int x, int y, int x1, int y2) <br> +void fl_xyline(int x, int y, int x1, int y2, int x3) + +\par +Draw horizontal and vertical lines. A horizontal line is +drawn first, then a vertical, then a horizontal. + +<A NAME="fl_yxline"></A> <!-- For old HTML links only ! --> +void fl_yxline(int x, int y, int y1) <br> +void fl_yxline(int x, int y, int y1, int x2) <br> +void fl_yxline(int x, int y, int y1, int x2, int y3) + +\par +Draw vertical and horizontal lines. A vertical line is drawn +first, then a horizontal, then a vertical. + +<A NAME="fl_pie"></A> <!-- For old HTML links only ! --> +void fl_arc(int x, int y, int w, int h, double a1, double a2) <br> +void fl_pie(int x, int y, int w, int h, double a1, double a2) + +\par +Draw ellipse sections using integer coordinates. These +functions match the rather limited circle drawing code provided +by X and WIN32. The advantage over using +<A href="#fl_arc"><tt>fl_arc</tt></A> +with floating point +coordinates is that they are faster because they often use the +hardware, and they draw much nicer small circles, since the +small sizes are often hard-coded bitmaps. + +If a complete circle is drawn it will fit inside the passed bounding +box. The two angles are measured in degrees counterclockwise from +3'oclock and are the starting and ending angle of the arc, <tt>a2</tt> +must be greater or equal to <tt>a1</tt>. + +fl_arc() draws a series of lines to approximate the arc. +Notice that the integer version of fl_arc() has a different +number of arguments than the +<A href="#fl_arc"><tt>fl_arc()</tt></A> +function described later in this chapter. + +fl_pie() draws a filled-in pie slice. This slice may +extend outside the line drawn by fl_arc(); to avoid this +use <tt>w - 1</tt> and <tt>h - 1</tt>. + +<A name="fl_scroll"></A> <!-- For old HTML links only ! --> +void fl_scroll(int X, int Y, int W, int H, int dx, int dy, +void (*draw_area)(void*, int,int,int,int), void* data) + +\par +Scroll a rectangle and draw the newly exposed portions. The contents +of the rectangular area is first shifted by <tt>dx</tt> and +<tt>dy</tt> pixels. The callback is then called for every newly +exposed rectangular area, + +<A name="complex"></A> <!-- For old HTML links only ! --> +\subsection ssect_Complex Drawing Complex Shapes + +The complex drawing functions let you draw arbitrary shapes +with 2-D linear transformations. The functionality matches that +found in the Adobe® PostScript&tm; language. The +exact pixels that are filled are less defined than for the fast +drawing functions so that FLTK can take advantage of drawing +hardware. On both X and WIN32 the transformed vertices are +rounded to integers before drawing the line segments: this +severely limits the accuracy of these functions for complex +graphics, so use OpenGL when greater accuracy and/or performance +is required. + +<A NAME="fl_push_matrix"></A> <!-- For old HTML links only ! --> +void fl_push_matrix() <br> +void fl_pop_matrix() + +\par +Save and restore the current transformation. The maximum +depth of the stack is 4. + +<A NAME="fl_scale"></A> <!-- For old HTML links only ! --> +void fl_scale(float x, float y) <br> +void fl_scale(float x) <br> +void fl_translate(float x, float y) <br> +void fl_rotate(float d) <br> +void fl_mult_matrix(float a, float b, float c, float d, float x, float y) + +\par +Concatenate another transformation onto the current one. The rotation +angle is in degrees (not radians) and is counter-clockwise. + +<A NAME="fl_transform"></A> <!-- For old HTML links only ! --> +double fl_transform_x(double x, double y) <br> +double fl_transform_y(double x, double y) <br> +double fl_transform_dx(double x, double y) <br> +double fl_transform_dy(double x, double y) <br> +void fl_transformed_vertex(double xf, double yf) + +\par +Transform a coordinate or a distance trough the current transformation matrix. +After transforming a coordinate pair, it can be added to the vertex +list without any forther translations using <tt>fl_transformed_vertex</tt>. + +<A NAME="fl_begin_points"></A> <!-- For old HTML links only ! --> +void fl_begin_points() <br> +void fl_end_points() + +\par +Start and end drawing a list of points. Points are added to +the list with <tt>fl_vertex</tt>. + +<A NAME="fl_begin_line"></A> <!-- For old HTML links only ! --> +void fl_begin_line() <br> +void fl_end_line() + +\par +Start and end drawing lines. + +<A NAME="fl_begin_loop"></A> <!-- For old HTML links only ! --> +void fl_begin_loop() <br> +void fl_end_loop() + +\par +Start and end drawing a closed sequence of lines. + +<A NAME="fl_begin_polygon"></A> <!-- For old HTML links only ! --> +void fl_begin_polygon() <br> +void fl_end_polygon() + +\par +Start and end drawing a convex filled polygon. + +<A NAME="fl_begin_complex_polygon"></A> <!-- For old HTML links only ! --> +void fl_begin_complex_polygon() <br> +void fl_gap() <br> +void fl_end_complex_polygon() + +\par +Start and end drawing a complex filled polygon. This polygon +may be concave, may have holes in it, or may be several +disconnected pieces. Call fl_gap() to separate loops of +the path. It is unnecessary but harmless to call +fl_gap() before the first vertex, after the last one, +or several times in a row. + +\par +\b Note: +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. + +\par +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(). + +<A NAME="fl_vertex"></A> <!-- For old HTML links only ! --> +void fl_vertex(float x, float y) + +\par +Add a single vertex to the current path. + +<A NAME="fl_curve"></A> <!-- For old HTML links only ! --> +void fl_curve(float x, float y, float x1, float y1, float x2, float y2, +float x3, float y3) + +\par +Add a series of points on a Bezier curve to the path. The curve ends +(and two of the points) are at <tt>x,y</tt> and <tt>x3,y3</tt>. + +<A NAME="fl_arc"></A> <!-- For old HTML links only ! --> +void fl_arc(float x, float y, float r, float start, float end) + +\par +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(). <tt>x,y</tt> are the center of +the circle, and <tt>r</tt> is its radius. fl_arc() +takes <tt>start</tt> and <tt>end</tt> angles that are measured +in degrees counter-clockwise from 3 o'clock. If <tt>end</tt> is +less than <tt>start</tt> then it draws the arc in a clockwise +direction. + +<A NAME="fl_circle"></A> <!-- For old HTML links only ! --> +void fl_circle(float x, float y, float r) + +\par +fl_circle() is equivalent to fl_arc(...,0,360) but +may be faster. It must be the <I>only</I> thing in the path: if you +want a circle as part of a complex polygon you must use fl_arc(). + +\par +\b Note: +fl_circle() draws incorrectly if the transformation is both rotated and +non-square scaled. + +<A name="text"></A> <!-- For old HTML links only ! --> +\subsection ssect_Text Drawing Text + +All text is drawn in the +<A href="#fl_font">current font</A>. +It is undefined whether this location or the characters are +modified by the current transformation. + +<A NAME="fl_draw"></A> <!-- For old HTML links only ! --> +void fl_draw(const char *, int x, int y) <br> +void fl_draw(const char *, int n, int x, int y) + +\par +Draw a nul-terminated string or an array of <tt>n</tt> 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 +<i>y</i>. 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. + +void fl_draw(const char *, int x, int y, int w, int h, +Fl_Align align, Fl_Image *img = 0, int draw_symbols = 1) + +\par +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 <i>x</i>, <i>y</i>, <i>w</i> and <i>h</i>. See +Fl_Widget::align() for values for <tt>align</tt>. The value +<tt>FL_ALIGN_INSIDE</tt> is ignored, as this function always +prints inside the box. + +\par +If <tt>img</tt> is provided and is not <tt>NULL</tt>, the +image is drawn above or below the text as specified by the +<tt>align</tt> value. + +\par +The <tt>draw_symbols</tt> argument specifies whether or not +to look for symbol names starting with the "@" character. + +\par +The text length is limited to 1024 caracters per line. + +<A NAME="fl_measure"></A> <!-- For old HTML links only ! --> +void fl_measure(const char *, int &w, int &h, int draw_symbols = 1) + +\par +Measure how wide and tall the string will be when printed by +the <tt>fl_draw(...align)</tt> function. If the incoming +<tt>w</tt> is non-zero it will wrap to that width. + +<A NAME="fl_height"></A> <!-- For old HTML links only ! --> +int fl_height() + +\par +Recommended minimum line spacing for the current font. You +can also just use the value of <tt>size</tt> passed to +<A href="#fl_font"><tt>fl_font()</tt></A>. + +<A NAME="fl_descent"></A> <!-- For old HTML links only ! --> +int fl_descent() + +\par +Recommended distance above the bottom of a fl_height() tall box to draw +the text at so it looks centered vertically in that box. + +<A NAME="fl_width"></A> <!-- For old HTML links only ! --> +float fl_width(const char*) <br> +float fl_width(const char*, int n) <br> +float fl_width(uchar) + +\par +Return the pixel width of a nul-terminated string, a sequence of <tt>n</tt> +characters, or a single character in the current font. + +<A NAME="fl_shortcut_label"></A> <!-- For old HTML links only ! --> +const char *fl_shortcut_label(ulong) + +\par +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. + +<A name="fonts"></A> <!-- For old HTML links only ! --> +\subsection ssect_Fonts Fonts + +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. + +<A name="fl_font"></A> <!-- For old HTML links only ! --> +void fl_font(int face, int size) + +\par +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. + +\par +The font is identified by a <tt>face</tt> and a +<tt>size</tt>. The size of the font is measured in +<tt>pixels</tt> and not "points". Lines should be spaced +<tt>size</tt> pixels apart or more. + +<A NAME="fl_size"></A> <!-- For old HTML links only ! --> +int fl_font() <br> +int fl_size() + +\par +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. + +<A NAME="character_encoding"></A> <!-- For old HTML links only ! --> +\subsection ssect_CharacterEncoding Character Encoding + +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. + +<!-- Editor's note: + ** Caution: the following text contains utf-8 encoded characters. + ** be careful when using non-utf-8-aware editors ! +--> + +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 +<tt>Fahrvergn¸gen</tt> with a deformed umlaut u ("cedille", +html "¸"). +\code + btn = new Fl_Button(10, 10, 300, 25); + btn->copy_label(fl_latin1_to_local("Fahrvergnügen")); +\endcode + +\note 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, you might consider upgrading to FLTK 2 which supports + UTF-8 encoding. + +\todo drawing.dox: I fixed the above encoding problem of these \¸ + and umlaut characters, but this text is obsoleted by FLTK 1.3 + with utf-8 encoding, or must be rewritten accordingly: + How to use native (e.g. Windows "ANSI", or ISO-8859-x) + encoding in embedded strings for labels, error messages + and more. Please check this (utf-8) encoding on different + OS'es and with different language and font environments. + +For more information about character encoding, unicode and utf-8 +see chapter \ref unicode. + +<A name="overlay"></A> <!-- For old HTML links only ! --> +\subsection ssect_Overlay Drawing Overlays + +These functions allow you to draw interactive selection rectangles +without using the overlay hardware. FLTK will XOR a single rectangle +outline over a window. + +void fl_overlay_rect(int x, int y, int w, int h); <br> +void fl_overlay_clear(); + +\par +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. + +\par +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. + + +<A NAME="images"></A> <!-- For old HTML links only ! --> +\section drawing_images Drawing Images + +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 <I>much</I> faster. + +\subsection ssect_DirectImageDrawing Direct Image Drawing + +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. + +<A NAME="fl_draw_image"></A> <!-- For old HTML links only ! --> +void fl_draw_image(const uchar *, int X, int Y, int W, int H, +int D = 3, int LD = 0) <br> +void fl_draw_image_mono(const uchar *, int X, int Y, int W, int H, +int D = 1, int LD = 0) + +\par +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 <tt>r,g,b</tt> order. <tt>X,Y</tt> are where to +put the top-left corner. <tt>W</tt> and <tt>H</tt> define the +size of the image. <tt>D</tt> is the delta to add to the pointer +between pixels, it may be any value greater or equal to +<tt>3</tt>, or it can be negative to flip the image +horizontally. <tt>LD</tt> is the delta to add to the pointer +between lines (if 0 is passed it uses <tt>W * D</tt>), and may +be larger than <tt>W * D</tt> to crop data, or negative to flip +the image vertically. + +\par +It is highly recommended that you put the following code before the +first show() of <I>any</I> window in your program to get rid +of the dithering if possible: + +\code +Fl::visual(FL_RGB); +\endcode + +\par +Gray scale (1-channel) images may be drawn. This is done if +<tt>abs(D)</tt> 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 +<tt>D</tt> greater than 1 will let you display one channel of a +color image. + +\par +\b Note: +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. + +typedef void (*fl_draw_image_cb)(void *, int x, int y, int w, uchar *) <br> +void fl_draw_image(fl_draw_image_cb, void *, int X, int Y, int W, int H, +int D = 3) <br> +void fl_draw_image_mono(fl_draw_image_cb, void *, int X, int Y, int W, int H, +int D = 1) + +\par +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. + +\par +The callback is called with the <tt>void *</tt> user data +pointer which can be used to point at a structure of information +about the image, and the <tt>x</tt>, <tt>y</tt>, and <tt>w</tt> +of the scan line desired from the image. 0,0 is the upper-left +corner of the image, <I>not <tt>X,Y</tt></I>. A pointer to a +buffer to put the data into is passed. You must copy <tt>w</tt> +pixels from scanline <tt>y</tt>, starting at pixel <tt>x</tt>, +to this buffer. + +\par +Due to cropping, less than the whole image may be requested. +So <tt>x</tt> may be greater than zero, the first <tt>y</tt> may +be greater than zero, and <tt>w</tt> may be less than +<tt>W</tt>. The buffer is long enough to store the entire <tt>W * D</tt> +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 <tt>x</tt> is not +zero, copy the data over so the <tt>x</tt>'th pixel is at the +start of the buffer. + +\par +You can assume the <tt>y</tt>'s will be consecutive, except +the first one may be greater than zero. + +\par +If <tt>D</tt> is 4 or more, you must fill in the unused bytes +with zero. + +<A NAME="fl_draw_pixmap"></A> <!-- For old HTML links only ! --> +int fl_draw_pixmap(char **data, int X, int Y, Fl_Color = FL_GRAY) + +\par +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. + +\par +To use an XPM, do: + +\code +#include "foo.xpm" +... +fl_draw_pixmap(foo, X, Y); +\endcode + +\par +Transparent colors are replaced by the optional +Fl_Color argument. To draw with true transparency you must +use the Fl_Pixmap class. + +<A NAME="fl_measure_pixmap"></A> <!-- For old HTML links only ! --> +int fl_measure_pixmap(char **data, int &w, int &h) + +\par +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. + +\subsection ssect_DirectImageReading Direct Image Reading + +FLTK provides a single function for reading from the current +window or off-screen buffer into a RGB(A) image buffer. + +<A NAME="fl_read_image"></A> <!-- For old HTML links only ! --> +uchar *fl_read_image(uchar *p, int X, int Y, int W, int H, int alpha = 0); + +\par +Read a RGB(A) image from the current window or off-screen +buffer. The <tt>p</tt> argument points to a buffer that can hold +the image and must be at least <tt>W*H*3</tt> bytes when reading +RGB images and <tt>W*H*4</tt> bytes when reading RGBA images. If +<tt>NULL</tt>, <tt>fl_read_image()</tt> will create an array of +the proper size which can be freed using <tt>delete[]</tt>. + +\par +The <tt>alpha</tt> 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. + +<A name="Fl_Image"></A> <!-- For old HTML links only ! --> +\subsection ssect_Fl_Image Image Classes + +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: + +\li Fl_Bitmap +\li Fl_Pixmap +\li Fl_RGB_Image + +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. + +<A NAME="fl_can_do_alpha_blending"></A> <!-- For old HTML links only ! --> +char fl_can_do_alpha_blending() + +\par +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: + +\li Fl_GIF_Image +\li Fl_JPEG_Image +\li Fl_PNG_Image +\li Fl_PNM_Image +\li Fl_XBM_Image +\li Fl_XPM_Image + +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. + +virtual void copy(); <br> +virtual void copy(int w, int h); + +\par +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. + +void draw(int x, int y, int w, int h, int ox = 0, int oy = 0); + +\par +The draw() method draws the image object. +<tt>x,y,w,h</tt> indicates a destination rectangle. +<tt>ox,oy,w,h</tt> is a source rectangle. This source rectangle +is copied to the destination. The source rectangle may extend +outside the image, i.e. <tt>ox</tt> and <tt>oy</tt> may be +negative and <tt>w</tt> and <tt>h</tt> may be bigger than the +image, and this area is left unchanged. + +void draw(int x, int y) + +\par +Draws the image with the upper-left corner at <tt>x,y</tt>. +This is the same as doing draw(x,y,img->w(),img->h(),0,0). + +<A NAME="offscreen"></A> <!-- For old HTML links only ! --> +\subsection ssect_Offscreen Offscreen Drawing + +Sometimes it can be very useful to generate a complex drawing +in memory first and copy it to the screen at a later point in +time. This technique can significantly reduce the amount of +repeated drawing. Fl_Double_Window uses offscreen rendering +to avoid flickering on systems that don't support +double-buffering natively. + +<A NAME="fl_create_offscreen"></A> <!-- For old HTML links only ! --> +Fl_Offscreen fl_create_offscreen(int w, int h) + +\par +Create an RGB offscreen buffer with <tt>w*h</tt> pixels. + +<A NAME="fl_delete_offscreen"></A> <!-- For old HTML links only ! --> +void fl_delete_offscreen(Fl_Offscreen) + +\par +Delete a previously created offscreen buffer. All drawings are lost. + +<A NAME="fl_begin_offscreen"></A> <!-- For old HTML links only ! --> +void fl_begin_offscreen(Fl_Offscreen) + +\par +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. + +<A NAME="fl_end_offscreen"></A> <!-- For old HTML links only ! --> +void fl_end_offscreen() + +\par +Quit sending drawing commands to this offscreen buffer. + +<A NAME="fl_copy_offscreen"></A> <!-- For old HTML links only ! --> +void fl_copy_offscreen(int x, int y, int w, int h, +Fl_Offscreen osrc, int srcx, int srcy) + +\par +Copy a rectangular area of the size <tt>w*h</tt> from <tt>srcx, srcy</tt> +in the offscreen buffer into the current buffer at <tt>x, y</tt>. + +\htmlonly +<hr> +<a class="el" href="index.html">[Index]</a> +<a class="el" href="editor.html">[Previous] 4 - Designing a Simple Text Editor</a> +<a class="el" href="events.html">[Next] 6 - Handling Events</a> +\endhtmlonly +*/ |