diff options
| -rw-r--r-- | FL/Fl_Device.H | 23 | ||||
| -rw-r--r-- | documentation/src/drawing.dox | 36 | ||||
| -rw-r--r-- | src/Fl_Device.cxx | 3 |
3 files changed, 47 insertions, 15 deletions
diff --git a/FL/Fl_Device.H b/FL/Fl_Device.H index df66e7a75..caece3b7c 100644 --- a/FL/Fl_Device.H +++ b/FL/Fl_Device.H @@ -101,8 +101,8 @@ public: in the \ref fl_drawings and \ref fl_attributes modules. \p The Fl_Graphics_Driver class is of interest if one wants to perform new kinds of drawing operations. - An example would be to draw to a PDF file. This would involve creating a new Fl_Graphics_Driver derived class, - say, my_PDF_Graphics_Driver. This new class should implement all virtual methods of the Fl_Graphics_Driver class + An example would be to draw to a PDF file. This would involve creating a new Fl_Graphics_Driver derived + class. This new class should implement all virtual methods of the Fl_Graphics_Driver class to support all FLTK drawing functions. */ class FL_EXPORT Fl_Graphics_Driver : public Fl_Device { @@ -534,17 +534,17 @@ public: /** \brief A drawing surface that's susceptible to receive graphical output. A drawing surface is typically used as follows: - \li Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer). - \li Memorize what is the current drawing surface with <tt> Fl_Surface_Device *old_current = Fl_Surface_Device::surface();</tt> - \li Call \c surface->set_current(); to redirect all graphics requests to \c surface which becomes the new + <ol><li> Create \c surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer). + <li> Memorize what is the current drawing surface with <tt> Fl_Surface_Device *old_current = Fl_Surface_Device::surface();</tt> + <li> Call \c surface->set_current(); to redirect all graphics requests to \c surface which becomes the new current drawing surface (not necessary with class Fl_Printer because it is done by Fl_Printer::start_job()). - \li At this point any of the \ref fl_drawings (e.g., fl_rect()) or the \ref fl_attributes or \ref drawing_images functions - (e.g., fl_draw_image(), Fl_Image::draw()) operate on the new current drawing surface. + <li> At this point any of the \ref fl_drawings (e.g., fl_rect()) or the \ref fl_attributes or \ref drawing_images functions + (e.g., fl_draw_image(), Fl_Image::draw()) operates on the new current drawing surface. Certain drawing surfaces allow additional ways to draw to them (e.g., Fl_Printer::print_widget(), Fl_Image_Surface::draw()). - \li After all drawing requests have been performed, redirect graphics requests back to their previous destination + <li> After all drawing requests have been performed, redirect graphics requests back to their previous destination with \c old_current->set_current();. - \li Delete \c surface. - + <li> Delete \c surface. + </ol> The current drawing surface is initially the computer's display, an instance of the Fl_Display_Device class. */ class FL_EXPORT Fl_Surface_Device : public Fl_Device { @@ -562,7 +562,8 @@ public: inline void driver(Fl_Graphics_Driver *graphics_driver) {_driver = graphics_driver;}; /** \brief Returns the graphics driver of this drawing surface. */ inline Fl_Graphics_Driver *driver() {return _driver; }; - /** \brief the surface that currently receives graphics output */ + /** The current drawing surface. + In other words, the Fl_Surface_Device object that currently receives all graphics output */ static inline Fl_Surface_Device *surface() {return _surface; }; /** \brief The destructor. */ virtual ~Fl_Surface_Device() {} diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox index aa513c95b..c523bd4eb 100644 --- a/documentation/src/drawing.dox +++ b/documentation/src/drawing.dox @@ -6,7 +6,8 @@ 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. +There are only certain places you can execute FLTK code +that draws to the computer's display. Calling these functions at other places will result in undefined behavior! \li The most common place is inside the virtual Fl_Widget::draw() method. @@ -21,6 +22,33 @@ Calling these functions at other places will result in undefined behavior! \li You can call Fl_Window::make_current() to do incremental update of a widget. Use Fl_Widget::window() to find the window. + +In contrast, code that draws to other drawing surfaces than the display +(i.e., instances of derived classes of the Fl_Surface_Device class, except +Fl_Display_Device, such as Fl_Printer and Fl_Copy_Surface) can be executed +at any time as follows: +<ol><li> Memorize what is the current drawing surface calling Fl_Surface_Device::surface(), +and make your surface the new current drawing surface calling the surface's +set_current() function; +<li> Make a series of calls to any of the drawing functions described below; +these will operate on the new current drawing surface; +<li> Set the current drawing surface back to its previous state calling +the previous surface's set_current(). +</ol> + +\subsection ssect_DrawingUnit What Drawing Unit do FLTK drawing functions use? + +When drawing to the display or to instances of Fl_Copy_Surface and Fl_Image_Surface, +the unit of drawing functions corresponds +generally to one pixel. The so-called 'retina' displays of some recent +Apple computers are an exception to this rule: one drawing unit corresponds +to the width or the height of 2 display pixels on a retina display. + +When drawing to surfaces that are instances of Fl_Paged_Device +derived classes (i.e., Fl_Printer or Fl_PostScript_File_Device), the drawing unit +is initially one point, that is, 1/72 of an inch. But this unit is changed +after calls to Fl_Paged_Device::scale(). + \section sect_DrawingFunctions Drawing Functions @@ -961,10 +989,12 @@ standard image types for common file formats: \li Fl_XBM_Image \li Fl_XPM_Image -Each of these image classes load a named file of the +Each of these image classes loads 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. +the file and constructs an image of the appropriate type. It can also be used +to scale an image to a certain size in drawing units, independently from its size +in pixels (see Fl_Shared_Image::scale()). Finally, FLTK provides a special image class called Fl_Tiled_Image to tile another image object in the specified area. This class can be diff --git a/src/Fl_Device.cxx b/src/Fl_Device.cxx index 0657af401..5a959f806 100644 --- a/src/Fl_Device.cxx +++ b/src/Fl_Device.cxx @@ -37,7 +37,8 @@ const char *Fl_Xlib_Graphics_Driver::class_id = "Fl_Xlib_Graphics_Driver"; #endif -/** \brief Use this drawing surface for future graphics requests. */ +/** \brief Make this surface the current drawing surface. + This surface will receive all future graphics requests. */ void Fl_Surface_Device::set_current(void) { fl_graphics_driver = _driver; |