מדריך מפתחים של PDFium Delphi Component

Unit: FPdfTextShapingHb

עורף עיצוב טקסט HarfBuzz עבור יעדי Free Pascal, שקושר את libharfbuzz בזמן ריצה ומקבל את בתי הגופן מפותר שמספק המארח

Syntax

TPdfFontDataResolver = function(const FontName: WideString;
  out FontData: TBytes): Boolean of object;

EPdfHarfBuzzError = class(Exception);

TPdfHarfBuzzTextShaper = class(TPdfTextShaper)
  constructor Create(const Resolver: TPdfFontDataResolver);
  destructor Destroy; override;
  function Shape(const Text, FontName: WideString; FontSize: Single;
    const Options: TPdfTextShapingOptions;
    out Shaped: TPdfShapedText): Boolean; override;
end;

function HarfBuzzAvailable: Boolean;
function HarfBuzzVersionString: string;

Description

‏FPdfTextShapingHb הוא המקבילה של עורף ה-Uniscribe שב-FPdfTextShaping, עבור יעדים שאין להם usp10.dll. הממשק מקומפל תחת Free Pascal בלבד, כי יעדי Delphi הם Windows שבהם עורף ה-Uniscribe הוא זה שרלוונטי

שני העורפים מחלקים את העבודה אחרת: Uniscribe מפצל לפריטים, מעצב, ממקם ומסדר מחדש במעבר אחד, ואילו HarfBuzz מעצב ריצה בודדת שהכיוון והכתב שלה כבר ידועים. היחידה הזו מספקת את השאר: ‏FPdfBidi פותר את רמות ההטמעה, הכתב ה-Unicode של כל תו מפלח את הטקסט לריצות, והריצות מסודרות בסדר הוויזואלי שחוק L2 של UAX #9 נותן. תווים מכתב Common, ‏Inherited ולא מזוהה ממשיכים את הריצה שבתוכה הם נמצאים, כך שספרה או רווח לא מפצלים מילה

‏libharfbuzz נקשר בזמן ריצה דרך DynLibs, כך שהוא אינו תלות build, והיעדרותו מדווחת ואינה קטלנית. ‏HarfBuzzAvailable מדווח אם הספרייה נמצאה ונקודות הכניסה הדרושות נפתרו, ו-HarfBuzzVersionString מחזיר את הגרסה של הספרייה שנטענה

המעצב אינו מאתר גופנים בעצמו. Uniscribe קורא את הבינארי של הגופן מתוך הקשר התקן GDI, שאין לו מקבילה ניידת, ולכן המארח מעביר TPdfFontDataResolver אל Create שממפה שם גופן אל בתי ה-TrueType או ה-OpenType. כך ספירת הגופנים - fontconfig, ‏CoreText, או תיקיית הגופנים של היישום עצמו - נשארת מחוץ ליחידה שאין לה עסק בהכתבת מדיניות כזו

Functions

Function	Description
`HarfBuzzAvailable`	True כאשר libharfbuzz נמצאה ונקודות הכניסה הדרושות נפתרו; הקריאה הראשונה מבצעת את הקישור
`HarfBuzzVersionString`	הגרסה של הספרייה הטעונה בתבנית "major.minor.micro", או מחרוזת ריקה כאשר הספרייה אינה זמינה

Types

Type	Description
`TPdfFontDataResolver`	הפניה למתודה שממפה את `FontName` אל בתי קובץ הגופן ב-`FontData`; החזרת False גורמת למעצב לדחות את הבקשה בדיוק כפי שגופן GDI שאינו קריא נדחה ב-Windows
`EPdfHarfBuzzError`	חריגה שנזרקת כאשר לא הוגדר פותר, כאשר libharfbuzz אינה זמינה, או כאשר blob, face, font או buffer של HarfBuzz לא ניתנים ליצירה
`TPdfHarfBuzzTextShaper`	מימוש `TPdfTextShaper` מגובה HarfBuzz, עם `Create`,‏ `Destroy` ו-`Shape`

Members of TPdfHarfBuzzTextShaper

Member	Description
`Create(Resolver)`	יוצר את המעצב ושומר את ה-`TPdfFontDataResolver` שישמש לכל איתור גופן
`Destroy`	משחרר את ה-face וה-blob של HarfBuzz שנשמרו במטמון, ואז את ההורס היורש
`Shape(Text, FontName, FontSize, Options, Shaped)`	פותר את רמות ההטמעה, מפלח את הטקסט לפי רמה וכתב, מעצב כל ריצה דרך HarfBuzz ומחזיר את הריצות בסדר ויזואלי בתוך `Shaped`; מחזיר False כאשר הטקסט אינו מניב גליפים

Remarks

הקישור עצלן: הקריאה הראשונה ל-HarfBuzzAvailable בודקת את libharfbuzz-0.dll ו-harfbuzz.dll ב-Windows, את libharfbuzz.0.dylib ו-libharfbuzz.dylib ב-macOS, ואת libharfbuzz.so.0 ו-libharfbuzz.so בשאר הסביבות
ה-handle של הספרייה נשאר פתוח למשך חיי התהליך, כי פריקה בזמן שתהליון אחר נמצא בתוך קריאת עיצוב הייתה מפילה את המארח
‏Shape מעלה EPdfTextShapingError עבור טקסט ריק, שם גופן ריק, גודל גופן שאינו חיובי, מגבלות Options לא תקינות, טקסט החורג מ-MaxCharacters, גליפים החורגים מ-MaxGlyphs, או נתוני גופן שהפותר לא הצליח לספק
‏Shape מעלה EPdfHarfBuzzError כאשר לא הוגדר TPdfFontDataResolver, כאשר libharfbuzz אינה זמינה, או כאשר אובייקט HarfBuzz לא ניתן ליצירה
face אחד נשמר במטמון לכל שם גופן יחד עם הבתים שמהם נבנה, ומשוחרר כאשר השם המבוקש משתנה או שהמעצב נהרס
המחרוזת כולה נמסרת ל-HarfBuzz כשהריצה מסומנת בתוכה, כך שכתבים מצטרפים (joining scripts) עדיין רואים את התווים משני הצדדים ובוחרים את הצורות ההקשריות הנכונות
ההתקדמויות וההיסטים מוחזרים בנקודות, לאחר המרה מערכי נקודה-קבועה 26.6 ש-HarfBuzz מדווח
מיקומי האשכולות הם אינדקסים לוגיים אל טקסט המקור, ואורכי האשכולות נגזרים מהמרחק אל תחילת האשכול הבא, בכל אחד מכיווני הקריאה
מספר הריצות מוגבל על ידי Options.MaxRuns, ו-Options.Direction ממפה את ptdLeftToRight ו-ptdRightToLeft אל כיוון פסקה קבוע, כאשר כל שאר הערכים נפתרים באופן אוטומטי
‏Shaped.FontData מחזיק את הבתים שהפותר החזיר, וזה בדיוק מה ש-TPdf.AddShapedText צריך כדי לבנות גופן CID

יחידת FPdfTextShapingHb