IlvPrintableLayout Class Reference

Base class for the layout classes. More...

#include <ilviews/printing/layout.h>

Inheritance diagram for IlvPrintableLayout:

List of all members.

Public Member Functions
	IlvPrintableLayout ()
	Default constructor.
virtual	~IlvPrintableLayout ()
	Destructor.
IlvPrintableArea const &	getBackgroundArea (IlvPrintableJob &job, int pageIndex) const
	Gets the updated background area.
IlvPrintable *	getBackgroundPrintable () const
	Gets the IlvPrintable used to print the background.
IlvDim	getBottomMargin () const
	Returns the bottom margin.
IlvPrintableArea const &	getFooterArea (IlvPrintableJob &job, int pageIndex) const
	Gets the updated footer area.
virtual IlvDim	getFooterAreaHeight () const =0
	Returns the height of the footer area.
IlvPrintable *	getFooterPrintable () const
	Gets the IlvPrintable used to print the footer.
IlvPrintableArea const &	getForegroundArea (IlvPrintableJob &job, int pageIndex) const
	Gets the updated foreground area.
IlvPrintable *	getForegroundPrintable () const
	Gets the IlvPrintable used to print the foreground.
IlvDim	getGutterMargin () const
	Returns the gutter margin.
IlvPrintableArea const &	getHeaderArea (IlvPrintableJob &job, int pageIndex) const
	Gets the updated header area.
virtual IlvDim	getHeaderAreaHeight () const =0
	Returns the height of the header area.
IlvPrintable *	getHeaderPrintable () const
	Gets the IlvPrintable used to print the header.
IlvDim	getLeftMargin () const
	Returns the left margin.
IlvPrintableArea const &	getMainArea (IlvPrintableJob &job, int pageIndex) const
	Gets the updated main area.
void	getMargins (IlvDim &left, IlvDim &right, IlvDim &top, IlvDim &bottom, IlvDim &gutter) const
	Returns the margins.
IlUInt	getRefCount () const
	Returns the number of references on this instance.
IlvDim	getRightMargin () const
	Returns the right margin.
IlvDim	getTopMargin () const
	Returns the top margin.
IlvRect	getUsableArea (IlvPrinter const &printer, IlBoolean isGutterOnLeft=((IlBoolean) 1)) const
	Returns the usable logical printable area for a page.
IlBoolean	isRatioKept () const
	Returns whether the ratio is kept.
void	lock ()
	Locks the current instance.
IlBoolean	print (IlvPrintableJob &job, int copyNumber) const
	Prints an IlvPrintable according to the layout specified by this object.
void	setBackgroundPrintable (IlvPrintable *printable)
	Sets the IlvPrintable used to print the background.
void	setBottomMargin (IlvDim margin)
	Sets the bottom margin.
virtual void	setFooterAreaHeight (IlvDim height)=0
	Sets the height of the footer area.
void	setFooterPrintable (IlvPrintable *printable)
	Sets the IlvPrintable used to print the footer.
void	setForegroundPrintable (IlvPrintable *printable)
	Sets the IlvPrintable used to print the foreground.
void	setGutterMargin (IlvDim margin)
	Sets the gutter margin.
virtual void	setHeaderAreaHeight (IlvDim height)=0
	Sets the height of the header area.
void	setHeaderPrintable (IlvPrintable *printable)
	Sets the IlvPrintable used to print the header.
void	setKeepingRatio (IlBoolean keepRatio)
	Sets whether the ratio is kept.
void	setLeftMargin (IlvDim margin)
	Sets the left margin.
void	setMargins (IlvDim left, IlvDim right, IlvDim top, IlvDim bottom, IlvDim gutter=0)
	Sets the margins.
void	setRightMargin (IlvDim margin)
	Sets the right margin.
void	setTopMargin (IlvDim margin)
	Sets the top margin.
void	unlock ()
	Unlocks the current instance.
Protected Member Functions
IlvPrintableArea &	getBackgroundArea () const
	Gets the background area.
IlvPrintableArea &	getFooterArea () const
	Gets the footer area.
IlvPrintableArea &	getForegroundArea () const
	Gets the foreground area.
IlvPrintableArea &	getHeaderArea () const
	Gets the header area.
IlvPrintableArea &	getMainArea () const
	Gets the main area.
virtual int	getPageNumber (IlvPrintableJob &job) const =0
	Gets the number of logical pages for this layout and the print settings given as argument.
virtual void	initializeBackgroundArea (IlvPrintableJob &job) const =0
	Initializes the background area.
virtual void	initializeFooterArea (IlvPrintableJob &job) const =0
	Initializes the footer area.
virtual void	initializeForegroundArea (IlvPrintableJob &job) const =0
	Initializes the foreground area.
virtual void	initializeHeaderArea (IlvPrintableJob &job) const =0
	Initializes the header area.
virtual void	initializeMainArea (IlvPrintableJob &job) const =0
	Initializes the main area.
void	setBackgroundArea (IlvPrintableArea *area) const
	Sets the background area.
void	setFooterArea (IlvPrintableArea *area) const
	Sets the footer area.
void	setForegroundArea (IlvPrintableArea *area) const
	Sets the foreground area.
void	setHeaderArea (IlvPrintableArea *area) const
	Sets the header area.
void	setMainArea (IlvPrintableArea *area) const
	Sets the main area.
virtual void	updateBackgroundArea (IlvPrintableJob &job, int pageIndex) const =0
	Updates the background area.
virtual void	updateFooterArea (IlvPrintableJob &job, int pageIndex) const =0
	Updates the footer area.
virtual void	updateForegroundArea (IlvPrintableJob &job, int pageIndex) const =0
	Updates the foreground area.
virtual void	updateHeaderArea (IlvPrintableJob &job, int pageIndex) const =0
	Updates the header area.
virtual void	updateMainArea (IlvPrintableJob &job, int pageIndex) const =0
	Updates the main area.

---

Detailed Description

Base class for the layout classes.

Library: ilvprint

This class is intended to be inherited by implementing the virtual member functions.

Its purpose is to describe a way of mapping the IlvPrintable to the physical page layout.

This class defines left, right, top, bottom, and gutter margins as described in the following figure:

It also defines if the layout keeps the input's aspect ratio.

Warning:

[note] The copy constructor and the assignment operator are available although they are not explicitly declared and defined.

See also:

IlvPrintableDocument::append

---

Constructor & Destructor Documentation

IlvPrintableLayout::IlvPrintableLayout

(

)

Default constructor.

This is the default constructor. It initializes the object in a coherent state. The inherited classes must initialize the five areas. There are no additional margins by default.

virtual IlvPrintableLayout::~IlvPrintableLayout

(

)

[virtual]

Destructor.

The destructor actually does nothing, but it is declared as virtual so that inherited classes may override it.

---

Member Function Documentation

IlvPrintableArea & IlvPrintableLayout::getBackgroundArea

(

)

const [protected]

Gets the background area.

Returns:

A reference to the background area.

IlvPrintableArea const& IlvPrintableLayout::getBackgroundArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const

Gets the updated background area.

The purpose of this function is to update and return the IlvPrintableArea background object. The job as well as the page index given as parameters may be used to update the current size of the area, done through the virtual member function updateForegroundArea.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Returns:

The background area.

See also:

updateBackgroundArea.

IlvPrintable * IlvPrintableLayout::getBackgroundPrintable

(

)

const

Gets the IlvPrintable used to print the background.

Returns:

The background printable.

IlvDim IlvPrintableLayout::getBottomMargin

(

)

const

Returns the bottom margin.

Returns:

The bottom margin.

IlvPrintableArea & IlvPrintableLayout::getFooterArea

(

)

const [protected]

Gets the footer area.

Returns:

A reference to the footer area.

IlvPrintableArea const& IlvPrintableLayout::getFooterArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const

Gets the updated footer area.

The purpose of this function is to update and return the IlvPrintableArea footer object. The job as well as the page index given as parameters may be used to update the current size of the area, done through the virtual member function updateFooterArea.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Returns:

The footer area.

See also:

updateFooterArea.

virtual IlvDim IlvPrintableLayout::getFooterAreaHeight

(

)

const [pure virtual]

Returns the height of the footer area.

This pure virtual member function must be overloaded in inherited classes.

Returns:

The height of the footer area.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

IlvPrintable * IlvPrintableLayout::getFooterPrintable

(

)

const

Gets the IlvPrintable used to print the footer.

Returns:

The footer printable.

IlvPrintableArea & IlvPrintableLayout::getForegroundArea

(

)

const [protected]

Gets the foreground area.

Returns:

A reference to the foreground area.

IlvPrintableArea const& IlvPrintableLayout::getForegroundArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const

Gets the updated foreground area.

The purpose of this function is to update and return the IlvPrintableArea foreground object. The job as well as the page index given as parameters may be used to update the current size of the area, done through the virtual member function updateForegroundArea.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Returns:

The foreground area.

See also:

updateForegroundArea.

IlvPrintable * IlvPrintableLayout::getForegroundPrintable

(

)

const

Gets the IlvPrintable used to print the foreground.

Returns:

The foreground printable.

IlvDim IlvPrintableLayout::getGutterMargin

(

)

const

Returns the gutter margin.

Returns:

The gutter margin.

IlvPrintableArea & IlvPrintableLayout::getHeaderArea

(

)

const [protected]

Gets the header area.

Returns:

A reference to the header area.

IlvPrintableArea const& IlvPrintableLayout::getHeaderArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const

Gets the updated header area.

The purpose of this function is to update and return the IlvPrintableArea header object. The job as well as the page index given as parameters may be used to update the current size of the area, done through the virtual member function updateHeaderArea.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Returns:

The header area.

See also:

updateHeaderArea.

virtual IlvDim IlvPrintableLayout::getHeaderAreaHeight

(

)

const [pure virtual]

Returns the height of the header area.

This pure virtual member function must be overloaded in inherited classes.

Returns:

The height of the header area.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

IlvPrintable * IlvPrintableLayout::getHeaderPrintable

(

)

const

Gets the IlvPrintable used to print the header.

Returns:

The header printable.

IlvDim IlvPrintableLayout::getLeftMargin

(

)

const

Returns the left margin.

Returns:

The left margin.

IlvPrintableArea & IlvPrintableLayout::getMainArea

(

)

const [protected]

Gets the main area.

Returns:

A reference to the main area.

IlvPrintableArea const& IlvPrintableLayout::getMainArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const

Gets the updated main area.

The purpose of this function is to update and return the IlvPrintableArea main object. The job as well as the page index given as parameters may be used to update the current size of the area, done through the virtual member function updateMainArea.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Returns:

The main area.

See also:

updateMainArea.

void IlvPrintableLayout::getMargins	(	IlvDim &	left,
		IlvDim &	right,
		IlvDim &	top,
		IlvDim &	bottom,
		IlvDim &	gutter
	)			const

Returns the margins.

Parameters:

	left	The left margin.
	right	The right margin.
	top	The top margin.
	bottom	The bottom margin.
	gutter	The gutter margin.

virtual int IlvPrintableLayout::getPageNumber

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Gets the number of logical pages for this layout and the print settings given as argument.

This pure virtual function must be overloaded in inherited classes.

Parameters:

job

The current print settings.

Returns:

The number of logical pages.

Implemented in IlvPrintableLayoutFixedSize, IlvPrintableLayoutIdentity, IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

IlUInt IlvPrintableLayout::getRefCount

(

)

const

Returns the number of references on this instance.

Returns:

The number of references.

IlvDim IlvPrintableLayout::getRightMargin

(

)

const

Returns the right margin.

Returns:

The right margin.

IlvDim IlvPrintableLayout::getTopMargin

(

)

const

Returns the top margin.

Returns:

The top margin.

IlvRect IlvPrintableLayout::getUsableArea	(	IlvPrinter const &	printer,
		IlBoolean	isGutterOnLeft = ((IlBoolean) 1)
	)			const

Returns the usable logical printable area for a page.

This is the size available for the printing.

The gutter is taken into account on the left or right side according to the Boolean parameter.

If printer is an IlvWindowsPrinterinstance, before using this method,the internal attributes of the printer must be initialized through a call to IlvPrinter::initializeSettings().

Parameters:

	printer	The printer from which the physical area is taken.
	isGutterOnLeft	IlTrue means that the gutter must be on the left side of the paper.

Returns:

The usable logical printable area.

virtual void IlvPrintableLayout::initializeBackgroundArea

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Initializes the background area.

This pure virtual member function must be overloaded by inherited classes. Its purpose is to initialize the background area. It is called at the beginning of the print member function, before the loop on the pages.

Parameters:

job

The current print settings.

See also:

print.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::initializeFooterArea

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Initializes the footer area.

This pure virtual member function must be overloaded by inherited classes. Its purpose is to initialize the footer area. It is called at the beginning of the print member function, before the loop on the pages.

Parameters:

job

The current print settings.

See also:

print.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::initializeForegroundArea

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Initializes the foreground area.

This pure virtual member function must be overloaded by inherited classes. Its purpose is to initialize the foreground area. It is called at the beginning of the print member function, before the loop on the pages.

Parameters:

job

The current print settings.

See also:

print.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::initializeHeaderArea

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Initializes the header area.

This pure virtual member function must be overloaded by inherited classes. Its purpose is to initialize the header area. It is called at the beginning of the print member function, before the loop on the pages.

Parameters:

job

The current print settings.

See also:

print.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::initializeMainArea

(

IlvPrintableJob &

job

)

const [protected, pure virtual]

Initializes the main area.

This pure virtual member function must be overloaded by inherited classes. Its purpose is to initialize the main area. It is called at the beginning of the print member function, before the loop on the pages.

Parameters:

job

The current print settings.

See also:

print.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

IlBoolean IlvPrintableLayout::isRatioKept

(

)

const

Returns whether the ratio is kept.

Returns:

A Boolean value indicating whether the ratio is kept.

void IlvPrintableLayout::lock

(

)

Locks the current instance.

A reference counter is incremented internally.

IlBoolean IlvPrintableLayout::print	(	IlvPrintableJob &	job,
		int	copyNumber
	)			const

Prints an IlvPrintable according to the layout specified by this object.

The IlvPrintableJob references the IlvPrintable as well as other settings.

The function calls the print method on every printable referenced by the current object and by the job for each page specified by this layout.

Parameters:

	job	The current printable job.
	copyNumber	The number of copies to print.

Returns:

IlFalse when an error occurred during the print, IlTrue otherwise.

void IlvPrintableLayout::setBackgroundArea

(

IlvPrintableArea *

area

)

const [protected]

Sets the background area.

This function is intended to be called in the constructors of the inherited classes.

Parameters:

area

The background area.

void IlvPrintableLayout::setBackgroundPrintable

(

IlvPrintable *

printable

)

Sets the IlvPrintable used to print the background.

This function creates the background area. If the printable is null, an IlvPrintableNullArea is created; otherwise an IlvPrintableActualArea.

Parameters:

printable

The printable to store.

void IlvPrintableLayout::setBottomMargin

(

IlvDim

margin

)

Sets the bottom margin.

Parameters:

margin

The new bottom margin.

void IlvPrintableLayout::setFooterArea

(

IlvPrintableArea *

area

)

const [protected]

Sets the footer area.

This function is intended to be called in the constructors of the inherited classes.

Parameters:

area

The footer area.

virtual void IlvPrintableLayout::setFooterAreaHeight

(

IlvDim

height

)

[pure virtual]

Sets the height of the footer area.

This pure virtual member function must be overloaded in inherited classes.

Parameters:

height

The height of the footer area.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

void IlvPrintableLayout::setFooterPrintable

(

IlvPrintable *

printable

)

Sets the IlvPrintable used to print the footer.

This function creates the footer area. If the printable is null, an IlvPrintableNullArea is created; otherwise an IlvPrintableActualArea.

Parameters:

printable

The printable to store.

void IlvPrintableLayout::setForegroundArea

(

IlvPrintableArea *

area

)

const [protected]

Sets the foreground area.

This function is intended to be called in the constructors of the inherited classes.

Parameters:

area

The foreground area.

void IlvPrintableLayout::setForegroundPrintable

(

IlvPrintable *

printable

)

Sets the IlvPrintable used to print the foreground.

This function creates the foreground area. If the printable is null, an IlvPrintableNullArea is created; otherwise an IlvPrintableActualArea.

Parameters:

printable

The printable to store.

void IlvPrintableLayout::setGutterMargin

(

IlvDim

margin

)

Sets the gutter margin.

Parameters:

margin

The new gutter margin.

void IlvPrintableLayout::setHeaderArea

(

IlvPrintableArea *

area

)

const [protected]

Sets the header area.

This function is intended to be called in the constructors of the inherited classes.

Parameters:

area

The header area.

virtual void IlvPrintableLayout::setHeaderAreaHeight

(

IlvDim

height

)

[pure virtual]

Sets the height of the header area.

This pure virtual member function must be overloaded in inherited classes.

Parameters:

height

The height of the header area.

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

void IlvPrintableLayout::setHeaderPrintable

(

IlvPrintable *

printable

)

Sets the IlvPrintable used to print the header.

This function creates the header area. If the printable is null, an IlvPrintableNullArea is created; otherwise an IlvPrintableActualArea.

Parameters:

printable

The printable to store.

See also:

initHeaderArea

void IlvPrintableLayout::setKeepingRatio

(

IlBoolean

keepRatio

)

Sets whether the ratio is kept.

Parameters:

keepRatio

A Boolean value.

void IlvPrintableLayout::setLeftMargin

(

IlvDim

margin

)

Sets the left margin.

Parameters:

margin

The new left margin.

void IlvPrintableLayout::setMainArea

(

IlvPrintableArea *

area

)

const [protected]

Sets the main area.

This function is intended to be called in the constructors of the inherited classes.

Parameters:

area

The main area.

void IlvPrintableLayout::setMargins	(	IlvDim	left,
		IlvDim	right,
		IlvDim	top,
		IlvDim	bottom,
		IlvDim	gutter = 0
	)

Sets the margins.

Parameters:

	left	The new left margin.
	right	The new right margin.
	top	The new top margin.
	bottom	The new bottom margin.
	gutter	The new gutter margin.

void IlvPrintableLayout::setRightMargin

(

IlvDim

margin

)

Sets the right margin.

Parameters:

margin

The new right margin.

void IlvPrintableLayout::setTopMargin

(

IlvDim

margin

)

Sets the top margin.

Parameters:

margin

The new top margin.

void IlvPrintableLayout::unlock

(

)

Unlocks the current instance.

A reference counter is decremented internally. When the reference counter reaches 0 the instance is deleted.

virtual void IlvPrintableLayout::updateBackgroundArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const [protected, pure virtual]

Updates the background area.

This pure virtual function must be overloaded in inherited classes. The purpose of this function is to update the IlvPrintableArea background object. The job as well as the page index given as parameters may be used to compute the current size of the area.

Parameters:

	backgroundArea	A pointer to the background area to update.
	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::updateFooterArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const [protected, pure virtual]

Updates the footer area.

This pure virtual function must be overloaded in inherited classes. The purpose of this function is to update the IlvPrintableArea footer object. The job as well as the page index given as parameters may be used to compute the current size of the area.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::updateForegroundArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const [protected, pure virtual]

Updates the foreground area.

This pure virtual function must be overloaded in inherited classes. The purpose of this function is to update the IlvPrintableArea foreground object. The job as well as the page index given as parameters may be used to compute the current size of the area.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::updateHeaderArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const [protected, pure virtual]

Updates the header area.

This pure virtual function must be overloaded in inherited classes. The purpose of this function is to update the IlvPrintableArea header object. The job as well as the page index given as parameters may be used to compute the current size of the area.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Implemented in IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.

virtual void IlvPrintableLayout::updateMainArea	(	IlvPrintableJob &	job,
		int	pageIndex
	)			const [protected, pure virtual]

Updates the main area.

This pure virtual function must be overloaded in inherited classes. The purpose of this function is to update the IlvPrintableArea main object. The job as well as the page index given as parameters may be used to compute the current size of the area.

Parameters:

	job	The current print settings.
	pageIndex	The current logical page index (for this layout).

Implemented in IlvPrintableLayoutFixedSize, IlvPrintableLayoutIdentity, IlvPrintableLayoutMultiplePages, and IlvPrintableLayoutOnePage.