ListItemListener

Since: BlackBerry 10.0.0

#include <bb/cascades/ListItemListener>

An optional interface for VisualNodes used as items in a ListView.

The functions in this interface are called by ListView in order to visualize different item states. The interface contains three functions that you can override if you want to customize the behavior that occurs when they're invoked: select() is called whenever a visible list item is selected, activate() is called when an already visible item becomes activated, and reset() is called when a list item is about to be shown.

A ListView only calls the functions if the object implementing this interface is the root node in an item visual. For example, if the implemented object is placed as a child to a Container in the item visual, the ListView won't call any functions on it.

Here's a declaration for a class called MyItemClass that implements ListItemListener. In addition to overriding the member functions of ListItemListener, an additional function called updateItem() is declared.

class MyItemClass: public bb::cascades::CustomControl, public ListItemListener
{
Q_OBJECT

public:
    MyItemClass(Container *parent=0);

    void updateItem(const QString text, const QString imagePath);

    void select(bool select);

    void reset(bool selected, bool activated);

    void activate(bool activate);

private:
    ImageView *mItemImage;
    Label *mItemLabel;
    Container *mHighlighContainer;
};     

In the constructor for MyItemClass, a VisualNode object is created representing the list item. It contains an image and a label as well as an overlay that is used to show when an item is highlighted.

MyItemClass::MyItemClass(Container *parent) :
        CustomControl(parent)
{
    // Dock layout with margins inside.
    Container *itemContainer = new Container();
    DockLayout *itemLayout = new DockLayout();
    itemContainer->setLayout(itemLayout);

    // A background Container that will hold the item content Container.
    Container *backgroundContainer = new Container();
    DockLayout *backgroundLayout = new DockLayout();
    backgroundContainer->setLayout(backgroundLayout);
    backgroundContainer->setHorizontalAlignment(HorizontalAlignment::Center);

    // A Colored Container will be used to show if an item is highlighted.
    mHighlighContainer = new Container();
    mHighlighContainer->setBackground(Color::fromARGB(0xff75b5d3));
    mHighlighContainer->setHorizontalAlignment(HorizontalAlignment::Center);
    mHighlighContainer->setOpacity(0.0);
    mHighlighContainer->setPreferredWidth(760.0f);
    mHighlighContainer->setPreferredHeight(168.0f);

    // Content Container, Image + text with padding to get alignment on background image.
    Container *contentContainer = new Container();
    StackLayout *contentLayout = new StackLayout();
    contentLayout->setOrientation(LayoutOrientation::LeftToRight);
    contentContainer->setLayout(contentLayout);

    // The list item image, docked to the top, the actual image is set in updateItem.
    mItemImage =
            ImageView::create("").preferredSize(250.0f, 168.0f).layoutProperties(
                    StackLayoutProperties::create().vertical(VerticalAlignment::Top));

    // A list item label, docked to the center, the text is set in updateItem.
    mItemLabel = Label::create().text(" ").layoutProperties(
    StackLayoutProperties::create().vertical(VerticalAlignment::Center));
    mItemLabel->textStyle()->setBase(SystemDefaults::TextStyles::titleText());
   
    // Add the Image and Label to the content.
    contentContainer->add(mItemImage);
    contentContainer->add(mItemLabel);

    // Add the content to the full item container.
    backgroundContainer->add(mHighlighContainer);
    backgroundContainer->add(contentContainer);

    // Finally add the background Container to the item Container.
    itemContainer->add(backgroundContainer);

    setRoot(itemContainer);
}

When the application invokes updateItem(), the label and the image are updated with new data from the data model. Each of the select(), reset(), and activate() functions are overridden to provide custom functionality when they're invoked.

void MyItemClass::updateItem(const QString text, const QString imagePath)
{
    // Update image and text for the current item.
    mItemImage->setImage(Image(imagePath));
    mItemLabel->setText(text);
}

void MyItemClass::select(bool select)
{
    // When an item is selected show the colored highlight Container
    if(select) {
        mHighlighContainer->setOpacity(0.9f);
    } else {
        mHighlighContainer->setOpacity(0.0f);
    }
}

void MyItemClass::reset(bool selected, bool activated)
{
    Q_UNUSED(activated);

    // Since items are recycled the reset function is where we have
    // to make sure that item state, defined by the arguments, is correct.
    select(selected);
}

void MyItemClass::activate(bool activate)
{
    // There is no special activate state, select and activated looks the same.
    select(activate);
}


Overview

Inheritance

bb::cascades::ListItemListener
bb::cascades::StandardListItem

Public Functions Index

virtual ~ListItemListener ()
voidactivate (bool activate)=0
voidreset (bool selected, bool activated)=0
voidselect (bool select)=0

Protected Functions Index

Public Functions

virtual~ListItemListener ()

Destructor.

void activate (
  • boolactivate)

Called by ListView when an already visible item is active.

Parameters
activate

true if the item is active, false if deactivated

Since:

BlackBerry 10.0.0

void reset (
  • boolselected,
  • boolactivated )

Called by ListView when an item is about to be shown.

When updating the visuals for the item, animations may NOT be used.

Parameters
selected

true if the item should appear selected, false if deselected

activated

true if the item should appear active, false if deactivated

Since:

BlackBerry 10.0.0

void select (
  • boolselect)

Called by ListView when an already visible item becomes selected.

When updating the visuals for the item, animations may be used.

Parameters
select

true if the item has been selected, false if deselected

Since:

BlackBerry 10.0.0

Protected Functions

ListItemListener ()

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus