Okay, I need to rethink these APIs. Let's start doing so. Then I should also write a testsuite for uiAttributedString.
This commit is contained in:
Pietro Gagliardi
parent
1f33ca14d8
commit
e33879a283
|
|
@ -0,0 +1,8 @@
|
|||
= attributed strings
|
||||
attribute lengths are rounded to complete unicode codepoints
|
||||
zero-length attributes are elided
|
||||
consecutive attributes of the same type and value are merged
|
||||
overlapping attributes of different types do not split each other
|
||||
overlapping attributes of the same type but different values do split
|
||||
empty string is allowed
|
||||
empty string cannot have attributes
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
// 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);
|
||||
77
ui_attrstr.h
77
ui_attrstr.h
|
|
@ -1,23 +1,3 @@
|
|||
// 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.
|
||||
//
|
||||
// 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;
|
||||
|
||||
// uiAttribute specifies the types of possible attributes that can be
|
||||
// applied to a uiAttributedString. For every byte in the
|
||||
|
|
@ -175,63 +155,6 @@ struct uiAttributeSpec {
|
|||
const uiOpenTypeFeatures *Features;
|
||||
};
|
||||
|
||||
// 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.
|
||||
_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);
|
||||
|
||||
// uiAttributedStringAppendUnattributed() 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);
|
||||
|
||||
typedef struct uiDrawFontDescriptor uiDrawFontDescriptor;
|
||||
|
||||
_UI_ENUM(uiDrawTextWeight) {
|
||||
|
|
|
|||
Loading…
Reference in New Issue