| wxprintpagetemplate | ||
|---|---|---|
 | Chapter 11. The wxWidgets-based (WXWN) Components |  |
wxprintpagetemplate
Description
A wxprintpagetemplate object contains the description of where things will be printed, which font, which position, as well as the graphical objects that appear on any page that uses the template in a wxprintout. Each page in the printout requires a template that establishes what will be printed and where. The data for any given item of text or any image can be associated with the printout, the template or the individual page.
Type Tags
wxgraphiccontainer, wxprintdatacontainer
Object Value
wxprintpagetemplate.new()
Description
Creates a new wxprintpagetemplate object of the specified size and with the specified background color.
Prototype
wxprintpagetemplate.new (
integer widthheightbackgroundrgb
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| width | None | integer | The width of the new page template, in micrometers. |
| height | None | integer | The height of the new page template, in micrometers. |
| backgroundrgb | White | integer | The background color of the new page template. It is inadvisable to specify any value for this argument that is not the value of an existing rgb object. |
Properties
| Property | Type | Description |
|---|---|---|
| _ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. |
| __ | type(*) | This property is provided for use by the user to attach any object of any type to the type in which this property is provided. It has the additional feature of being marked with the resolve keyword, so that object resolution can continue down this property. |
| backgroundrgb | rgb | Shows the background color of the page. |
| firstbitmap | wxprintbitmap |
Specifies the first wxprintbitmap object in the ring of bitmaps
that contain the data associated with this template. This is
.nul if there are no bitmaps associated with the
template.
|
| firstbitmapitem | wxprintbitmapitem |
Specifies the first wxprintbitmapitem object in the ring of
bitmap items that contain the layout information for an item that is
to be printed using this template. This is .nul if
there are no bitmap items associated with the template.
|
| firstgraphic | type(wxgraphic) |
Gives the first graphic item on the template, or is .nul if
there are no graphic items on the template. These include lines,
triangles, rectangles, arcs, and ellipses.
|
| firststring | wxprintstring |
Specifies the first wxprintstring object in the ring of strings
that contain the data associated with this template. This is
.nul if there are no strings associated with the
template.
|
| firsttextitem | wxprinttextitem |
Specifies the first wxprinttextitem object in the ring of text
items that contain the layout information for an item that is to be
printed using this template. This is .nul if there
are no text items associated with the template.
|
| height | integer | Specifies the height of the printed page in micrometers. |
| type | type | Specifies the wxprintpagetemplate type object. |
| width | integer | Specifies the width of the printed page in micrometers. |
Methods
addbitmap()
Description
Adds a wxprintbitmap object to the ring of printbitmaps. An object of this type is added to hold the content for a wxprintbitmapitem object that is placed in a template. If the content is the same everywhere in the printout, then the bitmap should be added to the printout, if it is the same on each page that uses a specific template, then it should be added to the template, and if it is specific to a given page, then it should be added to the page.
![[Note]](images/note.png) | Note |
|---|---|
The name of any item: page, string, bitmap, etc. that can be accessed using the member operator must be unique across all rings associated with an object. For example in the case of a printout object, the same name cannot be assigned to a page and also to a string or a bitmap. The same name can also not be given to two items in the same ring. |
Prototype
wxprintpagetemplatevar.addbitmap (
wxbitmap bitmapnamenext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| bitmap | .nul | wxbitmap | The content for this wxprintbitmap object. |
| name | .nul | string | The name of the wxprintbitmap object. This value is used to link the object with the wxprintbitmapitem that will use it to provide the content for an item on a printed page. |
| next | .nul | wxprintbitmap |
This determines where in the ring of bitmaps the new bitmap will be placed.
The new bitmap will be created so that the bitmap specified as
next will be after the new bitmap in the
ring. If the next bitmap is the current
firstbitmap for the printout, then the new
bitmap will become the new firstbitmap. If
there are already some bitmaps in the printout and
next is specified to be
.nul then the next bitmap will be the current
firstbitmap for the printout, but the new
bitmap will not become a new firstbitmap
(i.e. it becomes the 'last' bitmap).
|
addbitmapitem()
Description
Creates a new wxprintbitmapitem object using the given arguments for many of the item's properties.
| Note |
|---|---|
The name of any item: page, string, bitmap, etc. that can be accessed using the member operator must be unique across all rings associated with an object. For example in the case of a printout object, the same name cannot be assigned to a page and also to a string or a bitmap. The same name can also not be given to two items in the same ring. |
Prototype
wxprintpagetemplatevar.addbitmapitem (
integer lefttopwidthheightalignmentscalingundergraphicscontentsourcecontentnamenamenext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| left | None | integer | The position of the left side of the new bitmap item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| top | None | integer | The position of the top edge of the new bitmap item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| width | None | integer | The width of the new bitmap item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| height | None | integer | The height of the new bitmap item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| alignment | "" | string |
The alignment of the bitmap within the new bitmap item. The default is
.nul, which will be left and top aligned.
Valid values are: "left",
"right", "top",
"bottom", "left,top",
"right,bottom",
"left,bottom", and
"right,top". To center something both
horizontally and vertically, use the empty string. If a value for
a dimension is not supplied, such as with
"left" by itself, then the unspecified
dimension will be centered.
|
| scaling | "" | string |
This is the scaling method to use for the bitmap, and can be either:
"hfit", "vfit",
"handvfit",
"preserveaspect", or "".
|
| undergraphics | .false | boolean | Decides whether the bitmap item is in front or behind the wxgraphic items. |
| contentsource | "" | string |
This contains the source of the bitmap item, either
"printout", "template",
"page", or the empty string
(""). If the value of this is the empty string
then nothing will be printed.
|
| contentname | "" | string | This is the name of the item that is stored in the content source and which is used to provide the actual content for the item when printed. If the value of this is the empty string, then nothing will be printed. |
| name | .nul | string | The name of the new bitmap item. |
| next | .nul | wxprintbitmapitem |
This determines where in the ring of bitmap items the new bitmap item will be
placed. The new bitmap item will be created so that the bitmap
item specified as next will be after the
new bitmap item in the ring. If the next
bitmap item is the current firstbitmapitem
for the template, then the new bitmap item will become the new
firstbitmapitem. If there are already some
bitmap items in the template and next is
specified to be .nul then the next bitmap item
will be the current firstbitmapitem for the
template, but the new bitmap item will not become a new
firstbitmapitem (i.e. it becomes a 'last'
bitmap item). Items are bottom to top in the z-order of the
template, so that an item later in the ring covers an item
located earlier in the ring.
|
addgraphic()
Description
Creates a new type(wxgraphic) object of the specified type, using
the given arguments for the graphic's properties. Graphics appear on
top of text and bitmap items whose undergraphics
property is set to .true, and under those where
the undergraphics property is set to
.false.
| Note |
|---|---|
The name of any item: page, string, bitmap, etc. that can be accessed using the member operator must be unique across all rings associated with an object. For example in the case of a printout object, the same name cannot be assigned to a page and also to a string or a bitmap. The same name can also not be given to two items in the same ring. |
Prototype
wxprintpagetemplatevar.addgraphic (
type typepoint1point2point3midpointrgbborderrgbwidthborderwidthvisiblebordervisiblenamenexterror
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| type | None | type | The type of the new graphic. This must be of a type that is tagged as being a wxgraphic. |
| point1 | None | point |
The starting point for the graphic. This can be created inline using:
point.new(10, 10) for example. All graphic types use
this property.
|
| point2 | None | point |
The second point of the graphic. This can be created inline using:
point.new(50, 100) for example.
|
| point3 | None | point |
This is the third vertex point for a triangle. Only the triangle type makes
use of this parameter. This can be created inline using:
point.new(80, 60) for example.
|
| midpoint | None | point |
This point represents the center of an ellipse or arc. This can be created
inline using: point.new(10, 10) for example.
|
| rgb | White | integer | The fill color of the new wxgraphic object. In the case of the line object, this is the color of the line, in all others the color of the border lines is handled by the borderrgb parameter. It is inadvisable to specify any value for this argument that is not the value of an existing rgb object. |
| borderrgb | Black | integer | The color of the lines representing the border of the new wxgraphic object. In the case of the line object, this parameter is invalid, use the rgb parameter instead. It is inadvisable to specify any value for this argument that is not the value of an existing rgb object. |
| width | 1 | integer |
This is the width in pixels of a line object. The minimum value is
1. To make the line invisible, set its
visibility to .false.
|
| borderwidth | 1 | integer |
This is the width in pixels of the border of a graphic object. The minimum
value is 1. If no border is desired, set its
visibility to .false.
|
| visible | .true | boolean |
Whether the content of the new graphic is visible or not. In the case of a
line object, this decides if the line is visible, in the case of
the other objects, this decides if the object is filled. If this
portion is set to invisible, then objects behind it will be
visible. To set any fillable object (triangle, rectangle, arc, or
ellipse) to be completely invisible, both this and the
bordervisible properties must be set to
.false.
|
| bordervisible | .true | boolean |
Whether the border of the new graphic is visible or not. This parameter is
invalid for line objects. If this portion is set to invisible,
then no border will be shown. If the visible parameter is also
set to .false, then the entrie graphic will be
invisible.
|
| name | .nul | string | The name of the graphic. This can be used together with the member operator (!) to access the graphic on a template via the wxprintpagetemplate object. |
| next | .nul | type(wxgraphic) |
This determines where in the ring of graphics the new graphic will be placed.
The new graphic will be created so that the graphic specified as
next will be after the new graphic in the
ring. If the next graphic is the current
firstgraphic for the template, then the new
graphic will become the new firstgraphic. If
there are already some graphics on the template and
next is specified to be
.nul then the next graphic will be the current
firstgraphic for the template, but the new
graphic will not become a new firstgraphic
(i.e. it becomes the 'last' graphic).
|
| error | .nul | integer |
Specifies an object which is used to output any error code generated during
creation of the wxgraphic object. If
error is not specified or is
.nul then any error which occurs during object
creation will halt the program. If an error object is specified
and an error occurs during object creation then the error code is
output into that object and the addgraphic
method returns .nul.
|
addstring()
Description
Adds a wxprintstring object to the ring of printstrings. An object of this type is added to hold the content for a wxprinttextitem object that is placed in a template. If the content is used on more than one template, then the string should be added to the printout, if it is the same on each page that uses a specific template, then it should be added to the template, and if it is specific to a given page, then it should be added to the page.
| Note |
|---|---|
The name of any item: page, string, bitmap, etc. that can be accessed using the member operator must be unique across all rings associated with an object. For example in the case of a printout object, the same name cannot be assigned to a page and also to a string or a bitmap. The same name can also not be given to two items in the same ring. |
Prototype
wxprintpagetemplatevar.addstring (
string stringnamenext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| string | "" | string | The content for this wxprintstring object. |
| name | .nul | string | The name of the wxprintstring object. This value is used to link the object with the wxprinttextitem that will use it to provide the content for an item on a printed page. |
| next | .nul | wxprintstring |
This determines where in the ring of strings the new string will be placed.
The new string will be created so that the string specified as
next will be after the new string in the
ring. If the next string is the current
firststring for the printout, then the new
string will become the new firststring. If
there are already some strings in the printout and
next is specified to be
.nul then the next string will be the current
firststring for the printout, but the new
string will not become a new firststring
(i.e. it becomes the 'last' string).
|
addtextitem()
Description
Creates a new wxprinttextitem object using the given arguments for many of the item's properties.
| Note |
|---|---|
The name of any item: page, string, bitmap, etc. that can be accessed using the member operator must be unique across all rings associated with an object. For example in the case of a printout object, the same name cannot be assigned to a page and also to a string or a bitmap. The same name can also not be given to two items in the same ring. |
Prototype
wxprintpagetemplatevar.addtextitem (
integer lefttopwidthheightbackgroundvisiblebackgroundrgbtextrgbalignmentfontundergraphicsunderbitmapscontentsourcecontentnamenamenext
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| left | None | integer | The position of the left side of the new text item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| top | None | integer | The position of the top edge of the new text item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| width | None | integer | The width of the new text item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| height | None | integer | The height of the new text item on the template, in micrometers. The item must be fully contained within the bounds of the template. |
| backgroundvisible | .true | boolean | Establishes whether the background of the text item is visible or transparent. |
| backgroundrgb | The current background color of the template | integer | The background color of the new text item. It is inadvisable to specify any value for this argument that is not the value of an existing rgb object. |
| textrgb | Black | integer | The color of the text in the new text item. It is inadvisable to specify any value for this argument that is not the value of an existing rgb object. |
| alignment | "" | string |
The alignment of the text within the new text item. The default is
.nul, which will be left and top aligned.
Valid values are: "left",
"right", "top",
"bottom", "left,top",
"right,bottom",
"left,bottom", and
"right,top". To center something both
horizontally and vertically, use the empty string. If a value for
a dimension is not supplied, such as with
"left" by itself, then the unspecified
dimension will be centered.
|
| font | .nul | wxfont | A valid wxfont object that will be used as the font for the associated text. |
| undergraphics | .false | boolean | Decides whether the text item is in front or behind the wxgraphic items. |
| underbitmaps | .false | boolean | Decides whether the text item is in front or behind the bitmap items. This parameter determines whether the text item appears above or below the bitmap items that have the same undergraphics setting. Text items that are on top of the graphics are (of course) on top of all text and bitmap items that are under the graphics, and text items that are under the graphics are always under all objects that are on top of the graphics. |
| contentsource | "" | string |
This contains the source of the text item, either
"printout", "template",
"page", "system" or the
empty string (""). If the value of this is the
empty string, then nothing will be printed.
|
| contentname | "" | string |
This is the name of the item that is stored in the content source and which is
used to provide the actual content for the item when printed. If
the source is "system" then the name must be
"pagenumber", which will supply the current
page number in the printout. If the value of this is the empty
string, then nothing will be printed.
|
| name | .nul | string | The name of the new text item. |
| next | .nul | wxprinttextitem |
This determines where in the ring of text items the new text item will be
placed. The new text item will be created so that the text item
specified as next will be after the new
text item in the ring. If the next text
item is the current firsttextitem for the
template, then the new text item will become the new
firsttextitem. If there are already some
text items in the template and next is
specified to be .nul then the next text item
will be the current firsttextitem for the
template, but the new text item will not become a new
firsttextitem (i.e. it becomes a 'last' text
item). Items are bottom to top in the z-order of the template, so
that an item later in the ring covers an item located earlier in
the ring.
|
setbackgroundrgb()
Description
Sets the background color of the template. The
wxprintpagetemplate object itself is returned, to allow
multiple setting methods to be put into one expression. It is an
error to specify both the rgb argument and one or
more of the red, green or
blue arguments.
Prototype
wxprintpagetemplatevar.setbackgroundrgb (
integer rgbredgreenblue
Parameters
| Parameter | Default value | Type name | Description |
|---|---|---|---|
| rgb | The current value of the backgroundrgb
property | integer | The new background color of the page. It is inadvisable to specify any value for this argument which is not the value of an existing rgb object. |
| red | The current value of the backgroundrgb.red
property | integer | The red component in the new background color of the page. This must be between 0 and 255 inclusive. |
| green | The current value of the backgroundrgb.green
property | integer | The green component in the new background color of the page. This must be between 0 and 255 inclusive. |
| blue | The current value of the backgroundrgb.blue
property | integer | The blue component in the new background color of the page. This must be between 0 and 255 inclusive. |
wxprintpagetemplate!
Get
If there is a graphic of the name following the member operator, then the graphic is returned, otherwise if there is a string of that name, then the string is returned, otherwise if there is a bitmap of that name the bitmap is returned, otherwise if there is a text item of that name the text item is returned, otherwise if there is a bitmap item of that name then the bitmap item is returned and if none of these are true an error will occur.
Set
Attempting to assign a reference or a value to a wxprintpagetemplate object using the ! operator is not supported.