다음을 통해 공유

ICustomDestinationList::AppendCategory 메서드(shobjidl_core.h)

  • 아티클

사용자 지정 점프 목록에 포함할 사용자 지정 범주 및 해당 범주에 포함된 대상을 정의합니다.

구문

HRESULT AppendCategory(
  [in] LPCWSTR      pszCategory,
  [in] IObjectArray *poa
);

매개 변수

[in] pszCategory

형식: LPCWSTR

사용자 지정 범주의 표시 이름을 포함하는 문자열에 대한 포인터입니다. 이 문자열은 점프 목록의 범주 헤더에 표시됩니다. 문자열은 표시 이름을 직접 보유하거나 저장된 문자열을 사용하기 위해 "@shell32.dll,-1324"와 같은 간접 문자열 표현일 수 있습니다. 간접 문자열을 사용하면 범주 헤더를 사용자가 선택한 언어로 표시할 수 있습니다.

참고 각 사용자 지정 범주에는 고유한 이름이 있어야 합니다. 범주 이름이 중복되면 점프 목록에서 프레젠테이션 문제가 발생합니다.
 

[in] poa

형식: IObjectArray*

범주의 대상을 나타내는 하나 이상의 IShellItem 개체를 나타내는 IObjectArray에 대한 포인터입니다. 목록의 일부 대상은 IShellLink 개체로 표시될 수도 있지만 빈도가 낮습니다.

참고 여기에서 사용되는 모든 IShellLink 는 SetArguments를 통해 인수 목록을 선언해야 합니다. 사용자가 점프 목록에서 이 유형의 항목을 고정하거나 고정 해제할 수 없고 추가하거나 제거할 수 없으므로 사용자 지정 범주에 인수가 없는 IShellLink 개체를 추가하는 것은 지원되지 않습니다.
 

반환 값

형식: HRESULT

성공하면 S_OK 반환하고, 그렇지 않으면 오류 값을 반환합니다.

AppendCategory 호출이 세션을 시작한 BeginList 호출에 의해 검색된 제거된 대상 목록에 있는 항목을 추가하려고 하면 AppendCategory 호출이 실패합니다.

AppendCategory가 애플리케이션이 처리하도록 등록되지 않은 IShellItem을 추가하려고 하면 호출이 실패합니다.

개인 정보 그룹 정책 또는 사용자 개인 정보 설정이 켜져 있는 경우 AppendCategory가 실패할 수 있습니다. 사용자 지정 범주에는 개인 정보 설정에서 허용되지 않는 개별 사용에 따라 사용자별 항목이 포함됩니다.

개인 정보 그룹 정책 또는 사용자 개인 정보 설정은 다른 ICustomDestinationList 메서드에서 오류를 일으키지 않습니다. 작업은 사용자별 작업이 아닙니다. AppendKnownCategory 는 데이터가 없으므로 최근 또는 자주 사용하는 범주가 표시되지 않지만 메서드 호출은 실패 코드를 반환하지 않습니다.

개인 정보 보호 그룹 정책 또는 사용자 개인 정보 설정(E_ACCESSDENIED)으로 인해 AppendCategory의 오류 코드가 발생하는 경우 애플리케이션은 작업을 계속 업데이트하고 CommitList를 호출해야 합니다.

연결된 애플리케이션에 대한 파일 형식 등록이 없으면 AppendCategory 는 HRESULT 0x80040F03 반환합니다. 이는 애플리케이션이 점프 목록에 추가하려는 파일 형식을 등록하지 않거나 애플리케이션이 명시적 AppUserModelID를 사용할 때 AppUserModelID를 제공하지 않는 것과 같은 등록 문제에서 발생할 수 있습니다.

설명

이 메서드를 호출하기 전에 BeginList 를 호출해야 합니다.

애플리케이션이 사용자 지정 범주를 제공하는 경우 해당 애플리케이션은 해당 범주를 채우는 책임을 집니다. 범주 콘텐츠는 여전히 사용자별이어야 하며 사용자의 기록 및 작업을 기반으로 하지만 사용자 지정 범주를 사용하여 애플리케이션에서 추적하려는 내용과 무시하려는 항목을 결정할 수 있습니다. instance 경우 다양한 애플리케이션 옵션을 선택할 때 다양한 시나리오가 관련될 수 있습니다. 예를 들어 오디오 프로그램은 최근에 재생된 앨범만 포함하고 최근에 재생된 개별 트랙을 무시하도록 선택할 수 있습니다. 애플리케이션에는 시스템의 기본 알고리즘보다 더 나은 결과를 제공하는 특정 용도에 맞게 조정된 사용량 추적 알고리즘이 있을 수도 있습니다.

애플리케이션은 목록 빌드 세션에서 AppendCategory 를 두 번 이상 호출하여 여러 사용자 지정 범주를 추가할 수 있습니다. 이 경우 해당 콘텐츠가 상호 배타적이 되도록 범주를 디자인해야 합니다. 각 사용자 지정 범주는 항목 간에 중복되지 않도록 특정 시나리오를 중심으로 빌드해야 합니다.

알려진 최근 또는 자주 사용하는 범주를 포함하여 사용자 지정 점프 목록의 범주는 추가되는 순서대로 표시되며 가장 최근 항목은 목록 끝에 추가됩니다. 모든 항목을 표시할 공간이 부족한 경우 목록의 마지막 항목이 먼저 화면에서 사라집니다. 따라서 가장 중요한 범주를 먼저 추가하여 항상 표시될 가능성이 가장 높아야 합니다. 범주 내의 대상은 poa가 가리키는 IObjectArray 개체에 저장되는 순서대로 표시됩니다.

사용자가 사용자 지정 범주에 제공된 대상 중 하나 이상을 점프 목록에 고정하도록 결정할 수 있습니다. 고정된 대상 목록을 애플리케이션에서 사용할 수 없지만 UI에서 중복을 방지하므로 애플리케이션에 대한 추가 작업이 필요하지 않습니다. 시각적으로 고정된 항목은 점프 목록의 고정된 섹션으로 이동하고 원래 위치에서 사라집니다.

AppendCategory를 성공적으로 호출해도 해당 항목이 표시된다는 보장은 없습니다. ICustomDestinationList::BeginList의 pcMinItems 매개 변수가 가리키는 값 위에 추가된 대상 수는 표시되지 않습니다. 고정된 범주는 다른 모든 대상 목록보다 우선합니다. 고정된 목록이 표시되면 나머지 공간이 다른 대상 목록에 할당됩니다. 사용자가 점프 목록에 충분한 대상을 고정하여 다른 대상이 표시되지 않도록 할 수 있습니다. 화면 해상도 감소 또는 글꼴 크기 증가와 같은 다른 요인으로 인해 애플리케이션 제공 대상이 목록에서 잘리게 될 수도 있습니다. 애플리케이션은 이러한 상황을 예측할 방법이 없으며 발생할 때 알림을 받지 않습니다. 애플리케이션은 가능성이 있다는 것을 알고 있어야 합니다. 대상 목록 또는 목록의 잘림이 아래에서 위로 발생하기 때문에 애플리케이션은 가장 중요한 범주와 대상을 목록 맨 위에 배치하여 표시할 가능성이 가장 높아야 합니다.

BeginList로 시작하고 CommitList로 끝나는 세션 중에 AppendCategory를 두 번 이상 호출할 수 있습니다. 제거된 항목 목록에 항목이 포함된 범주를 추가하려고 시도하여 이러한 호출 중 하나가 실패하는 경우 CommitList 호출은 제거된 항목 목록을 지우지 않습니다. 제거된 항목 목록을 지우려면 세션의 AppendCategory 에 대한 모든 호출이 성공적으로 반환되어야 합니다.

poa가 가리키는 IObjectArray를 통해 제공되는 IShellLink 인스턴스는 다음을 제공해야 합니다.

표시 이름은 항목의 System.Title(PKEY_Title) 속성을 통해 설정해야 합니다. 속성은 표시 이름을 직접 보유하거나 저장된 문자열을 사용하기 위해 "@shell32.dll,-1324"와 같은 간접 문자열 표현일 수 있습니다. 간접 문자열을 사용하면 항목 이름을 사용자가 선택한 언어로 표시할 수 있습니다.

필요에 따라 설명 필드(SetDescription)를 설정하여 점프 목록의 항목에 대한 사용자 지정 도구 설명을 제공할 수 있습니다.

요구 사항

   
지원되는 최소 클라이언트 Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 shobjidl_core.h(Shobjidl.h 포함)
라이브러리 Shell32.lib
DLL Shell32.dll(버전 6.1 이상)

추가 정보

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

작업 표시줄 확장