diff --git a/documentation/make_pdf b/documentation/make_pdf index 7580cb1d8..a5487bae4 100755 --- a/documentation/make_pdf +++ b/documentation/make_pdf @@ -2,7 +2,7 @@ # # Makefile helper script for the Fast Light Tool Kit (FLTK) documentation. # -# Copyright 1998-2015 by Bill Spitzak and others. +# Copyright 1998-2020 by Bill Spitzak and others. # # This library is free software. Distribution and use rights are outlined in # the file "COPYING" which should have been included with this file. If this diff --git a/documentation/src/common.dox b/documentation/src/common.dox index 4f7a59011..96880b661 100644 --- a/documentation/src/common.dox +++ b/documentation/src/common.dox @@ -441,7 +441,7 @@ image that is shown when the widget is inactive, while the \p image() method sets the image that is shown when the widget is active. To make an image you use a subclass of -\ref ssect_Fl_Image "Fl_Image". +\ref drawing_Fl_Image "Fl_Image". \par Making Your Own Label Types @@ -509,7 +509,7 @@ any label. To create a new symbol, you implement a drawing function void drawit(Fl_Color c) which typically uses the -functions described in \ref ssect_Complex +functions described in \ref drawing_complex to generate a vector shape inside a two-by-two units sized box around the origin. This function is then linked into the symbols table using fl_add_symbol(): diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox index 3ec17d6c0..847647800 100644 --- a/documentation/src/drawing.dox +++ b/documentation/src/drawing.dox @@ -4,7 +4,7 @@ This chapter covers the drawing functions that are provided with FLTK. -\section sect_WhenCanYouDraw When Can You Draw Things in FLTK? +\section drawing_WhenCanYouDraw When Can You Draw Things in FLTK? There are only certain places you can execute FLTK code that draws to the computer's display. @@ -35,20 +35,20 @@ these will operate on the new current drawing surface; Fl_Surface_Device::pop_current(). -\subsection ssect_DrawingUnit What Drawing Unit do FLTK drawing functions use? +\section drawing_DrawingUnit What Drawing Units Do FLTK Drawing Functions Use? -Before version 1.4, all graphical quantities used by FLTK are in pixel units: -a window of width 500 units is 500-pixel wide, a line of length 10 units is -10-pixel long, lines of text written using a 14-point font are 14 pixels below -each other. This organization is not sufficient to support GUI apps that can be drawn on -screens of varying pixel density, especially on High-DPI screens, because +Before version 1.4 all graphical quantities used by FLTK were in pixel units: +a window of width 500 units was 500 pixels wide, a line of length 10 units was +10 pixels long, lines of text written using a 14-point font were 14 pixels below +each other. This organization is not sufficient to support GUI apps that can be +drawn on screens of varying pixel density, especially on High-DPI screens, because widgets become very small and text becomes unreadable. FLTK version 1.4 introduces a new feature, a screen-specific scale factor which is a float number with a typical value in the 1-2.5 range and is used as follows: any graphical element with an FLTK value of \e v units is drawn on the screen with \e v * \e scale units. -Thus, a window with width 500 units is 500*scale-pixel wide, a line of length 10 units is -10*scale-pixel long, lines of text written using a 14-point font are 14*scale pixels below +Thus, a window with width 500 units is 500*scale pixels wide, a line of length 10 units is +10*scale pixels long, lines of text written using a 14-point font are 14*scale pixels below each other. Consider a system with two screens, one with regular DPI and one with a twice higher DPI. If the first screen's scale factor is set to 1 and that of the second screen to 2, the GUI of any FLTK app appears equally sized on the two screens. @@ -60,12 +60,14 @@ clipping regions) are in FLTK units which are both system- and DPI-indepe expressed in FLTK units by the current value of the scale factor for the screen in use and obtains quantities in drawing units. The current scale factor value, for an Fl_Window named \e window, is given by + \code -int nscreen = window->screen_num(); // the screen where window is mapped -float s = Fl::screen_scale(nscreen); // this screen's scale factor + int nscreen = window->screen_num(); // the screen where window is mapped + float s = Fl::screen_scale(nscreen); // this screen's scale factor \endcode -One drawing unit generally corresponds to one screen pixel... -
  • ...but not on Mac OS X and for retina displays, where one drawing unit corresponds + +One drawing unit generally corresponds to one screen pixel ... +
  • ... but not on macOS and for retina displays, where one drawing unit corresponds to two pixels. @@ -79,7 +81,7 @@ it's possible to set the it's possible to change the scale factor value of any screen at run time with ctrl/+/-/0/ keystrokes which enlarge, shrink, and reset, respectively, all FLTK windows on a screen and their content. -Under Mac OS X, the corresponding GUI scaling shortcuts are ⌘/+/-/0/. +Under macOS, the corresponding GUI scaling shortcuts are ⌘/+/-/0/. GUI rescaling involves also image drawing: the screen area covered by the drawn image contains a number of pixels that grows with the scale factor. When FLTK draws images, @@ -107,28 +109,28 @@ When drawing to Fl_Printer or Fl_PostScript_File_Device, the drawing unit is initially one point, that is, 1/72 of an inch. This unit is changed by calls to Fl_Paged_Device::scale(). -\section sect_DrawingFunctions Drawing Functions +\section drawing_DrawingFunctions Drawing Functions To use the drawing functions you must first include the header file. FLTK provides the following types of drawing functions: -\li \ref ssect_Boxes -\li \ref ssect_Clipping +\li \ref drawing_boxes +\li \ref drawing_clipping \li \ref drawing_colors -\li \ref ssect_Lines -\li \ref ssect_Fast -\li \ref ssect_Complex -\li \ref ssect_Text -\li \ref ssect_Fonts -\li \ref ssect_CharacterEncoding -\li \ref ssect_Overlay +\li \ref drawing_lines +\li \ref drawing_fast +\li \ref drawing_complex +\li \ref drawing_text +\li \ref drawing_fonts +\li \ref drawing_character_encoding +\li \ref drawing_overlay \li \ref drawing_images -\li \ref ssect_DirectImageDrawing -\li \ref ssect_DirectImageReading -\li \ref ssect_Fl_Image -\li \ref ssect_Offscreen +\li \ref drawing_direct_image_drawing +\li \ref drawing_direct_image_reading +\li \ref drawing_Fl_Image +\li \ref drawing_offscreen -\subsection ssect_Boxes Boxes +\subsection drawing_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 @@ -166,12 +168,12 @@ Note that is described in the \ref common_boxtypes section. -\subsection ssect_Clipping Clipping +\subsection drawing_clipping Clipping You can limit all your drawing to a rectangular region by calling \p %fl_push_clip(), and put the drawings back by using \p %fl_pop_clip(). -This rectangle is measured in \ref ssect_DrawingUnit "FLTK units" and is unaffected by the current +This rectangle is measured in \ref drawing_DrawingUnit "FLTK units" and is unaffected by the current transformation matrix. In addition, the system may provide clipping when updating windows @@ -235,7 +237,7 @@ Fl_Region is an operating system specific type. The second form returns the current clipping region. -\section drawing_colors Colors +\subsection drawing_colors Colors FLTK manages colors as 32-bit unsigned integers, encoded as RGBI. When the "RGB" bytes are non-zero, the value is treated as RGB. @@ -362,7 +364,7 @@ button->color(0xffffff00); // RGB: white If TrueColor is not available, any RGB colors will be set to the nearest entry in the colormap. -\subsection ssect_Lines Line Dashes and Thickness +\subsection drawing_lines Line Dashes and Thickness FLTK supports drawing of lines with different styles and widths. Full functionality is not available under Windows 95, 98, @@ -403,13 +405,13 @@ system-defined default of whatever value is fastest. \li FL_JOIN_BEVEL (flat) \par -\p width is the number of \ref ssect_DrawingUnit "FLTK units" thick to draw the lines. +\p width is the number of \ref drawing_DrawingUnit "FLTK units" 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. \par \p dashes is a pointer to an array of dash lengths, measured in -\ref ssect_DrawingUnit "FLTK units". The first location is how long to draw a solid portion, the +\ref drawing_DrawingUnit "FLTK units". 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 \p NULL pointer or a zero-length array results in a solid line. Odd array sizes are not supported and @@ -421,13 +423,13 @@ The dashes array does not work under Windows 95, 98, or Me, since those operating systems do not support complex line styles. -\subsection ssect_Fast Drawing Fast Shapes +\subsection drawing_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 -\ref ssect_Complex "transformation matrix", +\ref drawing_complex "transformation matrix", so you should only call these while the matrix is set to the identity matrix (the default). @@ -530,11 +532,11 @@ void \ref fl_scroll(int X, int Y, int W, int H, int dx, int dy, void (*draw_area \par Scroll a rectangle and draw the newly exposed portions. The contents of the rectangular area is first shifted by \p dx and -\p dy \ref ssect_DrawingUnit "FLTK units". The callback is then called for every newly +\p dy \ref drawing_DrawingUnit "FLTK units". The callback is then called for every newly exposed rectangular area, -\subsection ssect_Complex Drawing Complex Shapes +\subsection drawing_complex Drawing Complex Shapes The complex drawing functions let you draw arbitrary shapes with 2-D linear transformations. The functionality matches that @@ -669,7 +671,7 @@ a circle as part of a complex polygon you must use \p %fl_arc(). \p %fl_circle() draws incorrectly if the transformation is both rotated and non-square scaled. -\subsection ssect_Text Drawing Text +\subsection drawing_text Drawing Text All text is drawn in the \ref drawing_fl_font "current font". @@ -767,7 +769,7 @@ Determines the minimum dimensions of a nul-terminated string, ie. the 'inked area'. \par Given a string "txt" drawn using fl_draw(txt, x, y) you would determine -its extents in \ref ssect_DrawingUnit "FLTK units" on the display using fl_text_extents(txt, dx, dy, wo, ho) +its extents in \ref drawing_DrawingUnit "FLTK units" on the display using fl_text_extents(txt, dx, dy, wo, ho) such that a bounding box that exactly fits around the inked area of the text could be drawn with fl_rect(x+dx, y+dy, wo, ho). \par @@ -786,7 +788,7 @@ 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. -\subsection ssect_Fonts Fonts +\subsection drawing_fonts Fonts FLTK supports a set of standard fonts based on the Times, Helvetica/Arial, Courier, and Symbol typefaces, as well as @@ -821,7 +823,7 @@ the display. \par The font is identified by a \p face and a \p size. -The size of the font is measured in \ref ssect_DrawingUnit "FLTK units" and not "points". +The size of the font is measured in \ref drawing_DrawingUnit "FLTK units" and not "points". Lines should be spaced \p size FLTK units apart or more. int fl_font()
    @@ -831,7 +833,7 @@ int fl_size() Returns the face and size set by the most recent call to \p fl_font(a,b). This can be used to save/restore the font. -\subsection ssect_CharacterEncoding Character Encoding +\subsection drawing_character_encoding Character Encoding FLTK 1.3 expects all text in Unicode UTF-8 encoding. UTF-8 is ASCII compatible for the first 128 characters. International @@ -855,7 +857,7 @@ left-to-right scripts only. For more information about character encodings, see the chapter on \ref unicode. -\subsection ssect_Overlay Drawing Overlays +\subsection drawing_overlay Drawing Overlays These functions allow you to draw interactive selection rectangles without using the overlay hardware. FLTK will XOR a single rectangle @@ -890,7 +892,7 @@ 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 \e much faster. -\subsection ssect_DirectImageDrawing Direct Image Drawing +\subsection drawing_direct_image_drawing Direct Image Drawing The behavior when drawing images when the current transformation matrix is not the identity is not defined, so you @@ -1010,7 +1012,7 @@ 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 +\subsection drawing_direct_image_reading Direct Image Reading FLTK provides a single function for reading from the current window or off-screen buffer into a RGB(A) image buffer. @@ -1030,7 +1032,7 @@ The \p 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. -\subsection ssect_Fl_Image Image Classes +\subsection drawing_Fl_Image Image Classes FLTK provides a base image class called Fl_Image which supports creating, copying, and drawing images of various kinds, along @@ -1124,21 +1126,47 @@ Draws the image with the upper-left corner at x, y. This is the same as doing img->draw(x, y, img->w(), img->h(), 0, 0) where img is a pointer to any Fl_Image type. -\subsection ssect_Offscreen Offscreen Drawing +\section drawing_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. Offscreen drawing functions are declared in . -Fl_Double_Window uses offscreen rendering to avoid flickering on -systems that don't support double-buffering natively. +Fl_Double_Window uses offscreen rendering to avoid flickering on systems +that don't support double-buffering natively. + +FLTK can draw into an offscreen buffer at any time. There is no need to +wait for an Fl_Widget::draw() to occur. + +\note In FLTK 1.3.x and earlier versions all offscreen drawing functions +described below were implemented as macros and created certain temporary +variables to save context information. You needed to create local scope +blocks with curly braces { ... } if you used offscreen functions more than +once in a function or method. This is no longer necessary since offscreen +drawing is now implemented in real functions (no macros). + +Example: +\code + Fl_Offscreen oscr = fl_create_offscreen(120, 120); + fl_begin_offscreen(oscr); + fl_color(FL_WHITE); + fl_rectf(0, 0, 120, 120); + fl_end_offscreen(); + // other code here + fl_begin_offscreen(oscr); + fl_color(FL_BLACK); + fl_rectf(10, 10, 100, 100); + fl_end_offscreen(); + // other code here + fl_delete_offscreen(oscr); +\endcode Fl_Offscreen fl_create_offscreen(int w, int h) \par Create an RGB offscreen buffer containing as many pixels as in a screen area -of size \p w,h \ref ssect_DrawingUnit "FLTK units". +of size \p w,h \ref drawing_DrawingUnit "FLTK units". void fl_delete_offscreen(Fl_Offscreen) @@ -1149,8 +1177,6 @@ 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. void fl_end_offscreen() diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox index 9d727d87a..793b9834e 100644 --- a/documentation/src/opengl.dox +++ b/documentation/src/opengl.dox @@ -283,7 +283,7 @@ void gl_font(Fl_Font fontid, int size) \par Sets the current OpenGL font to the same font you get by calling -\ref ssect_Fonts "fl_font()". +\ref drawing_fonts "fl_font()". int gl_height()
    int gl_descent()
    @@ -317,7 +317,7 @@ void gl_draw(const char *s, int x, int y, int w, int h, Fl_Align) Draws a string formatted into a box, with newlines and tabs expanded, other control characters changed to ^X, and aligned with the edges or center. Exactly the same output as -\ref ssect_Text "fl_draw()". +\ref drawing_text "fl_draw()". \section opengl_speed Speeding up OpenGL diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox index d629acfab..069d7975a 100644 --- a/documentation/src/osissues.dox +++ b/documentation/src/osissues.dox @@ -162,10 +162,10 @@ extern XFontStruct *fl_xfont \par Points to the font selected by the most recent -\ref ssect_Fonts "fl_font()". +\ref drawing_fonts "fl_font()". This is not necessarily the current font of \c fl_gc, which is not set until -\ref ssect_Text "fl_draw()" +\ref drawing_text "fl_draw()" is called. If FLTK was compiled with Xft support, \c fl_xfont will usually be 0 and \c fl_xftfont will contain a pointer to the \c XftFont structure instead. @@ -175,7 +175,7 @@ extern void *fl_xftfont \par If FLTK was compiled with Xft support enabled, \c fl_xftfont points to the xft font selected by the most recent -\ref ssect_Fonts "fl_font()". +\ref drawing_fonts "fl_font()". Otherwise it will be 0. \c fl_xftfont should be cast to XftFont*. diff --git a/documentation/src/subclassing.dox b/documentation/src/subclassing.dox index f2a41472e..483473181 100644 --- a/documentation/src/subclassing.dox +++ b/documentation/src/subclassing.dox @@ -330,7 +330,7 @@ be redrawn, e.g. for an expose event. Expose events (and the \ref subclassing_damage "damage(mask,x,y,w,h)" function described above) will cause \p draw() to be called with FLTK's -\ref ssect_Clipping "clipping" +\ref drawing_clipping "clipping" turned on. You can greatly speed up redrawing in some cases by testing \p fl_not_clipped(x,y,w,h) or \p %fl_clip_box() and skipping invisible parts.