ScriptStringAnalyse 함수(usp10.h)

아티클
01/10/2024

일반 텍스트 문자열을 분석합니다.

구문

HRESULT ScriptStringAnalyse(
  [in]           HDC                    hdc,
  [in]           const void             *pString,
  [in]           int                    cString,
  [in]           int                    cGlyphs,
  [in]           int                    iCharset,
  [in]           DWORD                  dwFlags,
  [in]           int                    iReqWidth,
  [in, optional] SCRIPT_CONTROL         *psControl,
  [in, optional] SCRIPT_STATE           *psState,
  [in, optional] const int              *piDx,
  [in, optional] SCRIPT_TABDEF          *pTabdef,
  [in]           const BYTE             *pbInClass,
  [out]          SCRIPT_STRING_ANALYSIS *pssa
);

매개 변수

[in] hdc

디바이스 컨텍스트에 대한 핸들입니다. dwFlags가 SSA_GLYPHS 설정된 경우 디바이스 컨텍스트 핸들이 필요합니다. dwFlags가 SSA_BREAK 설정된 경우 디바이스 컨텍스트 핸들은 선택 사항입니다. 디바이스 컨텍스트 핸들이 제공되면 함수는 디바이스 컨텍스트에서 현재 글꼴을 검사합니다. 현재 글꼴이 기호화된 글꼴인 경우 함수는 문자열을 하나의 중립 SCRIPT_UNDEFINED 항목으로 처리합니다.

[in] pString

분석할 문자열에 대한 포인터입니다. 문자열에는 하나 이상의 문자가 있어야 합니다. iCharset 매개 변수에 지정된 대로 유니코드 문자열이거나 Windows ANSI 코드 페이지의 문자 집합을 사용할 수 있습니다.

[in] cString

분석할 문자열의 길이입니다. 길이는 ANSI 문자열의 경우 문자로 측정되거나 유니코드 문자열의 경우 와이드 문자로 측정됩니다. 길이는 1 이상이어야 합니다.

[in] cGlyphs

문자 모양 버퍼의 크기(WORD 값)입니다. 이 크기는 필수입니다. 권장되는 크기는 입니다 (1.5 * cString + 16).

[in] iCharset

문자 집합 설명자입니다. 입력 문자열이 ANSI 문자열인 경우 이 설명자는 문자 집합 식별자로 설정됩니다. 문자열이 유니코드 문자열인 경우 이 설명자는 -1로 설정됩니다.

다음 문자 집합 식별자가 정의됩니다.

[in] dwFlags

필요한 분석을 나타내는 플래그입니다. 이 매개 변수는 다음 표에 나열된 값 중 하나를 가질 수 있습니다.

값	의미
SSA_BREAK	중단 플래그, 즉 문자 및 단어 중지를 검색합니다.
SSA_CLIP	iReqWidth에서 문자열을 클리핑합니다.
SSA_DZWG	컨트롤 문자에 대한 표현 문자 모양을 제공합니다.
SSA_FALLBACK	대체 글꼴을 사용합니다.
SSA_FIT	문자열을 iReqWidth에 양쪽 맞춤합니다.
SSA_GCP	GetCharacterPlacement 규칙을 사용하여 누락된 문자 모양 및 pwLogClust를 검색합니다.
SSA_GLYPHS	문자 모양, 위치 및 특성을 생성합니다.
SSA_HIDEHOTKEY	표시된 문자열에서 첫 번째 "&"을 제거합니다.
SSA_HOTKEY	"&"을 후속 코드 포인트의 밑줄로 대체합니다.
SSA_HOTKEYONLY	밑줄만 표시합니다. XOR 마스크를 사용하여 결과 비트 패턴을 표시하여 텍스트를 방해하지 않고 바로 가기 키 밑줄의 표시 유형을 전환할 수 있습니다.
SSA_LINK	비호환 텍스트에 동아시아 글꼴 연결 및 연결을 적용합니다.
SSA_METAFILE	문자 모양이 아닌 ExtTextOutW 호출을 사용하여 항목을 작성합니다.
SSA_PASSWORD	단일 문자 cString 시간을 포함하는 중복 입력 문자열입니다.
SSA_RTL	기본 포함 수준 1을 사용합니다.
SSA_TAB	탭을 확장합니다.

[in] iReqWidth

맞춤 또는 클리핑에 필요한 너비입니다.

[in, optional] psControl

SCRIPT_CONTROL 구조체에 대한 포인터입니다. 애플리케이션은 이 매개 변수를 NULL 로 설정하여 모든 SCRIPT_CONTROL 멤버가 0으로 설정되었음을 나타낼 수 있습니다.

[in, optional] psState

SCRIPT_STATE 구조체에 대한 포인터입니다. 애플리케이션은 이 매개 변수를 NULL 로 설정하여 모든 SCRIPT_STATE 멤버가 0으로 설정되었음을 나타낼 수 있습니다. SCRIPT_STATEuBidiLevel 멤버는 무시됩니다. 사용된 값은 디바이스 컨텍스트의 레이아웃과 함께 SSA_RTL 플래그에서 파생됩니다.

[in, optional] piDx

요청된 논리 dx 배열에 대한 포인터입니다.

[in, optional] pTabdef

SCRIPT_TABDEF 구조체에 대한 포인터입니다. 이 값은 dwFlags 가 SSA_TAB 설정된 경우에만 필요합니다.

[in] pbInClass

GetCharacterPlacement 문자 분류를 나타내는 BYTE 값에 대한 포인터입니다.

[out] pssa

이 함수가 SCRIPT_STRING_ANALYSIS 구조를 검색하는 버퍼에 대한 포인터입니다. 이 구조체는 함수의 성공적인 반환에 동적으로 할당됩니다.

반환 값

성공하면 S_OK 반환합니다. 함수가 성공하지 못하면 0이 아닌 HRESULT 값을 반환합니다.

오류 반환은 다음과 같습니다.

E_INVALIDARG. 잘못된 매개 변수가 있습니다.
USP_E_SCRIPT_NOT_IN_FONT. SSA_FALLBACK 지정되지 않았거나 표준 대체 글꼴이 없습니다.

함수는 HRESULT 형식으로 변환된 시스템 오류를 반환할 수도 있습니다. 예를 들어 메모리 부족 또는 디바이스 컨텍스트를 사용하는 GDI 호출로 인해 반환되는 오류가 있습니다.

설명

이 함수의 사용은 일반 텍스트 문자열을 처리하는 첫 번째 단계입니다. 이러한 문자열에는 하나의 글꼴, 하나의 스타일, 하나의 크기, 하나의 색 등이 있습니다. ScriptStringAnalyse 는 항목 분석, 문자 모양, 고급 너비 등에 대한 임시 버퍼를 할당합니다. 그런 다음 ScriptItemize, ScriptShape, ScriptPlace 및 ScriptBreak를 자동으로 실행합니다. 결과는 다른 모든 ScriptString* 함수를 통해 사용할 수 있습니다.

이 함수에서 성공적으로 반환되면 pssa 는 애플리케이션이 다른 ScriptString* 함수에 연속적으로 전달할 수 있는 동적으로 할당된 구조를 나타냅니다. 애플리케이션은 궁극적으로 ScriptStringFree를 호출하여 구조를 해제해야 합니다.

ScriptStringAnalyse의 기능은 다른 함수에 대한 직접 호출을 통해 구현할 수 있지만 함수 자체를 사용하면 일반 텍스트 처리를 위해 애플리케이션에 필요한 코드 양이 크게 줄어듭니다.

중요 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 이상