com.trolltech.qt.gui
Class QGraphicsLayoutItem

java.lang.Object
  com.trolltech.qt.QSignalEmitter
      com.trolltech.qt.QtJambiObject
          com.trolltech.qt.gui.QGraphicsLayoutItem

All Implemented Interfaces:

QGraphicsLayoutItemInterface, QtJambiInterface

public abstract class QGraphicsLayoutItem
extends QtJambiObject
implements QGraphicsLayoutItemInterface

The QGraphicsLayoutItem class can be inherited to allow your custom items to be managed by layouts. QGraphicsLayoutItem is an abstract class that defines a set of virtual functions describing sizes, size policies, and size hints for any object arranged by QGraphicsLayout. The API contains functions relevant for both the item itself and for the user of the item as most of QGraphicsLayoutItem's functions are also part of the subclass' public API.

In most cases, existing layout-aware classes such as QGraphicsWidget and QGraphicsLayout already provide the functionality you require. However, subclassing these classes will enable you to create both graphical elements that work well with layouts (QGraphicsWidget) or custom layouts (QGraphicsLayout).

Subclassing QGraphicsLayoutItem

If you create a subclass of QGraphicsLayoutItem and reimplement its virtual functions, you will enable the layout to resize and position your item along with other QGraphicsLayoutItems including QGraphicsWidget and QGraphicsLayout.

You can start by reimplementing important functions: the protected sizeHint() function, as well as the public setGeometry() function. If you want your items to be aware of immediate geometry changes, you can also reimplement updateGeometry().

The geometry, size hint, and size policy affect the item's size and position. Calling setGeometry() will always resize and reposition the item immediately. Normally, this function is called by QGraphicsLayout after the layout has been activated, but it can also be called by the item's user at any time.

The sizeHint() function returns the item' minimum, preferred and maximum size hints. You can override these properties by calling setMinimumSize(), setPreferredSize() or setMaximumSize(). You can also use functions such as setMinimumWidth() or setMaximumHeight() to set only the width or height component if desired.

The effectiveSizeHint() function, on the other hand, returns a size hint for any given Qt::SizeHint , and guarantees that the returned size is bound to the minimum and maximum sizes and size hints. You can set the item's vertical and horizontal size policy by calling setSizePolicy(). The sizePolicy property is used by the layout system to describe how this item prefers to grow or shrink.

Nesting QGraphicsLayoutItems

QGraphicsLayoutItems can be nested within other QGraphicsLayoutItems, similar to layouts that can contain sublayouts. This is done either by passing a QGraphicsLayoutItem pointer to QGraphicsLayoutItem's protected constructor, or by calling setParentLayoutItem(). The parentLayoutItem() function returns a pointer to the item's layoutItem parent. If the item's parent is 0 or if the the parent does not inherit from QGraphicsItem, the parentLayoutItem() function then returns 0. isLayout() returns true if the QGraphicsLayoutItem subclass is itself a layout, or false otherwise.

Qt uses QGraphicsLayoutItem to provide layout functionality in the The Graphics View Framework, but in the future its use may spread throughout Qt itself.

See also:

QGraphicsWidget, QGraphicsLayout, QGraphicsLinearLayout, and QGraphicsGridLayout.

Nested Class Summary

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter

QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9

Constructor Summary

QGraphicsLayoutItem()
Constructs the QGraphicsLayoutItem object.

QGraphicsLayoutItem(QGraphicsLayoutItemInterface parent)
Constructs the QGraphicsLayoutItem object.

QGraphicsLayoutItem(QGraphicsLayoutItemInterface parent, boolean isLayout)
Constructs the QGraphicsLayoutItem object.

Method Summary

QRectF	contentsRect() Returns the contents rect in local coordinates.
QSizeF	effectiveSizeHint(Qt.SizeHint which) Returns the effective size hint for this QGraphicsLayoutItem.
QSizeF	effectiveSizeHint(Qt.SizeHint which, QSizeF constraint) Returns the effective size hint for this QGraphicsLayoutItem.
static QGraphicsLayoutItem	fromNativePointer(QNativePointer nativePointer) This method returns the QGraphicsLayoutItem instance pointed to by nativePointer.
QRectF	geometry() Returns the item's geometry (e.g., position and size) as a QRectF.
QMarginsF	getContentsMargins() This virtual function provides the left, top, right and bottom contents margins for this QGraphicsLayoutItem.
boolean	isLayout() Returns true if this QGraphicsLayoutItem is a layout (e.g., is inherited by an object that arranges other QGraphicsLayoutItem objects); otherwise returns false.
double	maximumHeight() Returns the maximum height.
QSizeF	maximumSize() Returns the maximum size.
double	maximumWidth() Returns the maximum width.
double	minimumHeight() Returns the minimum height.
QSizeF	minimumSize() Returns the minimum size.
double	minimumWidth() Returns the minimum width.
QGraphicsLayoutItemInterface	parentLayoutItem() Returns the parent of this QGraphicsLayoutItem, or 0 if there is no parent, or if the parent does not inherit from QGraphicsLayoutItem (QGraphicsLayoutItem is often used through multiple inheritance with QObject-derived classes).
double	preferredHeight() Returns the preferred height.
QSizeF	preferredSize() Returns the preferred size.
double	preferredWidth() Returns the preferred width.
void	setGeometry(QRectF rect) This pure virtual function sets the geometry of the QGraphicsLayoutItem to rect, which is in parent coordinates (e.g., the top-left corner of rect is equivalent to the item's position in parent coordinates).
void	setMaximumHeight(double height) Sets the maximum height to height.
void	setMaximumSize(double w, double h) This convenience function is equivalent to calling setMaximumSize(QSizeF(w, h)).
void	setMaximumSize(QSizeF size) Sets the maximum size to size.
void	setMaximumWidth(double width) Sets the maximum width to width.
void	setMinimumHeight(double height) Sets the minimum height to height.
void	setMinimumSize(double w, double h) This convenience function is equivalent to calling setMinimumSize(QSizeF(w, h)).
void	setMinimumSize(QSizeF size) Sets the minimum size to size.
void	setMinimumWidth(double width) Sets the minimum width to width.
void	setParentLayoutItem(QGraphicsLayoutItemInterface parent) Sets the parent of this QGraphicsLayoutItem to parent.
void	setPreferredHeight(double height) Sets the preferred height to height.
void	setPreferredSize(double w, double h) This convenience function is equivalent to calling setPreferredSize(QSizeF(w, h)).
void	setPreferredSize(QSizeF size) Sets the preferred size to size.
void	setPreferredWidth(double width) Sets the preferred width to width.
void	setSizePolicy(QSizePolicy.Policy hPolicy, QSizePolicy.Policy vPolicy) This function is equivalent to calling setSizePolicy(QSizePolicy(hPolicy, vPolicy, controlType)).
void	setSizePolicy(QSizePolicy.Policy hPolicy, QSizePolicy.Policy vPolicy, QSizePolicy.ControlType controlType) This function is equivalent to calling setSizePolicy(QSizePolicy(hPolicy, vPolicy, controlType)).
void	setSizePolicy(QSizePolicy policy) Sets the size policy to policy.
QSizeF	sizeHint(Qt.SizeHint which) This pure virtual function returns the size hint for which of the QGraphicsLayoutItem, using the width or height of constraint to constrain the output.
abstract QSizeF	sizeHint(Qt.SizeHint which, QSizeF constraint) This pure virtual function returns the size hint for which of the QGraphicsLayoutItem, using the width or height of constraint to constrain the output.
QSizePolicy	sizePolicy() Returns the current size policy.
void	updateGeometry() This virtual function discards any cached size hint information.

Methods inherited from class com.trolltech.qt.QtJambiObject

dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr

Methods inherited from class com.trolltech.qt.QSignalEmitter

blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread

Methods inherited from class java.lang.Object

clone, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.trolltech.qt.QtJambiInterface

disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership

Constructor Detail

QGraphicsLayoutItem

public QGraphicsLayoutItem(QGraphicsLayoutItemInterface parent)

Constructs the QGraphicsLayoutItem object. parent becomes the object's parent. If isLayout is true the item is a layout, otherwise isLayout is false.

QGraphicsLayoutItem

public QGraphicsLayoutItem()

Constructs the QGraphicsLayoutItem object. parent becomes the object's parent. If isLayout is true the item is a layout, otherwise isLayout is false.

QGraphicsLayoutItem

public QGraphicsLayoutItem(QGraphicsLayoutItemInterface parent,
                           boolean isLayout)

Constructs the QGraphicsLayoutItem object. parent becomes the object's parent. If isLayout is true the item is a layout, otherwise isLayout is false.

Method Detail

contentsRect

public final QRectF contentsRect()

Returns the contents rect in local coordinates.

The contents rect defines the subrectangle used by an associated layout when arranging subitems. This function is a convenience function that adjusts the item's geometry() by its contents margins. Note that getContentsMargins() is a virtual function that you can reimplement to return the item's contents margins.

See also:

getContentsMargins(), and geometry().

Specified by:

contentsRect in interface QGraphicsLayoutItemInterface

effectiveSizeHint

public final QSizeF effectiveSizeHint(Qt.SizeHint which)

Returns the effective size hint for this QGraphicsLayoutItem.

which is the size hint in question. constraint is an optional argument that defines a special constrain when calculating the effective size hint. By default, constraint is QSizeF(-1, -1), which means there is no constraint to the size hint.

If you want to specify the widget's size hint for a given width or height, you can provide the fixed dimension in constraint. This is useful for widgets that can grow only either vertically or horizontally, and need to set either their width or their height to a special value.

For example, a text paragraph item fit into a column width of 200 may grow vertically. You can pass QSizeF(200, -1) as a constraint to get a suitable minimum, preferred and maximum height).

You can adjust the effective size hint by reimplementing sizeHint() in a QGraphicsLayoutItem subclass, or by calling one of the following functions: setMinimumSize(), setPreferredSize, or setMaximumSize() (or a combination of both).

This function caches each of the size hints and guarantees that sizeHint() will be called only once for each value of which - unless constraint is not specified and updateGeometry() has been called.

See also:

sizeHint().

effectiveSizeHint

public final QSizeF effectiveSizeHint(Qt.SizeHint which,
                                      QSizeF constraint)

Returns the effective size hint for this QGraphicsLayoutItem.

which is the size hint in question. constraint is an optional argument that defines a special constrain when calculating the effective size hint. By default, constraint is QSizeF(-1, -1), which means there is no constraint to the size hint.

If you want to specify the widget's size hint for a given width or height, you can provide the fixed dimension in constraint. This is useful for widgets that can grow only either vertically or horizontally, and need to set either their width or their height to a special value.

For example, a text paragraph item fit into a column width of 200 may grow vertically. You can pass QSizeF(200, -1) as a constraint to get a suitable minimum, preferred and maximum height).

You can adjust the effective size hint by reimplementing sizeHint() in a QGraphicsLayoutItem subclass, or by calling one of the following functions: setMinimumSize(), setPreferredSize, or setMaximumSize() (or a combination of both).

This function caches each of the size hints and guarantees that sizeHint() will be called only once for each value of which - unless constraint is not specified and updateGeometry() has been called.

See also:

sizeHint().

Specified by:

effectiveSizeHint in interface QGraphicsLayoutItemInterface

geometry

public final QRectF geometry()

Returns the item's geometry (e.g., position and size) as a QRectF. This function is equivalent to QRectF(pos(), size()).

See also:

setGeometry().

Specified by:

geometry in interface QGraphicsLayoutItemInterface

isLayout

public final boolean isLayout()

Returns true if this QGraphicsLayoutItem is a layout (e.g., is inherited by an object that arranges other QGraphicsLayoutItem objects); otherwise returns false.

See also:

QGraphicsLayout.

Specified by:

isLayout in interface QGraphicsLayoutItemInterface

maximumHeight

public final double maximumHeight()

Returns the maximum height.

See also:

setMaximumHeight(), setMaximumSize(), and maximumSize().

Specified by:

maximumHeight in interface QGraphicsLayoutItemInterface

maximumSize

public final QSizeF maximumSize()

Returns the maximum size.

See also:

setMaximumSize(), minimumSize(), preferredSize(), Qt::MaximumSize , and sizeHint().

Specified by:

maximumSize in interface QGraphicsLayoutItemInterface

maximumWidth

public final double maximumWidth()

Returns the maximum width.

See also:

setMaximumWidth(), setMaximumSize(), and maximumSize().

Specified by:

maximumWidth in interface QGraphicsLayoutItemInterface

minimumHeight

public final double minimumHeight()

Returns the minimum height.

See also:

setMinimumHeight(), setMinimumSize(), and minimumSize().

Specified by:

minimumHeight in interface QGraphicsLayoutItemInterface

minimumSize

public final QSizeF minimumSize()

Returns the minimum size.

See also:

setMinimumSize(), preferredSize(), maximumSize(), Qt::MinimumSize , and sizeHint().

Specified by:

minimumSize in interface QGraphicsLayoutItemInterface

minimumWidth

public final double minimumWidth()

Returns the minimum width.

See also:

setMinimumWidth(), setMinimumSize(), and minimumSize().

Specified by:

minimumWidth in interface QGraphicsLayoutItemInterface

parentLayoutItem

public final QGraphicsLayoutItemInterface parentLayoutItem()

Returns the parent of this QGraphicsLayoutItem, or 0 if there is no parent, or if the parent does not inherit from QGraphicsLayoutItem (QGraphicsLayoutItem is often used through multiple inheritance with QObject-derived classes).

See also:

setParentLayoutItem().

Specified by:

parentLayoutItem in interface QGraphicsLayoutItemInterface

preferredHeight

public final double preferredHeight()

Returns the preferred height.

See also:

setPreferredHeight(), setPreferredSize(), and preferredSize().

Specified by:

preferredHeight in interface QGraphicsLayoutItemInterface

preferredSize

public final QSizeF preferredSize()

Returns the preferred size.

See also:

setPreferredSize(), minimumSize(), maximumSize(), Qt::PreferredSize , and sizeHint().

Specified by:

preferredSize in interface QGraphicsLayoutItemInterface

preferredWidth

public final double preferredWidth()

Returns the preferred width.

See also:

setPreferredWidth(), setPreferredSize(), and preferredSize().

Specified by:

preferredWidth in interface QGraphicsLayoutItemInterface

setMaximumHeight

public final void setMaximumHeight(double height)

Sets the maximum height to height.

See also:

maximumHeight(), setMaximumSize(), and maximumSize().

Specified by:

setMaximumHeight in interface QGraphicsLayoutItemInterface

setMaximumSize

public final void setMaximumSize(QSizeF size)

Sets the maximum size to size. This property overrides sizeHint() for Qt::MaximumSize and ensures that effectiveSizeHint() will never return a size larger than size. In order to unset the maximum size, use an invalid size.

See also:

maximumSize(), minimumSize(), preferredSize(), Qt::MaximumSize , and sizeHint().

Specified by:

setMaximumSize in interface QGraphicsLayoutItemInterface

setMaximumSize

public final void setMaximumSize(double w,
                                 double h)

This convenience function is equivalent to calling setMaximumSize(QSizeF(w, h)).

See also:

maximumSize(), setMinimumSize(), setPreferredSize(), and sizeHint().

Specified by:

setMaximumSize in interface QGraphicsLayoutItemInterface

setMaximumWidth

public final void setMaximumWidth(double width)

Sets the maximum width to width.

See also:

maximumWidth(), setMaximumSize(), and maximumSize().

Specified by:

setMaximumWidth in interface QGraphicsLayoutItemInterface

setMinimumHeight

public final void setMinimumHeight(double height)

Sets the minimum height to height.

See also:

minimumHeight(), setMinimumSize(), and minimumSize().

Specified by:

setMinimumHeight in interface QGraphicsLayoutItemInterface

setMinimumSize

public final void setMinimumSize(QSizeF size)

Sets the minimum size to size. This property overrides sizeHint() for Qt::MinimumSize and ensures that effectiveSizeHint() will never return a size smaller than size. In order to unset the minimum size, use an invalid size.

See also:

minimumSize(), maximumSize(), preferredSize(), Qt::MinimumSize , sizeHint(), setMinimumWidth(), and setMinimumHeight().

Specified by:

setMinimumSize in interface QGraphicsLayoutItemInterface

setMinimumSize

public final void setMinimumSize(double w,
                                 double h)

This convenience function is equivalent to calling setMinimumSize(QSizeF(w, h)).

See also:

minimumSize(), setMaximumSize(), setPreferredSize(), and sizeHint().

Specified by:

setMinimumSize in interface QGraphicsLayoutItemInterface

setMinimumWidth

public final void setMinimumWidth(double width)

Sets the minimum width to width.

See also:

minimumWidth(), setMinimumSize(), and minimumSize().

Specified by:

setMinimumWidth in interface QGraphicsLayoutItemInterface

setParentLayoutItem

public final void setParentLayoutItem(QGraphicsLayoutItemInterface parent)

Sets the parent of this QGraphicsLayoutItem to parent.

See also:

parentLayoutItem().

Specified by:

setParentLayoutItem in interface QGraphicsLayoutItemInterface

setPreferredHeight

public final void setPreferredHeight(double height)

Sets the preferred height to height.

See also:

preferredHeight(), preferredWidth(), setPreferredSize(), and preferredSize().

Specified by:

setPreferredHeight in interface QGraphicsLayoutItemInterface

setPreferredSize

public final void setPreferredSize(QSizeF size)

Sets the preferred size to size. This property overrides sizeHint() for Qt::PreferredSize and provides the default value for effectiveSizeHint(). In order to unset the preferred size, use an invalid size.

See also:

preferredSize(), minimumSize(), maximumSize(), Qt::PreferredSize , and sizeHint().

Specified by:

setPreferredSize in interface QGraphicsLayoutItemInterface

setPreferredSize

public final void setPreferredSize(double w,
                                   double h)

This convenience function is equivalent to calling setPreferredSize(QSizeF(w, h)).

See also:

preferredSize(), setMaximumSize(), setMinimumSize(), and sizeHint().

Specified by:

setPreferredSize in interface QGraphicsLayoutItemInterface

setPreferredWidth

public final void setPreferredWidth(double width)

Sets the preferred width to width.

See also:

preferredWidth(), preferredHeight(), setPreferredSize(), and preferredSize().

Specified by:

setPreferredWidth in interface QGraphicsLayoutItemInterface

setSizePolicy

public final void setSizePolicy(QSizePolicy.Policy hPolicy,
                                QSizePolicy.Policy vPolicy)

This function is equivalent to calling setSizePolicy(QSizePolicy(hPolicy, vPolicy, controlType)).

See also:

sizePolicy(), and QWidget::sizePolicy().

setSizePolicy

public final void setSizePolicy(QSizePolicy.Policy hPolicy,
                                QSizePolicy.Policy vPolicy,
                                QSizePolicy.ControlType controlType)

This function is equivalent to calling setSizePolicy(QSizePolicy(hPolicy, vPolicy, controlType)).

See also:

sizePolicy(), and QWidget::sizePolicy().

Specified by:

setSizePolicy in interface QGraphicsLayoutItemInterface

setSizePolicy

public final void setSizePolicy(QSizePolicy policy)

Sets the size policy to policy. The size policy describes how the item should grow horizontally and vertically when arranged in a layout.

QGraphicsLayoutItem's default size policy is (QSizePolicy::Fixed , QSizePolicy::Fixed , QSizePolicy::DefaultType ), but it is common for subclasses to change the default. For example, QGraphicsWidget defaults to (QSizePolicy::Preferred , QSizePolicy::Preferred , QSizePolicy::DefaultType ).

See also:

sizePolicy(), and QWidget::sizePolicy().

Specified by:

setSizePolicy in interface QGraphicsLayoutItemInterface

sizePolicy

public final QSizePolicy sizePolicy()

Returns the current size policy.

See also:

setSizePolicy(), and QWidget::sizePolicy().

Specified by:

sizePolicy in interface QGraphicsLayoutItemInterface

setGeometry

public void setGeometry(QRectF rect)

This pure virtual function sets the geometry of the QGraphicsLayoutItem to rect, which is in parent coordinates (e.g., the top-left corner of rect is equivalent to the item's position in parent coordinates).

Reimplement this function in a subclass of QGraphicsLayoutItem to enable your item to receive geometry updates.

If rect is outside of the bounds of minimumSize and maximumSize, it will be adjusted to its closest size so that it is within the legal bounds.

See also:

geometry().

Specified by:

setGeometry in interface QGraphicsLayoutItemInterface

sizeHint

public final QSizeF sizeHint(Qt.SizeHint which)

This pure virtual function returns the size hint for which of the QGraphicsLayoutItem, using the width or height of constraint to constrain the output.

Reimplement this function in a subclass of QGraphicsLayoutItem to provide the necessary size hints for your items.

See also:

effectiveSizeHint().

sizeHint

public abstract QSizeF sizeHint(Qt.SizeHint which,
                                QSizeF constraint)

This pure virtual function returns the size hint for which of the QGraphicsLayoutItem, using the width or height of constraint to constrain the output.

Reimplement this function in a subclass of QGraphicsLayoutItem to provide the necessary size hints for your items.

See also:

effectiveSizeHint().

Specified by:

sizeHint in interface QGraphicsLayoutItemInterface

updateGeometry

public void updateGeometry()

This virtual function discards any cached size hint information. You should always call this function if you change the return value of the sizeHint() function. Subclasses must always call the base implementation when reimplementing this function.

See also:

effectiveSizeHint().

Specified by:

updateGeometry in interface QGraphicsLayoutItemInterface

fromNativePointer

public static QGraphicsLayoutItem fromNativePointer(QNativePointer nativePointer)

This method returns the QGraphicsLayoutItem instance pointed to by nativePointer.

getContentsMargins

public final QMarginsF getContentsMargins()

This virtual function provides the left, top, right and bottom contents margins for this QGraphicsLayoutItem. The default implementation assumes all contents margins are 0. The parameters point to values stored in qreals. If any of the pointers is 0, that value will not be updated.

See also:

QGraphicsWidget::setContentsMargins().

Specified by:

getContentsMargins in interface QGraphicsLayoutItemInterface