The UAL_UI provides a Uniform Abstraction Layer that allows interactive programs to choose from multiple user interface backends without changing the program code. Currently, the UAL_UI supports NCurses and Notcurses, which are both terminal-based user interface libraries. In the future, additional backends may be added to support graphical user interfaces, such as GTK or Qt.
The UAL_UI uses NCurses-style function names, with "ui_" prepended. The abstraction layer provides NCurses-style functionality while obscuring the more complicated details of the underlying implementation. This allows developers to write portable code that works in an identical manner across different user interface backends.
The programmer can use ASCII text, UTF-8 encoded text, Unicode Code Points, or ANSI SGR (Select Graphic Rendition) escape sequences, which the UAL_UI will transform into NCurses complex character strings or Notcurses extended grapheme clusters. The UAL_UI provides extremely advanced input handling capabilities, returning a data structure that contains chyron zone, surface, and window identification for mouse events, as well as character and keypress information for keyboard events.
Often, the hardest part of learning NCurses, and to a greater degree Notcurses, is getting past the particular implementation details of each library. For example, Notcurses nccells are robust, but they don't support Unicode Code Points. The UAL_UI silently and automatically intercepts Unicode Code Points and encodes them as UTF-8 before handing them off to Notcurses. That's something the developer doesn't have to worry about. NCurses uses color pairs extensively, and stores colors as a closed interval [0,1000] while Notcurses uses a closed interval [0,255]. Accordingly, NCurses and Notcurses colors are not compatible and their data types aren't compatible. Notcurses uses the standard uint8_t type for color values, while NCurses uses int (32-bits). No need to worry, the UAL_UI takes care of all that for you. NCurses has functions to output strings of complex characters to the screen, but Notcurses doesn't have a function to display strings of nccells. No worries, the UAL_UI takes care of that too. We could go on all day about the intricate differences between NCurses and Notcurses, but why bother. The UAL_UI abstracts away the intricate details of each library, allowing you to create professional applications without having to learn the ins and outs of each user interface library. By providing a consistent and uniform API, the UAL_UI simplifies development and enhances code maintainability.
You may be one of the many developers who have used NCurses for years and you have seen what Notcurses has to offer. You may have even tried to use Notcurses, but found it difficult to learn and use. The UAL_UI is designed to help you transition from NCurses to Notcurses without having to learn the intricacies of Notcurses. The UAL_UI provides a consistent and uniform API that allows you to write code that works with both NCurses and Notcurses, without having to worry about the differences between the two libraries. Just prepend "ui_" to your NCurses function calls, compile and link. Viola! You now have a program that works with both NCurses and Notcurses.
uint *p, const uint atmost)
int ui_answer_yn(
char *msg0,
char *msg1,
char *msg2,
char *msg3)
const
UiCell *cell_base, uint *p, const uint atmost)
wtitle)
wbegy, uint wbegx, const char *wtitle)
int ui_border_draw(UiSurface *sfc)
int ui_tracked_sfc_split_box(uint wlines, uint wcols, uint split_y, uint split_x, uint wbegy, uint wbegx, const char *wtitle)
Create a new surface with a split box window.
const char * ui_sub_surface_str(ss_t w)
int ui_cm_surface_destroy(UiSurface *sfc)
Destroy the most recently created surface.
int ui_border_title(UiSurface *sfc, const char *title)
Draw a box with a title around the specified window.
int ui_border_ysplit_text(UiSurface *sfc, char *text, uint separator_line)
Draw a box with a separator line and text around the specified window.
int ui_border_ysplit(UiSurface *sfc, uint y)
Draw a box with a separator line around the specified window.
void ui_initialize_sio(SIO *sio)
int ui_tracked_sfc_box(uint wlines, uint wcols, uint wbegy, uint wbegx, const char *wtitle)
Create a new surface with a box window.
uint ui_mbstr_to_cellstr(UiSurface *sfc, ss_t w, UiCell *cmplx_buf, const char *str, const UiCell *cell_base, uint *p, const uint atmost)
Convert multibyte string to complex character array (Notcurses version).
void ui_unset_chyron_key(UiChyron *chyron, uint k)
Unset chyron key.
void ui_set_chyron_key(UiChyron *chyron, uint k, char *s, uint kc)
Set chyron key with default color pair (cp_nt_rev).
void ui_deactivate_all_chyron_keys(UiChyron *chyron)
Deactivate all chyron keys.
FILE * ui_open_log()
Open the log file for writing.
wchar_t * ui_mbstr_to_wcstr(const char *mb_str)
Convert a multibyte string to a wide character string.
UiChyron * ui_new_chyron(UiSurface *sfc, ss_t w)
Create new chyron structure.
char * ui_iso8601_timestamp(char *buf, size_t n, bool local)
Generate an ISO 8601 timestamp string.
RGB ui_xterm256_idx_to_rgb(uint idx)
Convert XTerm 256 color index to RGB.
void ui_activate_chyron_key(UiChyron *chyron, uint k)
Activate chyron key.
void ui_display_chyron(UiSurface *sfc, ss_t w, UiChyron *chyron, uint line, uint col)
Display chyron on the specified line and column of the surface.
void ui_set_chyron_key_cb(UiChyron *chyron, uint k, char *s, uint kc, UiCell cell_base)
Set chyron key with color pair (cp).
int ui_assign_chyron_win(UiChyron *chyron, UiSurface *sfc, ss_t w, char *y)
Assign surface and window to chyron structure.
bool ui_init_clr_palette(SIO *sio)
bool ui_is_set_chyron_key(UiChyron *chyron, uint k)
Check if function key label is set.
void ui_abend(int ec, char *s)
Convert multibyte string to complex character array.
void ui_parse_ansi(char *ansi_str, attr_t *attr, uint *cpx)
Parse ANSI escape sequences for color and attributes.
UiChyron * ui_destroy_chyron(UiChyron *chyron)
Destroy UiChyron structure.
int ui_get_chyron_key(UiChyron *chyron, uint x)
Get keycode from chyron.
void ui_mbc_to_wc(wchar_t wc[2], const char mbc)
Convert a multibyte character to a wide character.
void ui_deactivate_chyron_key(UiChyron *chyron, uint k)
Deactivate chyron key.
void ui_apply_gamma(RGB *rgb)
Apply gamma correction to RGB color.
void ui_activate_all_chyron_keys(UiChyron *chyron)
Deactivate chyron key.
uint ui_rgb_to_xterm256_idx(RGB *rgb)
Convert RGB color to XTerm 256 color index.
void ui_compile_chyron(UiChyron *chyron)
construct the chyron string from the chyron structure
uint ui__mbstr_to_cellstr(UiCell *cmplx_buf, const char *str, const UiCell *cell_base, uint *p, const uint atmost)
int ui_perror(char *emsg_str)
Display a simple error message window or print to stderr.
bool ui_action_disposition(char *title, char *action_str)
Display a simple action disposition message window or print to stderr.
int ui_answer_yn(char *msg0, char *msg1, char *msg2, char *msg3)
Accept a single letter answer.
int ui_display_error(char *msg0, char *msg1, char *msg2, char *msg3)
Display an error message window or print to stderr.
void *opts)
const void *opts)
begy, uint begx)
uint x)
uint x, const char *wtitle)
uint y, uint x)
int ui_surface_resize(UiSurface *s, ss_t w, uint lines, uint cols)
Resize a UiSurface to new dimensions.
int ui_surface_addwin(UiSurface *s, ss_t w, uint p, uint lines, uint cols, uint y, uint x)
Add a new window to the specified UiSurface.
UiRuntime * ui_init(const UiConfig *config, SIO *sio)
Initialize the UI runtime with the given configuration and SIO.
void ui_render()
Render the UI by updating panels and refreshing the display.
void ui_getyx(UiSurface *s, ss_t w, uint *lines, uint *cols)
Get the current cursor position within a window of a UI surface.
int ui_setscrreg(UiSurface *s, ss_t w, uint top, uint bottom)
Set the scrolling region for a UiSurface.
int ui_wmove(UiSurface *s, ss_t w, uint y, uint x)
Move the cursor to a specified position within a UiSurface.
void ui_getmaxyx(UiSurface *s, ss_t w, uint *lines, uint *cols)
Get the maximum dimensions of a UiSurface.
int ui_cursor_enable_yx(UiSurface *s, ss_t w, uint y, uint x, bool visible)
Enable or disable the cursor at a specific position within a UiSurface.
int ui_wscrl(UiSurface *s, ss_t w, int rows)
Scroll the contents of a UiSurface by a specified number of lines.
int ui_idcok(UiSurface *s, ss_t w, bool enable)
Enable or disable the use of the insert/delete character capabilities for a UiSurface.
int ui_surface_addpad(UiSurface *s, ss_t w, uint view_win, uint lines, uint cols, uint begy, uint begx)
Add a new pad to the specified UiSurface.
int ui_cursor_move(UiSurface *s, ss_t w, uint y, uint x)
Move the cursor to a specified position within a UiSurface.
int ui_suspend()
Suspend the UI, saving the current program state and ending the window session.
void ui_surface_destroy(UiSurface *s)
Destroy a UiSurface, cleaning up its windows and panels.
void ui_update_panels()
Update the panels in the UI.
int ui_bkgd(UiSurface *s, ss_t w, const UiCell *cell)
Set the background of a specific window within a UiSurface.
int ui_idlok(UiSurface *s, ss_t w, bool enable)
Enable or disable the use of the insert/delete line capabilities for a UiSurface.
int ui_surface_move(UiSurface *s, ss_t w, uint y, uint x)
Move a UiSurface to a new position on the screen.
int ui_getmaxy(UiSurface *s, ss_t w)
Get the maximum number of lines (rows) of a UiSurface.
UiSurface * ui_surface_box(UiSurface *parent, uint p, uint lines, uint cols, uint y, uint x, const char *title)
Create a new UI surface with a border box and optional title.
void ui_get_screen_size(uint *lines, uint *cols)
Get the current screen size (number of lines and columns).
int ui_surface_show(UiSurface *s, ss_t w)
Show a UiSurface, making it visible on the screen.
int ui_erase()
Erase the entire screen.
void ui_shutdown()
Shutdown the UI runtime, cleaning up resources and freeing memory.
UiSurface * ui_surface_new(ss_t w, UiSurface *parent, uint p, uint lines, uint cols, uint y, uint x)
Create a new UI surface with the specified parameters.
int ui_curs_set(int visibility)
Set the visibility of the cursor.
int ui_resume()
Resume the UI, restoring the previous program state and updating the display.
int ui_bkgrndset(UiSurface *s, ss_t w, const UiCell *cell)
Set the background for new content to be written to a specific window within a UiSurface.
int ui_top_surface(UiSurface *s, ss_t w)
Hide a UiSurface, making it invisible on the screen.
int ui_wclear(UiSurface *s, ss_t w)
Clear the contents of a UiSurface or all surfaces.
void ui_endwin()
End the UI application, cleaning up resources and shutting down the UI runtime.
int ui_cursor_enable(UiSurface *s, ss_t w, bool visible)
Enable or disable the cursor for a UiSurface.
int ui_clear()
Clear the entire screen.
int ui_getmaxx(UiSurface *s, ss_t w)
Get the maximum number of columns of a UiSurface.
int ui_surface_hide(UiSurface *s, ss_t w)
Hide a UiSurface, making it invisible on the screen.
int ui_bkgrnd(UiSurface *s, ss_t w, const UiCell *cell)
Set the background of a specific window within a UiSurface.
int ui_scrollok(UiSurface *s, ss_t w, bool enable)
Enable or disable scrolling for a UiSurface.
int ui_wnoutrefresh(UiSurface *s, ss_t w)
Refresh a specific window within a UiSurface.
void ui_get_caps(UiCaps *caps)
Get the UI backend capabilities.
int ui_bkgdset(UiSurface *s, ss_t w, const UiCell *cell)
Set the background for new content to be written to a specific window within a UiSurface.
int ui_doupdate()
Refresh the display by updating the screen.
int ui_werase(UiSurface *s, ss_t w)
Erase the contents of a UiSurface or all surfaces.
int ui_keypad(UiSurface *s, ss_t w, bool enable)
Enable or disable the keypad for a UiSurface.
int ui_setcchar(UiCell *cell, const wchar_t *wstr, const attr_t attrs, short pair, const void *opts)
Set the character and attributes of a UiCell.
int ui_chg_pair(uint pair, uint fg, uint bg)
Change the foreground and background colors of an existing color pair.
int ui_pair_content(uint pair, uint *fg, uint *bg)
Get the foreground and background colors of a specified color pair.
SCREEN * ui_ncurses_get_screen()
Get the current SCREEN pointer used by the UI.
int ui_getcchar(const UiCell *cell, wchar_t *wstr, attr_t *attrs, short *pair, const void *opts)
Get the character and attributes from a UiCell.
int ui_init_color(uint color, uint r, uint g, uint b)
Initialize a color in the curses color table with specified RGB values.
int ui_init_pair(uint pair, uint fg, uint bg)
Initialize a color pair in the curses color table with specified foreground and background colors.
uint ui_add_pair(uint fg, uint bg)
Add a new color pair to the UI, or retrieve the index of an existing pair.
uint32_t ui_get_color(uint16_t color_idx)
Get the RGB color value for a given color index.
int ui_color_content(uint color, uint *r, uint *g, uint *b)
void fast_exit(UiSurface *s)
Exit the UI application quickly, cleaning up resources.
RGB ui_hex_to_rgb(char *s)
Convert a hexadecimal color string to an RGB structure.
int ui_pair_from_hex(const char *fg, const char *bg)
Convert hex color strings to a curses color pair index.
WINDOW * ui_ncurses_surface_get_win(const UiSurface *s, ss_t w)
Get the current FILE pointer for the TTY used by the UI.
UiCell ui_cell_from_ucp(const wchar_t *ucp, const uint32_t *fg, const uint32_t *bg)
Convert a Unicode code point to a curses UiCell with specified foreground and background colors.
PANEL * ui_ncurses_surface_get_panel(const UiSurface *s, ss_t w)
Get the current PANEL pointer for a specific window within a UiSurface.
int ui_color_from_rgb(RGB *rgb)
Convert RGB to curses color index, adding new color if necessary.
int ui_chg_color(uint16_t color_idx, uint32_t *color)
Change the RGB color value for a given color index.
UiBackend ui_get_backend()
Get the UI backend type.
uint n)
int ui_draw_ch_yx(UiSurface *s, ss_t w, uint y, uint x, const char c)
Draw a character at a specific position in a surface window.
int ui_draw_text_n(UiSurface *s, ss_t w, uint y, uint x, const char *text, int m)
Draw a text string at a specific position in a surface window.
int ui_draw_text_fill(UiSurface *s, ss_t w, uint y, uint x, const char *text, int m)
Draw a text string at a specific position in a surface window, filling the remaining space with space...
int ui_draw_text(UiSurface *s, ss_t w, uint y, uint x, const char *text)
on specified window, move to y, x, add string
void ui_restore_wins()
Restore the state of all windows in the UI. This function refreshes the standard screen and all surfa...
int ui_draw_ch(UiSurface *s, ss_t w, const char c)
Draw a character in a surface window.
int ui_wclrtobot(UiSurface *s, ss_t w)
Set the style of a surface window.
int ui_wclrtoeol(UiSurface *s, ss_t w)
Clear to the end of the line in a surface window.
int ui_mvwadd_wchnstr(UiSurface *s, ss_t w, uint y, uint x, const UiCell *cmplx_buf, uint n)
Draw a complex character string at a specific position in a surface window, with a maximum length.
int ui_waddstr(UiSurface *s, ss_t w, const char *text)
Draw a text string in a surface window.
int ui_mvwaddnwstr(UiSurface *s, ss_t w, uint y, uint x, const wchar_t *wstr, int m)
Draw a wide-character string at a specific position in a surface window, with a maximum length.
int ui_waddwstr(UiSurface *s, ss_t w, const wchar_t *wstr)
Draw a wide-character string in a surface window.
int ui_mvwaddch(UiSurface *s, ss_t w, uint y, uint x, const char c)
Draw a character in a surface window.
int ui_waddnstr(UiSurface *s, ss_t w, const char *text, int m)
Draw a text string in a surface window, with a maximum length.
int ui_mvwaddnstr(UiSurface *s, ss_t w, uint y, uint x, const char *text, int m)
Draw a text string at a specific position in a surface window, with a maximum length.
int ui_mvwadd_wchstr(UiSurface *s, ss_t w, uint y, uint x, const UiCell *cmplx_buf)
Draw a complex character string at a specific position in a surface window.
int ui_mvwaddwstr(UiSurface *s, ss_t w, uint y, uint x, const wchar_t *wstr)
Draw a wide-character string at a specific position in a surface window.
int ui_mvwaddstr(UiSurface *s, ss_t w, uint y, uint x, const char *text)
Draw a text string at a specific position in a surface window.
int ui_mvwadd_wch(UiSurface *s, ss_t w, uint y, uint x, const UiCell *cell)
Draw a complex character at a specific position in a surface window.
int ui_mvwaddstr_fill(UiSurface *s, ss_t w, uint y, uint x, const char *str, int m)
Draw a text string at a specific position in a surface window, filling the remaining space with space...
int ui_wadd_wch(UiSurface *s, ss_t w, const UiCell *cell)
Draw a complex character in a surface window.
int ui_waddnwstr(UiSurface *s, ss_t w, const wchar_t *wstr, int m)
Draw a wide-character string in a surface window, with a maximum length.
int ui_wadd_wchstr(UiSurface *s, ss_t w, const UiCell *cmplx_buf)
Draw a complex character string in a surface window.
int ui_wadd_wchnstr(UiSurface *s, ss_t w, const UiCell *cmplx_buf, uint n)
Draw a complex character string in a surface window, with a maximum length.
1.17.0 