KSvg::FrameSvg Class
class KSvg::FrameSvgProvides an SVG with borders. More...
| Header: | #include <KSvg/FrameSvg> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS Svg)target_link_libraries(mytarget PRIVATE KF6::Svg) |
| Inherits: | KSvg::Svg |
Public Types
| enum | EnabledBorder { NoBorder, TopBorder, BottomBorder, LeftBorder, RightBorder, AllBorders } |
| flags | EnabledBorders |
| enum | LocationPrefix { Floating, TopEdge, BottomEdge, LeftEdge, RightEdge } |
| enum | MarginEdge { TopMargin, BottomMargin, LeftMargin, RightMargin } |
Properties
- enabledBorders : EnabledBorders
Public Functions
| FrameSvg(QObject *parent = nullptr) | |
| QString | actualPrefix() const |
| QPixmap | alphaMask() const |
| bool | cacheAllRenderedFrames() const |
| void | clearCache() |
| QRectF | contentsRect() const |
| KSvg::FrameSvg::EnabledBorders | enabledBorders() const |
| qreal | fixedMarginSize(const KSvg::FrameSvg::MarginEdge edge) const |
| QPixmap | framePixmap() |
| QSizeF | frameSize() const |
| void | getFixedMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const |
(since 5.77) void | getInset(qreal &left, qreal &top, qreal &right, qreal &bottom) const |
| void | getMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const |
| bool | hasElementPrefix(KSvg::FrameSvg::LocationPrefix location) const |
| bool | hasElementPrefix(const QString &prefix) const |
(since 5.77) qreal | insetSize(const KSvg::FrameSvg::MarginEdge edge) const |
(since 5.31) bool | isRepaintBlocked() const |
| qreal | marginSize(const KSvg::FrameSvg::MarginEdge edge) const |
| QRegion | mask() const |
(since 5.101) int | minimumDrawingHeight() |
(since 5.101) int | minimumDrawingWidth() |
| void | paintFrame(QPainter *painter, const QPointF &pos = QPointF(0, 0)) |
| void | paintFrame(QPainter *painter, const QRectF &target, const QRectF &source = QRectF()) |
| QString | prefix() |
| void | resizeFrame(const QSizeF &size) |
| void | setCacheAllRenderedFrames(bool cache) |
| void | setElementPrefix(KSvg::FrameSvg::LocationPrefix location) |
| void | setElementPrefix(const QString &prefix) |
| void | setEnabledBorders(const KSvg::FrameSvg::EnabledBorders borders) |
(since 5.31) void | setRepaintBlocked(bool blocked) |
Reimplemented Public Functions
| virtual void | setImagePath(const QString &path) override |
Detailed Description
When using SVG images for a background of an object that may change its aspect ratio, such as a dialog, simply scaling a single image may not be enough.
FrameSvg allows SVGs to provide several elements for borders as well as a central element, each of which are scaled individually. These elements should be named:
center- the central element, which will be scaled in both directionstop- the top border; the height is fixed, but it will be scaled horizontally to the same width ascenterbottom- the bottom border; scaled in the same way astopleft- the left border; the width is fixed, but it will be scaled vertically to the same height ascenterright- the right border; scaled in the same way aslefttopleft- fixed size; must be the same height astopand the same width asleftbottomleft,topright,bottomright- similar totopleft
center must exist, but all the others are optional. topleft and topright will be ignored if top does not exist, and similarly for bottomleft and bottomright.
See also KSvg::Svg.
Member Type Documentation
enum FrameSvg::EnabledBorder
flags FrameSvg::EnabledBorders
This flag enum specifies which borders should be drawn.
| Constant | Value |
|---|---|
KSvg::FrameSvg::NoBorder | 0 |
KSvg::FrameSvg::TopBorder | 1 |
KSvg::FrameSvg::BottomBorder | 2 |
KSvg::FrameSvg::LeftBorder | 4 |
KSvg::FrameSvg::RightBorder | 8 |
KSvg::FrameSvg::AllBorders | TopBorder | BottomBorder | LeftBorder | RightBorder |
The EnabledBorders type is a typedef for QFlags<EnabledBorder>. It stores an OR combination of EnabledBorder values.
enum FrameSvg::LocationPrefix
| Constant | Value | Description |
|---|---|---|
KSvg::FrameSvg::Floating | 0 | Free floating. |
KSvg::FrameSvg::TopEdge | 1 | Along the top of the screen. |
KSvg::FrameSvg::BottomEdge | 2 | Along the bottom of the screen. |
KSvg::FrameSvg::LeftEdge | 3 | Along the left side of the screen. |
KSvg::FrameSvg::RightEdge | 4 | Along the right side of the screen. |
enum FrameSvg::MarginEdge
| Constant | Value | Description |
|---|---|---|
KSvg::FrameSvg::TopMargin | 0 | The top margin. |
KSvg::FrameSvg::BottomMargin | 1 | The bottom margin. |
KSvg::FrameSvg::LeftMargin | 2 | The left margin. |
KSvg::FrameSvg::RightMargin | 3 | The right margin. |
Property Documentation
enabledBorders : EnabledBorders
Access functions:
| KSvg::FrameSvg::EnabledBorders | enabledBorders() const |
| void | setEnabledBorders(const KSvg::FrameSvg::EnabledBorders borders) |
Member Function Documentation
[explicit] FrameSvg::FrameSvg(QObject *parent = nullptr)
Constructs a new FrameSvg that paints the proper named subelements as borders. It may also be used as a regular KSvg::Svg object for direct access to elements in the Svg.
parent options QObject to parent this to
See also KSvg::Theme.
QString FrameSvg::actualPrefix() const
This method returns the prefix that is actually being used (including a '-' at the end if not empty).
See also prefix().
QPixmap FrameSvg::alphaMask() const
This method returns a pixmap whose alpha channel is the opacity of the frame. It may be the frame itself or a special frame with the "mask-" prefix.
[invokable] bool FrameSvg::cacheAllRenderedFrames() const
This method returns whether all the different prefixes should be kept in a cache when rendered.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also setCacheAllRenderedFrames().
[invokable] void FrameSvg::clearCache()
This method deletes the internal cache.
Calling this method frees memory. Use this if you want to switch the rendered element and you don't plan to switch back to the previous one for a long time.
This only works if setUsingRenderingCache(true) has been called.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also KSvg::Svg::setUsingRenderingCache().
[invokable] QRectF FrameSvg::contentsRect() const
This method returns the rectangle of the center element, taking the margins into account.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
KSvg::FrameSvg::EnabledBorders FrameSvg::enabledBorders() const
This is a convenience method to get the enabled borders. Returns what borders are painted
Note: Getter function for property enabledBorders.
See also setEnabledBorders().
[invokable] qreal FrameSvg::fixedMarginSize(const KSvg::FrameSvg::MarginEdge edge) const
This method returns the margin size for the specified edge.
Compared to marginSize(), this does not depend on whether the margin is enabled or not.
edge the margin edge we want, top, bottom, left or right Returns the margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QPixmap FrameSvg::framePixmap()
This method returns a pixmap of the SVG represented by this object.
elementId the ID string of the element to render, or an empty string for the whole SVG (the default).
Returns a QPixmap of the rendered SVG
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QSizeF FrameSvg::frameSize() const
Returns the size of the frame
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] void FrameSvg::getFixedMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const
This is a convenience method that extracts the size of the four margins and saves their size into the passed variables.
Compared to getMargins(), this doesn't depend on whether the margins are enabled or not.
left left margin size
top top margin size
right right margin size
bottom bottom margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable, since 5.77] void FrameSvg::getInset(qreal &left, qreal &top, qreal &right, qreal &bottom) const
This is a convenience method that extracts the size of the four inset margins and saves their size into the passed variables.
left left margin size
top top margin size
right right margin size
bottom bottom margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.77.
[invokable] void FrameSvg::getMargins(qreal &left, qreal &top, qreal &right, qreal &bottom) const
This is a convenience method that extracts the size of the four margins and saves their size into the passed variables.
If you don't care about the margins being on or off, use getFixedMargins() instead.
left left margin size
top top margin size
right right margin size
bottom bottom margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] bool FrameSvg::hasElementPrefix(KSvg::FrameSvg::LocationPrefix location) const
This is an overloaded method provided for convenience that is equivalent to hasElementPrefix("north"), hasElementPrefix("south") hasElementPrefix("west") and hasElementPrefix("east").
Returns true if the svg has the necessary elements with the given prefix to draw a frame.
location the given prefix we want to check if drawable
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] bool FrameSvg::hasElementPrefix(const QString &prefix) const
This method returns whether the SVG has the necessary elements with the given prefix to draw a frame.
prefix the given prefix we want to check if drawable (can have trailing '-' since 5.59)
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable, since 5.77] qreal FrameSvg::insetSize(const KSvg::FrameSvg::MarginEdge edge) const
This method returns the insets margin size for the specified edge.
edge the margin edge we want, top, bottom, left or right
Returns the margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.77.
[since 5.31] bool FrameSvg::isRepaintBlocked() const
This method returns whether we are in a transaction of many changes at once.
This is used to restrict rebuilding generated graphics for each change made.
This function was introduced in 5.31.
[invokable] qreal FrameSvg::marginSize(const KSvg::FrameSvg::MarginEdge edge) const
This method returns the margin size for the given edge.
Note that 0 will be returned if the given margin is disabled.
If you don't care about the margin being on or off, use fixedMarginSize() instead.
edge the margin edge we want, top, bottom, left or right
Returns the margin size
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QRegion FrameSvg::mask() const
This method returns a mask that tightly contains the fully opaque areas of the SVG.
Returns a region of opaque areas
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable, since 5.101] int FrameSvg::minimumDrawingHeight()
This method returns the minimum height required to correctly draw this SVG.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.101.
[invokable, since 5.101] int FrameSvg::minimumDrawingWidth()
This method returns the minimum width required to correctly draw this SVG.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
This function was introduced in 5.101.
[invokable] void FrameSvg::paintFrame(QPainter *painter, const QPointF &pos = QPointF(0, 0))
This method paints the loaded SVG with the elements that represents the border.
This is an overloaded member provided for convenience
painter the QPainter to use
pos where to paint the svg
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] void FrameSvg::paintFrame(QPainter *painter, const QRectF &target, const QRectF &source = QRectF())
This method paints the loaded SVG with the elements that represents the border.
painter the QPainter to use
target the target rectangle on the paint device
source the portion rectangle of the source image
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] QString FrameSvg::prefix()
This method returns the prefix for SVG elements of the FrameSvg (including a '-' at the end if not empty).
Returns the prefix
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also actualPrefix().
[invokable] void FrameSvg::resizeFrame(const QSizeF &size)
This method resizes the frame, maintaining the same border size.
size the new size of the frame
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[invokable] void FrameSvg::setCacheAllRenderedFrames(bool cache)
This method sets whether saving all the rendered prefixes in a cache or not.
cache whether to use the cache.
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also cacheAllRenderedFrames().
[invokable] void FrameSvg::setElementPrefix(KSvg::FrameSvg::LocationPrefix location)
This method sets the prefix to 'north', 'south', 'west' and 'east' when the location is TopEdge, BottomEdge, LeftEdge and RightEdge, respectively. Clears the prefix in other cases.
The prefix must exist in the SVG document, which means that this can only be called successfully after setImagePath is called.
location location in the UI this frame will be drawn
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
See also hasElementPrefix() and setElementPrefix.
[invokable] void FrameSvg::setElementPrefix(const QString &prefix)
This method sets the prefix for the SVG elements to be used for painting.
For example, if prefix is 'active', then instead of using the 'top' element of the SVG file to paint the top border, the 'active-top' element will be used. The same goes for other SVG elements.
If the elements with prefixes are not present, the default ones are used. (for the sake of speed, the test is present only for the 'center' element)
Setting the prefix manually resets the location to Floating.
The prefix must exist in the SVG document, which means that this can only be called successfully after setImagePath is called.
prefix prefix for the SVG elements that make up the frame
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
void FrameSvg::setEnabledBorders(const KSvg::FrameSvg::EnabledBorders borders)
This method sets which borders should be painted.
borders the borders we want to paint
Note: Setter function for property enabledBorders.
See also enabledBorders() and EnabledBorder.
[override virtual invokable] void FrameSvg::setImagePath(const QString &path)
Reimplements: Svg::setImagePath(const QString &svgFilePath).
Loads a new Svg imagePath the new file
Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.
[since 5.31] void FrameSvg::setRepaintBlocked(bool blocked)
This method sets whether we should block rebuilding generated graphics for each change made.
Setting this to true will block rebuilding the generated graphics for each change made and will do these changes in blocks instead.
How to use this method: When making several changes at once to the frame properties–such as prefix, enabled borders, and size–set this property to true to avoid regenerating the graphics for each change. Set it to false again after applying all required changes.
Note that any change will not be visible in the painted frame while this property is set to true.
This function was introduced in 5.31.
See also isRepaintBlocked().