427 lines
17 KiB
C
427 lines
17 KiB
C
// 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);
|