ScriptItemize 함수(usp10.h)

아티클
03/03/2024

유니코드 문자열을 개별적으로 셰이프 가능한 항목으로 나눕니다.

구문

HRESULT ScriptItemize(
  [in]           const WCHAR          *pwcInChars,
  [in]           int                  cInChars,
  [in]           int                  cMaxItems,
  [in, optional] const SCRIPT_CONTROL *psControl,
  [in, optional] const SCRIPT_STATE   *psState,
  [out]          SCRIPT_ITEM          *pItems,
  [out]          int                  *pcItems
);

매개 변수

[in] pwcInChars

항목화할 유니코드 문자열에 대한 포인터입니다.

[in] cInChars

항목별로 지정할 pwcInChars의 문자 수입니다.

[in] cMaxItems

처리할 항목을 정의하는 최대 SCRIPT_ITEM 구조체 수입니다.

[in, optional] psControl

수행할 항목화 유형을 나타내는 SCRIPT_CONTROL 구조체에 대한 포인터입니다.

또는 SCRIPT_CONTROL 속성이 필요하지 않은 경우 애플리케이션에서 이 매개 변수를 NULL로 설정할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.

[in, optional] psState

초기 양방향 알고리즘 상태를 나타내는 SCRIPT_STATE 구조체에 대한 포인터입니다.

또는 스크립트 상태가 필요하지 않은 경우 애플리케이션에서 이 매개 변수를 NULL 로 설정할 수 있습니다. 자세한 내용은 주의 섹션을 참조하세요.

[out] pItems

함수가 처리된 항목을 나타내는 SCRIPT_ITEM 구조를 검색하는 버퍼에 대한 포인터입니다. 버퍼의 길이는 바이트여야 (cMaxItems + 1) * sizeof(SCRIPT_ITEM) 합니다. 버퍼를 사용하여 이 함수를 호출하여 두 개 미만의 SCRIPT_ITEM 구조를 보유하는 것은 유효하지 않습니다. 함수는 항상 항목 분석 배열에 터미널 항목을 추가하여 0부터 시작하는 인덱스 "i"가 있는 항목의 길이를 항상 다음과 같이 사용할 수 있도록 합니다.

pItems[i+1].iCharPos - pItems[i].iCharPos;

[out] pcItems

처리된 SCRIPT_ITEM 구조체 수에 대한 포인터입니다.

반환 값

정상적으로 실행되는 경우 0을 반환합니다. 함수가 성공하지 못하면 0이 아닌 HRESULT 값을 반환합니다.

pwcInChars가 NULL로 설정되고, cInChars가 0이고, pItems가 NULL 또는 cMaxItems 2로 설정된 경우 함수는 E_INVALIDARG 반환합니다<.

함수는 cMaxItems 값이 부족한 경우 E_OUTOFMEMORY 반환합니다. 모든 오류 사례에서와 같이 항목이 완전히 처리되지 않으며 출력 배열의 일부에 정의된 값이 포함되지 않습니다. 함수가 E_OUTOFMEMORY 반환하는 경우 애플리케이션은 더 큰 pItems 버퍼를 사용하여 다시 호출할 수 있습니다.

설명

이 함수가 일반적으로 호출되는 컨텍스트에 대한 설명은 유니스크립을 사용하여 텍스트 표시 를 참조하세요.

함수는 셰이핑 엔진의 변경 또는 방향 변경으로 항목을 구분합니다.

애플리케이션은 ScriptItemize에서 검색한 각 SCRIPT_ITEM 구조에서 단일 항목 내에 완전히 속하는 여러 범위를 만들거나 실행할 수 있습니다. 그러나 여러 항목을 단일 실행으로 결합하면 안 됩니다. 나중에 측정하거나 렌더링할 때 애플리케이션은 각 실행에 대해 ScriptShape 를 호출할 수 있으며 SCRIPT_ITEM 구조에서 ScriptItemize 에서 검색한 SCRIPT_ANALYSIS 구조를 전달해야 합니다.

애플리케이션에서 처리하는 텍스트에 오른쪽에서 왼쪽 콘텐츠가 포함될 수 있는 경우 애플리케이션은 ScriptItemize를 호출할 때 psControl 및 psState 매개 변수를 사용합니다. 그러나 애플리케이션은 이 작업을 수행할 필요가 없으며 Uniscribe를 사용하는 대신 양방향 텍스트 자체를 처리할 수 있습니다. psControl 및 psState 매개 변수는 SCRIPT_CONTROL fLinkStringBefore 멤버가 오른쪽에서 왼쪽 스크립트와 관련이 없는 경우와 같이 일부 엄격하게 왼쪽에서 오른쪽 시나리오에서 유용합니다. 애플리케이션은 psControl 및 psState 를 NULL 로 설정하여 ScriptItemize 가 문자 코드로만 유니코드 문자열을 중단하도록 합니다.

애플리케이션은 모든 매개 변수를 NULL 이 아닌 값으로 설정하여 함수가 전체 유니코드 양방향 분석을 수행하도록 할 수 있습니다. 올바른 유니코드 양방향 분석을 허용하려면 단락 시작 시 읽기 순서에 따라 SCRIPT_STATE 구조를 초기화해야 하며 ScriptItemize 는 전체 단락에 전달되어야 합니다. 특히 uBidiLevel 멤버는 왼쪽에서 오른쪽으로 0으로, 오른쪽에서 왼쪽으로 1로 초기화해야 합니다.

SCRIPT_ANALYSISfRTL 멤버는 SCRIPT_ITEM enabled="1"에서 참조됩니다. SCRIPT_PROPERTIESfNumeric 멤버는 ScriptGetProperties에 의해 검색됩니다. 이러한 멤버는 GetCharacterPlacement의 lpResults에서 참조하는 GCP_RESULTSlpClass 멤버와 동일한 분류를 제공합니다.

다음 표와 같이 유럽 숫자 U+0030~U+0039를 국가 숫자로 렌더링할 수 있습니다.

SCRIPT_STATE.fDigitSubstitute	SCRIPT_CONTROL.fContextDigits	유니코드 U+0030~U+0039에 대해 표시되는 숫자 셰이프
FALSE	모두	유럽 숫자
TRUE	FALSE	SCRIPT_CONTROL uDefaultLanguage 멤버에 지정된 대로
TRUE	TRUE	이전의 강력한 텍스트로, 기본값은 SCRIPT_CONTROL uDefaultLanguage 멤버입니다.

컨텍스트 숫자 모드에서 다음 작업 중 하나가 발생합니다.

uDefaultLanguage에서 지정한 스크립트가 출력과 동일한 방향이면 첫 번째 문자 이전에 발생한 모든 숫자가 uDefaultLanguage로 표시된 언어로 렌더링됩니다.
uDefaultLanguage로 지정된 스크립트가 출력과 반대 방향이면 첫 번째 문자가 유럽 숫자로 렌더링되기 전에 발생한 모든 숫자가 렌더링됩니다.

예를 들어 uDefaultLanguage 가 LANG_ARABIC 나타내는 경우 초기 숫자는 오른쪽에서 왼쪽 포함에 Arabic-Indic 있습니다. 그러나 왼쪽에서 오른쪽 포함의 유럽 숫자로 표시됩니다.

자세한 내용은 숫자 셰이프를 참조하세요.

유니코드 컨트롤 문자와 정의 및 SCRIPT_STATE 멤버에 미치는 영향은 다음 표에 나와 있습니다. 유니코드 컨트롤 문자에 대한 자세한 내용은 유니코드 표준을 참조하세요.

유니코드 컨트롤 문자	의미	SCRIPT_STATE 영향
NADS	국가별 숫자 셰이프를 사용하여 NODS(유럽 숫자)를 재정의합니다.	fDigitSubstitute를 설정합니다.
끄 덕	명목 숫자 셰이프(유럽 숫자라고도 함)를 사용합니다. NADS를 참조하세요.	fDigitSubstitute를 지웁니다.
엉덩이	대칭 쌍(예: 괄호)의 교환을 활성화합니다. 이러한 문자의 경우 왼쪽과 오른쪽은 여는 것과 닫는 것으로 해석됩니다. 이것이 기본값입니다. ISS를 참조하세요.	fInhibitSymSwap을 지웁니다.
ISS	대칭 쌍의 교환을 금지합니다. ASS를 참조하세요.	fInhibitSymSwap을 설정합니다.
AAFS	아랍어 프레젠테이션 양식에 대한 아랍어 양식 셰이핑을 활성화합니다. IAFS를 참조하세요.	fCharShape를 설정합니다.
IAFS	아랍어 프레젠테이션 양식의 경우 아랍어 양식 셰이핑, 즉 합자 및 필기체 연결을 억제합니다. 명목 아랍어 문자는 영향을 받지 않습니다. 이것이 기본값입니다. AAFS를 참조하세요.	fCharShape를 지웁다.

SCRIPT_STATEfArabicNumContext 멤버는 아랍어 스크립트 텍스트에서 상황에 맞는 숫자 표시를 지원합니다. 네이티브 아랍어 스크립트 숫자 셰이프 또는 유럽 숫자를 사용하여 숫자가 렌더링되는지 여부를 나타냅니다. 단락의 시작 부분에서 이 멤버는 일반적으로 아랍어 로캘의 경우 TRUE 로 초기화되고 다른 로캘의 경우 FALSE 로 초기화되어야 합니다. 함수는 강력한 텍스트를 처리할 때 스크립트 상태를 업데이트합니다.

중요 Windows 8 시작: Windows 7에서 실행하는 기능을 유지하려면 Uniscribe를 사용하는 모듈이 라이브러리 목록에서 gdi32.lib 전에 Usp10.lib를 지정해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	usp10.h
라이브러리	Usp10.lib
DLL	Usp10.dll
재배포 가능 파일	Windows Me/98/95의 인터넷 Explorer 5 이상