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