93 lines
4.7 KiB
C
93 lines
4.7 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 provided by OpenType like superscripts
|
|
// and small caps. These attributes can be combined in a variety of
|
|
// ways.
|
|
//
|
|
// Attributes are applied to runs of Unicode codepoints in the string.
|
|
// Zero-length runs are elided. Consecutive runs that have the same
|
|
// attribute type and value are merged. Each attribute is independent
|
|
// of each other attribute; overlapping attributes of different types
|
|
// do not split each other apart, but different values of the same
|
|
// attribute type do.
|
|
//
|
|
// The empty string can also be represented by uiAttributedString,
|
|
// but because of the no-zero-length-attribute rule, it will not have
|
|
// attributes.
|
|
//
|
|
// TODO note here about attribute ownership
|
|
//
|
|
// 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".
|
|
// TODO does uiAttributedString itself need this
|
|
//
|
|
// 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;
|
|
|
|
// uiAttributedStringForEachAttributeFunc is the type of the function
|
|
// invoked by uiAttributedStringForEachAttribute() for every
|
|
// attribute in s. Refer to that function's documentation for more
|
|
// details.
|
|
typedef uiForEach (*uiAttributedStringForEachAttributeFunc)(const uiAttributedString *s, const 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.
|
|
// TODO note here about attribute ownership
|
|
_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(const 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(const uiAttributedString *s);
|
|
|
|
// uiAttributedStringAppendUnattributed() adds the '\0'-terminated
|
|
// UTF-8 string str to the end of s. The new substring will be
|
|
// unattributed.
|
|
_UI_EXTERN void uiAttributedStringAppendUnattributed(uiAttributedString *s, const char *str);
|
|
|
|
// uiAttributedStringInsertAtUnattributed() adds the '\0'-terminated
|
|
// UTF-8 string str to s at the byte position specified by at. The new
|
|
// substring will be unattributed; existing attributes will be moved
|
|
// along with its text.
|
|
_UI_EXTERN void uiAttributedStringInsertAtUnattributed(uiAttributedString *s, const char *str, size_t at);
|
|
|
|
// TODO add the Append and InsertAtExtendingAttributes functions
|
|
// TODO and add functions that take a string + length
|
|
|
|
// uiAttributedStringDelete() deletes the characters and attributes of
|
|
// s in the range [start, end).
|
|
_UI_EXTERN void uiAttributedStringDelete(uiAttributedString *s, size_t start, size_t end);
|
|
|
|
// TODO const correct this somehow (the implementation needs to mutate the structure)
|
|
_UI_EXTERN size_t uiAttributedStringNumGraphemes(uiAttributedString *s);
|
|
|
|
// TODO const correct this somehow (the implementation needs to mutate the structure)
|
|
_UI_EXTERN size_t uiAttributedStringByteIndexToGrapheme(uiAttributedString *s, size_t pos);
|
|
|
|
// TODO const correct this somehow (the implementation needs to mutate the structure)
|
|
_UI_EXTERN size_t uiAttributedStringGraphemeToByteIndex(uiAttributedString *s, size_t pos);
|
|
|
|
_UI_EXTERN void uiAttributedStringSetAttribute(uiAttributedString *s, uiAttributeSpec *spec, size_t start, size_t end);
|
|
|
|
// TODO document this
|
|
// TODO possibly copy the spec each time to ensure it doesn't get clobbered
|
|
_UI_EXTERN void uiAttributedStringForEachAttribute(uiAttributedString *s, uiAttributedStringForEachAttributeFunc f, void *data);
|