yappologistic/CUI v1.4.0

CUI 1.4

on GitHub

Five components that read like an instrument, a new example that puts them together, three guides and a reference of every function. Linux desktops can now match a window to its app, and fixes cover the single file after windows.h and the keyboard in three components.

Added

• Instruments, five components for interfaces that read like an instrument: values as dots, labels in the monospaced font, hairlines and one accent. See Instruments and the gallery's new Instruments page.
  • Dot-matrix chart (cui_dot_chart): values as a grid of dots, lit up to each column's value and dim above it. Series stack, an accent series stands out, the pointer or the arrow keys show a readout, and a click returns where it landed.
  • Chart annotations (cui_chart_annotation): vertical lines, dashed thresholds and labelled points over the dot chart, the line chart and the bar chart. Labels that would overlap move to the other side of their line, then down.
  • Event track (cui_event_track): moments on a time axis as dots you drag, add with a click and remove with a double-click, snapped to a step, with full keyboard control. It lines up with a dot chart above it.
  • Readout (cui_readout): a label, a value with its unit on the value's baseline, and a line of context.
  • Dot-matrix display (cui_dot_display): text in a 5 by 7 dot font that shrinks to fit or scrolls.
  • In a right-to-left interface the readout and the display's placement follow the reading direction, the chart and the track keep time running left to right, and Persian or Arabic labels are shaped with CUI_TEXT_SHAPING.
• cui_axis_units: CUI_AXIS_HOURS labels an axis as times of day, with 30 reading 06:00 the next morning.
• Caffeine, a new example (examples/caffeine.c) that puts the instruments on one screen: how much caffeine is still in you at bedtime, with cups you drag. It runs on the site and ships in the release downloads.
• Three new guides. Building an app covers the window, when frames happen, what components return, work on other threads and shipping. Recipes has six complete programs: a form that validates, a table sorted by its headers, a list with a detail pane, a long task on another thread, a clock, and settings that are remembered. Questions says what CUI is and is not, how it compares with other libraries, and what it cannot do.
• A function reference. The site has a page that lists every public function of cui.h, cui_app.h and cui_render.h (496 of them) under the headers' own sections: its signature, the comment written beside it, and a link to the component page or guide that explains it. It has a filter, and site search finds a function by name.
• Complete programs on component pages. A page's usage block is a fragment. 71 of the 147 pages now also have the example as a whole program, with its includes, a frame function and main, under "Complete program". The site build compiles each one and leaves out any that does not build.
• cui_app_quit, cui_app_set_title, cui_app_set_size, cui_app_size, cui_app_ui, cui_app_is_software and cui_app_native_window take NULL for the app that is running, as cui_app_file_dialog already did. A cui_app_run callback had no way to close its window or change its title: now it is cui_app_quit(NULL).
• tests/doc_programs.sh, run on every push: it builds every complete program in the docs with warnings as errors.
• cui_app_desc.app_id lets a Linux desktop show your app's name and icon for its window in the taskbar, the dock and Alt+Tab. Name your .desktop file after the ID (for example org.example.Notes.desktop). It sets WM_CLASS on X11, and the Wayland app ID with SDL2 or GLFW 3.4. Before this, every window of the X11 backend had the class CUI. See Your app's name and icon on Linux.

Changed

• Every component has a description. Each section of the component docs now opens with one sentence that says what the component is and what it is for. The site shows it under the page title, on the cards that link to the page and in search results, where it used to show whatever sentence came first ("Weeks start on Monday." for the date picker).
• Site search reads the whole site. It now searches the text of the guides, the options and struct fields of every component and the changelog, and shows the words around a match. It used to look at titles and summaries only, so "install", "find_package" or the name of an option found nothing.
• Every page has its own address for search engines. The site was one page as far as a search engine could tell, so nobody searching for "C date picker" could land on the date picker. The build now writes a page per component and per guide (c/date-picker-and-calendar/, guide/tutorial/) with its text, title and description, plus sitemap.xml and robots.txt. Opened in a browser, such a page becomes the live site at that page.
• Links to the site show a preview. Every page carries a title, a description and an image for the cards that chat apps and social sites draw; a component's card shows the component.
• The site shows the version it documents beside the name.
• Fuller component pages. Sections that showed a snippet and a sentence now say what the call returns and when, which variables are yours and what the library writes into them, and the limits people run into, each checked against the code.
• Every option is described. All 1,277 fields of the options and data structs on the component pages now have a description: comments added in cui.h for the 395 that had none (checked against the code), and a shared description for fields that mean the same everywhere, such as width or disabled. A field whose type is an enum lists its values.
• A new README. It opens with what CUI is in plain words, says what it is not (it draws its own components and does not wrap the system's), compares it with the libraries people know, and lists the limitations in full, including the eight components that still need a pointer. It also says how the code is written and what tests it.
• A component page lists only its own functions, and no longer repeats its option names in a sentence above the options table.
• Release notes link to the files they mention with full addresses, so the links work from the release page.
• The shared library's name carries the minor version (libcui.so.1.4 instead of libcui.so.1). Option and description structs gain fields in minor releases, and an app built against older headers passes the library a smaller struct than it reads. With the old name, an app built against 1.3 could load a newer library and read garbage past the end of cui_app_desc (the new app_id). Now each minor version is its own library, and an app keeps the one it was built against. Rebuild against the new headers to move to a new minor version. Static builds and the single-file version are not affected.

Fixed

• The path bar's "..." menu had the same fault as the split button: after opening it from the keyboard, Enter on the highlighted segment closed the menu without choosing it. Its docs now list its keys.
• The split button's Enter key chooses the highlighted menu action when the chevron has keyboard focus. It previously closed the menu without choosing an action (#25).
• The copy button keeps keyboard focus while it shows the confirmation check, so Enter or Space can copy again without pressing Tab (#23).
• The single-file distribution failed to compile after #include <windows.h> with the Microsoft SDK, which defines small as a macro; two variables had that name (#17). CI now compiles it with the macros a full windows.h defines.
• The values of an enum on a component page's "Data and results" section showed as [object HTMLElement] (17 pages).
• Eight component pages said things their component does not do: the icon button's icon swap (it animates on cui_button, not on cui_icon_button), a tooltip placed after a badge, a hover card on an avatar, Tab inside the time picker and the color picker, and the keys of the onboarding checklist, comments and JSON viewer. The pages now say what the code does, and the README lists the time picker and color picker among the parts that still need a pointer.