// uiAttributedString represents a string of UTF-8 text that can // optionally be embellished with formatting attributes. libui // provides the list of formatting attributes, which cover common // formatting traits like boldface and color as well as advanced // typographical features like superscripts and small caps. // These attributes can be combined in a variety of ways. // // In addition, uiAttributedString provides facilities for moving // between grapheme clusters, which represent a character // from the point of view of the end user. The cursor of a text editor // is always placed on a grapheme boundary, so you can use these // features to move the cursor left or right by one "character". // // uiAttributedString does not provide enough information to be able // to draw itself onto a uiDrawContext or respond to user actions. // In order to do that, you'll need to use a uiDrawTextLayout, which // is built from the combination of a uiAttributedString and a set of // layout-specific properties. typedef struct uiAttributedString uiAttributedString; // Note: where you say "1 = on", any nonzero value means "on". (TODO) _UI_ENUM(uiAttribute) { uiAttributeFamily, uiAttributeSize, // use Double uiAttributeWeight, uiAttributeItalic, uiAttributeStretch, uiAttributeColor, // use R, G, B, A uiAttributeBackground, // use R, G, B, A uiAttributeUnderline, // enum uiDrawUnderlineStyle // TODO document that the color in the case we don't specify it is the text color uiAttributeUnderlineColor, // enum uiDrawUnderlineColor // TODO note that for the purpose of uiAttributedString two sets of features are only the same (and thus their attributes are merged) only if the pointers are the same; whether the tag sets are the same only become relevant to uiDrawTextLayout uiAttributeFeatures, // object of type uiOpenTypeFeatures #if 0 // These attributes represent typographic features. Each feature // is a separate attribute, to make composition easier. The // availability of for each attribute are defined by the font; the // default values are defined by the font and/or by the OS. // // A note about features whose parameter is an enumeration: // OS X defines typographic features using the AAT specification // and converts to OpenType internally when needed, whereas // other platforms use OpenType directly. OpenType is less // precise about what each enumeration value means than AAT // is, so enumeration values do not necessarily represent what // OS X expects with all fonts. In cases where they do, libui // provides an enumeration type to use. Otherwise, the AAT // enumeration values are provided in comments for // documentation purposes. // AAT calls these "common ligatures" uiAttributeStandardLigatures, // 0 = off, 1 = on uiAttributeRequiredLigatures, // 0 = off, 1 = on // AAT calls these "rare ligatures" uiAttributeDiscretionaryLigatures, // 0 = off, 1 = on uiAttributeContextualLigatures, // 0 = off, 1 = on uiAttributeHistoricalLigatures, // 0 = off, 1 = on uiAttributeUnicase, // 0 = off, 1 = on // TODO rename this uiAttributeNumberSpacings, // enum uiAttributeNumberSpacing uiAttributeSuperscripts, // enum uiAttributeSuperscript uiAttributeFractionForms, // enum uiAttributeFractionForm uiAttributeSlashedZero, // 0 = off, 1 = on uiAttributeMathematicalGreek, // 0 = off, 1 = on // AAT defines the following values: // 0 = none // 1 = dingbats // 2 = pi characters // 3 = fleurons // 4 = decorative borders // 5 = international symbols // 6 = mathematical symbols // OpenType says alphanumeric characters must(? TODO) have one form each and the bullet character U+2022 (•) can have many uiAttributeOrnamentalForms, // an integer from 0 to a font-specified upper bound // TODO provide a function to get the upper bound? // AAT calls this "character alternatives" and defines the // following values: // 0 = none // OpenType calls this "access all alternates". uiAttributeSpecificCharacterForm, // an integer from 0 to a font-specified upper bound // TODO provide a function to get the upper bound? uiAttributeTitlingCapitalForms, // 0 = off, 1 = on // AAT calls these "character shapes" uiAttributeHanCharacterForms, // enum uiAttributeHanCharacterForm // OpenType calls these "old-style" uiAttributeLowercaseNumbers, // 0 = off, 1 = on uiAttributeHanjaToHangul, // 0 = off, 1 = on // AAT defines the following values: // 0 = none // 1 = box // 2 = rounded box // 3 = circle // 4 = inverted circle // 5 = parentheses // 6 = period // 7 = roman numeral // 8 = diamond // 9 = inverted box // 10 = inverted rounded box uiAttributeAnnotatedGlyphForms, // an integer from 0 to a font-specified upper bound // TODO provide a function to get the upper bound? uiAttributeRubyKanaForms, // 0 = off, 1 = on uiAttributeCJKRomansToItalics, // 0 = off, 1 = on // AAT calls this "case-sensitive layout" uiAttributeCaseSensitiveForms, // 0 = off, 1 = on // AAT: this is called "case-sensitive spacing" uiAttributeCapitalSpacing, // 0 = off, 1 = on uiAttributeAlternateHorizontalKana, // 0 = off, 1 = on uiAttributeAlternateVerticalKana, // 0 = off, 1 = on // TODO document that these are guaranteed to be consecutive uiAttributeStylisticAlternate1, // 0 = off, 1 = on uiAttributeStylisticAlternate2, // 0 = off, 1 = on uiAttributeStylisticAlternate3, // 0 = off, 1 = on uiAttributeStylisticAlternate4, // 0 = off, 1 = on uiAttributeStylisticAlternate5, // 0 = off, 1 = on uiAttributeStylisticAlternate6, // 0 = off, 1 = on uiAttributeStylisticAlternate7, // 0 = off, 1 = on uiAttributeStylisticAlternate8, // 0 = off, 1 = on uiAttributeStylisticAlternate9, // 0 = off, 1 = on uiAttributeStylisticAlternate10, // 0 = off, 1 = on uiAttributeStylisticAlternate11, // 0 = off, 1 = on uiAttributeStylisticAlternate12, // 0 = off, 1 = on uiAttributeStylisticAlternate13, // 0 = off, 1 = on uiAttributeStylisticAlternate14, // 0 = off, 1 = on uiAttributeStylisticAlternate15, // 0 = off, 1 = on uiAttributeStylisticAlternate16, // 0 = off, 1 = on uiAttributeStylisticAlternate17, // 0 = off, 1 = on uiAttributeStylisticAlternate18, // 0 = off, 1 = on uiAttributeStylisticAlternate19, // 0 = off, 1 = on uiAttributeStylisticAlternate20, // 0 = off, 1 = on uiAttributeContextualAlternates, // 0 = off, 1 = on uiAttributeSwashes, // 0 = off, 1 = on uiAttributeContextualSwashes, // 0 = off, 1 = on uiAttributeLowercaseCapForms, // enum uiAttributeCapForm uiAttributeUppercaseCapForms, // enum uiAttributeCapForm }; #endif }; _UI_ENUM(uiDrawUnderlineStyle) { uiDrawUnderlineStyleNone, uiDrawUnderlineStyleSingle, uiDrawUnderlineStyleDouble, uiDrawUnderlineStyleSuggestion, // wavy or dotted underlines used for spelling/grammar checkers }; _UI_ENUM(uiDrawUnderlineColor) { uiDrawUnderlineColorCustom, // also use R/G/B/A fields uiDrawUnderlineColorSpelling, uiDrawUnderlineColorGrammar, uiDrawUnderlineColorAuxiliary, // for instance, the color used by smart replacements on OS X }; #if 0 _UI_ENUM(uiAttributeNumberSpacing) { uiAttributeNumberSpacingProportional, // AAT calls this "monospaced" uiAttributeNumberSpacingTabular, }; _UI_ENUM(uiAttributeSuperscript) { uiAttributeSuperscriptNone, uiAttributeSuperscriptSuperscript, // AAT: "superior" uiAttributeSuperscriptSubscript, // AAT: "inferior" uiAttributeSuperscriptOrdinal, uiAttributeSuperscriptScientificInferior, }; _UI_ENUM(uiAttributeFractionForm) { uiAttributeFractionFormNone, uiAttributeFractionFormVertical, uiAttributeFractionFormDiagonal, }; _UI_ENUM(uiAttributeHanCharacterForm) { uiAttributeHanCharacterFormTraditional, uiAttributeHanCharacterFormSimplified, uiAttributeHanCharacterFormJIS1978, uiAttributeHanCharacterFormJIS1983, uiAttributeHanCharacterFormJIS1990, uiAttributeHanCharacterFormExpert, uiAttributeHanCharacterFormJIS2004, uiAttributeHanCharacterFormHojo, uiAttributeHanCharacterFormNLC, uiAttributeHanCharacterFormTraditionalNames, }; _UI_ENUM(uiAttributeCapForm) { uiAttributeCapFormNormal, uiAttributeCapFormSmallCaps, uiAttributeCapFormPetiteCaps, }; #endif // TODO rename? typedef struct uiOpenTypeFeatures uiOpenTypeFeatures; // TODO pass the feature set? typedef int (*uiOpenTypeFeaturesForEachFunc)(char a, char b, char c, char d, uint32_t value, void *data); // TODO detailed constructor? _UI_EXTERN uiOpenTypeFeatures *uiNewOpenTypeFeatures(void); _UI_EXTERN void uiFreeOpenTypeFeatures(uiOpenTypeFeatures *otf); // TODO put above Free? // TODO Copy instead of Clone? _UI_EXTERN uiOpenTypeFeatures *uiOpenTypeFeaturesClone(uiOpenTypeFeatures *otf); _UI_EXTERN void uiOpenTypeFeaturesAdd(uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t value); _UI_EXTERN void uiOpenTypeFeaturesRemove(uiOpenTypeFeatures *otf, char a, char b, char c, char d); _UI_EXTERN int uiOpenTypeFeaturesGet(uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t *value); _UI_EXTERN void uiOpenTypeFeaturesForEach(uiOpenTypeFeatures *otf, uiOpenTypeFeaturesForEachFunc f, void *data); _UI_EXTERN int uiOpenTypeFeaturesEqual(uiOpenTypeFeatures *a, uiOpenTypeFeatures *b); typedef struct uiAttributeSpec uiAttributeSpec; struct uiAttributeSpec { uiAttribute Type; uintptr_t Value; double Double; double R; double G; double B; double A; }; // TODO name the foreach return values typedef int (*uiAttributedStringForEachAttributeFunc)(uiAttributedString *s, uiAttributeSpec *spec, size_t start, size_t end, void *data); // @role uiAttributedString constructor // uiNewAttributedString() creates a new uiAttributedString from // initialString. The string will be entirely unattributed. _UI_EXTERN uiAttributedString *uiNewAttributedString(const char *initialString); // @role uiAttributedString destructor // uiFreeAttributedString() destroys the uiAttributedString s. _UI_EXTERN void uiFreeAttributedString(uiAttributedString *s); // uiAttributedStringString() returns the textual content of s as a // '\0'-terminated UTF-8 string. The returned pointer is valid until // the next change to the textual content of s. _UI_EXTERN const char *uiAttributedStringString(uiAttributedString *s); // uiAttributedStringLength() returns the number of UTF-8 bytes in // the textual content of s, excluding the terminating '\0'. _UI_EXTERN size_t uiAttributedStringLen(uiAttributedString *s); _UI_EXTERN void uiAttributedStringAppendUnattributed(uiAttributedString *s, const char *str); _UI_EXTERN void uiAttributedStringInsertAtUnattributed(uiAttributedString *s, const char *str, size_t at); _UI_EXTERN void uiAttributedStringDelete(uiAttributedString *s, size_t start, size_t end); _UI_EXTERN size_t uiAttributedStringNumGraphemes(uiAttributedString *s); _UI_EXTERN size_t uiAttributedStringByteIndexToGrapheme(uiAttributedString *s, size_t pos); _UI_EXTERN size_t uiAttributedStringGraphemeToByteIndex(uiAttributedString *s, size_t pos); _UI_EXTERN void uiAttributedStringSetAttribute(uiAttributedString *s, uiAttributeSpec *spec, size_t start, size_t end); _UI_EXTERN void uiAttributedStringForEachAttribute(uiAttributedString *s, uiAttributedStringForEachAttributeFunc f, void *data); typedef struct uiDrawFontDescriptor uiDrawFontDescriptor; // TODO Minimum == 1? IIRC there is at least one font on OS X that actually has a weight of 0 // TODO Maximum == 999? IIRC there is at least one font on OS X that actually has a weight of 1000 _UI_ENUM(uiDrawTextWeight) { uiDrawTextWeightMinimum = 0, uiDrawTextWeightThin = 100, uiDrawTextWeightUltraLight = 200, uiDrawTextWeightLight = 300, uiDrawTextWeightBook = 350, uiDrawTextWeightNormal = 400, uiDrawTextWeightMedium = 500, uiDrawTextWeightSemiBold = 600, uiDrawTextWeightBold = 700, uiDrawTextWeightUltraBold = 800, uiDrawTextWeightHeavy = 900, uiDrawTextWeightUltraHeavy = 950, uiDrawTextWeightMaximum = 1000, }; _UI_ENUM(uiDrawTextItalic) { uiDrawTextItalicNormal, uiDrawTextItalicOblique, uiDrawTextItalicItalic, }; // TODO realign this so that Normal == 0? _UI_ENUM(uiDrawTextStretch) { uiDrawTextStretchUltraCondensed, uiDrawTextStretchExtraCondensed, uiDrawTextStretchCondensed, uiDrawTextStretchSemiCondensed, uiDrawTextStretchNormal, uiDrawTextStretchSemiExpanded, uiDrawTextStretchExpanded, uiDrawTextStretchExtraExpanded, uiDrawTextStretchUltraExpanded, }; struct uiDrawFontDescriptor { char *Family; double Size; uiDrawTextWeight Weight; uiDrawTextItalic Italic; uiDrawTextStretch Stretch; }; typedef struct uiDrawTextLayout uiDrawTextLayout; typedef struct uiDrawTextLayoutParams uiDrawTextLayoutParams; typedef struct uiDrawTextLayoutLineMetrics uiDrawTextLayoutLineMetrics; // TODO drop the Layout from this? _UI_ENUM(uiDrawTextLayoutAlign) { uiDrawTextLayoutAlignLeft, uiDrawTextLayoutAlignCenter, uiDrawTextLayoutAlignRight, }; struct uiDrawTextLayoutParams { uiAttributedString *String; uiDrawFontDescriptor *DefaultFont; double Width; uiDrawTextLayoutAlign Align; }; // Height will equal ParagraphSpacingBefore + LineHeightSpace + Ascent + Descent + Leading + LineSpacing + ParagraphSpacing. // The above values are listed in vertical order, from top to bottom. // Ascent + Descent + Leading will give you the typographic bounds // of the text. BaselineY is the boundary between Ascent and Descent. // X, Y, and BaselineY are all in the layout's coordinate system, so the // start point of the baseline will be at (X, BaselineY). All values are // nonnegative. struct uiDrawTextLayoutLineMetrics { // This describes the overall bounding box of the line. double X; double Y; double Width; double Height; // This describes the typographic bounds of the line. double BaselineY; double Ascent; double Descent; double Leading; // This describes any additional whitespace. // TODO come up with better names for these. double ParagraphSpacingBefore; double LineHeightSpace; double LineSpacing; double ParagraphSpacing; // TODO trailing whitespace? }; // TODO // - allow creating a layout out of a substring // - allow marking compositon strings // - allow marking selections, even after creation // - add the following functions: // - uiDrawTextLayoutHeightForWidth() (returns the height that a layout would need to be to display the entire string at a given width) // - uiDrawTextLayoutRangeForSize() (returns what substring would fit in a given size) // - uiDrawTextLayoutNewWithHeight() (limits amount of string used by the height) // - some function to fix up a range (for text editing) _UI_EXTERN uiDrawTextLayout *uiDrawNewTextLayout(uiDrawTextLayoutParams *params); _UI_EXTERN void uiDrawFreeTextLayout(uiDrawTextLayout *tl); _UI_EXTERN void uiDrawText(uiDrawContext *c, uiDrawTextLayout *tl, double x, double y); _UI_EXTERN void uiDrawTextLayoutExtents(uiDrawTextLayout *tl, double *width, double *height); _UI_EXTERN int uiDrawTextLayoutNumLines(uiDrawTextLayout *tl); _UI_EXTERN void uiDrawTextLayoutLineByteRange(uiDrawTextLayout *tl, int line, size_t *start, size_t *end); _UI_EXTERN void uiDrawTextLayoutLineGetMetrics(uiDrawTextLayout *tl, int line, uiDrawTextLayoutLineMetrics *m); // TODO number of lines visible for clipping rect, range visible for clipping rect? // TODO rewrite all this documentation // uiDrawTextLayoutHitTest() returns the byte offset and line closest // to the given point. The point is relative to the top-left of the layout. // If the point is outside the layout itself, the closest point is chosen; // this allows the function to be used for cursor positioning with the // mouse. Do keep the returned line in mind if used in this way; the // user might click on the end of a line, at which point the cursor // might be at the trailing edge of the last grapheme on the line // (subject to the operating system's APIs). _UI_EXTERN void uiDrawTextLayoutHitTest(uiDrawTextLayout *tl, double x, double y, size_t *pos, int *line); // uiDrawTextLayoutByteLocationInLine() returns the point offset // into the given line that the given byte position stands. This is // relative to the line's X position (as returned by // uiDrawTextLayoutLineGetMetrics()), which in turn is relative to // the top-left of the layout. This function can be used for cursor // positioning: if start and end are the start and end of the line // (as returned by uiDrawTextLayoutLineByteRange()), you will get // the correct offset, even if pos is at the end of the line. If pos is not // in the range [start, end], a negative value will be returned, // indicating you need to move the cursor to another line. // TODO make sure this works right for right-aligned and center-aligned lines and justified lines and RTL text _UI_EXTERN double uiDrawTextLayoutByteLocationInLine(uiDrawTextLayout *tl, size_t pos, int line); _UI_EXTERN void uiDrawCaret(uiDrawContext *c, double x, double y, uiDrawTextLayout *layout, size_t pos, int *line); // TODO allow blinking typedef struct uiFontButton uiFontButton; #define uiFontButton(this) ((uiFontButton *) (this)) _UI_EXTERN void uiFontButtonFont(uiFontButton *b, uiDrawFontDescriptor *desc); // TOOD SetFont, mechanics _UI_EXTERN void uiFontButtonOnChanged(uiFontButton *b, void (*f)(uiFontButton *, void *), void *data); _UI_EXTERN uiFontButton *uiNewFontButton(void);