ICS

QicsTable Documentation Set

QicsPrintPreviewWidget Class Reference

The base class for WYSIWYG printing. More...

#include <QicsPrintPreviewWidget.h>

Inherits QScrollArea.

List of all members.

Public Slots

void print ()
void printAllPages ()
void selectAll (bool yes=true)
void deselectAll ()
void enableAll (bool yes=true)
void disableAll ()
void enableSelected (bool yes=true)
void disableSelected ()
void pageCounted ()

Signals

void countPages (int *pages, QPrinter *printer)
void drawPage (QicsPrintPreviewPage *page)
void printPage (QicsPrintPreviewPage *page, QPainter *painter)
void terminateCount ()
void pagePrinting (int i, QicsPrintPreviewPage *page)
void pagePrinted (int i, QicsPrintPreviewPage *page)
void printingStarted (int totalPages)
void printingFinished ()
void printingAborted ()
void printingError ()
void updatePerformed (const PageLayoutData &opt)
void contextMenuRequest (QicsPrintPreviewPage *page, QContextMenuEvent *event)

Public Member Functions

 QicsPrintPreviewWidget (QWidget *parent, PageCountMode pcm=PCM_DYNAMIC)
QPrinter * printer () const
void updatePages (QPrinter *printer)
int pagesCount () const
void setPrintCopies (int num)
int printCopies () const
void setPrintCopyOrder (PrintCopyOrder order)
PrintCopyOrder printCopyOrder () const
void setPrintPageOrder (PrintPageOrder order)
PrintPageOrder printPageOrder () const
void setPrintPageSet (PrintPageSet set)
PrintPageSet printPageSet () const
void setPrintPageSequence (PrintPageSequence sequence)
PrintPageSequence printPageSequence () const
void setPagesToPrint (const QList< int > &numbers)
const QList< int > & pagesToPrint () const
void showPageNumbers (bool show=true)
bool isPageNumbersVisible () const
void showRulers (bool show=true)
bool isRulersVisible () const
void autoShowActivePage (bool yes=true)
bool isAutoShowActivePage () const
void enableClickZoom (bool yes=true)
bool isClickZoomEnabled () const
void ensurePageVisibleIndex (int index)
void ensurePageVisible (QicsPrintPreviewPage *page)
void setActivePageIndex (int index)
void setActivePage (QicsPrintPreviewPage *page)
QicsPrintPreviewPageactivePage () const
void setControlMode (ControlMode cm)
ControlMode controlMode () const
void setPageCountMode (PageCountMode pcm)
PageCountMode pageCountMode () const
void setPreviewOptions (const PageLayoutData &opt)
const PageLayoutDatapreviewOptions () const
void setPageOrdering (PageLayoutOrdering lo)
PageLayoutOrdering pageOrdering () const
void setScale (double percent)
double scale () const
void setPageDirection (PageLayoutDirection dir, int count=-1)
PageLayoutDirection pageDirection () const
int pagesX () const
int pagesY () const
void setPageScaling (PageLayoutScaling ls)
PageLayoutScaling pageScaling () const
void setPageCounting (PageLayoutCounting lc)
PageLayoutCounting pageCounting () const

Protected Types

 HINT_NoZoom = 1
 HINT_LayoutOnFitChanged = 2
enum  UpdateHints { HINT_NoZoom = 1, HINT_LayoutOnFitChanged = 2 }

Protected Slots

void updateXRuler (int=0)
void updateYRuler (int=0)
void doStaticUpdate ()
void doDynamicUpdate ()

Protected Member Functions

virtual void resizeEvent (QResizeEvent *event)
bool eventFilter (QObject *obj, QEvent *event)
virtual void keyPressEvent (QKeyEvent *event)
virtual void contextMenuEvent (QContextMenuEvent *event)
virtual void hideEvent (QHideEvent *event)
void doZoom ()
int doCalculateHorizontalFit ()
int doCalculateVerticalFit ()
void doCalculateHorizontalZoom ()
void doCalculateVerticalZoom ()
void doLayoutPages ()
void doDeletePages ()
void doFullUpdate (uint hint=0)
bool doPrintPage (int number, QPainter &p)
void doUpdateRulers ()

Protected Attributes

QPrinter * m_printer
QWidget * m_preview
QicsRulerm_rulerX
QicsRulerm_rulerY
QVector< QicsPrintPreviewPage * > m_pages
QicsPrintPreviewPagem_activePage
bool m_showNumbers
bool m_activePageJump
bool m_zoomOn
bool m_showRulers
PageLayoutData m_params
PageLayoutData m_storedParams
QList< int > m_pagesToPrint
int m_copies
PrintCopyOrder m_printCopyOrder
PrintPageOrder m_printPageOrder
PrintPageSet m_printPageSet
PrintPageSequence m_printPageSequence
bool m_newPage
int m_printPageIndex
ControlMode m_cm
bool m_modeState
QPoint m_modePos
PageCountMode m_pcm
bool m_updateInProgress


Detailed Description

The base class for WYSIWYG printing.

QicsPrintPreviewWidget is the core of Print Preview Framework used for WYSIWYG printing. This class allows to display a set of pages before they will be sent to printer, using several layout policies, to choose printer/paper options, to customize printing order and number of copies, and more others.

QicsPrintPreviewWidget inherits itself from QScrollArea. It holds QicsPrintPreviewPage objects each of them representing single page to preview/print. Also, it provides vertical and horizontal QicsRuler objects used as metrical rulers to view original page size in millimeters. It provides user interaction to select range of pages, quickly zoom the current page and so on.

Designing own preview

When designing own print preview dialog, QicsPrintPreviewWidget is supposed to be a main widget. It provides a couple of methods to set page layout policy, numeration, printing order and so on. Dialog's GUI elements should be responcible to get/set appropriate values from/to QicsPrintPreviewWidget. Stocks2 demo shows how to set up its own preview & printing options functionality.

QicsPrintPreviewWidget contains a QPrinter object which is used for printing and can be obtained with printer() method. To change current printer and respectively update the pages, use updatePages(QPrinter *printer) method. The typical usage is to provide the user with standard QPrintDialog/QPageSetupDialog passing printer() to its constructor, and then update pages passing QPrintDialog::printer()/QPageSetupDialogprinter() back to updatePages() when the user has changed something.

The signals countPages(), drawPage() and printPage() emitted from the widget are obligatory to handle in the program. countPages() is emitted every time when printer/paper settings were changed; the handler should count the number of pages fits current settings. There are two page count modes - static and dynamic - are used to organize page counting. Current mode can be set in the constructor or via setPageCountMode() method. In the dynamic mode, terminateCount() must be also handled. See Counting the pages topic for reference.

drawPage() and printPage() are emitted when a page should be previewed or printed accordingly; the handlers should perform actual drawing of page's content. See Painting page content topic for reference.

updatePerformed(const PageLayoutData &opt) signal is emitted every time when the page layout was updated. Handle it to provide corresponding GUI controls update.

To invoke own popup menu, handle contextMenuRequest(QicsPrintPreviewPage *page, QContextMenuEvent* event) signal. This signal is emitted accordingly to current context menu policy set for QicsPrintPreviewWidget; see QWidget::customContextMenuRequested() for reference.

Layouting capabilities

QicsPrintPreviewWidget has a wide set of options to control automatic page layouting. There are two ways in which these options could be set/retrieved: using individual methods to set every option separately (convenient while performing interaction with dialog's control elements, such as choosing the scale with combobox, and so on), or impact all the options by one call.

setPreviewOptions(const PageLayoutData &opt) method allows to set all the layout options passed as parameter; they could be obtained in the same way by calling previewOptions().

There are enumerations for setting current layout policy: PageLayoutDirection, PageLayoutOrdering, PageLayoutScaling and PageLayoutCounting. Their combination will inform QicsPrintPreviewWidget about the way how to layout the pages.

See PageLayoutData description to realize how to setup desired layout policy.

User interaction

There are two user control modes available - select and pan - which can be set with setControlMode() method.

In the select mode, pages can be selected with the mouse (single left click). The page which was clicked becomes "active" and drawn with the green border. To add/remove others pages to/from selection, use Ctrl + left mouse click. Selected pages are drawn with blue border.

Also, each page can be quickly zoomed to 100% size and unzoomed back to previous state with double-clicking left mouse button. This behavior can be set with enableClickZoom() method.

Some keyboard combinations provided in this mode. Ctrl-A will select all the pages. Ctrl-E will enable selected pages, and Ctrl-D will disable them. Disabled pages are marked as crossed-out. This feature can be useable while choosing which pages to exclude from printing.

See also setActivePage(), setActivePageIndex(), selectAll(), deselectAll(), enableAll(), disableAll(), enableSelected() and disableSelected() methods.

In the pan mode, a "hand" cursor is shown, and you can drag the whole layout to quickly browse/preview the desired page(s).

Metrical rulers

QicsPrintPreviewWidget provides vertical and horizontal metrical rulers to view original page size in millimeters. It is possible to show/hide these rulers via showRulers() method.

Page numbers

Every page has its logical page number used to locate it and make available/not available for printing. These numbers are shown in the right-bottom corner of every page, independent of current scale settings. It is possible to show/hide these numbers via showPageNumbers() method.

Printing

Generally, actual printing is performed when calling print() or printAllPages() methods. printAllPages() is intended for the simple printing of all the pages available, one copy, one-by-one order starting by first page. It does not need any setup.

print() performs more customizable printing. It uses the current printing settings. There are:

A subset of pages is defined by PrintPageSet enum passed to setPrintPageSet() method.

Order in which pages will be sent to printer is defined by PrintPageOrder enum passed to setPrintPageOrder() method.

Sequence of the subset which will be sent to printer is defined by PrintPageSequence enum passed to setPrintPageSequence() method.

If the number of copies (set by setPrintCopies()) is more than 1, then order of copies also will be applied. It is defined by PrintCopyOrder enum passed to setPrintCopyOrder() method.

Feedback from print process

There are signals which should be handled to get feedback from print process. After print() method was called, printingStarted(int totalPages) signal will be emitted first. It can be used to set up the GUI indicating how many pages were selected to be printed. Then, for each page, pagePrinting(int i, QicsPrintPreviewPage *page) and pagePrinted(int i, QicsPrintPreviewPage *page) signals are emitted before and after the page was printed, respectively. The signals printingFinished(), printingAborted() or printingError() will be emitted to indicate if the printing is finished with no issues, aborted by the user, or some issue while printing was happened, respectively.


Constructor & Destructor Documentation

QicsPrintPreviewWidget::QicsPrintPreviewWidget ( QWidget *  parent,
PageCountMode  pcm = PCM_DYNAMIC 
)

Constructor.

Parameters:
parent Parent widget.
pcm Page control mode. See setPageCountMode().


Member Function Documentation

QicsPrintPreviewPage* QicsPrintPreviewWidget::activePage (  )  const [inline]

Returns active page if exists.

See also:
setActivePageIndex(int index), setActivePage(QicsPrintPreviewPage* page)

void QicsPrintPreviewWidget::autoShowActivePage ( bool  yes = true  ) 

Sets jump to active page to yes. If enabled, then after each layout update viewport will be scrolled to show currently active page.

See also:
isAutoShowActivePage()

void QicsPrintPreviewWidget::contextMenuRequest ( QicsPrintPreviewPage page,
QContextMenuEvent *  event 
) [signal]

Emitted when a context menu has been requested on page page. If page is 0, then the menu has been requested on viewport. event is QContextMenuEvent passed from viewport. Handle this signal to organize own context menu.

ControlMode QicsPrintPreviewWidget::controlMode (  )  const [inline]

Returns current user control mode.

See also:
setControlMode()

void QicsPrintPreviewWidget::countPages ( int *  pages,
QPrinter *  printer 
) [signal]

Emitted when printer/paper options was changed so number of pages should be recalculated. This signal is obligatory to handle when building own preview. See Counting the pages topic for reference.

See also:
pageCounted(), terminateCount(), setPageCountMode()

void QicsPrintPreviewWidget::deselectAll (  )  [inline, slot]

Sets selection state of all the pages to false.

See also:
selectAll()

void QicsPrintPreviewWidget::disableAll (  )  [inline, slot]

Sets enabled state of all the pages to false.

See also:
enableAll()

void QicsPrintPreviewWidget::disableSelected (  )  [inline, slot]

Sets enabled state of all the selected pages to false.

See also:
enableSelected()

void QicsPrintPreviewWidget::drawPage ( QicsPrintPreviewPage page  )  [signal]

Emitted when a page must be redrawn during preview. This signal is obligatory to handle when building own preview. See Painting page content topic for reference.

See also:
printPage()

void QicsPrintPreviewWidget::enableAll ( bool  yes = true  )  [slot]

Sets enabled state of all the pages to yes.

See also:
disableAll()

void QicsPrintPreviewWidget::enableClickZoom ( bool  yes = true  ) 

Sets double click zoom enabled yes. If enabled, then double-click on the page in select mode will zoom it to 100%, and the next double-click will revert zoom back.

See also:
isClickZoomEnabled()

void QicsPrintPreviewWidget::enableSelected ( bool  yes = true  )  [slot]

Sets enabled state of all the selected pages to yes.

See also:
disableSelected()

void QicsPrintPreviewWidget::ensurePageVisible ( QicsPrintPreviewPage page  ) 

Scrolls viewport to the page page if exists.

See also:
ensurePageVisible(int index)

void QicsPrintPreviewWidget::ensurePageVisibleIndex ( int  index  ) 

Scrolls viewport to the page with logical index index if exists.

See also:
ensurePageVisible(QicsPrintPreviewPage* page)

bool QicsPrintPreviewWidget::isAutoShowActivePage (  )  const [inline]

Returns true if jump to active page is enabled. false if not.

See also:
autoShowActivePage()

bool QicsPrintPreviewWidget::isClickZoomEnabled (  )  const [inline]

Returns true if double click zoom is enabled. false if not.

See also:
enableClickZoom()

bool QicsPrintPreviewWidget::isPageNumbersVisible (  )  const [inline]

Returns visibility of logical page numbers.

See also:
showPageNumbers()

bool QicsPrintPreviewWidget::isRulersVisible (  )  const [inline]

Returns visibility of metrical rulers.

See also:
showRulers()

void QicsPrintPreviewWidget::pageCounted (  )  [slot]

In dynamic page count mode, it should be called after a page has been counted. It is obligatory to call when building own preview. See Counting the pages topic for reference.

See also:
countPages(), terminateCount(), setPageCountMode()

PageLayoutCounting QicsPrintPreviewWidget::pageCounting (  )  const [inline]

Returns current page counting.

See also:
setPageCounting()

PageCountMode QicsPrintPreviewWidget::pageCountMode (  )  const [inline]

Returns current page count mode.

See also:
setPageCountMode()

PageLayoutDirection QicsPrintPreviewWidget::pageDirection (  )  const [inline]

Returns current page direction.

See also:
setPageDirection()

PageLayoutOrdering QicsPrintPreviewWidget::pageOrdering (  )  const [inline]

Returns current page ordering.

See also:
setPageOrdering()

void QicsPrintPreviewWidget::pagePrinted ( int  i,
QicsPrintPreviewPage page 
) [signal]

Emitted after the page page with order i has been printed. Handle this signal to perform GUI interaction. i is the order in which this page is sent to printer, and it is always in range [1...totalPages]. For every next page printed, i will be increased by 1.

See also:
printingStarted(), pagePrinting()

void QicsPrintPreviewWidget::pagePrinting ( int  i,
QicsPrintPreviewPage page 
) [signal]

Emitted when the page page with order i is about to be printed. Handle this signal to perform GUI interaction. i is the order in which this page is sent to printer, and it is always in range [1...totalPages]. For every next page printed, i will be increased by 1.

See also:
printingStarted(), pagePrinted()

PageLayoutScaling QicsPrintPreviewWidget::pageScaling (  )  const [inline]

Returns current page scaling.

See also:
setPageScaling()

int QicsPrintPreviewWidget::pagesCount (  )  const [inline]

Returns total numbers of pages shown.

const QList<int>& QicsPrintPreviewWidget::pagesToPrint (  )  const [inline]

Returns numbers of pages to print with print() method.

See also:
setPagesToPrint()

int QicsPrintPreviewWidget::pagesX (  )  const [inline]

Returns current page number to fit horizontally.

See also:
setPageDirection()

int QicsPrintPreviewWidget::pagesY (  )  const [inline]

Returns current page number to fit vertically.

See also:
setPageDirection()

const PageLayoutData& QicsPrintPreviewWidget::previewOptions (  )  const [inline]

Returns current preview options.

See also:
setPreviewOptions()

void QicsPrintPreviewWidget::print (  )  [slot]

Starts printing, using current printer and paper settings, current set of pages, number of copies and order.

See also:
setPrintCopies(), setPrintCopyOrder(), setPrintPageOrder(), setPrintPageSet(), setPrintPageSequence(), setPagesToPrint()

void QicsPrintPreviewWidget::printAllPages (  )  [slot]

Simply prints single copy of all the pages using current printer and paper settings. May be deprecated in the future releases; use print() instead.

int QicsPrintPreviewWidget::printCopies (  )  const [inline]

Returns number of copies to print with print() method.

See also:
setPrintCopies()

PrintCopyOrder QicsPrintPreviewWidget::printCopyOrder (  )  const [inline]

Returns order of copies to print with print() method.

See also:
setPrintCopyOrder()

QPrinter* QicsPrintPreviewWidget::printer (  )  const [inline]

Returns current printer object.

See also:
updatePages()

void QicsPrintPreviewWidget::printingAborted (  )  [signal]

Emitted when the actual printing was aborted (i.e. by the user etc.). Handle this signal to perform GUI interaction.

See also:
printingFinished(), printingError()

void QicsPrintPreviewWidget::printingError (  )  [signal]

Emitted when the actual printing was aborted or was not started because some error was happened. Handle this signal to perform GUI interaction.

See also:
printingFinished(), printingAborted()

void QicsPrintPreviewWidget::printingFinished (  )  [signal]

Emitted after the actual printing has finished normally (all pages have been printed). Handle this signal to perform GUI interaction.

See also:
printingAborted(), printingError()

void QicsPrintPreviewWidget::printingStarted ( int  totalPages  )  [signal]

Emitted just before the actual printing starts. Handle this signal to perform GUI interaction. totalPages is the total amount of pages to print in this session.

See also:
pagePrinting(), pagePrinted(), printingFinished()

void QicsPrintPreviewWidget::printPage ( QicsPrintPreviewPage page,
QPainter *  painter 
) [signal]

Emitted when a page must be redrawn during printing. This signal is obligatory to handle when building own preview. See Painting page content topic for reference.

See also:
drawPage()

PrintPageOrder QicsPrintPreviewWidget::printPageOrder (  )  const [inline]

Returns order of pages to print with print() method.

See also:
setPrintPageOrder(), print()

PrintPageSequence QicsPrintPreviewWidget::printPageSequence (  )  const [inline]

Returns sequence of pages to print with print() method.

See also:
setPrintPageSequence()

PrintPageSet QicsPrintPreviewWidget::printPageSet (  )  const [inline]

Returns set of pages to print with print() method.

See also:
setPrintPageSet()

double QicsPrintPreviewWidget::scale (  )  const [inline]

Returns current scale in percents.

See also:
setScale()

void QicsPrintPreviewWidget::selectAll ( bool  yes = true  )  [slot]

Sets selection state of all the pages to yes.

See also:
deselectAll()

void QicsPrintPreviewWidget::setActivePage ( QicsPrintPreviewPage page  ) 

Sets active page page if exists.

See also:
setActivePageIndex(int index), activePage()

void QicsPrintPreviewWidget::setActivePageIndex ( int  index  ) 

Sets active page with index index if exists.

See also:
setActivePage(QicsPrintPreviewPage* page), activePage()

void QicsPrintPreviewWidget::setControlMode ( ControlMode  cm  ) 

Sets current user control mode to cm. It can be one of the following:

See also:
controlMode()

void QicsPrintPreviewWidget::setPageCounting ( PageLayoutCounting  lc  ) 

Sets page counting to lc. See PageLayoutData description for reference.

See also:
pageCounting()

void QicsPrintPreviewWidget::setPageCountMode ( PageCountMode  pcm  ) 

Sets current page count mode to pcm. It can be one of the following:

See Counting the pages topic for reference.

See also:
pageCountMode()

void QicsPrintPreviewWidget::setPageDirection ( PageLayoutDirection  dir,
int  count = -1 
)

Sets page direction to dir and number of pages to fit to count. If count <= 0 (by default), it will remain unchanged. See PageLayoutData description for reference.

See also:
pageDirection()

void QicsPrintPreviewWidget::setPageOrdering ( PageLayoutOrdering  lo  ) 

Sets page ordering to lo. See PageLayoutData description for reference.

See also:
pageOrdering()

void QicsPrintPreviewWidget::setPageScaling ( PageLayoutScaling  ls  ) 

Sets page scaling to ls. See PageLayoutData description for reference.

See also:
pageScaling()

void QicsPrintPreviewWidget::setPagesToPrint ( const QList< int > &  numbers  ) 

Sets explicitly numbers of pages to print with print() method. Logical numbers (from 1 to pagesCount()) must be used.

See also:
pagesToPrint()

void QicsPrintPreviewWidget::setPreviewOptions ( const PageLayoutData opt  ) 

Sets preview options to opt. See PageLayoutData description for reference.

See also:
previewOptions()

void QicsPrintPreviewWidget::setPrintCopies ( int  num  ) 

Sets num number of copies to print with print() method. If the number of copies is more than 1, then order of copies also will be applied (set by setPrintCopyOrder()).

See also:
printCopies(), setPrintCopyOrder(), print()

void QicsPrintPreviewWidget::setPrintCopyOrder ( PrintCopyOrder  order  ) 

Sets order of copies to print with print() method. It can be one of the following:

See also:
printCopyOrder(), setPrintCopies(), print()

void QicsPrintPreviewWidget::setPrintPageOrder ( PrintPageOrder  order  ) 

Sets order of pages to print with print() method. It can be one of the following:

See also:
printPageOrder()

void QicsPrintPreviewWidget::setPrintPageSequence ( PrintPageSequence  sequence  ) 

Sets sequence of pages to print with print() method. It can be one of the following:

See also:
printPageSequence(), print()

void QicsPrintPreviewWidget::setPrintPageSet ( PrintPageSet  set  ) 

Sets set of pages to print with print() method. It can be one of the following:

See also:
printPageSet(), print()

void QicsPrintPreviewWidget::setScale ( double  percent  ) 

Sets current scale (in percents) to percent.

See also:
scale()

void QicsPrintPreviewWidget::showPageNumbers ( bool  show = true  ) 

Sets visibility of logical page numbers to show.

See also:
isPageNumbersVisible()

void QicsPrintPreviewWidget::showRulers ( bool  show = true  ) 

Sets visibility of metrical rulers to show.

See also:
isRulersVisible()

void QicsPrintPreviewWidget::terminateCount (  )  [signal]

Emitted in dynamic mode when page counting was restarted, so older counter should be terminated. This signal is obligatory to handle when building own preview with dynamic mode support. See Counting the pages topic for reference.

See also:
countPages(), pageCounted(), setPageCountMode()

void QicsPrintPreviewWidget::updatePages ( QPrinter *  printer  ) 

Updates pages layout according to the printer parameter which will be set as current printer. Typical usage is to call this function after showing QPrintDialog or QPageSetupDialog with their printer() value.

See also:
printer()

void QicsPrintPreviewWidget::updatePerformed ( const PageLayoutData opt  )  [signal]

Emitted when page layout was updated. Handle this signal to perform GUI interaction. opt is the current preview layout data.

See also:
setPreviewOptions()


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

All trademarks and copyrights on this page are properties of their respective owners.
The rest is copyright 1999-2006 Integrated Computer Solutions, Inc.