Fl_Surface_Device Class Reference

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? More...
virtual void	set_current (void)
	Make this surface the current drawing surface. More...
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. More...
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. More...
static Fl_Surface_Device *	surface ()
	The current drawing surface. More...

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. More...
	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:

1. Create surface, an object from an Fl_Surface_Device derived class (e.g., Fl_Image_Surface, Fl_Printer, Fl_Copy_Surface).
2. 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 / Fl_PDF_File_Surface because it is done by Fl_Paged_Device::begin_page()).
3. 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. It's also possible to draw to the current surface any widget with Fl_Widget_Surface::draw(Fl_Widget*, int, int), a window and its titlebar with Fl_Widget_Surface::draw_decorated_window(), or the content of a rectangular zone of a window with Fl_Widget_Surface::print_window_part().
4. 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 / Fl_PDF_File_Surface).
5. 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.

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, Fl_PDF_File_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.

Since 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 is 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() and Fl_Surface_Device::pop_current().

Reimplemented in Fl_Copy_Surface, Fl_Image_Surface, Fl_PDF_File_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