Package qtwidget provides convenient way
to make drawings and capture user events.
In particular, class QtLuaPainter gives
the ability to draw simple graphics using well known
postscript-like operators. Graphic output can be sent to an
arbitrary widget, to a PS or PDF file, or to a printer.
Class QtLuaListener gives the
ability to listen to events on arbitrary widgets
For instance, the convenient function qtwidget.newwindow creates a main window and returns its descriptor.
require 'qtwidget'
w=qtwidget.newwindow(400,300,"Some QWidget")Drawing is easily achieved using Postscript-like operators.
w:moveto(0,0); w:curveto(0,300,400,0,400,300); w:closepath()
w:setcolor("red"); w:fill(false)
w:setcolor("blue"); w:setlinewidth(5); w:stroke()Text output is of course supported using show.
w:moveto(90,40)
w:setcolor("black")
w:setfont(qt.QFont{serif=true,italic=true,size=20})
w:show("The Quick Brown Fox...")Alpha-transparency works as well.
w:rectangle(50,50,300,200)
w:setcolor(1,1,0,.5)
w:fill()Finally you can capture Qt events using the qt.connect function on the predefined qt.QtLuaListener object,
qt.connect(w.listener,
'sigMousePress(int,int,QByteArray,QByteArray,QByteArray)',
function(...) print("MousePress",...) end );and you can erase everything with
w:showpage()The following convenience functions provide simple ways to perform graphic display whose output is directed to a window on the screen, to an image in memory, to a PostScript file, to a PDF file, or to a printer. Each of these functions return a Lua table that defines a number of useful fields and methods. In particular, all the painting functions defined by class qt.QtLuaPainter can be called directly using the Lua method syntax on these tables.
Expression qtwidget.newwindow(w,h,title) creates a
toplevel widget of class qt.QWidget
and a qt.QtLuaPainter object
operating on that widget.
Numerical arguments w and h specify the size of the widget.
String argument title specifies a window title.
The expression returns a Lua table that
serves as a drawing port descriptor.
Function qtwidget.newimage creates an image in memory
that can be the target of drawing operations.
This function returns a Lua table that
serves as a drawing port descriptor.
There are several ways to specify its arguments:
qtwidget.newimage(w,h,[monoflag])
Creates an image of width w and height h.
When the optional argument monoflag is true,
a bitonal image is created.
Otherwise the image can contain arbitrary RGBA colors.
qtwidget.newimage(filename,[format])
Creates an image by loading the contents of file filename.
The file format is defined by the optional string argument format
or derived from the file name extension.
qtwidget.newimage(torchtensor)
Creates an image by extracting the contents of the specified torch.Tensor. The valid tensor formats are described in the documentation for function qt.QImage.fromTensor. This only works when both packages torch and qttorch have been loaded.
Expression qtwidget.newps(w,h,filename) returns a Lua table that
serves as a drawing port descriptor.
Drawing operations will be output
into the PostScript file filename.
Arguments w and h represent the
initial size of the coordinate system.
The output file contains incomplete data until you delete the painter object or call method close.
Expression qtwidget.newpdf(w,h,filename) returns a Lua table that
serves as a drawing port descriptor.
Drawing operations will be output
into the PDF file filename.
Arguments w and h represent the
initial size of the coordinate system.
The output file contains invalid data until you delete the painter object or call method close.
Expression qtwidget.newsvg(w,h,filename) returns a Lua table that
serves as a drawing port descriptor.
The optional argument filename contains the
name of the destination file for the SVG data.
Arguments w and h represent the
initial size of the coordinate system.
The output contains invalid data until
you delete the painter object or call
method close.
When argument filename is not specified,
the SVG data is written into an internal memory buffer
accessible using expression
desc.svg:data().
Expression qtwidget.newprint(w,h,printername)
returns a Lua table that
serves as a drawing port descriptor.
Drawing operations will be output to printer printername.
When argument printername is omitted,
this function pops a print dialog that allows the user
to choose a printer and specify its settings.
Arguments w and h represent the
initial size of the coordinate system.
All the painting functions defined by class qt.QtLuaPainter can be called directly using the Lua method syntax on the table returned by the functions qtwidget.newwindow, qtwidget.newimage, qtwidget.newps, qtwidget.newpdf, qtwidget.newsvg, and qtwidget.newprint.
These calls are simply forwarded to the underlying qt.QtLuaPainter object.
The following fields and functions are defined on the descriptor tables returned by the functions qtwidget.newwindow, qtwidget.newimage, qtwidget.newps, qtwidget.newpdf, and qtwidget.newprint.
Field desc.port contains the
qt.QtLuaPainter object
that is used to perform the drawings.
Field desc.widget contains the
qt.QWidget object
that underlies drawing port descriptors created with
qtwidget.newwindow.
Field desc.widget contains a
qt.QtLuaListener object.
that can be used to capture events on the widget created by
qtwidget.newwindow.
Field desc.printer contains the
qt.QtLuaPrinter object
that underlies drawing port descriptors created with
qtwidget.newps,
qtwidget.newpdf, or
qtwidget.newprint.
Field desc.svg contains the
qt.QtLuaSvgGenerator object
associated with drawing ports created with
qtwidget.newsvg.
Field desc.width contains the width of the drawing surface.
Field desc.height contains the height of the drawing surface.
Function desc:close() closes the qt.QtLuaPainter.
In the case of a drawing port descriptor returned by function
qtwidget.newwindow,
this function also closes the qt.QWidget
and the windows disappears from the screen.
Function desc:resize(w,h) is only available for
drawing port descriptor returned by function
qtwidget.newwindow.
It resizes the underlying widget.
Function desc:onResize(f) is only available for
drawing port descriptor returned by function
qtwidget.newwindow.
It ensures that
function f(w,h) gets called whenever the widget size changes.
The function argument indicate the new widget size.
Each call of desc:onResize replaces the previous callback function by f.
Calling it with argument nil removes the current callback.
Expression desc:valid() returns false if the
underlying drawing target is no longer valid,
for instance because the window has been closed.
Otherwise it returns true.
Class QtLuaListener emits signals when its parent receives event messages.
This is convenient because the Lua program can define event handling functions
using the signal connection function qt.connect.
Expression qt.QtLuaListener(qwidget) returns a new QtLuaListener object
that relays the event messages received by widget qwidget.
This object is a child of qwidget.
Signal sigClose is emitted when the underlying widget receives a
QCloseEvent.
Signal sigResize is emitted whenever the underlying widget receives a
QResizeEvent
because it has changed size. The two arguments are the new widget size.
Signal sigKeyPress is emitted whenever the underlying widget receives a
QKeyEvent
of type QEvent::KeyPress because a key was pressed on the keyboard.
The first argument is a string representing the text associated with the key.
The second argument is the
key name.
The third argument is a string containing the
keyboard modifier names
separated by a vertical bar.
Signal sigKeyRelease is emitted whenever the underlying widget receives a
QKeyEvent
of type QEvent::KeyRelease because a key was released on the keyboard.
The first argument is a string representing the text associated with the key.
The second argument is the
key name.
The third argument is a string containing the
keyboard modifier names
separated by a vertical bar.
Signal sigMousePress is emitted whenever the underlying widget receives a
QMouseEvent
of type QEvent::MouseButtonPress because a mouse button was pressed.
The first two arguments are the
pixel coordinates of the mouse pointer when the button was clicked
The third argument is a string containing the
button name.
The fourth argument is a string containing the
keyboard modifier names
separated by a vertical bar.
The fifth argument is a string containing the names of all depressed buttons
separated by a vertical bar.
Signal sigMouseRelease is emitted whenever the underlying widget receives a
QMouseEvent
of type QEvent::MouseButtonRelease because a mouse button was released.
The first two arguments are the
pixel coordinates of the mouse pointer when the button was released
The third argument is a string containing the
button name.
The fourth argument is a string containing the
keyboard modifier names
separated by a vertical bar.
The fifth argument is a string containing the names of all depressed buttons
separated by a vertical bar.
Signal sigMouseRelease is emitted whenever the underlying widget receives a
QMouseEvent
of type QEvent::MouseButtonDblClick because a mouse button was double-clicked.
The first two arguments are the
pixel coordinates of the mouse pointer when the button was clicked
The third argument is a string containing the
button name.
The fourth argument is a string containing the
keyboard modifier names
separated by a vertical bar.
The fifth argument is a string containing the names of all depressed buttons
separated by a vertical bar.
Signal sigMouseRelease is emitted whenever the underlying widget receives a
QMouseEvent
of type QEvent::MouseMove because the mouse was moved.
Such events occur only when a mouse button is pressed down,
unless the widget property mouseTracking has been set to true.
The first two arguments are the
pixel coordinates of the mouse pointer when the button was released
The third argument is a string containing the
keyboard modifier names
separated by a vertical bar.
The fourth argument is a string containing the names of all depressed buttons
separated by a vertical bar.
Signal sigEnter is emitted whenever the underlying widget receives an
event of type
QEvent::Enter
or
QEvent::Leave.
The boolean argument indicates whether the mouse pointer has just
entered or left the widget area.
Signal sigEnter is emitted whenever the underlying widget receives
a QFocusEvent.
The boolean argument indicates whether the widget has just gained
or just lost the keyboard focus.
Signal sigEnter is emitted whenever the underlying widget receives
a QShowEvent or a
a QHideEvent.
The boolean argument indicates whether the widget has just been
shown or just been hidden.
Signal sigEnter is emitted whenever the underlying widget receives
a QPaintEvent.
Painting in Qt is usually achieved using class
QPainter.
Since this class is neither a subclass of
QObject
nor a value class suitable for storing into a Qt variant,
the QtLua class QtLuaPainter defines a Qt object that
exposes the painting capabilities of Qt in a more flexible way.
Instances of class QtLuaPainter can target:
- Any image stored in memory represented as a qt.QImage or a qt.QPixmap.
- Any widget represented as a qt.QWidget.
- Any
QPaintDeviceencapsulated in a Qt object class such as class qt.QtLuaPrinter.
Class QtLuaPainter provides an automatic buffering
capability when it targets a widget. Drawing functions
paint onto an offline image. The class logic ensures
that the widget is automatically refreshed or updated
when appropriate.
Despite these differences, the Qt documentation for the Qt paint system contains lots of useful information. In particular, the documentation for class QPainter accurately describes how the painter settings affects drawing operations.
Function qt.QtLuaPainter constructs a new QtLuaPainter instance.
Constructs a painter instance that targets an offscreen image. The image is initialized with a copy of the qt.QImage passed as argument. Painting operations do not modify the image passed as argument. Instead a copy of the current image can be accessed using expression painter:image().
Constructs a painter instance that targets an offscreen image
initialized by reading the image file filename.
The file format is determined by the optional string
format or by the file name extension.
Use expression painter.image() to
obtain a copy of the offscreen image.
Constructs a painter instance that targets an offscreen image
of width w and height h. The image is bitonal when
the optional boolean flag monoflag is true. Otherwise
the image is a 32 bits RGBA image.
Use expression painter.image() to
obtain a copy of the offscreen image.
Constructs a painter instance that targets a
device-dependent pixmap in memory.
The pixmap is initialized with a copy of
the qt.QPixmap passed as argument.
Use expression painter:pixmap().
to obtain a copy of the target pixmap.
Since Qt only supports painting a device-dependent QPixmap from
the main thread, one must use qt.pcall
to ensure that painting operations are performed from the main thread.
Otherwise Qt prints a lot of warnings and behaves erratically.
Constructs a painter instance that targets the
specified qt.QWidget.
The resulting painter is a child of qwidget.
The optional boolean argument buffered indicates
whether drawing should be performed in a offscreen buffer
or directly on the widget surface. The default is to
create a buffered painter.
A buffered painter always draws onto an offscreen image
and ensures that the widget surface is automatically refreshed or
updated when needed. Since the painting functions target
a qt.QImage,
they can be called from any thread at any time.
This is the recommended mode of operation.
An unbuffered painter directly draws onto the widget surface. Unfortunately Qt4 only supports painting a widget from the paint event handler QObject::paintEvent. While this is happening in the main thread, the Lua interpreter might be unavailable for painting because the Lua thread is busy running another program. Unbuffered widget painters are therefore difficult to use for painting; they are mostly useful for grabbing the on-screen representation of a widget using function painter.image().
Constructs a painter instance that target the output
device represented by the instance object of a suitable Qt object class.
The class must implement an invokable method device() that returns
a pointer of type =QPaintDevice*=.
The class can also define an invokable method printer()
that returns a pointer of type QPrinter*= and a signal =closing(QObject*)
that indicates that the object is being destroyed.
Class qt.QtLuaPrinter does all this.
This property contains a string defining how arguments
representing angles are interpreted in painter functions
such as painter:rotate(angle).
The acceptable values are the strings "Degrees" and "Radians".
The default unit is the degree.
This property contains the qt.QBrush used to draw the spaces in stippled lines, the text background, and the zero color of bitonal images. The default background brush is an empty brush meaning that these pixels are not painted at all.
Property painter.brush contains a Qt variant of class
qt.QBrush representing the painter settings
that determine how function painter:fill
fills shapes and how function painter:show
draws text.
Property painter.clippath contient a Qt variant of class
qt.QPainterPath
representing the boundary
of the current clipping region. Drawing operations
only modify pixels located within the clip region.
An empty path means that no clipping is performed.
The
composition mode
defines how new drawings are merged with previous drawings in the image.
Composition modes are representing as a string containing the
name of the composition mode without the prefix QPainter::.
The default composition mode is "SourceOver".
Not all devices support complex alpha-blending composition modes. In particular printers often support only the default composition mode. When a composition mode is not supported, the Qt library prints a warning.
Expression painter.depth returns the color depth
of the target surface for drawings.
A depth of 1 indicates a bitonal surface.
A depth of 24 or 32 indicates a true color surface.
Property painter.font contient a Qt variant of class
qt.QFont representing the font settings
used for drawing text.
Expression painter.height returns the height of
the drawing surface expressed in pixels.
The returned value
is not affected by the current transformation matrix.
It corresponds to the default coordinate system
set by painter:initmatrix.
Property painter.font contient a Qt variant of class
qt.QTransform representing
how coordinates passed to the path construction functions
are transformed into device depending coordinates.
Property painter.path contient a Qt variant of class
qt.QPainterPath
representing the current path.
A path is a mathematical boundary delimiting regions in the plane.
The current path is used implicitely by functions
painter:fill
and painter:stroke.
The current path is modified by a rich collection
of path defining functions.
Property painter.pen contains a Qt variant of class
qt.QPen representing the painter settings
that determine how function painter:stroke
draws shapes.
Property painter.point contient a Qt variant of class
qt.QPointF representing the
coordinates of the current point. These coordinates
are used and updated implicitely by the majority
of the path construction functions.
Rendering hints
are flags controlling the quality of the drawing operations.
They are represented by a string containing the concatenation of
the names of the active rendering flags (without the prefix QPainter::)
separated with a vertical bar "|" symbolizing a boolean or operator.
This property contains a string containing a CSS style sheet that is used when drawing rich text with function show.
Expression painter.width returns the width of
the drawing surface expressed in pixels.
The returned value
is not affected by the current transformation matrix.
It corresponds to the default coordinate system
set by painter:initmatrix.
Class QtLuaPainter provides a broad array of
painting functions that closely resemble
the well-known PostScript operators.
Additional functions provide capabilities
that are unique to the Qt platform.
Expression painter:arc(x,y,r,angle1,angle2)
appends an arc of a circle to the current path.
The arc is centered at coordinates (x,y)
with radius r and extends from angle angle1
to angle angle2 in the trigonometric direction.
If there is a current point, a line segment joins the current point to the first endpoint of the arc. The second endpoint becomes the new current point.
Angles can be expressed in degrees or radians according to the current angle unit. The default angle unit is the degree.
See also: PostScript operator arc.
Expression painter:arcn(x,y,r,angle1,angle2)
appends an arc of a circle to the current path.
The arc is centered at coordinates (x,y)
with radius r and extends from angle angle1
to angle angle2 in the inverse trigonometric direction.
If there is a current point, a line segment joins the current point to the first endpoint of the arc. The second endpoint becomes the new current point.
Angles can be expressed in degrees or radians according to the current angle unit. The default angle unit is the degree.
See also: PostScript operator arcn.
Expression painter:arcto(x1,y1,x2,y2,r)
appends an arc of a circle to the current path
defined by the radius r and two tangent lines
extending from the current point (x0,y0) to (x1,y1)
and from (x1,y1) to (x2,y2).
When the current point is set, a line segment joins the current point to the first endpoint of the arc. The second endpoint becomes the new current point.
See also: PostScript operators arct and arcto.
Expression painter:charpath(string)
computes the path for the glyph outlines that would
result if string string was displayed
using painter:show(string).
This path is appended to the current path
and is therefore suitable for functions
painter:stroke
or painter:fill.
After calling this function, the current point is left unset.
See also: PostScript operators charpath.
Function painter:clip intersects the
current clip region
with the region described by the current path,
that is the region that would be painted by
qtpainter.fill.
This intersection becomes the new clip region.
The optional boolean optnewpath specifies
whether this function resets the current path
using painter:newpath().
The default is to leave the current path unchanged.
The interior of the current path is determined using the
winding rule.
See function painter:eoclip for an alternative.
This function cannot enlarge the clipping path. The recommended approach is to call painter:gsave() before reducing the clip region and painter:grestore() to restore the initial clip region.
See also: PostScript operator clip.
Expression painter:close() detaches
the QtLuaPainter object from the underlying widget.
After doing this, you cannot draw anything.
Painters operating on a widget or a printer should
be closed before the underlying widget
or printer is destroyed.
Expression painter:closepath()
closes the current subpath by appending a
straight line segment connecting the
current point to the subpath to its starting point.
This function does nothing if the current subpath
is already closed.
Using function painter:closepath is better than specifying
the line segment using painter:lineto because it will
ensure that the line segments are joined using the
current pen capStyle and joinStyle attributes.
After calling this function, the current point is left unset.
See also: PostScript operator closepath.
Expression painter:concat(qtransform)
replaces the current transformation matrix
by the product of the current matrix
by the QTransform object qtransform.
It is much easier to use functions painter:translate, painter:scale, or painter:rotate.
See also: PostScript operator concat.
Expression painter:currentangleunit() returns the
current angle unit
for angles in functions such as painter:rotate.
Possible values are strings "Degrees" and "Radians".
The default angle unit are degrees.
Expression painter:currentbackground()
returns a qt.QBrush
representing the current background brush
used for displaying the backgrounds when painting
dashed line, text, or bitonal images.
The default is an empty brush.
Expression painter:currentbrush()
returns a qt.QBrush
representing the current brush
used for filling path with painter:fill().
The default is an empty brush.
Expression painter:currentclip()
returns a QPainterPath
representing the current clip region.
Expression painter:currentcolor()
returns four numbers representing the
red, green, blue, and alpha components
of the color of the current brush.
This numbers range from zero to one.
Expression painter:currentdash()
returns the dash pattern and the dash offset
of the current pen.
Expression painter:currentfont()
returns a QFont
describing the current font
for drawing text.
Expression painter:currentfontsize()
returns the size in points of the
current font.
Expression painter:currenthints() returns the
current rendering hints
controlling the quality of the drawings.
Expression painter:currentlinewidth() returns
the line width associated with the
current pen.
Expression painter:currentmatrix() returns a Qt variant of class
qt.QTransform representing the
current transformation matrix.
Expression painter:currentmode() returns a string representing the
current composition mode.
Expression painter:currentpath() returns a Qt variant of class
qt.QPainterPath representing the
current path.
Expression painter:currentpath() returns a Qt variant of class
qt.QPen representing the
current pen.
Expression painter:currentpoint() returns two numbers
representing the coordinates of the
current point.
Expression painter:currentsize() returns two numbers
representing the width and height of the drawing are
expressed in pixels. The returned values
are not affected by the current transformation matrix.
They correspond to the default coordinate system
sets by painter:initmatrix.
Expression painter:currentstylesheet() returns the
the current style sheet
used by function show for
displaying rich text.
Expression painter:curveto(x1,y1,x2,y2,x3,y3)
appends a section of a cubic Bezier curve to the current path.
The curve starts on the current point and ends in point (x3,y3)
using (x1,y1) and (x2,y2) as the Bezier control points.
The endpoint (x3,y3) then becomes the new current point.
The behavior of this function is undefined when the current point is not set
See also: PostScript operator curveto.
Expression painter:device() returns a pointer to the Qt
paint device underlying the painter.
Since the Qt class
QPaintDevice
is neither a Qt variant not a Qt object, this pointer
is represented by a Qt variant of type =QPaintDevice*=.
This is not very useful in Lua.
Function painter:eoclip is similar to function
painter:clip. However the interior of the
current path is interpreted using the
odd-even rule
instead of the winding rule.
Function painter:eofill is similar to function
painter:fill. However the interior of the
current path is determined using the
odd-even rule
instead of the winding rule.
See also: PostScript operator eofill.
Function painter:fill fills the interior of the
current path using
the current brush.
The optional boolean optnewpath specifies
whether this function resets the current path
using painter:newpath().
The default is to reset the current path.
The interior of the current path is determined using the
winding rule.
See function painter:eofill for an alternative.
See also: PostScript operator fill.
Functions painter:gbegin and
painter:gend can be used
to bracket code segments that perform drawings that
are meaningful as a whole. The actual display is
usually postponed until the last call to painter:gend.
This is useful for implementing smooth transitions
between successive drawings.
Functions painter:gbegin and
painter:gend can be used
to bracket code segments that perform drawings that
are meaningful as a whole. The actual display is
usually postponed until the last call to painter:gend.
This is useful for implementing smooth transitions
between successive drawings.
When the target device is a buffered widget,
setting flag invalidate to true
ensures that the whole widget will be refreshed.
This is useful after drawing directly into
the underlying QPainter object without
using the QtLuaPainter functions.
Expression painter:grestore() restores the painter settings
previously saved by a matching expression painter:gsave().
Functions painter:gsave and painter:restore should be used to bracket code segments that perform some rendering in order to ensure that the painter settings remain unchanged.
Expression painter:gsave() records the painter settings
and pushes this information on top of a stack of painter settings.
Subsequent calls to painter:grestore()
can be used to restore the saved settings.
Functions painter:gsave and painter:restore should be used to bracket code segments that perform some rendering in order to ensure that the painter settings remain unchanged.
Expression painter:image() returns a Qt variant of class
qt.QImage
representing the drawing surface.
When the underlying surface is a widget without backing store,
this function grabs the widget image from the display.
When the painter operates on a device that cannot be represented
as an image, for instance a printer,
this function returns an empty image for which method
tobool returns false.
Note that this function must be invoked without arguments. Otherwise see the documentation for painter:image(...).
Function painter:image paints a segment of image image
at position (x,y) in the current coordinate systems
with with w and height h. The source segment
is defined by the rectangle of size (sw,sh)
starting on point (sx,sy).
The default source width sw and height sh are the width and height of the
source image. The default source origin (sx,sy) is the origin (0,0).
The default target width w and height h are
the source width sw and height sh.
Argument image can be a Qt variant of
class qt.QImage
or qt.QPixmap
or a Qt object of class qt.QtLuaPainter.
In the latter case, the function
painter:image() without arguments
is used to obtain the source surface.
- To blit an image
imgconstructed with qtwidget.newimage, you must specify the associated painter img.port. - To blit a torch.Tensor, first create a qt.QImage using the function qt.QImage.fromTensor from by package qttorch.
Blit is of course affected by the current composition mode.
Note that this function must be invoked with arguments. Otherwise see the documentation for painter:image().
See also: PostScript operator image.
Expression painter:initclip() resets the
current clip region
to the empty path. This effectively means
that clipping is disabled and therefore
that all surface pixels can be affected
by a subsequent drawing operation.
See also: PostScript operator initclip.
Expression painter:initgraphics() resets
all painter settings to their default values.
After calling this function:
- The current clip region is set as with painter:initclip().
- The current transformation matrix is set as with painter:initmatrix().
- The current brush is a solid black brush with brush origin (0,0).
- The current pen is a solid black pen with line width
1, flat caps, and miter joins. - The current background is an empty brush meaning that background pixels are not painted at all.
- The current font is a 10 points sans serif font.
- The current path is empty and the current point is unset.
- The current rendering hints are
"Antialiasing|TextAntialiasing". - The current composition mode is
"SourceOver". - The current angle unit is
"Degrees".
See also: PostScript operator initgraphics.
Expression painter:initmatrix() resets the
current transformation matrix
to its default value.
The coordinate system has then its origin
in the upper left corner of the surface
with X coordinates ordered from left to right
and Y coordinates ordered from top to bottom.
Coordinates are expressed in device pixels
on most devices.
See also: PostScript operator initmatrix.
Expression painter:lineto(x,y) appends
a line segment to the current path,
starting from the current point
and ending at coordinates (x,y).
The segment end point then becomes
the new current point.
The behavior of this function is undefined when the current point is not set
See also: PostScript operator lineto.
Expression painter:moveto(x,y) terminates the
last subpath of the current path and moves
the current point to coordinates (x,y).
See also: PostScript operator moveto.
Expression painter:newpath() terminates the last subpath.
After calling this function, the current point is left unset.
See also: PostScript operator newpath.
Expression painter:object() returns the Qt object
that represents the paint device if such an object exists.
Typical return values are instance of class
qt.QWidget or class
qt.QtLuaPrinter.
Expression painter:painter() returns a pointer
to the underlying Qt painter.
Since the Qt class
QPainter
is neither a Qt variant not a Qt object, this pointer
is represented by a Qt variant of type =QPainter*=.
Expression painter:pixmap() returns a Qt variant of class
qt.QPixmap representing the drawing surface.
When the underlying surface is a widget without backing store,
this function grabs the widget representation from the display.
When the painter operates on a device that cannot be represented
as a pixmap, for instance a printer,
this function returns an empty pixmap for which method
tobool returns false.
Expression painter:printer() returns a pointer
to the underlying Qt printer.
Since the Qt class
QPrinter
is neither a Qt variant not a Qt object, this pointer
is represented by a Qt variant of type =QPrinter*=.
This is similar to calling function painter:curveto with the following arguments
painter:curveto(x0+x1,y0+y1,x0+x2,y0+y2,x0+x3,y0+y3)where (x0,y0) are the coordinates of the previous
current point.
The behavior of this function is undefined when the current point is not set.
See also: PostScript operator rcurveto.
Expression painter:rect() returns a Qt variant
of class =qt.QRect
representing the pixel coordinates of the drawing surface.
This does not depend on the transformation matrix
but corresponds to the default coordinate system
set by painter:initmatrix().
The same information can be obtained more conveniently using function painter:currentsize() or properties painter.width and painter.height.
Expression painter:rectangle(x,y,w,h)
appends a rectangle to the current path.
The rectangle starts is defined by its origin (x,y),
its width w and its height h.
After calling this function, the current point is left unset.
Expression painter:refresh() immediately
repaints the displayed image,
regardless of the nesting count of functions
painter:gbegin() and
painter:gend().
Expression painter:lineto(x,y) appends a line segment
to the current path, starting from the current point (x0,y0)
and ending at coordinates (x0+x,y0+y).
The segment end point then becomes
the new current point.
The behavior of this function is undefined when the current point is not set
See also: PostScript operator rlineto.
Expression painter:moveto(x,y) terminates the
last subpath of the current path and moves
the current point to coordinates (x0+x,y0+y)
where (x0,y0) are the coordinates of the previous
current point.
The behavior of this function is undefined when the current point is not set
See also: PostScript operator rmoveto.
Expression painter:rotate(angle)
rotates the axes of the coordinate system by angle angle units
in the trigonometric direction around the coordinate origin.
The position of the coordinate origin and the size of the coordinate units
are unaffected.
Argument angle can be expressed in degrees or radians
according to the current angle unit.
The default angle unit is the degree.
See also: PostScript operator rotate.
Expression scale(sx,sy) scales the units of the
coordinate space by a factor of sx horizontally and
sy vertically. The position of the coordinate origin and
the orientation of the axes are unaffected.
See also: PostScript operator scale.
Expression painter:setangleunit(unit) sets the
angle unit
for functions such as painter:rotate
that require an angle as argument.
Argument unit must be string "Degrees"
for expressing angles in degrees,
or "Radians" for expressing angles in radians.
The default angle unit is the degree.
Expression painter:setbackground(brush) sets the
current background brush.
Argument brush must be a Qt variant of type
qt.QBrush.
Expression painter:setbrush(brush) sets the
current brush.
Argument brush must be a Qt variant of type
qt.QBrush.
Expression painter:setclip(qpainterpath) sets the
current clipping region
to be the interior of the specified path.
Argument brush must be a Qt variant of type
qt.QPainterPath.
Function painter:setcolor sets the color of both the
current brush
and current pen.
There are several ways to specify a color:
painter:setcolor(qcolor)
Argument qcolor is a Qt variant of
class qt.QColor.
painter:setcolor(string)
Argument string is a string representing a color name.
All SVG color names
are recognized.Color names can have also the format "#RGB",
"#RRGGBB", "#RRRGGGBBB", or ="#RRRRGGGGBBBB"
where letters R, G, or B represent hexadecimal
digits for each of the color component.
painter:setcolor(r,g,b,[a])
Arguments r, g, b, and a are numbers in range [0,1]
representing the intensities of the red, green, blue, and alpha channels.
The default value for argument a is 1 for a fully opaque color.
Function painter:setdash changes the
style of the current pen.
When this function is called without argument,
or when argument sizes is nil,
this function sets the current pen style
to "SolidLine".
Otherwise argument sizes can be a single number or
a table containing a list of numbers.
The number or the list of numbers represent the length of successive
dashes and blanks
along the drawn curve, expressed in units of the line width.
When the size of the sequence is odd, the last blank
is assumed to have the same size as the last dash.
The optional argument offset is a length
representing the starting position of the dash sequence.
Expression painter:setfont(qfont) sets the
current font.
Argument font must be a Qt variant of type
qt.QFont.
Expression painter:setfontsize(size) changes the size
of the current font.
Argument size must be a positive number.
Expression painter:sethints(hints) sets the
current rendering hints.
Argument hints must be a string containing
a concatenation of the names of the active
rendering flags
separated with a vertical bar "|".
Expression painter:setlinewidth(lw) changes the line width
of the current pen.
Argument lw must be a positive number.
Expression painter:setmatrix(qtransform) sets the
current transformation matrix.
Argument qtransform must be a Qt variant of type
qt.QTransform.
Expression painter:setmode(compositionmode) sets the
current composition mode
for subsequent drawing operations.
Argument compositionmode must be a string containing the name of a
composition mode.
Expression painter:setpath(qpainterpath) sets the
current path.
Argument qpainterpath must be a Qt variant of type
qt.QPainterPath.
Expression painter:setpattern(pattern,[x,y])
creates a textured pattern brush.
This brush is used to set both the current brush
and the brush of the current pen.
Argument p can be either a Qt variant
of type qt.QImage or an object
equipped with a method image returning a suitable image.
Such objects include instances of qt.QtLuaPainter
as well as the return values of functions
qtwidget.newwindow
or qtwidget.newimage
The optional arguments x and y specify
the origin of the pattern in the source image.
Expression painter:setpen(qpen) sets the
current pen.
Argument qpen must be a Qt variant of type
qt.QPen.
Expression painter:setpoint(x,y) sets the
current point coordinates to (x,y).
Arguments x and y must be valid numbers.
Expression painter:setstylesheet(s) sets the
the current style sheet
used by function show for
displaying rich text.
Function painter:show draws string string using
the current font.
When called with a single string argument string,
this function draws the specified text
starting from the current point.
After displaying each glyph, the current point is adjusted
with a displacement computed from the font's glyph-spacing information.
The behavior of this function is undefined
when the current point is not set.
When called with more arguments, this function draws
the text string within the rectangle specified by
the origin (x,y), the width w, and the heigth h.
Argument textflags is then a string composed by concatenating
a subset of the following keywords separated
by a vertical bar "|" symbolizing a or operator:
AlignLeft,
AlignRight,
AlignTop,
AlignBottom,
AlignHCenter,
AlignVCenter,
AlignCenter,
AlignJustify.
TextSingleLine,
TextExpandTabs,
TextShowMnemonic,
TextWordWrap,
RichText.
The flag RichText is directly implemented by the QtLuaPainter class.
It indicates that the text contains rich text data using the
subset of HTML
supported by Qt and can be used in conjunction with alignment flags only.
Display is affected by
the current font,
the current brush color, and
the current style sheet.
You can use the css style attribute in HTML tags
to specify more complicated formats.
See also: PostScript operator show.
Expression painter:showpage()
clears the current drawing
and paints the background all white.
Things are a bit different when the painting device is a printer.
Function painter:showpage ensures that the next drawing operation
will first print the current page and initialize a new page.
Successive calls of painter:showpage() do not print multiple pages
unless some drawing operation is performed on each page.
See also: PostScript operator showpage.
Expression painter:size() returns a Qt variant
of class qt.QSize
representing the size in pixels of the drawing surface.
This does not depend on the transformation matrix
but corresponds to the default coordinate system
set by painter:initmatrix().
The same information can be obtained more conveniently using function painter:currentsize() or properties painter.width and painter.height.
Function painter:stringrect returns a Qt variant of type
qt.QRectF representing
the bounding box of the text that would be displayed
by calling function painter:show
with the same arguments.
Fonction painter:stringwidth returns
two numbers representing the total displacement (dx,dy)
that would be applied to the current point
by expression show(string).
See also: PostScript operator stringwidth.
Function painter:stroke draws the boundary of the
current path using
the current pen.
The optional boolean optnewpath specifies
whether this function resets the current path
using painter:newpath().
The default is to reset the current path.
See also: PostScript operator stroke.
Expression translate(dx,dy) translates the coordinate
origin by dx units along the X axis and dy units
along the Y axis. The the size of the coordinate units and
the orientation of the axes are unaffected.
See also: PostScript operator translate.
Expression painter:widget() returns the Qt object of class
qt.QWidget underlying the painter.
When the painter is not associated with a widget,
this expression returns nil.
Expression painter:write(f) saves the image
associated with the painter into the file named f.
Argument f can be a file name or a Lua file descriptor.
The image data is obtained using
function painter:image().
The image format is determined by the
optional string argument format or
deduced from the file name extension.
Printing in Qt is usually achieved using class
QPrinter.
Since this class is neither a subclass of
QObject
nor a value class suitable for storing into a Qt variant,
the QtLua class QtLuaPrinter defines a Qt object that
acts as a thin wrapper for class QPrinter.
Most usual
printer settings
are exposed by class qt.QtLuaPrinter as properties.
Property printer.paperSize
can be used to specify the size of the drawing in pixels.
Printers can be selected using printer.printerName
and PostScript and PDF files can be produced with
properties printer.outputFileName
and printer.outputFormat.
Alternatively, function printer:setup() pops a print dialog
that lets the user adjust these properties interactively.
Expression qt.QtLuaPrinter(mode) returns a
new instance of class qt.QtLuaPrinter.
The optional argument mode is a string specifying
the resolution of the initial coordinate system.
The default value ScreenResolution replicates the screen resolution.
Value HighResolution initializes the coordinate
system with the resolution of the printer.
Most printer properties should be set before creating the qt.QtLuaPainter that will peform the drawings.
Expression printer:abort() aborts the current print run.
Returns true if the print run was successfully aborted.
Property printer.printerState
will then be "Aborted".
It is not always possible to abort a print job.
Boolean property printer.collateCopies specifies
if collation is turned on when multiple copies is selected.
Boolean property printer.colorMode is true
when one prints in color (the default) and false
when one prints in gray scale.
Property printer.creator is a string containing
the name of the application producing the printout.
This information is passed to the print spooling system.
Property printer.creator is a string containing
the name of the document being printed.
This information is passed to the print spooling system
Boolean property printer.doubleSidedPrinting
indicates whether double sided printing is requested.
Boolean property printer.fontEmbeddingEnabled indicates
whether the output data should embed a font description.
This is true by default.
Readonly numerical property printer.fromPage
contains the index of the first page to print.
Use function printer:setFromTo to change it.
Setting boolean property printer.fullPage to true
enables support for painting over the entire page.
Otherwise painting is restricted to the printable area
reported by the device.
Setting boolean property printer.landscape to true
sets the printout in landscape mode.
Otherwise printing happens in portrait mode.
Expression printer:newPage()
tells the printer to eject the current page and
to continue printing on a new page.
Returns true if this was successful.
Property printer.numCopies contains the number of copies to be printed.
The default value is 1.
Qt handles the number of copies in a rather strange way:
the value you obtain by reading property printer.numCopies is not
the value you have set but reports the number of times you should
draw the document in order to achieve the desired effect.
On Windows, Mac OS X and X11 systems that support CUPS,
reading property printer.numCopies always return 1 because these systems
internally handle the number of copies.
Setting property printer.outputFileName to a nonempty
string indicates that printing should be redirected
to the specified file.
Property printer.outputFormat contains a string describing
the output format for this file or printer.
Recognized values are "PdfFormat", "PostScriptFormat",
and "NativeFormat".
Read-only property painter.pageRect contains
a qt.QRect
describing the coordinates of the printable
area of a page.
This rectangle is expressed in coordinates starting from the top-left corner of the page and with units specified according to =printer.resolution. This coordinate system is not related the the drawing coordinate system.
String property printer.pageSize contains the name of the paper format.
The recognized names are
"A4", "B5", "Letter", "Legal", "Executive",
"A0", "A1", "A2", "A3", "A5", "A6",
"A7", "A8", "A9", "B0", "B1",
"B10", "B2", "B3", "B4", "B6",
"B7", "B8", "B9", "C5E", "Comm10E",
"DLE", "Folio", "Ledger", and "Tabloid".
When using Qt-4.4 or greater,
this property can also contain the value "Custom"
to indicate that the produced output must
describe an image whose size matches
exactly the specified paper size.
When using an earlier version of Qt,
setting this property to "Custom" does nothing.
Read-only property painter.paperRect contains
a qt.QRect
describing the full size of the paper.
This rectangle is expressed in coordinates starting from the top-left corner of the page and with units specified according to printer.resolution. This coordinate system is not related the the drawing coordinate system.
Property printer.paperSize contains a
qt.QSizeF
describing the desired size of the drawable area.
When this property contains a valid size, that is a size with positive width and height, the painter initial coordinate system is adjusted to display the specified drawable area within the desired page size.
Furthermore, with Qt-4.4. or greater,
when property printer.pageSize
is equal to "Custom", property printer.paperSize
also specifies the size of the image described
by the output file.
Returns a pointer to the real QPrinter object
which is a subclass of QPaintDevice.
Setting string property printer.printProgram overrides
the name of the program used to submit the printout
to the spooling system.
String property printer.printerName
contains the name of the target printer.
This value is initially set to the name of the
default printer for your system.
Readonly string property printer.printerState
returs a string describing the state of the printer.
Possible values are Idle, Active, Aborted and Error.
That does not work on all systems.
Numerical property printer.resolution
contains the resolution of the printer.
This is initially set by the mode argument
of the constructor qt.QtLuaPrinter(mode).
The resolution affects the coordinate systems
for properties printer.paperRect
and printer.pageRect.
It only affects the drawing coordinate systems
when property printer.papersize
does not contain a valid size.
Function printer:setFromTo
specifies the indices of the page range to print.
If both frompage and topage are zero (the default),
the whole document is printed.
Expression printer:setup() displays a dialog
allowing the user to choose a printer
and select various print settings.
It returns true if the user presses the button "Print"
and false if the user cancels.
Readonly numerical property printer.toPage
contains the index of the last page to print.
Use function printer:setFromTo to change it.