Пример работы с Hierarchical Lists API (SingleStyleTreeList) - S60 Touch UI

From Forum Nokia Wiki

Статья базируется на материалах англоязычной части Wiki, все они перечислены в разделе ссылки.

1 Обзор
2 Hierarchical Lists API
3 Реализация иерархического списка SingleStyleTreeList
- 3.1 HierarchicalListsAppView.h
- 3.2 HierarchicalListsAppView.cpp
4 Как добавить новый узел в дерево списка
5 Как удалить узел из дерева списка
6 Как добавить потомка (leaf) в узел, находящийся в фокусе
7 Как добавить потомка из узела, находящегося в фокусе
8 Как целиком удалить дерево списка
9 Полезные функции
10 Ключевые моменты
11 Демонстрационное приложение
12 Связанные ссылки
13 Источники дополнительной информации

Обзор

Hierarchical Lists API позволяет представить данные в виде иерархического списка, текста и графики. Это новый компонент пользовательского интерфейса, доступный начиная с S60 5-го издания. В данной статье мы рассмотрим пример работы с этим API.

Hierarchical Lists API

Иерархические списки используются для представления структур данных в виде дерева списка
Существует три типа списков:
- Иерархический список общего назначения, представленный в виде дерева
- A single-column style list (пункты списка могут быть представлены в виде строки текста с основной иконкой (плюс опциональная возможность отображения еще двух иконок). Пункты списка могут быть двух видов:
  - узел (node) (например, папка в списке директорий)
  - лист (leaf) (например, файл в папке)
- A single-style tree. Пункты списка могут быть трех типов:
  - Простая строка данных (Simple data row) - это простой пункт списка типа лист (leaf), состоящий из одной строки текста, одной основной иконки (и еще одной опциональной). По-умолчанию данному типу иконки не назначаются.
  - Основная строка данных (Core data row) - это простой пункт списка типа лист (leaf), состоящий из строки текста, разделенной на 3 колонки (3-я отображается только при ландшафтной ориентации экрана), одной основной иконки (и еще двух опциональных). По-умолчанию данному типу иконки не назначаются.
  - Subtitle row - это тип похож на простые строки данных (simple data row), но кроме того может иметь различные иконки в зависимости от состояния (узел свернут/развернут). По-умолчанию данному типу назначаются системные иконки открытой/закрытой папки, соответствующие состоянию узла.
Для обработки событий от иерархического списка необходимо реализовать интерфейс класса MAknTreeListObserver

Реализация иерархического списка SingleStyleTreeList

HierarchicalListsAppView.h

Унаследуем класс от MAknTreeListObserver и реализуем его виртуальную функцию HandleTreeListEvent для получения и обработки событий от SingleStyleTreeList.
Объявляем объект CAknSingleStyleTreeList членом класса и используем его для того, чтобы назначить наблюдателя (observer), который будет обрабатывать события.

...
...
#include <aknsinglestyletreelist.h>
#include <akntreelist.h>
 
// CLASS DECLARATION
class CHierarchicalListsAppView : public CCoeControl, public MAknTreeListObserver
    {
        .....
        .....
        //From MAknTreeListObserver
        virtual void HandleTreeListEvent( CAknTreeList& aList, TAknTreeItemID aItem, TEvent aEvent );
 
        //For SingleStyleTreeList
        void CreateHierarchicalSingleStyleListL();
        void AddNodeL();
        void AddLeafL();
        void DeleteNodeL();
        void DeleteLeafL();
        void DeleteTreeL();
 
        //From CCoeControl
        TInt CountComponentControls() const;
        CCoeControl* ComponentControl(TInt aIndex) const;
        .....
    private:
        CAknSingleStyleTreeList* iSingleStyleTreeList;
        ....
    };

HierarchicalListsAppView.cpp

Вызываем функцию создания Single Style Tree List в ConstructL()

// -----------------------------------------------------------------------------
// CHierarchicalListsAppView::ConstructL()
// Symbian 2nd phase constructor can leave.
// -----------------------------------------------------------------------------
//
void CHierarchicalListsAppView::ConstructL(const TRect& aRect)
    {
    // Создаем окно
    CreateWindowL();
 
    CreateHierarchicalSingleStyleListL();
    ....
    ....
 
    // Устанавливаем размеры окна
    SetRect(aRect);
 
    // Активизируем окно
    ActivateL();
    }

Создаем Single Style Tree List и заполняем его данными.
Устанавливаем класс CHierarchicalListsAppView в качестве наблюдателя и обработчика событий от SingleStyleTreeList, реализуем функцию HandleTreeListEvent()

void CHierarchicalListsAppView::CreateHierarchicalSingleStyleListL()
    {
        iSingleStyleTreeList = CAknSingleStyleTreeList::NewL();
        iSingleStyleTreeList->SetContainerWindowL(*this);
        iSingleStyleTreeList->SetRect(Rect());
        iSingleStyleTreeList->MakeVisible(ETrue);
        iSingleStyleTreeList->ActivateL();
 
        // Устанавливаем класс CHierarchicalListsAppView в качестве наблюдателя и обработчика событий от SingleStyleTreeList
        iSingleStyleTreeList->AddObserverL(this);
 
        // Объявляем константы, используемые при создании пунктов списка
        const TInt KPersistent = CAknSingleStyleTreeList::EPersistent;
        const TInt KExpanded = CAknSingleStyleTreeList::EExpanded;
 
        // Создаем первый родительский узел на самом верхнем уровне
        _LIT( KNodeText1, "Parent folder" );
        TAknTreeItemID parentNode1 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNodeText1, KPersistent | KExpanded, ETrue );
 
        // Добавляем иконку
        TInt id1 = iSingleStyleTreeList->AddIconL( KAknsIIDQgnIndiBrowserCursorPhone,
                                                    AknIconUtils::AvkonIconFileName(),
                                                    EMbmAvkonQgn_prop_nrtyp_video,
                                                    EMbmAvkonQgn_prop_nrtyp_video_mask,
                                                    EAspectRatioPreserved );
 
        // Создаем потомков (листы) и добавляем их в первый родительский узел
        _LIT( KLeafText1, "Leaf with Icon!!!" );
        TAknTreeItemID leaf1 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText1,KPersistent, ETrue );        
        _LIT( KLeafText2, "Leaf item2" );
        TAknTreeItemID leaf2 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText2,KPersistent, ETrue );
        _LIT( KLeafText3, "Leaf item3" );
        TAknTreeItemID leaf3 = iSingleStyleTreeList->AddLeafL( parentNode1, KLeafText3,KPersistent, ETrue );
 
        // Устанавливаем иконку к первому потомку (листу) на первом родительском узле
        iSingleStyleTreeList->SetIcon( leaf1, CAknSingleStyleTreeList::ELeaf, id1, EFalse );
 
        // Создаем второй родительский узел, создаем потомков (листы) и добавляем их в созданный узел
        _LIT( KNodeText2, "Parent folder" );
        TAknTreeItemID parentNode2 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNodeText2, KPersistent | KExpanded, ETrue );
        _LIT( KLeafText4, "Leaf item4" );
        TAknTreeItemID leaf4 = iSingleStyleTreeList->AddLeafL( parentNode2, KLeafText4,KPersistent, ETrue );        
        _LIT( KLeafText5, "Leaf item5" );
        TAknTreeItemID leaf5 = iSingleStyleTreeList->AddLeafL( parentNode2, KLeafText5,KPersistent, ETrue );
 
    }

Для обработки событий от Single Style Tree List'a необходимо реализовать функцию HandleTreeListEvent

void CHierarchicalListsAppView::HandleTreeListEvent( CAknTreeList& aList, TAknTreeItemID aItem, TEvent aEvent )
    {
        //Код обработки событий
    }

Возвращаем число компонентов, содержащихся в контейнере, у нас он один - iSingleStyleTreeList

TInt CHierarchicalListsAppView::CountComponentControls() const
{
    return 1; // возвращаем число компонентов в контейнере
}
 
CCoeControl* CHierarchicalListsAppView::ComponentControl(TInt aIndex) const
{
    switch ( aIndex )
    {
        case 0:
            return iSingleStyleTreeList;
        default:
            return NULL;
    }
}

Не забудьте удалить iSingleStyleTreeList в деструкторе класса.

// -----------------------------------------------------------------------------
// CHierarchicalListsAppView::~CHierarchicalListsAppView()
// Destructor.
// -----------------------------------------------------------------------------
//
CHierarchicalListsAppView::~CHierarchicalListsAppView()
{
    ....
    ....
    if(iSingleStyleTreeList)
    {
        delete iSingleStyleTreeList;
        iSingleStyleTreeList = NULL;
    }
}

Как добавить новый узел в дерево списка

void CHierarchicalListsAppView::AddNodeL()
    {
        // Добавляем родительский узел на самом верхнем уровне
        _LIT( KNewNodeText, "New Node" );
        TAknTreeItemID parentNode1 = iSingleStyleTreeList->AddNodeL( KAknTreeIIDRoot,KNewNodeText, KPersistent | KExpanded, ETrue );
    }

Как удалить узел из дерева списка

void CHierarchicalListsAppView::DeleteNodeL()
    {
        TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
        if(iSingleStyleTreeList->IsNode(focusedItem))
        {
            iSingleStyleTreeList->RemoveItem(focusedItem,ETrue);
        }
    }

Как добавить потомка (leaf) в узел, находящийся в фокусе

void CHierarchicalListsAppView::AddLeafL()
    {
        TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
        if(iSingleStyleTreeList->IsNode(focusedItem))
        {
            _LIT( KNewLeafText, "New Leaf" );
            TAknTreeItemID leaf1 = iSingleStyleTreeList->AddLeafL( focusedItem, KNewLeafText,KPersistent, ETrue );    
        }
    }

Как добавить потомка из узела, находящегося в фокусе

void CHierarchicalListsAppView::DeleteLeafL()
    {
        TAknTreeItemID focusedItem = iSingleStyleTreeList->FocusedItem();
        if(iSingleStyleTreeList->IsLeaf(focusedItem))
        {
            iSingleStyleTreeList->RemoveItem(focusedItem,ETrue);    
        }        
    }

Как целиком удалить дерево списка

void CHierarchicalListsAppView::DeleteTreeL()
    {
        if(! iSingleStyleTreeList->IsEmpty(KAknTreeIIDRoot))
        {
            iSingleStyleTreeList->RemoveItem(KAknTreeIIDRoot,ETrue);
        }

Полезные функции

CAknSingleStyleTreeList

AddNodeL()
AddLeafL()
SortL()
SetTextL()
SetIcon()

CAknTreeList

RemoveItem()
ExpandNode()
CollapseNode()
FocusedItem()
AddIconL()

MAknTreeListObserver

HandleTreeListEvent()

Ключевые моменты

Заголовочные файлы

#include <aknSingleStyleTreeList.h>
#include <akntreelist.h>

Классы

CAknSingleStyleTreeList
CAknTreeList
MAknTreeListObserver

Библиотеки

aknhlist.lib

Демонстрационное приложение

SingleStyleTreeList.zip

Связанные ссылки

При подготовке статьи использованы следующие материалы:

Working with SingleStyleTreeList with Hierarchical Lists API - S60 Touch UI

Источники дополнительной информации

S60 5th edition SDK help
S60 5th Edition C++ Developer's Library v1.0

Community: Wiki