From cde1a201f4bc479d7df744d4948be59de7acfd97 Mon Sep 17 00:00:00 2001 From: Pietro Gagliardi Date: Thu, 8 Jun 2017 15:31:28 -0400 Subject: [PATCH] Expanded documentation in ui_attrstr.h in an attempt to reduce TODOs. Instead, I added more. :D --- ui_attrstr.h | 60 ++++++++++++++++++++++++++++++++++++++++++++++++---- unix/area.c | 3 +++ 2 files changed, 59 insertions(+), 4 deletions(-) diff --git a/ui_attrstr.h b/ui_attrstr.h index 9a5e1bfe..e5147a02 100644 --- a/ui_attrstr.h +++ b/ui_attrstr.h @@ -19,6 +19,7 @@ // layout-specific properties. typedef struct uiAttributedString uiAttributedString; +// TODO either here or above, say that only one attribute can be applied per attribute type per character // TODO just make a separate field in uiAttributeSpec for everything? or make attribute objects opaque instead? _UI_ENUM(uiAttribute) { // uiAttributeFamily changes the font family of the text it is @@ -80,19 +81,70 @@ _UI_ENUM(uiDrawUnderlineColor) { uiDrawUnderlineColorAuxiliary, // for instance, the color used by smart replacements on OS X }; +// uiOpenTypeFeatures represents a set of OpenType feature +// tag-value pairs, for applying OpenType features to text. +// OpenType feature tags are four-character codes defined by +// OpenType that cover things from design features like small +// caps and swashes to language-specific glyph shapes and +// beyond. Each tag may only appear once in any given +// uiOpenTypeFeatures instance. Each value is a 32-bit integer, +// often used as a Boolean flag, but sometimes as an index to choose +// a glyph shape to use. +// +// The full list of OpenType features is part of the OpenType +// specification: +// https://www.microsoft.com/typography/otspec/featuretags.htm +// Refer to it for information on specific features and how to use +// them. +// TODO reformat this somehow (how do Go packages do things like this?) typedef struct uiOpenTypeFeatures uiOpenTypeFeatures; -// TODO pass the feature set? + +// TODO pass the feature set? (resolve const struct issue below first) typedef uiForEach (*uiOpenTypeFeaturesForEachFunc)(char a, char b, char c, char d, uint32_t value, void *data); + +// @role uiOpenTypeFeatures constructor +// uiNewOpenTypeFeatures() returns a new uiOpenTypeFeatures +// instance, with no tags yet added. _UI_EXTERN uiOpenTypeFeatures *uiNewOpenTypeFeatures(void); + +// @role uiOpenTypeFeatures destructor +// uiFreeOpenTypeFeatures() frees otf. _UI_EXTERN void uiFreeOpenTypeFeatures(uiOpenTypeFeatures *otf); -// TODO put above Free? -// TODO Copy instead of Clone? + +// uiOpenTypeFeaturesClone() makes a copy of otf and returns it. +// Changing one will not affect the other. _UI_EXTERN uiOpenTypeFeatures *uiOpenTypeFeaturesClone(const uiOpenTypeFeatures *otf); + +// uiOpenTypeFeaturesAdd() adds the given feature tag and value +// to otf. The feature tag is specified by a, b, c, and d. If there is +// already a value associated with the specified tag in otf, the old +// value is removed. _UI_EXTERN void uiOpenTypeFeaturesAdd(uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t value); + +// uiOpenTypeFeaturesRemove() removes the given feature tag +// and value from otf. +// TODO what happens if the tag isn't there? _UI_EXTERN void uiOpenTypeFeaturesRemove(uiOpenTypeFeatures *otf, char a, char b, char c, char d); + +// uiOpenTypeFeaturesGet() determines whether the given feature +// tag is present in otf. If it is, *value is set to the tag's value and +// nonzero is returned. Otherwise, zero is returned. +// TODO zero-fill value unconditionally? and if so, to other functions in libui +// TODO allow NULL for value? and throughout libui? +// TODO const-correct this function (can we do that given the members of the struct on some platforms being full blown objects that may or may not themselves be const-correct?) _UI_EXTERN int uiOpenTypeFeaturesGet(uiOpenTypeFeatures *otf, char a, char b, char c, char d, uint32_t *value); -// TODO make other enumerators const (and in general const-correct everything) + +// uiOpenTypeFeaturesForEach() executes f for every tag-value +// pair in otf. The enumeration order is unspecified. +// TODO make other enumerators const (and in general const-correct everything) (but see the const struct TODO below and the const struct object member TODO above) _UI_EXTERN void uiOpenTypeFeaturesForEach(const uiOpenTypeFeatures *otf, uiOpenTypeFeaturesForEachFunc f, void *data); + +// uiOpenTypeFeaturesEqual() returns nonzero if a is equal to b. +// a is defined as equal to b if and only if both +// - contain the same tags, without any extras or missing tags +// either way, and +// - have each tag have the same values +// TODO what if either or both are NULL? _UI_EXTERN int uiOpenTypeFeaturesEqual(const uiOpenTypeFeatures *a, const uiOpenTypeFeatures *b); typedef struct uiAttributeSpec uiAttributeSpec; diff --git a/unix/area.c b/unix/area.c index ca99e602..24cd9513 100644 --- a/unix/area.c +++ b/unix/area.c @@ -92,6 +92,9 @@ static void areaWidget_size_allocate(GtkWidget *w, GtkAllocation *allocation) if (!a->scrolling) // we must redraw everything on resize because Windows requires it + // TODO https://developer.gnome.org/gtk3/3.10/GtkWidget.html#gtk-widget-set-redraw-on-allocate ? + // TODO drop this rule; it was stupid and documenting this was stupid — let platforms where it matters do it on their own + // TODO or do we not, for parity of performance? gtk_widget_queue_resize(w); }