FLTK 1.4.5: Fl_Surface_Device Class Reference

FLTK 1.4.5

Loading...
Searching...
No Matches
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?
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:

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()

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