Метод ICustomDestinationList::AppendCategory (shobjidl_core.h)
Определяет пользовательскую категорию и содержащиеся в ней назначения для включения в настраиваемый список переходов.
Синтаксис
HRESULT AppendCategory(
[in] LPCWSTR pszCategory,
[in] IObjectArray *poa
);
Параметры
[in] pszCategory
Тип: LPCWSTR
Указатель на строку, содержащую отображаемое имя настраиваемой категории. Эта строка отображается в заголовке категории в списке переходов. Строка может напрямую содержать отображаемое имя или быть косвенным строковым представлением, например "@shell32.dll,-1324", для использования хранимой строки. Непрямая строка позволяет отображать заголовок категории на выбранном пользователем языке.
[in] poa
Тип: IObjectArray*
Указатель на объект IObjectArray , представляющий один или несколько объектов IShellItem , представляющих назначения в категории. Некоторые назначения в списке также могут быть представлены объектами IShellLink , хотя и реже.
Возвращаемое значение
Тип: HRESULT
Возвращает S_OK в случае успешного выполнения или значение ошибки в противном случае.
Если вызов AppendCategory пытается добавить элемент, который находится в списке удаленных назначений, полученном вызовом BeginList , который инициировал сеанс, вызов AppendCategory завершается ошибкой .
Если AppendCategory пытается добавить элемент IShellItem , для обработки который приложение не зарегистрировано, вызов завершается ошибкой.
AppendCategory может завершиться ошибкой, если включена групповая политика конфиденциальности или включен параметр конфиденциальности пользователей. Пользовательские категории содержат элементы, относящиеся к конкретному пользователю, в зависимости от их использования, что не допускается в этих параметрах конфиденциальности.
Параметр конфиденциальности групповая политика или конфиденциальности пользователя не приведет к сбою в любом другом методе ICustomDestinationList. Задачи не зависят от пользователя. AppendKnownCategory не приведет к отображению категорий Последние или Частые , так как они не будут содержать данных, но вызов метода не вернет код сбоя.
В случае сбоя кода в AppendCategory, вызванного групповая политика конфиденциальности или параметром конфиденциальности пользователя (E_ACCESSDENIED), приложение должно продолжать обновлять задачи и вызывать CommitList.
Если регистрация типа файла для связанного приложения не найдена, AppendCategory возвращает 0x80040F03 HRESULT. Это может быть вызвано тем, что приложение не регистрирует тип файла, который оно пытается добавить в список переходов, или из-за проблемы при регистрации, например из-за не предоставления AppUserModelID, когда приложение использует явный Идентификатор AppUserModelID.
Комментарии
Перед вызовом этого метода необходимо вызвать BeginList .
Если приложение предоставляет пользовательскую категорию, оно берет на себя ответственность за ее заполнение. Содержимое категории должно по-прежнему зависеть от пользователя и основываться на журнале и действиях пользователя, но с помощью пользовательской категории приложение может определить, что оно хочет отслеживать и что оно хочет игнорировать. Например, при выборе различных параметров приложения могут использоваться разные сценарии. Например, аудиопрограмма может включать только недавно воспроизведенные альбомы и игнорировать недавно воспроизведенные отдельные треки. Приложение также может просто иметь алгоритм отслеживания использования, адаптированный к его конкретному использованию, который дает лучшие результаты, чем алгоритмы системы по умолчанию.
Приложение может вызывать AppendCategory несколько раз в сеансе создания списка, чтобы добавить несколько пользовательских категорий. В этом случае категории должны быть разработаны таким образом, чтобы их содержимое было взаимоисключающим. Каждая пользовательская категория должна быть построена на основе определенного сценария, чтобы элементы не дублировались между ними.
Категории в настраиваемом списке переходов, включая известные категории "Последние " или "Частые ", отображаются в порядке их добавления, а самые последние элементы добавляются в конец списка. Если места недостаточно для отображения всех записей, последние записи в списке сначала исчезают с экрана. Поэтому в первую очередь следует добавить наиболее важные категории, чтобы обеспечить их наилучшую вероятность отображения. Назначения в категории отображаются в порядке их хранения в объекте IObjectArray , на который указывает poa.
Пользователь может решить закрепить одно или несколько назначений, указанных в пользовательской категории, в списке переходов. Список закрепленных назначений недоступен приложению, но дублирование предотвращается пользовательским интерфейсом, поэтому от приложения не требуется никаких дополнительных действий. Визуально закрепленный элемент перемещается в раздел Закрепленные списка переходов и исчезает из исходного расположения.
Успешный вызов AppendCategory не гарантирует, что эти элементы будут отображаться. Любое количество назначений, добавленных над значением, указанным параметром pcMinItems в ICustomDestinationList::BeginList , не отображается. Категория Закрепленные имеет приоритет над всеми остальными списками назначения. Отобразится закрепленный список, а затем оставшееся пространство выделяется другим целевым спискам. Пользователь может закрепить достаточное количество назначений в списке переходов, чтобы другие назначения не отображались. Другие факторы, такие как уменьшение разрешения экрана или увеличение размера шрифта, также могут привести к усечению мест назначения, предоставляемых приложением, из списка. Приложение не может предсказать эти ситуации и не получает уведомления о их возникновении. Приложение должно просто знать, что эта возможность существует. Поскольку усечение списка назначения или списков происходит снизу вверх, приложение должно поместить свои наиболее важные категории и назначения в начало списка, чтобы они имели наилучшие шансы на отображение.
Во время сеанса, начинающегося с BeginList и заканчивающегося на CommitList, вы можете вызывать AppendCategory несколько раз. Если какой-либо из этих вызовов завершается ошибкой из-за попытки добавить категорию, содержащую элемент в списке удаленных элементов, вызов CommitList не очищает список удаленных элементов. Чтобы очистить список удаленных элементов, все вызовы AppendCategory в сеансе должны быть успешно возвращены.
Экземпляры IShellLink, предоставляемые через IObjectArray, на который указывает poa, должны предоставлять следующее:
- Указатель на список идентификаторов элементов (PIDL) (SetIDList) или целевой путь (SetPath или SetRelativePath).
- Аргументы командной строки (SetArguments)
- Расположение значка (SetIconLocation)
При необходимости можно задать поле описания (SetDescription), чтобы предоставить настраиваемую подсказку для элемента в списке переходов.
Требования
| Минимальная версия клиента | Windows 7 [только классические приложения] |
| Минимальная версия сервера | Windows Server 2008 R2 [только классические приложения] |
| Целевая платформа | Windows |
| Header | shobjidl_core.h (включая Shobjidl.h) |
| Библиотека | Shell32.lib |
| DLL | Shell32.dll (версия 6.1 или более поздняя) |
См. также раздел
ICustomDestinationList::AddUserTasks
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по