A drawing surface that's susceptible to receive graphical output. More...

#include <Fl_Device.H>

Inheritance diagram for Fl_Surface_Device:

Public Member Functions
Fl_Graphics_Driver *	driver ()
	Returns the graphics driver of this drawing surface.

virtual bool	is_current ()
	Is this surface the current drawing surface?

virtual void	set_current (void)
	Make this surface the current drawing surface.

virtual	~Fl_Surface_Device ()
	The destructor.

Static Public Member Functions
static Fl_Surface_Device *	pop_current ()
	Removes the top element from the current drawing surface stack, and makes the new top element current.

static void	push_current (Fl_Surface_Device *new_current)
	Pushes `new_current` on top of the stack of current drawing surfaces, and makes it current.

static Fl_Surface_Device *	surface ()
	The current drawing surface.

Protected Member Functions
void	driver (Fl_Graphics_Driver *graphics_driver)
	Sets the graphics driver of this drawing surface.

virtual void	end_current ()
	FLTK calls this each time a surface ceases to be the current drawing surface.

	Fl_Surface_Device (Fl_Graphics_Driver *graphics_driver)
	Constructor that sets the graphics driver to use for the created surface.

Detailed Description

A drawing surface that's susceptible to receive graphical output.

Any FLTK application has at any time a current drawing surface to which all drawing requests are directed. The current surface is given by Fl_Surface_Device::surface(). When main() begins running, the current drawing surface has been set to the computer's display, an instance of the Fl_Display_Device class.

A drawing surface other than the computer's display, is typically used as follows:

Create surface, an object from a particular Fl_Surface_Device derived class (e.g., Fl_Copy_Surface, Fl_Printer).
Call Fl_Surface_Device::push_current(surface); to redirect all graphics requests to surface which becomes the new current drawing surface (not necessary with classes Fl_Printer / Fl_PostScript_File_Device because it is done by Fl_Paged_Device::begin_page()).
At this point all of the Drawing functions (e.g., fl_rect()) or the Color & Font functions or Drawing Images functions (e.g., fl_draw_image(), Fl_Image::draw()) operate on the new current drawing surface. Drawing surfaces from Fl_Widget_Surface derived classes allow additional ways to draw to them (e.g., Fl_Printer::print_widget(), Fl_Image_Surface::draw()).
After all drawing requests have been performed, redirect graphics requests back to their previous destination with Fl_Surface_Device::pop_current(); (not necessary with classes Fl_Printer / Fl_PostScript_File_Device).
Delete surface.

For back-compatibility, it is also possible to use the Fl_Surface_Device::set_current() member function to change the current drawing surface, once to the new surface, once to the previous one.

Class Fl_Surface_Device can also be derived to define new kinds of graphical output usable with FLTK drawing functions. An example would be to draw to a PDF file. This would require to create a new class, say PDF_File_Surface, derived from class Fl_Surface_Device, and another new class, say PDF_Graphics_Driver, derived from class Fl_Graphics_Driver. Class PDF_Graphics_Driver should implement all virtual methods of the Fl_Graphics_Driver class to support all FLTK drawing functions and have them draw into PDF files. Alternatively, class PDF_Graphics_Driver could implement only some virtual methods, and only part of the FLTK drawing API would be usable when drawing to PDF files.

Member Function Documentation

◆ end_current()

virtual void Fl_Surface_Device::end_current ( )

inlineprotectedvirtual

FLTK calls this each time a surface ceases to be the current drawing surface.

This member function is mostly of interest to developers of new Fl_Surface_Device derived classes. It allows to perform surface-specific operations necessary when this surface ceases to be current. Each implementation should end with a call to Fl_Surface_Device::end_current().

Reimplemented in Fl_PostScript_File_Device.

◆ is_current()

bool Fl_Surface_Device::is_current ( )

virtual

Is this surface the current drawing surface?

Reimplemented in Fl_Copy_Surface, Fl_Image_Surface, and Fl_Printer.

◆ pop_current()

Fl_Surface_Device * Fl_Surface_Device::pop_current ( )

static

Removes the top element from the current drawing surface stack, and makes the new top element current.

Returns: A pointer to the new current drawing surface.

See also: Fl_Surface_Device::push_current(Fl_Surface_Device *)

Version: 1.4.0

◆ push_current()

void Fl_Surface_Device::push_current ( Fl_Surface_Device * new_current )

static

Pushes new_current on top of the stack of current drawing surfaces, and makes it current.

new_current will receive all future graphics requests.

Any call to push_current() must be matched by a subsequent call to Fl_Surface_Device::pop_current(). The max height of this stack is 16.

Version: 1.4.0

◆ set_current()

void Fl_Surface_Device::set_current ( void )

virtual

Make this surface the current drawing surface.

This surface will receive all future graphics requests. Starting from FLTK 1.4.0, the preferred API to change the current drawing surface is Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().

Note

It's recommended to use this function only as follows :

The current drawing surface is the display;
make current another surface, e.g., an Fl_Printer or an Fl_Image_Surface object, calling set_current() on this object;
draw to that surface;
make the display current again with Fl_Display_Device::display_device()->set_current(); . Don't do any other call to set_current() before this one.

Other scenarios of drawing surface changes should be performed via Fl_Surface_Device::push_current( ) / Fl_Surface_Device::pop_current().

Reimplemented in Fl_Copy_Surface, Fl_Image_Surface, Fl_PostScript_File_Device, and Fl_Printer.

◆ surface()

static Fl_Surface_Device * Fl_Surface_Device::surface ( )

inlinestatic

The current drawing surface.

In other words, the Fl_Surface_Device object that currently receives all graphics requests.

Note: It's possible to transiently remove the GUI scaling factor in place in the current drawing surface with fl_override_scale().

The documentation for this class was generated from the following files:

Fl_Device.H
Fl_Device.cxx

Public Member Functions

Static Public Member Functions

Protected Member Functions