diff --git a/checklist_attrstr b/checklist_attrstr index e4c6bf3f..47117def 100644 --- a/checklist_attrstr +++ b/checklist_attrstr @@ -20,3 +20,5 @@ should FeaturesAttribute be changed to OpenTypeFeaturesAttribute and likewise fo should uiNewFeaturesAttribute() accept NULL should uiNewFamilyAttribute() accept NULL it is an error in ForEach too +invalid values for uiDrawTextAlign +empty text layouts have one line diff --git a/new_ui_attrstr.h b/new_ui_attrstr.h index 8772f4e0..f180ad66 100644 --- a/new_ui_attrstr.h +++ b/new_ui_attrstr.h @@ -416,3 +416,81 @@ struct uiDrawFontDescriptor { uiTextItalic Italic; uiTextStretch Stretch; }; + +// uiDrawTextLayout is a concrete representation of a +// uiAttributedString that can be displayed in a uiDrawContext. +// It includes information important for the drawing of a block of +// text, including the bounding box to wrap the text within, the +// alignment of lines of text within that box, areas to mark as +// being selected, and other things. +// +// Unlike uiAttributedString, the content of a uiDrawTextLayout is +// immutable once it has been created. +// +// TODO talk about OS-specific differences with text drawing that libui can't account for... +typedef struct uiDrawTextLayout uiDrawTextLayout; + +// uiDrawTextAlign specifies the alignment of lines of text in a +// uiDrawTextLayout. +_UI_ENUM(uiDrawTextAlign) { + uiDrawTextAlignLeft, + uiDrawTextAlignCenter, + uiDrawTextAlignRight, +}; + +// uiDrawTextLayoutParams describes a uiDrawTextLayout. +// DefaultFont is used to render any text that is not attributed +// sufficiently in String. Width determines the width of the bounding +// box of the text; the height is determined automatically. +typedef struct uiDrawTextLayoutParams uiDrawTextLayoutParams; + +// TODO const-correct this somehow +struct uiDrawTextLayoutParams { + uiAttributedString *String; + uiDrawFontDescriptor *DefaultFont; + double Width; + uiDrawTextAlign Align; +}; + +// @role uiDrawTextLayout constructor +// uiDrawNewTextLayout() creates a new uiDrawTextLayout from +// the given parameters. +// +// 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); + +// @role uiDrawFreeTextLayout destructor +// uiDrawFreeTextLayout() frees tl. The underlying +// uiAttributedString is not freed. +_UI_EXTERN void uiDrawFreeTextLayout(uiDrawTextLayout *tl); + +// uiDrawText() draws tl in c with the top-left point of tl at (x, y). +_UI_EXTERN void uiDrawText(uiDrawContext *c, uiDrawTextLayout *tl, double x, double y); + +// uiDrawTextLayoutExtents() returns the width and height of tl +// in width and height. The returned width may be smaller than +// the width passed into uiDrawNewTextLayout() depending on +// how the text in tl is wrapped. Therefore, you can use this +// function to get the actual size of the text layout. +_UI_EXTERN void uiDrawTextLayoutExtents(uiDrawTextLayout *tl, double *width, double *height); + +// uiDrawTextLayoutNumLines() returns the number of lines in tl. +// This number will always be greater than or equal to 1; a text +// layout with no text only has one line. +_UI_EXTERN int uiDrawTextLayoutNumLines(uiDrawTextLayout *tl); + +// uiDrawTextLayoutLineByteRange() returns the byte indices of the +// text that falls into the given line of tl as [start, end). +_UI_EXTERN void uiDrawTextLayoutLineByteRange(uiDrawTextLayout *tl, int line, size_t *start, size_t *end); + +// TODO metrics functions + +// TODO number of lines visible for clipping rect, range visible for clipping rect? diff --git a/ui_attrstr.h b/ui_attrstr.h index c4d8382b..5dfc921c 100644 --- a/ui_attrstr.h +++ b/ui_attrstr.h @@ -1,20 +1,6 @@ -typedef struct uiDrawTextLayout uiDrawTextLayout; -typedef struct uiDrawTextLayoutParams uiDrawTextLayoutParams; + typedef struct uiDrawTextLayoutLineMetrics uiDrawTextLayoutLineMetrics; -_UI_ENUM(uiDrawTextAlign) { - uiDrawTextAlignLeft, - uiDrawTextAlignCenter, - uiDrawTextAlignRight, -}; - -struct uiDrawTextLayoutParams { - uiAttributedString *String; - uiDrawFontDescriptor *DefaultFont; - double Width; - uiDrawTextAlign 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 @@ -45,25 +31,9 @@ struct uiDrawTextLayoutLineMetrics { // 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 +// TODO rewrite 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.