---

Создание Виджета Списка

Эта глава охватывает следующие темы:

• Краткий обзор
• Структура элемента
• Структура образца виджета
• Методы
• Удобные Функции

Краткий обзор

Библиотека Фотона обеспечивает универсальный класс виджета списка PtGenList для создания заказных виджетов списков. Класс PtGenList отображает вертикальный список любого числа элементов. Пользователь может выбрать один или более элементов из этого списка, в зависимости от политики выбора.

Дочерний класс не должен переназначать метод Рисования или потреблять события мыши или клавиатуры. Вместо этого, он должен определить для рисования метод Рисования Списка и может определить метод События Мыши и/или Клавиатуры, если дополнительная обработка этих типов событий требуется. Обычно, дочерний класс также определяет метод Выбора, который будет вызван обработчиком события PtGenList.

Структура элемента

Класс PtGenList никогда не распределяет или освобождает элементы. Это ответственность дочернего класса. Класс PtGenList ожидает, что каждый элемент будет представлен структурой PtGenListItem_t -- смотрите Справочник По Виджетам - Widget Reference Фотона.

Когда Вы вызываете удобную функцию PtGenList*(), Вы передаете ей указатель на структуру PtGenListItem_t как элемент. Когда PtGenList вызывает один из ваших методов, он обеспечивает указатель на структуру PtGenListItem_t как элемент.

Так как дочерний класс будет наиболее вероятно нуждаться в дополнительных данных, описывающих элемент, он обычно определит свой элемент как структуру, чей первый член PtGenListItem_t. Это делает преобразования в и из PtGenListItem_t простым.

Дочерний класс ответствен за распределение элементов и добавления их к виджету. Перед добавлением элемента к виджету, члены структуры элемента должны быть установлены в требуемые значения. После добавления элемента к виджету, не изменяйте PtGenListItem_t непосредственно -- используют удобные функции вместо этого.

Структура PtGenListItem_t определена следующим образом:

typedef struct Pt_genlist_item {
     unsigned flags;
     PhDim_t size;
     PtGenListItem_t *next, *prev;
     }
     PtGenListItem_t;

flags

Следующие флаги описывают состояние элемента:

Pt_LIST_ITEM_SELECTED

Этот элемент выбран. Используйте PtGenListSelect() и PtGenListUnselect(), чтобы изменить этот флаг.

Pt_LIST_ITEM_CURRENT

Этот элемент является текущим. Используйте PtGenListGoto(), чтобы изменить этот флаг.

Pt_LIST_ITEM_DAMAGED

Этот элемент нужно перерисовать. Используйте PtGenListDamageItem(), чтобы вынудить перерисовку.

Pt_LIST_ITEM_ABOVE

Этот элемент выше видимого диапазона элементов. Используйте ресурс Pt_ARG_TOP_ITEM_POS или PtGenListShow(), чтобы прокрутить список.

Pt_LIST_ITEM_BELOW

Этот элемент ниже видимого диапазона элементов. Используйте ресурс Pt_ARG_TOP_ITEM_POS или PtGenListShow(), чтобы прокрутить список.

Макрос Pt_LIST_ITEM_USED_FLAGS определяет флаги, используемые виджетом PtGenList. Оставшиеся биты доступны для дочернего класса.

size

Структура PhDim_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона) определяет ширину и высоту элемента. Если дочерний класс должен изменить размер элемента после того, как он был добавлен к виджету, необходимо использовать удобные функции PtGenListLockItem() и PtGenListUnlockItem(). Если виджет имеет столбцы, ширина элементов игнорируется.

next, prev

Виджет использует эти ссылки, чтобы найти следующий и предыдущий элементы в списке. Не изменяйте эти ссылки после добавления элемента к виджету. Ссылка next используется для соединения элементов прежде, чем они будут добавлены к виджету (смотрите PtGenListAddItems()).

Структура образца виджета

Некоторые члены структуры PtGenListWidget_t могут использоваться дочерним классом. В общих чертах, не изменяйте члены структуры непосредственно; используйте вместо этого обеспеченные ресурсы и удобные функции.

---

Об информации об соответствии между членами структуры и ресурсами, смотрите раздел "Определения ресурсов" для PtGenList в главе по Использованию Виджетов Суперклассов.

---

gflags

Флаги, которые затрагивают поведение виджета. Дочерний класс вероятно установит все или большинство этих флагов в установленное значение; однако, если класс должен изменить gflags после того, как виджет был создан, используйте PtGenListSetGflags().

Pt_GEN_LIST_NO_BACKGROUND

Если установлен, метод Рисования не будет рисовать фон (под элементами) или поля.

Pt_GEN_LIST_ITEM_BACKGROUND

Если этот флаг установлен, но флаг Pt_GEN_LIST_NO_BACKGROUND очищен, метод Рисования будет рисовать фон ниже каждого элемента и вызовет метод Рисования Списка однажды для каждого элемента, который должен быть нарисован.

Pt_GEN_LIST_NO_CLIPPING

Если этот флаг очищен, метод Рисования установит отсечение холста виджета перед вызовом метода Рисования Списка. Отсечение не будет установлено, если нет элементов шире чем холст.

Pt_GEN_LIST_SHOW_DAMAGED

Если этот флаг установлен, метод Рисования будет сканировать список повреждения и устанавливать флаг Pt_LIST_ITEM_DAMAGE в элементах, которые должны перерисоваться. Метод Рисования Списка не будет вызван вообще, если никакие элементы не повреждены.

Pt_GEN_LIST_FULL_WIDTH

Если этот флаг установлен, пространство справа от элемента рассматривается частью элемента - ширина, сохраненная в элементе, обрабатывается как предложенный минимум. Если это пространство повреждено, элемент будет отмечен как поврежденный. Если этот флаг не установлен, пространство справа от элемента обрабатывается как поле. Нажатия мыши на этом пространстве игнорируются.

Pt_GEN_LIST_NO_AUTOFOCUS

Если этот флаг очищен, при даче фокуса виджету, когда нет текущего элемента в этом виджете, автоматически установится текущим элемент отображенный первым.

Pt_LIST_BALLOONS_IN_COLUMNS

Если этот флаг установлен, и виджет имеет столбцы, виджет уничтожит и создаст заново всплывающую подсказку, когда указатель пересекает границы столбца.

sel_xmode and sel_xflags

"Анализируемое" значение текущего режима выбора. Значение sel_xmode может быть одно из:

• Pt_SELECTION_MODE( Pt_SELECTION_MODE_NONE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_SINGLE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_MULTIPLE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_RANGE )

Член sel_xflags содержит часть "флагов" текущего режима выбора:

• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOSCROLL )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOMOVE )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOREST )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_AUTO )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOCLEAR )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_TOGGLE )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOFOCUS )

current_item

Указатель на текущий элемент.

cur_ndx

Индекс текущего элемента (первый элемент в списке имеет индекс 1).

Методы

Методы, описанные в этом разделе, определены в классе PtGenList.

Метод Рисования Списка

Метод Рисования вызывает метод Рисования Списка со следующими параметрами:

PtGenListWidget_t *widget

Указатель на виджет.

PtGenListItem_t *items

Указатель на структуру PtGenListItem_t первого элемента, который должен быть перерисован.

unsigned index

Индекс элемента, который будет перерисован (первый элемент в списке имеет индекс 1).

unsigned nitems

Число элементов, которые функция должна просмотреть.

PhRect_t *where

Указатель на структуру PhRect_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая определяет размерности элементов (функция позволяет изменять структуру PhRect_t, указанную where).

Метод Мыши Списка

Необработанные обратные вызовы класса списка вызывают метод Списка Мыши при каждом событии мыши, если мышь указывает на элемент. Функция может возвращать значение отличное от Pt_CONTINUE, чтобы подавить нормальную обработку мыши.

Метод Мыши Списка вызывается со следующими параметрами:

PtGenListWidget_t *widget

Указатель на виджет.

PtGenListItem_t *item

Указатель на структуру PtGenListItem_t элемента под курсором мыши.

unsigned index

Индекс этого элемента (первый элемент в списке имеет индекс 1).

PhPoint_t *where

Указатель на структуру PhPoint_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая определяет позицию мыши, относительно элемента. Функция позволяет изменять структуру, указанную where.

int column

Индекс столбца под указателем мыши, или -1, если указатель не находится на столбце или виджете не имеет столбцов.

PhEvent_t const *event

Указатель на структуру PhEvent_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая описывает событие.

Метод Клавиатуры Списка

Необработанные обратные вызовы класса списка вызывают метод Клавиатуры Списка при каждое событии клавиатуры. Этот метод должен возвращать одно из следующих значений:

Pt_CONTINUE

Класс PtGenList будет обычно обрабатывать данные, содержащиеся в структуре PhKeyEvent_t. Обратите внимание, что необработанные обратные вызовы класса позволяют изменять содержание этой структуры.

Pt_END

Виджет игнорирует событие, и необработанные обратные вызовы класса возвратят Pt_CONTINUE немедленно.

Pt_HALT

Событие будет использовано виджетом, но PtGenList не предпримет никаких дальнейших действий. Необработанные обратные вызовы класса возвратят Pt_END немедленно.

Метод Клавиатуры Списка вызывается со следующими параметрами:

PtGenListWidget_t *widget

Указатель на виджет.

PhEvent_t const *event

Указатель на структуру PhEvent_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая описывает событие.

PhKeyEvent_t *kevent

Указатель на данные события (которые функция может изменять). Смотрите PhKeyEvent_t в Справочное Руководство по Библиотеке - Library Reference Фотона.

PtGenListItem_t *newcur

Указатель на структуру PtGenListItem_t нового текущего элемента (если событие обработано обычно).

int index

Индекс этого элемента (первый элемент в списке имеет индекс 1).

Метод Выбора Списка

Необработанные обратные вызовы класса списка вызывают метод Выбора Списка, когда элемент выделяется или теряет выделение. Параметры:

PtGenListWidget_t *list

Указатель на виджет.

PtGenListItem_t *item

Указатель на структуру PtGenListItem_t. При Pt_SELECTION_MODE_RANGE режиме выбора, это указатель на первый выбранный элемент. В других режимах, это указатель на элемент, который был выделен или потерял выделение.

int index

Индекс этого элемента (первый элемент в списке имеет индекс 1).

int column

Индекс столбца под указателем мыши, или -1, если указатель не находится на столбце или виджете не имеет столбцов.

int nitems

Текущее число выбранных элементов (тоже что и list->sel_count).

int subtype

Подтип выбора.

PhEvent_t const *event

Указатель на структуру PhEvent_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая описывает событие.

Метод Подсказки Списка

Метод Подсказки Списка вызывается всякий раз, когда виджет всплывающей подсказки должен быть создан. Метод Подсказки Списка должен создать всплывающую подсказку и возвратить ее указатель на виджет.

Метод Подсказки Списка вызывается со следующими параметрами:

PtWidget_t *widget

Виджет списка.

PtWidget_t *parent

Родительский виджет всплывающей подсказки.

PtGenListItem_t *item

Указатель на структуру PtGenListItem_t элемента под указателем мыши.

unsigned index

Индекс этого элемента (первый элемент в списке имеет индекс 1).

int column

Индекс столбца под указателем мыши, или -1, если указатель не находится на столбце или виджете не имеет столбцов.

PhArea_t *area

Указатель на структуру PhArea_t (смотрите Справочное Руководство по Библиотеке - Library Reference Фотона), которая определяет область (относительно родительского виджета) соответствующую полному элементу. Используйте PtGenListSetColumnBalloon(), чтобы корректировать область к указанному столбцу, если Вы не используете PtGenListCreateTextBalloon(). Эти функции описаны в Справочник Виджетов - Widget Reference Фотона.

Удобные Функции

Класс PtGenList определяет следующие удобные функции (смотрите Справочник Виджетов - Widget Reference Фотона):

PtGenListAddItems()

Добавляет элементы к списку.

PtGenListAllItems()

Дает указатели на все элементы в списке.

PtGenListClearSelection()

Очищает выбор.

PtGenListDamageItem()

Перерисовывает элемент, когда его данные был изменены.

PtGenListDrawBackground()

Рисует фон списка.

PtGenListDrawString()

Рисует строку.

PtGenListFirstItem()

Возвращает указатель на первый элемент в списке.

PtGenListGetCurrent()

Возвращает указатель на текущий элемент в списке.

PtGenListGetSelIndexes()

Дает индексы выбранных элементов.

PtGenListGoto()

Устанавливает текущий элемент так, чтобы новый текущий элемент был видим.

PtGenListHold()

Предотвращает видимый ремонт виджета списка.

PtGenListItemIndex()

Находит индекс элемента.

PtGenListItemRealloc()

Перераспределяет память для элемента.

PtGenListLastItem()

Возвращает указатель на последний элемент в списке.

PtGenListLockItem()

Блокируйте элемент, так чтобы он мог быть изменен в размере.

PtGenListRelease()

Выпускает связь с видимым ремонтом виджета списка.

PtGenListRemoveItems()

Удаляет элементы из списка.

PtGenListResize()

Изменяет размеры виджета списка.

PtGenListSelect()

Выберает элемент в списке.

PtGenListSelectedItems()

Дает указатели на выбранные элементы.

PtGenListSetGflags()

Изменяет поле виджета gflags.

PtGenListSetSelIndexes()

Устанавливает индексы выбора.

PtGenListShow()

Устанавливает текущую позицию, так чтобы данный элемент был видим.

PtGenListUnlockItem()

Разблокирует элемент, так чтобы он мог быть модифицирован.

PtGenListUnselect()

Снимает выделение с элемента в списке.

PtSuperClassGenListDraw()

Вызывает метод Рисования Списка в суперклассе.

PtSuperClassGenListInflate()

Вызывает метод Подсказки Списка в суперклассе.

PtSuperClassGenListKey()

Вызывает метод Клавиатуры Списка в суперклассе.

PtSuperClassGenListMouse()

Вызывает метод Мыши Списка в суперклассе.

PtSuperClassGenListSelect()

Вызывает метод Выбора Списка в суперклассе.

---

---

Все мессаги сюда:yanich@inbox.ru