FLTK 1.4.4: Fl_Printer Class Reference

FLTK 1.4.4

Loading...
Searching...
No Matches
Fl_Printer Class Reference

OS-independent print support. More...

`#include <Fl_Printer.H>`

Inheritance diagram for Fl_Printer:

## Public Member Functions
int | begin_job (int pagecount=0, int *frompage=NULL, int *topage=NULL, char **perr_message=NULL) FL_OVERRIDE
| Begins a print job.
int | begin_page (void) FL_OVERRIDE
| Begins a new printed page.
void | end_job (void) FL_OVERRIDE
| To be called at the end of a print job.
int | end_page (void) FL_OVERRIDE
| To be called at the end of each page.
| Fl_Printer (void)
| The constructor.
bool | is_current () FL_OVERRIDE
| Is this surface the current drawing surface?
void | margins (int *left, int *top, int *right, int *bottom) FL_OVERRIDE
| Computes the dimensions of margins that lie between the printable page area and the full page.
void | origin (int *x, int *y) FL_OVERRIDE
| Computes the coordinates of the current origin of graphics functions.
void | origin (int x, int y) FL_OVERRIDE
| Sets the position of the origin of graphics in the drawable part of the drawing surface.
int | printable_rect (int *w, int *h) FL_OVERRIDE
| Computes the width and height of the drawable area of the drawing surface.
void | rotate (float angle) FL_OVERRIDE
| Rotates the graphics operations relatively to paper.
void | scale (float scale_x, float scale_y=0.) FL_OVERRIDE
| Changes the scaling of page coordinates.
void | set_current (void) FL_OVERRIDE
| Make this surface the current drawing surface.
void | translate (int x, int y) FL_OVERRIDE
| Translates the current graphics origin accounting for the current rotation.
void | untranslate (void) FL_OVERRIDE
| Undoes the effect of a previous translate() call.
| ~Fl_Printer (void)
| The destructor.
Public Member Functions inherited from Fl_Paged_Device
void | print_widget (Fl_Widget *widget, int delta_x=0, int delta_y=0)
| Synonym of draw(Fl_Widget*, int, int).
void | print_window (Fl_Window *win, int x_off=0, int y_off=0)
| Synonym of draw_decorated_window(Fl_Window*, int, int).
int | start_job (int pagecount=0, int *frompage=NULL, int *topage=NULL, char **perr_message=NULL)
| Synonym of begin_job(int pagecount, int *frompage, int *topage, char **perr_message).
int | start_page ()
| Synonym of begin_page().
virtual | ~Fl_Paged_Device ()
| The destructor.
Public Member Functions inherited from Fl_Widget_Surface
void | draw (Fl_Widget *widget, int delta_x=0, int delta_y=0)
| Draws the widget on the drawing surface.
void | draw_decorated_window (Fl_Window *win, int x_offset=0, int y_offset=0)
| Draws a window with its title bar and frame if any.
void | print_window_part (Fl_Window *win, int x, int y, int w, int h, int delta_x=0, int delta_y=0)
| Draws a rectangular part of an on-screen window.
Public Member Functions inherited from Fl_Surface_Device
Fl_Graphics_Driver * | driver ()
| Returns the graphics driver of this drawing surface.
virtual | ~Fl_Surface_Device ()
| The destructor.

## Static Public Attributes
These attributes are useful for the Linux/Unix platform only.
static const char * | dialog_title = "Print"
| [this text may be customized at run-time]
static const char * | dialog_printer = "Printer:"
| [this text may be customized at run-time]
static const char * | dialog_range = "Print Range"
| [this text may be customized at run-time]
static const char * | dialog_copies = "Copies"
| [this text may be customized at run-time]
static const char * | dialog_all = "All"
| [this text may be customized at run-time]
static const char * | dialog_pages = "Pages"
| [this text may be customized at run-time]
static const char * | dialog_from = "From:"
| [this text may be customized at run-time]
static const char * | dialog_to = "To:"
| [this text may be customized at run-time]
static const char * | dialog_properties = "Properties..."
| [this text may be customized at run-time]
static const char * | dialog_copyNo = "# Copies:"
| [this text may be customized at run-time]
static const char * | dialog_print_button = "Print"
| [this text may be customized at run-time]
static const char * | dialog_cancel_button = "Cancel"
| [this text may be customized at run-time]
static const char * | dialog_print_to_file = "Print To File"
| [this text may be customized at run-time]
static const char * | property_title = "Printer Properties"
| [this text may be customized at run-time]
static const char * | property_pagesize = "Page Size:"
| [this text may be customized at run-time]
static const char * | property_mode = "Output Mode:"
| [this text may be customized at run-time]
static const char * | property_use = "Use"
| [this text may be customized at run-time]
static const char * | property_save = "Save"
| [this text may be customized at run-time]
static const char * | property_cancel = "Cancel"
| [this text may be customized at run-time]
Static Public Attributes inherited from Fl_Paged_Device
static const page_format | page_formats [NO_PAGE_FORMATS]
| width, height and name of all elements of the enum Page_Format.

## Additional Inherited Members
Public Types inherited from Fl_Paged_Device
enum | Page_Format { A0 = 0 , A1 , A2 , A3 , A4 , A5 , A6 , A7 , A8 , A9 , B0 , B1 , B2 , B3 , B4 , B5 , B6 , B7 , B8 , B9 , B10 , C5E , DLE , EXECUTIVE , FOLIO , LEDGER , LEGAL , LETTER , TABLOID , ENVELOPE , MEDIA = 0x1000 }
| Possible page formats. More...
enum | Page_Layout { PORTRAIT = 0 , LANDSCAPE = 0x100 , REVERSED = 0x200 , ORIENTATION = 0x300 }
| Possible page layouts. More...
Static Public Member Functions inherited from Fl_Surface_Device
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 inherited from Fl_Paged_Device
| Fl_Paged_Device ()
| The constructor.
Protected Member Functions inherited from Fl_Widget_Surface
| Fl_Widget_Surface (Fl_Graphics_Driver *d)
| The constructor.
Protected Member Functions inherited from Fl_Surface_Device
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.
Protected Attributes inherited from Fl_Widget_Surface
int | x_offset
| horizontal offset to the origin of graphics coordinates
int | y_offset
| vertical offset to the origin of graphics coordinates

## Detailed Description

OS-independent print support.

Fl_Printer allows to use all drawing, color, text, image, and clip FLTK functions, and to have them operate on printed page(s). There are two main, non exclusive, ways to use it.

- Print any widget (standard, custom, Fl_Window, Fl_Gl_Window) as it appears on screen, with optional translation, scaling and rotation. This is done by calling print_widget(), print_window() or print_window_part().
- Use a series of FLTK graphics commands (e.g., font, text, lines, colors, clip, image) to compose a page appropriately shaped for printing.

In both cases, begin by begin_job(), begin_page(), printable_rect() and origin() calls and finish by end_page() and end_job() calls.

Example of use: print a widget centered in a page

#include <FL/Fl_Printer.H>
#include <FL/fl_draw.H>
int width, height;
Fl_Widget *widget = ... // a widget we want printed
Fl_Printer *printer = new Fl_Printer();
if (printer->begin_job(1) == 0) {
printer->begin_page();
printer->printable_rect(&width, &height);
fl_color(FL_BLACK);
fl_line_style(FL_SOLID, 2);
fl_rect(0, 0, width, height);
fl_font(FL_COURIER, 12);
time_t now; time(&now); fl_draw(ctime(&now), 0, fl_height());
printer->origin(width/2, height/2);
printer->print_widget(widget, -widget->w()/2, -widget->h()/2);
printer->end_page();
printer->end_job();
}
delete printer;
FL_COURIER
const Fl_Font FL_COURIER
Courier normal.
Definition Enumerations.H:1069
Fl_Printer.H
declaration of class Fl_Printer.
Fl_Printer::Fl_Printer
Fl_Printer(void)
The constructor.
Definition Fl_Printer.cxx:152
Fl_Widget
Fl_Widget is the base class for all widgets in FLTK.
Definition Fl_Widget.H:112
Fl_Widget::w
void w(int v)
Internal use only.
Definition Fl_Widget.H:154
Fl_Widget::h
void h(int v)
Internal use only.
Definition Fl_Widget.H:156
fl_draw.H
utility header to pull drawing functions together
fl_height
int fl_height()
Return the recommended minimum line spacing for the current font.
Definition fl_draw.H:827
fl_font
Fl_Font fl_font()
Return the face set by the most recent call to fl_font().
Definition fl_draw.H:811
fl_color
Fl_Color fl_color()
Return the last fl_color() that was set.
Definition fl_draw.H:74
fl_draw
void fl_draw(const char *str, int x, int y)
Draw a nul-terminated UTF-8 string starting at the given x, y location.
Definition fl_font.cxx:32
fl_rect
void fl_rect(int x, int y, int w, int h)
Draw a border inside the given bounding box.
Definition fl_draw.H:298
fl_line_style
void fl_line_style(int style, int width=0, char *dashes=0)
Set how to draw lines (the "pen").
Definition fl_draw.H:252
FL_SOLID
@ FL_SOLID
line style: solid line
Definition fl_draw.H:262

Recommended method to refresh GUI while printing :

printer->begin_job(0);
……
Fl_Surface_Device::push_current(Fl_Display_Device::display_device());
Fl::check(); // or any operation that draws to display
Fl_Surface_Device::pop_current();
……
printer->end_job();
Fl_Display_Device::display_device
static Fl_Display_Device * display_device()
Returns a pointer to the unique display device.
Definition Fl_Device.cxx:119
Fl_Surface_Device::pop_current
static Fl_Surface_Device * pop_current()
Removes the top element from the current drawing surface stack, and makes the new top element current...
Definition Fl_Device.cxx:154
Fl_Surface_Device::push_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.
Definition Fl_Device.cxx:140
Fl::check
static int check()
Same as Fl::wait(0).
Definition Fl.cxx:694

Platform specifics

- X11 and Wayland platforms:
  - FLTK expresses all graphics data using (Level 2) PostScript and sends that to the selected printer. See class Fl_PostScript_File_Device for a description of how text and transparent images appear in print.
  - If the GTK library is available at run-time, class Fl_Printer runs GTK's printer dialog which allows to set printer, paper size and orientation.
  - If the GTK library is not available, or if Fl::option(Fl::OPTION_PRINTER_USES_GTK) has been turned off, class Fl_Printer runs FLTK's print dialog.
    - Unless it has been previously changed, the default paper size is A4. To change that, press the "Properties" button of the "Print" dialog window opened by an Fl_Printer::begin_job() call. This opens a "Printer Properties" window where it's possible to select the adequate paper size. Finally press the "Save" button therein to assign the chosen paper size to the chosen printer for this and all further print operations.
    - Use the static public attributes of this class to set the print dialog to other languages than English. For example, the "Printer:" dialog item Fl_Printer::dialog_printer can be set to French with:
      Fl_Printer::dialog_printer = "Imprimante:";
      Fl_Printer::dialog_printer
      static const char * dialog_printer
      [this text may be customized at run-time]
      Definition Fl_Printer.H:128
      before creation of the Fl_Printer object.
    - Use Fl_PostScript_File_Device::file_chooser_title to customize the title of the file chooser dialog that opens when using the "Print To File" option of the print dialog.
- Windows platform: Transparent Fl_RGB_Image 's don't print with exact transparency on most printers (a workaround is to use print_window_part() ). Fl_RGB_Image 's don't rotate() well.
- Mac OS X platform: all graphics requests print as on display and accept rotation and scaling.

## Member Function Documentation

## ◆ begin_job()

int Fl_Printer::begin_job | ( | int | pagecount = 0,
|  | int * | frompage = NULL,
|  | int * | topage = NULL,
|  | char ** | perr_message = NULL )
| virtual

Begins a print job.

Parameters

  [in] | pagecount | the total number of pages of the job (or 0 if you don't know the number of pages)
  [out] | frompage | if non-null, *frompage is set to the first page the user wants printed
  [out] | topage | if non-null, *topage is set to the last page the user wants printed
  [out] | perr_message | if non-null and if the returned value is ≥ 2, *perr_message is set to a string describing the error. That string can be delete[]'d after use.

Returns
  0 if OK, 1 if user cancelled the job, ≥ 2 if any error.

Reimplemented from Fl_Paged_Device.

## ◆ begin_page()

int Fl_Printer::begin_page | ( | void |  | ) |
| virtual

Begins a new printed page.

The page coordinates are initially in points, i.e., 1/72 inch, and with origin at the top left of the printable page area. This function also makes this surface the current drawing surface with Fl_Surface_Device::push_current().

Note
  begin_page() calls Fl_Surface_Device::push_current() and leaves this device as the active surface. If any calls between begin_page() and end_page() open dialog boxes or will otherwise draw into FLTK windows, those calls must be put between a call to Fl_Surface_Device::pop_current() and a call to Fl_Surface_Device::push_current(), or the content of the dialog box will be rendered to the printer instead of the screen.

Returns
  0 if OK, non-zero if any error

Reimplemented from Fl_Paged_Device.

## ◆ end_job()

void Fl_Printer::end_job | ( | void |  | ) |
| virtual

To be called at the end of a print job.

Reimplemented from Fl_Paged_Device.

## ◆ end_page()

int Fl_Printer::end_page | ( | void |  | ) |
| virtual

To be called at the end of each page.

This function also stops this surface from being the current drawing surface with Fl_Surface_Device::pop_current().

Note
  end_page() calls Fl_Surface_Device::pop_current(). If any calls between begin_page() and end_page() open dialog boxes or will otherwise draw into FLTK windows, those calls must be put between a call to Fl_Surface_Device::pop_current() and a call to Fl_Surface_Device::push_current().

Returns
  0 if OK, non-zero if any error.

Reimplemented from Fl_Paged_Device.

## ◆ is_current()

bool Fl_Printer::is_current | ( |  | ) |
| virtual

Is this surface the current drawing surface?

Reimplemented from Fl_Surface_Device.

## ◆ margins()

void Fl_Printer::margins | ( | int * | left,
|  | int * | top,
|  | int * | right,
|  | int * | bottom )
| virtual

Computes the dimensions of margins that lie between the printable page area and the full page.

Values are in the same unit as that used by FLTK drawing functions. They are changed by scale() calls.

Parameters

  [out] | left | If non-null, *left is set to the left margin size.
  [out] | top | If non-null, *top is set to the top margin size.
  [out] | right | If non-null, *right is set to the right margin size.
  [out] | bottom | If non-null, *bottom is set to the bottom margin size.

Reimplemented from Fl_Paged_Device.

## ◆ origin() [1/2]

void Fl_Printer::origin | ( | int * | x,
|  | int * | y )
| virtual

Computes the coordinates of the current origin of graphics functions.

Parameters

  [out] | x,y | If non-null, *x and *y are set to the horizontal and vertical coordinates of the graphics origin.

Reimplemented from Fl_Widget_Surface.

## ◆ origin() [2/2]

void Fl_Printer::origin | ( | int | x,
|  | int | y )
| virtual

Sets the position of the origin of graphics in the drawable part of the drawing surface.

Arguments should be expressed relatively to the result of a previous printable_rect() call. That is, printable_rect(&w, &h); origin(w/2, 0); sets the graphics origin at the top center of the drawable area. Successive origin() calls don't combine their effects. Origin() calls are not affected by rotate() calls (for classes derived from Fl_Paged_Device).

Parameters

  [in] | x,y | Horizontal and vertical positions in the drawing surface of the desired origin of graphics.

Reimplemented from Fl_Widget_Surface.

## ◆ printable_rect()

int Fl_Printer::printable_rect | ( | int * | w,
|  | int * | h )
| virtual

Computes the width and height of the drawable area of the drawing surface.

Values are in the same unit as that used by FLTK drawing functions and are unchanged by calls to origin(). If the object is derived from class Fl_Paged_Device, values account for the user-selected paper type and print orientation and are changed by scale() calls.

Returns
  0 if OK, non-zero if any error

Reimplemented from Fl_Widget_Surface.

## ◆ rotate()

void Fl_Printer::rotate | ( | float | angle | ) |
| virtual

Rotates the graphics operations relatively to paper.

The rotation is centered on the current graphics origin. Successive rotate() calls don't combine their effects.

Parameters

  angle | Rotation angle in counter-clockwise degrees.

Reimplemented from Fl_Paged_Device.

## ◆ scale()

void Fl_Printer::scale | ( | float | scale_x,
|  | float | scale_y = 0. )
| virtual

Changes the scaling of page coordinates.

This function also resets the origin of graphics functions at top left of printable page area. After a scale() call, do a printable_rect() call to get the new dimensions of the printable page area. Successive scale() calls don't combine their effects.

Parameters

  scale_x | Horizontal dimensions of plot are multiplied by this quantity.
  scale_y | Same as above, vertically. The value 0. is equivalent to setting `scale_y` = `scale_x`. Thus, scale(factor); is equivalent to scale(factor, factor);

Reimplemented from Fl_Paged_Device.

## ◆ set_current()

void Fl_Printer::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 from Fl_Surface_Device.

## ◆ translate()

void Fl_Printer::translate | ( | int | x,
|  | int | y )
| virtual

Translates the current graphics origin accounting for the current rotation.

Each translate() call must be matched by an untranslate() call. Successive translate() calls add up their effects.

Reimplemented from Fl_Widget_Surface.

## ◆ untranslate()

void Fl_Printer::untranslate | ( | void |  | ) |
| virtual

Undoes the effect of a previous translate() call.

Reimplemented from Fl_Widget_Surface.

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

- Fl_Printer.H
- Fl_Printer.cxx