Development/Tutorials/Plasma4/JavaScript/API-Painting: Difference between revisions

From KDE TechBase
(→‎Svg: Document the SVG image lookup order)
 
(No difference)

Latest revision as of 23:27, 11 September 2014

Painting

See the "Painting and Layout" section, part of the Global Plasmoid object chapter, for information on using these classes within a widget.

Pixmaps

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap constructor:

    var pixmap = new QPixmap("myimage.png")

In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Read-only properties:

  • boolean null: true if the pixmap is empty
  • QRectF rect: the rect of the pixmap

Functions:

  • QPixmap scaled(number width, number height): returns a scaled version of the pixmap with width and height dimensions.

Icons

(Since 4.4.1)

The QIcon object provides simple access to icons. They can be constructed using a String or a QPixmap, with the String version either loading a file from disk if given an absolute path (useful for loading icons from the Plasmoid's package) or from the desktop icon theme if given just a name (e.g. "file-open").

Read-only properties:

  • boolean null: true if the icon is empty

Functions:

  • addPixmap(QPixmap): adds another pixmap to this icon
  • addFile(String): adds another file to this icon

SVG Images

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

Svg

Constructors:

  • Svg(string fileName)': fileName can be a file in the desktop theme or the plasmoid package; it will first look in the "images" directory of the plasmoid package, then in the current desktop theme (and its fallbacks), then (from 4.11 onwards) in the "theme" directory of the plasmoid package.

Read-only properties:

  • QSizeF size: the current size of the svg

Read-write properties:

  • boolean multipleImages: whether or not the svg contains multiple separate images
  • string imagePath: the file path, including name of the svg
  • boolean 'usingRenderingCache: whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

Functions:

  • QSizeF elementSize(String svgElemen)
  • QRectF elementRect(String svgElemen)
  • boolean hasElement(String svgElement)
  • elementAtPoint(QPoint pos)
  • boolean isValid()
  • QPixmap pixmap(String svgElement): a pixmap of the element in the svg rendered to the current size
  • QPixmap pixmap(): a pixmap of the entire svg rendered to the current size
  • paint(QPainter painter, QPointF point)
  • paint(QPainter painter, QPointF point, String svgElement)
  • paint(QPainter painter, number x, number y)
  • paint(QPainter painter, number x, number y, String svgElement)
  • paint(QPainter painter, QRectF destination)
  • paint(QPainter painter, QRectF destination, String svgElement)
  • paint(QPainter painter, number y, number width, number height)
  • paint(QPainter painter, number x, number y, number width, number height, QString svgElement)
  • resize(number width, number height)
  • resize(QSizeF size)
  • resize(): resizes the SVG to the document size defined in the SVG itself

Signals:

  • repaintNeeded(): emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

FrameSvg

Constructors:

  • FrameSvg(String fileName): fileName can be a file in the desktop theme or the plasmoid package

Read-only properties:

  • boolean multipleImages: whether or not the svg contains multiple separate images

Functions:

  • setEnabledBorders(EnabledBorders borders): sets which borders are enabled when painting
  • EnabledBorders enabledBorders(): the borders which are enabled when painting
  • resizeFrame(QSizeF size): resizes the frame to size
  • QSizeF frameSize(): the size of the current frame
  • number marginSize(MarginEdge margin): the size of the margin for a given edge
  • getMargins(number left, number top, number right, number bottom): stores the margin values in the variables passed in
  • QRectF contentsRect(): the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
  • setElementPrefix(Location): sets the frame element for the given location if it exists
  • setElementPrefix(String prefix): sets the element prefix
  • boolean hasElementPrefix(String prefix): returns true if the SVG contains a frame with the given prefix
  • boolean hasElementPrefix(Location location): true if the SVG contains a frame element for the given location
  • prefix()
  • mask()
  • setCacheAllRenderedFrames(bool)
  • cacheAllRenderedFrames()
  • QPixmap framePixmap(): a pixmap containing the current frame at the current size
  • paintFrame(QPainter painter)
  • paintFrame(QPainter painter, QPointF target)
  • paintFrame(QPainter painter, QRectF target)
  • paintFrame(QPainter painter, QRectF target, QRectF source)

Enumerations

  • EnabledBorder
    • NoBorder
    • TopBorder
    • BottomBorder
    • LeftBorder
    • RightBorder
    • AllBorders

Painting on the Canvas

QColor

  • Constructors:
    • QColor
    • QColor(string colorName)
    • QColor(number red, number green, number blue, number alpha)


Functions:

  • setThemeColor(ThemeColor color): sets the color to the appropriate ThemeColor


Read/write properties:

  • number red
  • number green
  • number blue
  • number alpha
  • boolean valid

QFont

  • Constructors:
    • QFont
    • QFont(string fontName)
    • QFont(string fontName, number pointSize)
    • QFont(string fontName, number pointSize, number weight)
    • QFont(string fontName, number pointSize, number weight, boolean italic)
  • string key
  • string lastResortFamily
  • string lastResortFont
  • string defaultFamily
  • boolean exactMatch
  • string toString
  • boolean bold
  • string family
  • boolean fixedPitch
  • undefined fromString
  • boolean italic
  • boolean kerning
  • boolean overline
  • number pixelSize
  • number pointSize
  • number pointSizeF
  • boolean strikeOut
  • number stretch
  • boolean underline
  • number weight
  • function isCopyOf
  • function resolve

QPainter

  • Constructors
    • QPainter
    • QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
  • object background
  • number backgroundMode
  • object brush
  • undefined setBrush
  • object brushOrigin
  • undefined clipping
  • object clipPath
  • object clipRegion
  • number compositionMode
  • object font
  • number layoutDirection
  • number opacity
  • object pen
  • number renderHints
  • undefined transform
  • object viewport
  • boolean viewTransformEnabled
  • object window
  • object worldMatrix
  • object worldTransform
  • boolean worldMatrixEnabled
  • object combinedMatrix
  • object combinedTransform
  • boolean active
  • function begin
  • function end
  • function boundingRect
  • function drawChord
  • function drawConvexPolygon
  • function drawArc
  • function drawEllipse
  • function drawImage
  • function drawLine
  • function drawLines
  • function drawPath
  • function drawPicture
  • function drawPie
  • function drawPixmap
  • function drawPoint
  • function drawPoints
  • function drawPolygon
  • function drawPolyline
  • function drawRect
  • function drawRects
  • function drawRoundRect
  • function drawText
  • function drawTiledPixmap
  • function eraseRect
  • function fillPath
  • function fillRect
  • function resetMatrix
  • function resetTransform
  • function restore
  • function rotate
  • function save
  • function scale
  • function setClipRect
  • function setRenderHint
  • function shear
  • function strokePath
  • function testRenderHint
  • function toString
  • function translate

QPen

  • Constructors:
    • QPen
  • object brush
  • object color
  • number capStyle
  • number joinStyle
  • number style
  • number dashOffset
  • number miterLimit
  • number width
  • boolean solid
  • number red
  • number green
  • number blue
  • number alpha
  • boolean valid

QRectF

Read-only properties:

  • boolean empty: true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
  • boolean null: true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
  • boolean valid: true if the rectangle has a width > 0 and height 0.

Read-write properties:

  • number left
  • number top
  • number bottom
  • number right
  • number height
  • number width
  • number x
  • number y

Constructors:

  • QRectF
  • QRectF(number x, number y, number width, number height): Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

Functions:

  • adjust(number dx1, number dy1, number dx2, number dy2): adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
  • QRectF adjusted(number dx1, number dy1, number dx2, number dy2): returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
  • translate(number dx, number dy): translates the rect by dx, dy
  • setCoords(number x1, number y1, number x2, number y2): sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
  • setRect(number x, number y, number width, number height): sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
  • boolean contains(number x, number y): returns true if the rect contains the point (x, y)
  • 'moveBottom(number delta): moves the bottom by delta pixels
  • moveLeft(number delta): moves the left by delta pixels
  • moveRight(number delta): moves the right by delta pixels
  • moveTo(number x, number y): moves the top left of the rect to point (x, y)
  • moveTop(number delta): moves the top by delta pixels

QSizeF

  • Constructors:
    • QSizeF
    • QSizeF(number width, number height)
  • number height
  • number width

QPoint

Constructors:

  • QPoint
  • QPoint(number x, number y)

Read-only properties:

  • bool null
  • number manhattanLength

Read-write propertie:

  • number x
  • number y