Сведения о элементах управления "Дерево"

Элемент управления "Представление дерева" — это окно, в котором отображается иерархический список элементов, таких как заголовки документа, записи в индексе или файлы и каталоги на диске. Каждый элемент состоит из метки и необязательного битового изображения, и каждый элемент может иметь список вложенных элементов, связанных с ним. Щелкнув элемент, пользователь может развернуть или свернуть связанный список вложенных элементов.

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

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

В этом разделе рассматриваются следующие разделы.

• Стили представления дерева
• Родительские и дочерние элементы
• Метки элементов
• Редактирование меток в виде дерева
• Позиция элемента представления дерева
• Общие сведения о состояниях элементов представления дерева
• Выбор элемента
• Сведения о элементах
• Списки изображений в виде дерева
• Операции перетаскивания
• Сообщения уведомлений элемента управления "Представление дерева"
• Обработка сообщений с представлением дерева по умолчанию
• Связанные статьи

Стили представления дерева

Стили представления дерева управляют аспектами внешнего вида элемента управления "Дерево". При создании элемента управления "Представление дерева" задаются начальные стили. Вы можете получить и изменить стили после создания элемента управления "Представление дерева" с помощью функций GetWindowLong и SetWindowLong.

Стиль TVS_HASLINES улучшает графическое представление иерархии элемента управления деревом путем рисования линий, которые связывают дочерние элементы с родительским элементом, как показано на следующем рисунке.

По себе этот стиль не рисует линии в корне иерархии. Для этого необходимо объединить стили TVS_HASLINES и TVS_LINESATROOT. Результат показан на следующем рисунке.

Пользователь может развернуть или свернуть список дочерних элементов родительского элемента, дважды щелкнув родительский элемент. Элемент управления "Представление дерева", имеющий стиль TVS_HASBUTTONS , добавляет кнопку слева от каждого родительского элемента. Пользователь может нажать кнопку один раз, а не дважды щелкнуть родительский элемент, чтобы развернуть или свернуть дочерний элемент. TVS_HASBUTTONS не добавляет кнопки в элементы в корне иерархии. Для этого необходимо объединить TVS_HASLINES, TVS_LINESATROOT и TVS_HASBUTTONS. Это сочетание стилей показано на следующем рисунке.

Стиль TVS_CHECКБ OXES создает проверка boxes рядом с каждым элементом. Если вы хотите использовать стиль проверка box, необходимо задать стиль TVS_CHECКБ OXES (с SetWindowLong) после создания элемента управления "Представление дерева" и перед заполнением дерева. В противном случае проверка boxes могут отображаться без проверка в зависимости от проблем с временем. На следующем рисунке показан стиль проверка box.

Стиль TVS_FULLROWSELECT приводит к тому, что выделение выделения расширяется по всей ширине элемента управления, а не только по самому элементу. На следующем рисунке показан этот стиль.

Стиль TVS_EDITLABELS позволяет пользователю изменять метки элементов представления дерева. Дополнительные сведения об изменении меток см. в разделе "Редактирование меток в виде дерева".

Дополнительные сведения об этих и других стилях см. в разделе "Стили окна управления "Представление дерева".

Родительские и дочерние элементы

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

Чтобы добавить элемент в элемент управления деревом, отправьте TVM_INSERTITEM сообщение в элемент управления. Сообщение возвращает дескриптор типу HTREEITEM, который однозначно идентифицирует элемент. При добавлении элемента необходимо указать дескриптор родительского элемента нового элемента. Если указать ЗНАЧЕНИЕ NULL или значение TVI_ROOT вместо родительского элемента в структуре TVINSERTSTRUCT, элемент добавляется в качестве корневого элемента.

В любое время состояние списка дочерних элементов родительского элемента может быть развернуто или свернуто. При развертывании состояния дочерние элементы отображаются под родительским элементом. При сворачивании дочерние элементы не отображаются. Список автоматически переключается между развернутыми и свернутыми состояниями, когда пользователь дважды щелкает родительский элемент или, если родительский элемент имеет стиль TVS_HASBUTTONS , когда пользователь нажимает кнопку, связанную с родительским элементом. Приложение может развернуть или свернуть дочерние элементы с помощью сообщения TVM_EXPAND.

Элемент управления представлением дерева отправляет родительское окно сообщение TVN_ITEMEXPANDING уведомления, когда список дочерних элементов родительского элемента будет развернут или свернут. Уведомление дает приложению возможность предотвратить изменение или задать какие-либо атрибуты родительского элемента, зависящее от состояния списка дочерних элементов. После изменения состояния списка элемент управления "Представление дерева" отправляет родительское окно сообщение TVN_ITEMEXPANDED уведомления.

При развертывании списка дочерних элементов он отступит относительно родительского элемента. Можно задать объем отступа с помощью сообщения TVM_SETINDENT или получить текущую сумму с помощью сообщения TVM_GETINDENT.

Элемент управления представлением дерева использует память, выделенную из кучы процесса, создающего элемент управления "Представление дерева". Максимальное количество элементов в представлении дерева зависит от объема памяти, доступной в куче.

Метки элементов

Обычно при добавлении элемента в элемент управления "Представление дерева" указывается текст метки элемента. Сообщение TVM_INSERTITEM содержит структуру TVITEM, которая определяет свойства элемента, включая строку, содержащую текст метки.

Элемент управления "Представление дерева" выделяет память для хранения каждого элемента; Текст меток элемента занимает значительную часть этой памяти. Если приложение поддерживает копию строк в элементе управления "Дерево", можно уменьшить требования к памяти элемента управления, указав значение LPSTR_TEXTCALLBACK в элементе PSZText TVITEM вместо передачи фактических строк в представление дерева. Использование LPSTR_TEXTCALLBACK приводит к тому, что элемент управления "Представление дерева" извлекает текст метки элемента из родительского окна всякий раз, когда элемент должен быть перезаписован. Чтобы получить текст, элемент управления представлением дерева отправляет сообщение TVN_GETDISPINFO уведомления, которое включает адрес структуры NMTVDISPINFO. Родительское окно должно заполнить соответствующие элементы включенной структуры.

Редактирование меток в виде дерева

Пользователь может напрямую редактировать метки элементов в элементе управления "Дерево", который имеет стиль TVS_EDITLABELS. Пользователь начинает редактирование, щелкнув метку элемента с фокусом. Приложение начинает редактирование с помощью сообщения TVM_EDITLABEL. Элемент управления "Представление дерева" уведомляет родительское окно при начале редактирования и при отмене или завершении. После завершения редактирования родительское окно отвечает за обновление метки элемента при необходимости.

Когда начинается редактирование меток, элемент управления "Представление дерева" отправляет родительское окно TVN_BEGINLABELEDIT уведомление. Обрабатывая это уведомление, приложение может разрешить редактирование некоторых меток и запретить редактирование других. Возвращая ноль, можно редактировать и возвращать ненулевое значение.

Когда редактирование меток отменено или завершено, элемент управления "Представление дерева" отправляет родительское окно сообщение TVN_ENDLABELEDIT уведомления. Параметр lParam — это адрес структуры NMTVDISPINFO . Параметр элемента — это структура TVITEM, которая определяет элемент и включает измененный текст. Родительское окно отвечает за обновление метки элемента, если она хочет сохранить новую метку. Элемент pszText tvITEM равен нулю, если редактирование отменено.

При редактировании меток обычно в ответ на сообщение уведомления TVN_BEGINLABELEDIT можно получить дескриптор, используемый для редактирования меток, с помощью сообщения TVM_GETEDITCONTROL . Элемент управления редактированием можно отправить EM_SETLIMITTEXT сообщение, чтобы ограничить объем текста, который пользователь может ввести или подклассить элемент управления редактирования для перехвата и отключения карта недопустимых символов. Обратите внимание, что элемент управления редактирования отображается только после отправки TVN_BEGINLABELEDIT.

Позиция элемента представления дерева

Начальная позиция элемента устанавливается при добавлении элемента в элемент управления "Представление дерева" с помощью сообщения TVM_INSERTITEM. Сообщение содержит структуру TVINSERTSTRUCT , указывающую дескриптор родительского элемента и дескриптор элемента, после которого необходимо вставить новый элемент. Второй дескриптор должен определить дочерний элемент заданного родительского или одного из этих значений: TVI_FIRST, TVI_LAST или TVI_SORT.

Если указана TVI_FIRST или TVI_LAST, элемент управления представлением дерева помещает новый элемент в начало или конец списка дочерних элементов данного родительского элемента. При указании TVI_SORT элемент управления представлением дерева вставляет новый элемент в список дочерних элементов в алфавитном порядке на основе текста меток элементов.

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

Сообщение TVM_SORTCHILDRENCB позволяет отсортировать дочерние элементы в зависимости от заданных критериев. При использовании этого сообщения вы указываете функцию обратного вызова, определяемую приложением, которую элемент управления "Представление дерева" может вызывать всякий раз, когда необходимо решить относительный порядок двух дочерних элементов. Функция обратного вызова получает два 32-разрядных значения, определенных приложением для сравниваемых элементов, и третье 32-разрядное значение, указанное при отправке TVM_SORTCHILDRENCB.

Общие сведения о состояниях элементов представления дерева

Каждый элемент в элементе управления "Дерево" имеет текущее состояние. Сведения о состоянии каждого элемента включают набор битовых флагов, а также индексы списка изображений, указывающие изображение состояния элемента и изображение наложения. Битовые флаги указывают, выбран ли элемент, отключен, развернут и т. д. В большинстве случаев элемент управления "Представление дерева" автоматически задает состояние элемента для отражения действий пользователя, таких как выбор элемента. Однако вы также можете задать состояние элемента с помощью сообщения TVM_SETITEM и получить текущее состояние элемента с помощью сообщения TVM_GETITEM. Полный список состояний элементов см. в разделе "Состояния элементов управления "Представление дерева".

Текущее состояние элемента указывается членом государства структуры TVITEM. Элемент управления "Представление дерева" может изменить состояние элемента, чтобы отразить действие пользователя, например выбор элемента или задание фокуса на элемент. Кроме того, приложение может изменить состояние элемента, чтобы отключить или скрыть элемент или указать изображение наложения или изображение состояния.

При указании или изменении состояния элемента элемент statemask в TVITEM указывает, какие биты состояния следует задать, а член государства содержит новые значения для этих битов.

Чтобы задать изображение наложения элемента, маска состояния должна включать значение TVIS_OVERLAYMASK, а состояние должно содержать одноуровневый индекс изображения наложения, смещенного 8 битами, с помощью макроса INDEXTOOVERLAYMASK. Индекс может быть равен нулю, чтобы не указывать изображение наложения.

Изображение состояния отображается рядом с значком элемента, чтобы указать определенное приложением состояние. Изображения состояния содержатся в списке образов состояния, который указан путем отправки сообщения TVM_SETIMAGELIST. Чтобы задать изображение состояния элемента, добавьте значение TVIS_STATEIMAGEMASK в элемент statemask структуры TVITEM. Биты 12–15 члена государства структуры указывают индекс в списке изображений состояния, который необходимо нарисовать.

Чтобы задать индекс изображения состояния, используйте INDEXTOSTATEIMAGEMASK. Этот макрос принимает индекс и задает биты 12–15 соответствующим образом. Чтобы указать, что элемент не имеет образа состояния, задайте для индекса нулевое значение. Это соглашение означает, что изображение в списке образов состояния не может использоваться в качестве образа состояния. Чтобы изолировать биты от 12 до 15 членов государства , используйте маску TVIS_STATEIMAGEMASK . Дополнительные сведения о наложении и изображениях состояния см. в списках изображений в виде дерева.

Выбор элемента

Элемент управления "Дерево" уведомляет родительское окно при изменении выделения одного элемента на другой, отправив TVN_SELCHANGING и TVN_SELCHANGED уведомления. Оба уведомления включают значение, указывающее, является ли изменение результатом щелчка мыши или нажатия клавиши. Уведомления также содержат сведения о элементе, который получает выбор, и элемент, который теряет выбранный элемент. Эти сведения можно использовать для задания атрибутов элементов, зависящих от состояния выбора элемента. Возврат TRUE в ответ на TVN_SELCHANGING предотвращает изменение выделения и возвращает значение FALSE.

Приложение может изменить выбор, отправив сообщение TVM_SELECTITEM .

Сведения о элементах

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

Сообщение TVM_GETITEM может получить дескриптор и атрибуты элемента. Атрибуты элемента включают текущее состояние, индексы в списке изображений элемента управления выбранных и неизбираемых битовых изображений элемента, флаг, указывающий, имеет ли элемент дочерние элементы, адрес строки метки элемента и 32-разрядное значение элемента.

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

Сообщение TVM_GETITEMRECT извлекает ограничивающий прямоугольник для элемента представления дерева. Сообщения TVM_GETCOUNT и TVM_GETVISIBLECOUNT извлекают количество элементов в элементе управления "Дерево", а также количество элементов, которые могут быть полностью видимы в окне элемента управления "Дерево" соответственно. Вы можете убедиться, что определенный элемент отображается с помощью сообщения TVM_ENSUREVISIBLE.

Списки изображений в виде дерева

Каждый элемент в элементе управления "Дерево" может иметь четыре битовых изображения, связанных с ним.

• Изображение, например открытая папка, отображаемое при выборе элемента.
• Изображение, например закрытая папка, отображается, когда элемент не выбран.
• Изображение наложения, нарисованное прозрачно по выбранному или неизбираемом изображению.
• Изображение состояния, которое является дополнительным изображением, отображаемым слева от выбранного или неизбираемого изображения. Вы можете использовать изображения состояния, такие как проверка и снятые проверка поля, чтобы указать состояния элементов, определяемых приложением.

По умолчанию элемент управления "Представление дерева" не отображает изображения элементов. Чтобы отобразить изображения элементов, необходимо создать списки изображений и связать их с элементом управления. Дополнительные сведения о списках изображений см. в разделе "Списки изображений".

Элемент управления "Представление дерева" может содержать два списка изображений: обычный список изображений и список изображений состояния. Обычный список изображений хранит выбранные, неизбираемые и наложенные изображения. Список образов состояния хранит изображения состояния. Используйте функцию ImageList_Create для создания списка изображений и использования других функций списка изображений для добавления растровых изображений в список изображений. Затем, чтобы связать список изображений с элементом управления "Представление дерева", используйте сообщение TVM_SETIMAGELIST . Сообщение TVM_GETIMAGELIST извлекает дескриптор в один из списков изображений элемента управления деревом. Это сообщение полезно, если вам нужно добавить в список дополнительные изображения.

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

По умолчанию все элементы отображают первое изображение в обычном списке изображений для выбранных и неизбираемых состояний. Кроме того, по умолчанию элементы не отображают изображения наложения или изображения состояний. Вы можете изменить это поведение по умолчанию для элемента, отправив TVM_INSERTITEM или TVM_SETITEM сообщение. Эти сообщения используют структуру TVITEM для указания индексов списка изображений для элемента.

Чтобы указать выбранные и неизбираемые изображения элемента, задайте TVIF_SELECTEDIMAGE и TVIF_IMAGE биты в элементе маски структуры TVITEM и укажите индексы из обычного списка изображений элемента управления в элементах iSelectImage и iImage. Кроме того, можно указать значение I_IMAGECALLBACK в iSelectImage и iImage вместо указания индексов. Это приводит к тому, что элемент управления запрашивает родительское окно для индекса списка изображений каждый раз, когда элемент будет перезаписыван. Элемент управления отправляет сообщение уведомления TVN_GETDISPINFO для получения индекса.

Чтобы связать изображение наложения с элементом, используйте макрос INDEXTOOVERLAYMASK, чтобы указать индекс маски наложения в элементе состояния структуры TVITEM элемента. Необходимо также задать TVIS_OVERLAYMASK биты в члене stateMask . Индексы маски наложения являются однонационными; Индекс нуля указывает, что изображение наложения не указано.

Образы состояния хранятся в отдельном списке образов состояния и определяются их индексом. Чтобы указать список образов состояния, отправьте TVM_SETIMAGELIST сообщение. В отличие от элемента управления представлением списка, который использует одноуровневый индекс для идентификации изображений состояний, образы состояний управления представлением дерева определяются отсчитываемым от нуля индексом. Однако индекс нуля указывает, что элемент не имеет образа состояния. Следовательно, нулю изображения нельзя использовать в качестве образа состояния. Дополнительные сведения о состояниях элементов и изображениях состояния см. в обзоре состояний элементов в виде дерева.

Операции перетаскивания

Элемент управления "Дерево" уведомляет родительское окно, когда пользователь начинает перетаскивать элемент. Родительское окно получает сообщение TVN_BEGINDRAG уведомления, когда пользователь начинает перетаскивать элемент с левой кнопкой мыши и сообщение уведомления TVN_BEGINRDRAG при начале перетаскивания с помощью правой кнопки. Вы можете запретить отправку этих уведомлений элементу управления представления дерева, предоставив элементу управления представлением дерева TVS_DISABLEDRAGDROP стиль.

Изображение для отображения во время операции перетаскивания с помощью сообщения TVM_CREATEDRAGIMAGE. Элемент управления "Представление дерева" создает перетаскиваемое растровое изображение на основе метки перетаскиваемого элемента. Затем элемент управления "Представление дерева" создает список изображений, добавляет к нему растровое изображение и возвращает дескриптор в список изображений.

Необходимо указать код, который фактически перетаскивает элемент. Обычно это включает использование возможностей перетаскивания функций списка изображений и обработки сообщений WM_MOUSEMOVE и WM_LBUTTONUP (или WM_RBUTTONUP), отправленных в родительское окно после начала операции перетаскивания.

Если элементы в элементе управления представлением дерева должны быть целевыми объектами операций перетаскивания, необходимо знать, когда указатель мыши находится на целевом элементе. Вы можете узнать, используя сообщение TVM_HITTEST. Вы указываете адрес структуры TVHITTESTINFO , содержащей текущие координаты указателя мыши. Когда функция SendMessage возвращается, структура содержит флаг, указывающий расположение указателя мыши относительно элемента управления представлением дерева. Если указатель находится над элементом в элементе управления "Дерево-представление", структура также содержит дескриптор элемента.

Можно указать, что элемент является целью операции перетаскивания с помощью сообщения TVM_SETITEM, чтобы задать состояние значением TVIS_DROPHILITED. Элемент, имеющий это состояние, рисуется в стиле, используемом для указания целевого объекта перетаскивания.

Сообщения уведомлений элемента управления "Представление дерева"

Элемент управления "Представление дерева" отправляет следующие сообщения уведомлений в родительское окно в виде WM_NOTIFY сообщений.

Обработка сообщений с представлением дерева по умолчанию

В этом разделе описывается обработка сообщений окна, выполняемая элементом управления "Представление дерева". Сообщения, относящиеся к элементам управления представлением дерева, рассматриваются в других разделах этого документа, поэтому они здесь не включены.

См. также

ПРИМЕР: CustDTv иллюстрирует настраиваемое рисование в treeView (Q248496)