GetCharacterPlacement

該函式得到一個字元串的參數,如字元寬度、脫字元號定位、字元串的定序和字元翻譯,返回信息的類型依賴於參數dwFlags和在給定顯示環境裡的當前選擇字型,此函式將信息複製到指定的GCP_RESULTS結構里或一個或多個由此結構指定的數組裡。

 

詞語注音

函式功能:該函式得到一個字元串的參數,如字元寬度、脫字元號定位、字元串的定序和字元翻譯,返回信息的類型依賴於參數dwFlags和在給定顯示環境裡的當前選擇字型,此函式將信息複製到指定的GCP_RESULTS結構里或一個或多個由此結構指定的數組裡。
    函式原型:DWORD GetCharacterPlacement(HDC hdc, LPCTSTR lpString, int nCount, int nMaxExtent, LPGCP_RESULTS lpResults, DWORD dwFlags);

函式參數

    hdc:設備環境句柄。
    lpString:指向將要處理的字元串的指針。
    nCount:指定字元串里的字元個數。
    nMaxExtent:指定字元串處理的最大寬度(邏輯單位)。如果要處理的字元超進此範圍,則忽略不計。為任何要求的定序或字元數組進行的計算都只套用到包括進來的字元上。只有當參數dwFlags設定為GCP_MAXEXTENT時此參數才有用。當此參數處理輸入的字元串時,每個字元及其寬度都被加入到輸出寬度和其他數組裡,只要總的寬度沒有超過最大值。一旦達到最大值,處理就會停止。
    lpResults:指向結構GCP_RESULTS的指針,該結構用於接收此函式的運行結果。
    dwFlags:指定如何處理字元串並放入指定的數組裡,此參數可取一個或多個下列值:
GCP_CLASSIN:指定數組lpClass里含有對字元的預置分類。此分類可以與輸出時的相同,如果對一個字元的特殊分類是未知的,則數組裡的相應位置必須設定為0。要得到更多關於分類的信息,參見GCP_RESULTS。只有當GetFontLanguageInfo返回GCP_REORDER標誌值,此值才是有用的。
    GCP_DIACRITIC:決定如何處理字元串里的變數符。如果來設定此值,變音符被當作零寬度的字元。例如,一個Hebrew字元中可以包含讀音符,但可以不顯示它們。
    用GetFontLanguageInfo可以確定一種字型是否支持讀音符。如果支持,可以根據應用程式的需要在GetCharacterPlacement調時或使用或不使用GCP_DIACRITIC標誌。
GCP_DISPLAYZWG:用於那些需要重新排序,需要根據字元在一個單位中的不同位置而改變字元形狀的語言,非顯示字元經常出現在其代碼頁里。例如,在Hebrew代碼頁里,有Left-To-Right和Right-To-Left標記,用於決定輸出字元串里字元的最終位置。通常這些標誌不被顯示並且會從lpGlyphs和lpDx數組裡刪除。可以用GCP_DISPLAYZWG標誌來顯示這些字元。
    GCP_GLYPHSHAPE:指定將顯示的字元串里的部分或所有字元使用與當前代碼頁里所選字型的標準形狀不同的形狀來顯示,有一些語言,如阿拉伯語,若不設定此值將不支持字形創建。通常,如果GetFontLanguageInfo為一個字元串返回此值,則此值必須用於GetCharacterPlacement。
    GCP_JUSTIFY:調整數組lpDx里的寬度,使字元串長度和nMaxextent相同。GCP_JUSTIFY只能和GCP_MAXEXTENT一起使用。
    GCP_JUSTIFYIN:指定輸入時數組lpDx包含的對齊權值。通常,一個對齊權值可取0或1,當取1時,表示給字元的寬度可以為對齊而調整。對那些GetFontLanguageInfo函式將返回GCP_KASHIDA標誌的語言,對齊權值可以是GCP_ARAJUST_*值之一。
    GCP_KASHIDA:使用Kashidas和(或)調整寬度來修改字元串的長度,使它能與nMaxExtent給定的值相等,在數組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:只對Arabic/Thai。對數字使用標準Latin符號,忽略系統的預設值。要確定一種字型的語言是否提供此選項,用GetStringTypeEx來查看該語言是否支持一種以上的數字格式。
    GCP_NUMERICSLOCAL:只對Arabic/Thai。對數字使用標準Latin符號,忽略系統的預設值。要確定一種字型的語言是否提供此選項,用GetStringTypeEx來查看該語言是否支持一種以上數字格式。
    GCP_REORDER:對字元串重排序,用於那些不是SBCS的且有從左到右閱讀順序的語言。如果沒有給定此值,字元串被認為已經是按顯示順序排列的。
    若此標誌用於Semitic語言並且使用了lpClass數組,則數組的前兩個元素是用來指定字元串範圍之外部分的閱讀順序的。GCP_CLASS_PREBOUNDRTL和GCP_CLASS_PREBOUNDLTR可用來設定該順序。如果不要求預先設定的順序,則賦該值為0。如果設定了GCPCLASSIN標誌,則這些值可以組合起來使用。
    如果GCP_REORDER值沒有給定,則lpString參數用於將語言進行可視排序,並且忽略欄位lpOutString和lpOrder。
    用GetFontLanguageInfo來確定當前的字型是否支持重新排序。
    GCP_SYMSWAPOFF只對Semitic語言使用。指定可交換字元不重新設定。例如,在一個從右到左的字元串里'('和')'不被交換。
    GCP_USEKERNING:當創建寬度數組時,在字型里(如果存在)使用字距調整對。用GetFontLanguage可確定當前字型是否支持字距調整對。
    注意:不能因為GetFontLanguage返回了GCP_USEKERNIN值就認為該值被用於調用GetCharacterPlacement,這隻說明該值可以被選用。大多數TrueType字型都有一個字距調整表,但卻不能使用它。
    建議應用程式使用GetFontLanguageInfo來確定GCP_DIACRITIC, GCP_DBCS, GCP_USEKERNING, GCP_LIGATE, GCP_REORDER, GCP_GLYPHSHAPE和GCP_KASHIDA等值對當前所選字型是否有效。如果無效,GetCharacterPlacement將不採用這些值。
    GCP_NODIACRITICS:不再有定義,故不能使用。
    返回值:如果函式調用成功,返回值和GetTextExtentPoint32的返回值一樣,是字元串的寬度和高度;如果函式調用失敗,返回值是零。
    Windows NT:若想獲得更多錯誤信息,請調用GetLastError函式。
    備註:GetCharacterPlacement用來確保應用程式是否可以正確處理正文,不管國際通用設定和可用字型的類型如何。應用程式在調用函式ExtTextOut之前調用此函式,並用它來代替GetTextExtentPoint32(偶爾也代替函式GetCharWidth32GetCharABCWidths)。
    用GetCharacterPlacement來獲得字元間隔和指數數組並不總是必需的,除非對齊和字距調整是必需的。對於非Latin字型,應用程式可以在ExtTextOut交付正文時提高速度,只要在調用ExtTextOut之前用GetCharacterPlacement來獲得字元間的間隔和指數數組。這對於重複移交相同正文或利用字元間隔來給脫字元號定位特別有用。如果在調用ExtTextOut時要使用lpGlyphs輸出數組,則ETO_GLYPH_INDEX標誌必須被設定。
    GetCharacterPlacement檢查GCP_RESULTS結果里的lpOrder, lpDx, lpCarePos, lpOutString,lpGlyphs等成員,如果這些成員沒有被設定為NULL,為確保獲得有效的信息,應用程式有責任在調用此函式前將成員放置到有效的地址,並且在調用以後要檢查成員的值。如果給定了GCP_JUSTIFY或GCP_USEKERNING值,lpDx各/或lpCaretPos成員必須有有效地址。如果GCP_JUSTIFYIN被設定,lpDx成員也必須有合法地址。
    在進行對齊計算時,如果字元串的結尾字元是空格,此函式將養活字元串的長度值並且在計算前刪除這些空格。如果此數組全由空格組成,則函式返回出錯信息。
    速查:Windows NT:4.0及以上版本;Windows:95及以上版本;Windows CE:不支持;頭檔案:wingdi.h;庫檔案:gdi32.lib;Unicode:在Windows NT環境下實現為Unicode和ANSI兩種版本。

相關詞條

相關搜尋

熱門詞條

聯絡我們