FlowListLayoutProperties

#include <bb/cascades/FlowListLayoutProperties>

Layout properties that are assigned to controls in a FlowListLayout.

This class represents layout properties that you can assign to controls in a ListView. The ListView must use a FlowListLayout as its layout.

FlowListLayoutProperties can be used to link the size of items in a FlowListLayout to the size of the ListView, with padding and margins taken into consideration.

This QML example demonstrates how to use FlowListLayoutProperties on the root node of an item visual declared in a ListItemComponent. If all items in this example are of the type "item", the items are arranged in a grid containing three square-shaped images per row. Note that this particular example could have been implemented more easily by using GridListLayout, since all items are the same size.

ListView {
    dataModel: XmlDataModel { source: "model.xml" }
    layout: FlowListLayout { headerMode: ListHeaderMode.None }
    listItemComponents: [
        ListItemComponent {
            type: "item"

            ImageView {
                rightMargin: 6
                bottomMargin: 6
                imageSource: ListItemData.imagePath
                layoutProperties: FlowListLayoutProperties {
                    aspectRatio: 1
                    fillRatio: 1/3
                }
            }
        }
    ]
}

This class can only be used with children of a ListView that uses a FlowListLayout. If you attempt to use this class with another type of Layout, it is ignored.

See:

ListView, FlowListLayout

Since:

BlackBerry 10.0.0

Inheritance

bb::cascades::BaseObject
	bb::cascades::UIObject
		bb::cascades::LayoutProperties
			bb::cascades::FlowListLayoutProperties

QML properties

aspectRatio	: float
fillRatio	: float
attachedObjects	: QDeclarativeListProperty< QObject > [read-only]
objectName	: QString
parent	: QObject [read-only]

QML signals

onAspectRatioChanged	: {}
onFillRatioChanged	: {}
onCreationCompleted	: {}
onObjectNameChanged	: {}

Properties Index

float	aspectRatio
float	fillRatio
QDeclarativeListProperty< QObject >	attachedObjects [read-only]
QString	objectName
QObject	parent [read-only]

Public Functions Index

	FlowListLayoutProperties ()
virtual	~FlowListLayoutProperties ()
float	aspectRatio () const
Q_SLOT void	setAspectRatio (float _aspectRatio)
Q_SLOT void	resetAspectRatio ()
float	fillRatio () const
Q_SLOT void	setFillRatio (float _fillRatio)
Q_SLOT void	resetFillRatio ()
virtual bool	event (QEvent *event)
void	setObjectName (const QString &name)
virtual Q_INVOKABLE QString	toDebugString () const

Static Public Functions Index

Builder	create (QObject *parent=0)
Builder	updateFor (Control *targetControl)

Protected Functions Index

Only has inherited protected functions

	BaseObject (QObject *parent=0)
virtual void	connectNotify (const char *signal)
virtual void	disconnectNotify (const char *signal)

Signals Index

void	aspectRatioChanged (float aspectRatio)
void	fillRatioChanged (float fillRatio)
void	creationCompleted ()
void	objectNameChanged (const QString &objectName)

Properties

float aspectRatio

The aspect ratio (width divided by height) for the Control.

If set, FlowListLayout ignores the value set on either preferredWidth (in horizontal lists) or preferredHeight (in vertical lists) on the item visual root node, and instead calculates the preferredWidth or preferredHeight from the layout height or width of the Control by using one of these equations:

Horizontal list: width = height * aspectRatio Vertical list: height = width / aspectRatio

For example, a value of 1.3333 (or simply 4/3) for the aspectRatio ensures that width = 1.3333 * height for the item visual, regardless of whether the list orientation is vertical or horizontal.

The properties minWidth, maxWidth, minHeight, and maxHeight on the item visual root are not affected by this property. They still limit the size of the item visual.

If this property is set to 0 or less, no aspect ratio is taken into account.

The default value is -1.

Since:

BlackBerry 10.0.0

float fillRatio

The size of the Control, as a fraction of the ListView size.

This property specifies the desired width or height (width in vertical lists, height in horizontal lists) of the item visual, expressed as a fraction of the ListView width or height (minus padding and item margins). If set, FlowListLayout ignores the value set for preferredWidth or preferredHeight on the item visual root node, and instead uses a value calculated using fillRatio.

For example, a value of 0.3333 (or simply 1/3) for fillRatio causes the item to use one third of the available size in the row/column, so that there's room for two more items of the same size in that row/column.

There's room for three items on a row when fillRatio is 0.3333 for all of them, even if the items have margins. This is because the available size on a row is reduced by the size of the margins between the items, before calculating the size of each item using the fillRatio.

The properties minWidth, maxWidth, minHeight, and maxHeight on the item visual root are not affected by this property. They still limit the size of the item visual.

If this property is set to 0 or less, no size ratio is taken into account.

The default value is -1.

Since:

BlackBerry 10.0.0

QDeclarativeListProperty< QObject > attachedObjects[read-only]

A hierarchical list of the UIObject's attached objects.

This QDeclarativeListProperty can contain any QObject. When a QObject is added to property, the UIObject takes ownership of the attached object.

This feature is typically used from QML to specify business logic object or any other shared objects for the subnodes of this UIObject. In C++ the same functionality can be achived by setting a parent of a QObject to be attached to the QObject which is going to own it.

QML usage example (MyObject is a custom class registered for QML using the qmlRegisterType() function):

Container {
    Label { text: "Title: " + myObject.title } 
    Label { text: "Subject: " + myObject.subject }
    attachedObjects: [
        MyObject { id: myObject
            title: "Hello World"
            subject: "Nice Day"
        }
    ]
}

Since:

BlackBerry 10.0.0

QString objectName

This property is overridden from QObject.

As the objectName property is overridden from the QObject class, this signal will not be emitted if setObjectName() function is called directly on QObject.

The default value of this property is QString::null.

See:

QObject::objectName().

Since:

BlackBerry 10.0.0

QObject parent[read-only]

A read-only property that represents this object's parent.

The parent of an object is specified using QObject::setParent(QObject*). The purpose of the property is to expose the object's parent to QML.

This property is read-only to prevent modifications from QML, where typically the parent is declaratively set. In C++ code, the parent can be explicitly set using QObject::setParent(QObject*), or implicitly set by adding it to a visual container.

The default value of this property is 0.

Since:

BlackBerry 10.0.0

Public Functions

FlowListLayoutProperties ()

Constructs a FlowListLayoutProperties object.

Since:

BlackBerry 10.0.0

virtual~FlowListLayoutProperties ()

Destructor.

float aspectRatio ()

Returns the aspect ratio of the Control.

Return:

The aspect ratio of the Control.

Since:

BlackBerry 10.0.0

Q_SLOT void setAspectRatio (
float_aspectRatio)

Sets the aspect ratio of the Control.

After the aspect ratio is set, the aspectRatioChanged() signal is emitted.

Parameters
_aspectRatio	The new aspect ratio of the Control.

Since:

BlackBerry 10.0.0

Q_SLOT void resetAspectRatio ()

Resets the aspect ratio to its default value.

The default aspect ratio is a negative value.

After the aspect ratio is reset, the aspectRatioChanged() signal is emitted.

Since:

BlackBerry 10.0.0

float fillRatio ()

Returns the fill ratio of the Control.

Return:

The fill ratio of the Control.

Since:

BlackBerry 10.0.0

Q_SLOT void setFillRatio (
float_fillRatio)

Sets the fill ratio of the Control.

After the fill ratio is set, the fillRatioChanged() signal is emitted.

Parameters
_fillRatio	The fill ratio of the Control.

Since:

BlackBerry 10.0.0

Q_SLOT void resetFillRatio ()

Resets the fill ratio to its default value.

The default fill ratio is a negative value.

After the fill ratio is reset, the fillRatioChanged() signal is emitted.

Since:

BlackBerry 10.0.0

virtual bool event (
QEvent *event)

Overloaded to implement the event mechanism in Cascades.

Warning:

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
event	The received event.

Return:

True if the received event was recognized and processed, false otherwise.

Since:

BlackBerry 10.0.0

void setObjectName (
const QString &name)

Sets the objectName property.

Parameters
name	The new name for the object.

Since:

BlackBerry 10.0.0

virtual Q_INVOKABLE QString toDebugString ()

Returns a debug string representing this object.

Return:

A debug string for the object.

Since:

BlackBerry 10.0.0

Static Public Functions

Builder create (
QObject *parent)

Creates and returns a builder for constructing flow list layout properties.

Using the builder to create a FlowListLayoutProperties object:

FlowListLayoutProperties* layoutProperties = FlowListLayoutProperties::create()
        .aspectRatio(0.5);
        .fillRatio(0.5);

Return:

A builder used for constructing a FlowListLayoutProperties object.

Since:

BlackBerry 10.0.0

Builder updateFor (
Control *targetControl)

Builds and sets the flow list layout properties for a control.

If the control already has a FlowListLayoutProperties set on it, the original layout properties remain as is. Otherwise, a new FlowListLayoutProperties object is created and set as the layout properties for the control.

Using the builder to set a control's FlowListLayoutProperties:

Label *pLabel = Label::create().text("Hello World!");
FlowListLayoutProperties::updateFor(pLabel).fillRatio(2.0f);

Parameters
targetControl	The control to set the layout properties for.

Return:

A builder used for constructing a FlowListLayoutProperties object.

Since:

BlackBerry 10.0.0

Protected Functions

(Only has inherited protected functions)

BaseObject (
QObject *parent)

Constructs an instance of BaseObject's subclass.

Parameters
parent	An optional parent, defaults to 0.

Since:

BlackBerry 10.0.0

virtual void connectNotify (
const char *signal)

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal	The connected signal.

Since:

BlackBerry 10.0.0

virtual void disconnectNotify (
const char *signal)

Overloaded to implement the event mechanism in Cascades.

If this function is overridden, it must be called by the derived class for events to work properly in Cascades.

Parameters
signal	The disconnected signal.

Since:

BlackBerry 10.0.0

Signals

void aspectRatioChanged (
floataspectRatio)

Emitted when the aspectRatio property changes.

Parameters
aspectRatio	The new aspect ratio of the Control.

Since:

BlackBerry 10.0.0

void fillRatioChanged (
floatfillRatio)

Emitted when the fillRatio property changes.

Parameters
fillRatio	The new fill ratio of the Control.

Since:

BlackBerry 10.0.0

void creationCompleted ()

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node, or when an object is being constructed using its builder class.

This signal is emitted only when this object is instantiated as a result of loading a QML document and creating the root node (only after the root component that caused this instantiation has completed construction), or when the object is being constructed from its builder class. This signal is emitted to indicate that the construction and initialization of the object has been completed, the properties are initialized, and any QML binding values have been assigned to the object.

This signal is not emitted when the object is constructed from C++ using the constructor. If the object is constructed using its builder class, the signal is emitted when the the builder class returns the fully constructed object.

This signal can be used when there is an activity that needs to be performed, such as a property state integrity verification after the object is instantiated from a QML document or a builder, but before control is returned to the application.

See:

QmlDocument

Since:

BlackBerry 10.0.0

void objectNameChanged (
const QString &objectName)

This signal is emitted when the objectName property is changed.

See:

QObject, BaseObject::objectName.

Since:

BlackBerry 10.0.0

FlowListLayoutProperties

Inheritance

QML properties

QML signals

Properties Index

Public Functions Index

Static Public Functions Index

Protected Functions Index

Signals Index

Properties

float aspectRatio

float fillRatio

QDeclarativeListProperty< QObject > attachedObjects[read-only]

QString objectName

QObject parent[read-only]

Public Functions

FlowListLayoutProperties ()

virtual~FlowListLayoutProperties ()

float aspectRatio ()

Q_SLOT void setAspectRatio (float_aspectRatio)

Q_SLOT void resetAspectRatio ()

float fillRatio ()

Q_SLOT void setFillRatio (float_fillRatio)

Q_SLOT void resetFillRatio ()

virtual bool event (QEvent *event)

void setObjectName (const QString &name)

virtual Q_INVOKABLE QString toDebugString ()

Static Public Functions

Builder create (QObject *parent)

Builder updateFor (Control *targetControl)

Protected Functions

BaseObject (QObject *parent)

virtual void connectNotify (const char *signal)

virtual void disconnectNotify (const char *signal)

Signals

void aspectRatioChanged (floataspectRatio)

void fillRatioChanged (floatfillRatio)

void creationCompleted ()

void objectNameChanged (const QString &objectName)

Q_SLOT void setAspectRatio (
float_aspectRatio)

Q_SLOT void setFillRatio (
float_fillRatio)

virtual bool event (
QEvent *event)

void setObjectName (
const QString &name)

Builder create (
QObject *parent)

Builder updateFor (
Control *targetControl)

BaseObject (
QObject *parent)

virtual void connectNotify (
const char *signal)

virtual void disconnectNotify (
const char *signal)

void aspectRatioChanged (
floataspectRatio)

void fillRatioChanged (
floatfillRatio)

void objectNameChanged (
const QString &objectName)