GetCharacterPlacementA 함수(wingdi.h)

아티클
08/27/2023

GetCharacterPlacement 함수는 문자 너비, 캐리트 위치 지정, 문자열 내 순서 지정 및 문자 모양 렌더링과 같은 문자 문자열에 대한 정보를 검색합니다. 반환되는 정보의 형식은 dwFlags 매개 변수에 따라 달라지고 지정된 표시 컨텍스트에서 현재 선택된 글꼴을 기반으로 합니다. 함수는 지정된 GCP_RESULTS 구조체 또는 구조체에 지정된 하나 이상의 배열에 정보를 복사합니다.

이 함수는 한때 문자 문자열 작업에 적합했지만 점점 더 많은 언어와 스크립트로 작업해야 하므로 더 이상 사용되지 않게 되었습니다. Uniscribe 모듈의 기능으로 대체되었습니다. 자세한 내용은 Uniscribe을 참조하세요.

애플리케이션은 GetFontLanguageInfo 함수를 사용하여 현재 선택한 글꼴에 대해 GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE 및 GCP_KASHIDA 값이 유효한지 확인하는 것이 좋습니다. 유효하지 않은 경우 GetCharacterPlacement 는 값을 무시합니다.

GCP_NODIACRITICS 값은 더 이상 정의되지 않으므로 사용하면 안 됩니다.

구문

DWORD GetCharacterPlacementA(
  [in]      HDC            hdc,
  [in]      LPCSTR         lpString,
  [in]      int            nCount,
  [in]      int            nMexExtent,
  [in, out] LPGCP_RESULTSA lpResults,
  [in]      DWORD          dwFlags
);

매개 변수

[in] hdc

디바이스 컨텍스트에 대한 핸들입니다.

[in] lpString

처리할 문자열에 대한 포인터입니다. nCount는 문자열의 길이를 지정하므로 문자열을 0으로 종료할 필요가 없습니다.

[in] nCount

lpString이 가리키는 문자열의 길이입니다.

[in] nMexExtent

문자열이 처리되는 최대 익스텐트(논리 단위)입니다. 처리되는 경우 이 범위를 초과하는 문자는 무시됩니다. 필요한 순서 또는 문자 모양 배열에 대한 계산은 포함된 문자에만 적용됩니다. 이 매개 변수는 GCP_MAXEXTENT 값이 dwFlags 매개 변수에 지정된 경우에만 사용됩니다. 함수가 입력 문자열을 처리할 때 각 문자와 해당 익스텐트는 총 범위가 아직 최대값을 초과하지 않은 경우에만 출력, 익스텐트 및 기타 배열에 추가됩니다. 제한에 도달하면 처리가 중지됩니다.

[in, out] lpResults

함수의 결과를 수신하는 GCP_RESULTS 구조체에 대한 포인터입니다.

[in] dwFlags

문자열을 필요한 배열로 처리하는 방법을 지정합니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값	의미
GCP_CLASSIN	lpClass 배열에 문자에 대한 미리 설정된 분류가 포함되도록 지정합니다. 분류는 출력에서와 같을 수 있습니다. 문자에 대한 특정 분류를 알 수 없는 경우 배열의 해당 위치를 0으로 설정해야 합니다. 분류에 대한 자세한 내용은 GCP_RESULTS 참조하세요. 이는 GetFontLanguageInfo 가 GCP_REORDER 플래그를 반환한 경우에만 유용합니다.
GCP_DIACRITIC	문자열의 분음 부호를 처리하는 방법을 결정합니다. 이 값을 설정하지 않으면 분음 부호는 너비가 0인 문자로 처리됩니다. 예를 들어 히브리어 문자열에는 분음 부호가 포함될 수 있지만 표시하지 않을 수 있습니다. GetFontLanguageInfo를 사용하여 글꼴이 분음 부호를 지원하는지 여부를 확인합니다. 이 경우 애플리케이션의 요구 사항에 따라 GetCharacterPlacement 호출에서 GCP_DIACRITIC 플래그를 사용하거나 사용할 수 없습니다.
GCP_DISPLAYZWG	단어 내의 문자 위치에 따라 순서를 변경하거나 문자 모양이 다른 언어의 경우 표시할 수 없는 문자가 코드 페이지에 표시되는 경우가 많습니다. 예를 들어 히브리어 코드 페이지에는 출력 문자열 내에서 문자의 최종 위치를 결정하는 데 도움이 되는 왼쪽에서 오른쪽 및 오른쪽에서 왼쪽으로 표식이 있습니다. 일반적으로 이러한 항목은 표시되지 않으며 lpGlyphs 및 lpDx 배열에서 제거됩니다. GCP_DISPLAYZWG 플래그를 사용하여 이러한 문자를 표시할 수 있습니다.
GCP_GLYPHSHAPE	현재 코드 페이지에 대해 현재 선택한 글꼴에 정의된 표준 셰이프 이외의 셰이프를 사용하여 문자열의 일부 또는 모든 문자를 표시하도록 지정합니다. 아랍어와 같은 일부 언어는 이 값을 지정하지 않는 한 문자 모양 만들기를 지원할 수 없습니다. 일반적으로 GetFontLanguageInfo 가 문자열에 대해 이 값을 반환하는 경우 이 값을 GetCharacterPlacement와 함께 사용해야 합니다.
GCP_JUSTIFY	문자열 길이가 nMaxExtent와 같도록 lpDx 배열의 익스텐트를 조정합니다. GCP_JUSTIFY GCP_MAXEXTENT 함께 사용할 수 있습니다.
GCP_KASHIDA	nMaxExtent에서 지정한 값과 같도록 조정된 익스텐트뿐만 아니라 또는 대신 Kashidas를 사용하여 문자열의 길이를 수정합니다. lpDx 배열에서 Kashida는 음의 근거 인덱스로 표시됩니다. GCP_KASHIDA GCP_JUSTIFY 함께 사용할 수 있으며 글꼴(및 언어)이 Kashidas를 지원하는 경우에만 사용할 수 있습니다. GetFontLanguageInfo를 사용하여 현재 글꼴이 Kashidas를 지원하는지 여부를 확인합니다. Kashidas를 사용하여 문자열을 정당화하면 필요한 문자 모양 수가 입력 문자열의 문자 수보다 클 수 있습니다. 이 때문에 Kashidas를 사용하는 경우 애플리케이션은 배열을 입력 문자열의 크기로 설정하면 충분하다고 가정할 수 없습니다. (가능한 최대값은 대략 dxPageWidth/dxAveCharWidth입니다. 여기서 dxPageWidth는 문서의 너비이고 dxAveCharWidth는 GetTextMetrics 호출에서 반환된 평균 문자 너비입니다). GetFontLanguageInfo가 GCP_KASHIDA 플래그를 반환한다고 해서 GetCharacterPlacement 호출에 사용해야 한다는 의미는 아니며 옵션을 사용할 수 있다는 의미입니다.
GCP_LIGATE	문자가 리게이트되는 위치에 합자를 사용합니다. 합자는 두 개 이상의 문자에 대해 하나의 문자 모양이 사용되는 경우에 발생합니다. 예를 들어, 문자 a와 e는 ?에 리게이트할 수 있습니다. 그러나 이를 사용하려면 언어 지원과 글꼴이 모두 필요한 문자 모양을 지원해야 합니다(예제는 기본적으로 영어로 처리되지 않음). GetFontLanguageInfo를 사용하여 현재 글꼴이 합자를 지원하는지 여부를 확인합니다. 이 작업을 수행하고 리게이트할 문자 수에 대해 특정 최대값이 필요한 경우 lpGlyphs 배열의 첫 번째 요소에 있는 숫자를 설정합니다. 일반 합자 필요 하는 경우이 값을 0으로 설정 합니다. GCP_LIGATE 지정하지 않으면 합자는 발생하지 않습니다. 자세한 내용은 GCP_RESULTS 참조하세요. 일반적으로 문자 집합에 GCP_REORDER 값이 필요하지만 지정되지 않은 경우 전달되는 문자열이 이미 시각적 순서로 되어 있지 않으면 출력은 의미가 없습니다(즉, GetCharacterPlacement에 대한 한 번의 호출에서 lpGcpResults-lpOutString>에 배치되는 결과는 두 번째 호출의 입력 문자열임). GetFontLanguageInfo가 GCP_LIGATE 플래그를 반환한다고 해서 GetCharacterPlacement 호출에 사용해야 한다는 의미는 아니며 옵션을 사용할 수 있다는 의미입니다.
GCP_MAXEXTENT	결과 익스텐트(논리 단위)가 nMaxExtent 매개 변수에 지정된 값을 초과하지 않는 한 문자열의 컴퓨팅 익스텐트입니다.
GCP_NEUTRALOVERRIDE	특정 언어만 해당됩니다. 중립의 정상적인 처리를 재정의하고 문자열 읽기 순서와 일치하는 강력한 문자로 처리합니다. GCP_REORDER 플래그에만 유용합니다.
GCP_NUMERICOVERRIDE	특정 언어만 해당됩니다. 숫자의 일반적인 처리를 재정의하고 문자열 읽기 순서와 일치하는 강력한 문자로 처리합니다. GCP_REORDER 플래그에만 유용합니다.
GCP_NUMERICSLATIN	아랍어/태국어만 해당. 숫자에 표준 라틴 문자 모양을 사용하고 시스템 기본값을 재정의합니다. 이 옵션을 글꼴 언어로 사용할 수 있는지 확인하려면 GetStringTypeEx를 사용하여 언어가 둘 이상의 숫자 형식을 지원하는지 확인합니다.
GCP_NUMERICSLOCAL	아랍어/태국어만 해당. 숫자 문자에 로컬 문자 모양을 사용하고 시스템 기본값을 재정의합니다. 이 옵션을 글꼴 언어로 사용할 수 있는지 확인하려면 GetStringTypeEx를 사용하여 언어가 둘 이상의 숫자 형식을 지원하는지 확인합니다.
GCP_REORDER	문자열의 순서를 다시 지정합니다. SBCS 및 왼쪽에서 오른쪽 읽기 순서가 아닌 언어에 사용합니다. 이 값을 지정하지 않으면 문자열은 이미 표시 순서로 간주됩니다. 이 플래그가 세미틱 언어에 대해 설정되고 lpClass 배열을 사용하는 경우 배열의 처음 두 요소를 사용하여 문자열 범위를 벗어나는 읽기 순서를 지정합니다. GCP_CLASS_PREBOUNDRTL 및 GCP_CLASS_PREBOUNDLTR 사용하여 순서를 설정할 수 있습니다. 미리 설정된 순서가 필요하지 않은 경우 값을 0으로 설정합니다. GCPCLASSIN 플래그가 설정된 경우 이러한 값을 다른 값과 결합할 수 있습니다. GCP_REORDER 값을 지정하지 않으면 lpString 매개 변수가 사용되는 언어에 대해 시각적 순서로 지정되고 lpOutString 및 lpOrder 필드는 무시됩니다. GetFontLanguageInfo를 사용하여 현재 글꼴이 다시 정렬을 지원하는지 여부를 확인합니다.
GCP_SYMSWAPOFF	세미틱 언어만 해당합니다. 교환 가능한 문자가 다시 설정되지 않도록 지정합니다. 예를 들어 오른쪽에서 왼쪽 문자열에서는 '(' 및 ')'이 반전되지 않습니다.
GCP_USEKERNING	너비 배열을 만들 때 글꼴(있는 경우)에서 커닝 쌍을 사용합니다. GetFontLanguageInfo를 사용하여 현재 글꼴이 커닝 쌍을 지원하는지 여부를 확인합니다. GetFontLanguageInfo가 GCP_USEKERNING 플래그를 반환한다고 해서 GetCharacterPlacement 호출에 사용해야 한다는 의미는 아니며 옵션을 사용할 수 있다는 의미입니다. 대부분의 TrueType 글꼴에는 커닝 테이블이 있지만 사용할 필요는 없습니다.

GCP_NODIACRITICS 값은 더 이상 정의되지 않으므로 사용하면 안 됩니다.

반환 값

함수가 성공하면 반환 값은 논리 단위로 문자열의 너비와 높이입니다. 너비는 낮은 순서의 단어이고 높이는 높은 순서의 단어입니다.

함수가 실패하면 반환 값은 0입니다.

설명

GetCharacterPlacement 를 사용하면 응용 프로그램이 사용 가능한 국가별 설정 및 글꼴 유형에 관계없이 텍스트를 올바르게 처리할 수 있습니다. 애플리케이션은 ExtTextOut 함수를 사용하기 전과 GetTextExtentPoint32 함수 대신 이 함수를 사용합니다(때로는 GetCharWidth32 및 GetCharABCWidths 함수 대신).

타당성 또는 커닝이 필요하지 않으면 GetCharacterPlacement 를 사용하여 문자 간 간격 및 인덱스 배열을 검색하는 것이 항상 필요한 것은 아닙니다. 라틴어가 아닌 글꼴의 경우 애플리케이션은 ExtTextOut 을 호출하기 전에 GetCharacterPlacement 를 사용하여 문자 간 간격 및 인덱스 배열을 검색하여 ExtTextOut 함수가 텍스트를 렌더링하는 속도를 향상시킬 수 있습니다. 이는 동일한 텍스트를 반복적으로 렌더링하거나 문자 간 간격을 사용하여 캐리트를 배치할 때 특히 유용합니다. extTextOut 호출에서 lpGlyphs 출력 배열을 사용하는 경우 ETO_GLYPH_INDEX 플래그를 설정해야 합니다.

GetCharacterPlacement는 GCP_RESULTS 구조체의 lpOrder, lpDX, lpCaretPos, lpOutString 및 lpGlyphs 멤버를 확인하고 이러한 멤버가 NULL로 설정되지 않은 경우 해당 배열을 채웁니다. GetCharacterPlacement가 배열을 채울 수 없는 경우 해당 멤버를 NULL로 설정합니다. 유효한 정보를 검색하기 위해 애플리케이션은 함수를 호출하기 전에 멤버를 유효한 주소로 설정하고 호출 후 멤버의 값을 확인해야 합니다. GCP_JUSTIFY 또는 GCP_USEKERNING 값을 지정하면 lpDX 및/또는 lpCaretPos 멤버에 유효한 주소가 있어야 합니다.

GCP_RESULTS.lpGlyphs에서 반환되는 문자 모양 인덱스는 디바이스 컨텍스트의 현재 글꼴과 관련이 있으며 해당 글꼴이 선택된 상태로 유지되는 동안에만 디바이스 컨텍스트에서 텍스트를 그리는 데만 사용해야 합니다.

근거를 계산할 때 문자열의 후행 문자가 공백인 경우 함수는 문자열의 길이를 줄이고 근거를 계산하기 전에 공백을 제거합니다. 배열이 공백으로만 구성된 경우 함수는 오류를 반환합니다.

ExtTextOut 에는 DBCS 문자열의 각 바이트에 대해 lpDX 항목이 필요한 반면 GetCharacterPlacement 는 각 문자 모양에 대해 lpDX 항목을 할당합니다. 이 함수 조합을 사용할 때 이 불일치를 해결하려면 GetGlyphIndices 를 사용하거나 DBCS 바이트 쌍의 해당 두 번째 바이트에 대해 너비가 0인 항목이 있는 lpDX 배열을 확장합니다.

논리 너비가 입력 문자열의 선행 문자 너비보다 작으면 GCP_RESULTS.nMaxFit은 잘못된 값을 반환합니다. 이 경우 문자 모양 인덱스 및 lpDX 배열에 대해 GetCharacterPlacement를 호출합니다. 그런 다음 lpDX 배열을 사용하여 각 문자의 사전 너비를 사용하여 익스텐트 계산을 수행합니다. 여기서 nMaxFit 은 문자 모양 인덱스의 사전 너비가 선행 문자의 너비보다 작은 문자 수입니다.

참고

wingdi.h 헤더는 GETCharacterPlacement를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	wingdi.h(Windows.h 포함)
라이브러리	Gdi32.lib
DLL	Gdi32.dll