From: Christian Goeschel Ndjomouo Date: Sun, 21 Sep 2025 05:07:58 +0000 (-0400) Subject: libsmartcols: new scols_column_{refer,get}_annotation routines X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5836f3ee6dd2fd18af0e2fda1698115b4f9619a0;p=thirdparty%2Futil-linux.git libsmartcols: new scols_column_{refer,get}_annotation routines The new routines can be used to add an annotation to columns which are intended to serve as descriptions for column headers. These annotations are formatted with OSC8 escape sequences and then sent to the output stream. A supporting terminal can then display the formatted string as a tooltip. This can be fairly useful when an application wants to provide a translated description for a column header name, since the latter is sometimes a mere abbreviation and not necessarily telling enough. Addresses: #1291 Signed-off-by: Christian Goeschel Ndjomouo --- diff --git a/include/ttyutils.h b/include/ttyutils.h index 46df3cddd..38b891b62 100644 --- a/include/ttyutils.h +++ b/include/ttyutils.h @@ -221,7 +221,7 @@ static inline void reset_virtual_console(struct termios *tp, int flags) * Alternatively, BEL (\a) can be used instead of ST. */ #define UL_HYPERLINK_START UL_OSC8 -#define UL_HYPERLINK_PARAMS ";;" +#define UL_HYPERLINK_PARAMS ";;" /* Reserved for future extendability by the OSC8 */ #define UL_HYPERLINK_LINK UL_ST #define UL_HYPERLINK_END (UL_OSC8 ";;" UL_ST) diff --git a/libsmartcols/docs/libsmartcols-sections.txt b/libsmartcols/docs/libsmartcols-sections.txt index da4b8c8f4..b386f7959 100644 --- a/libsmartcols/docs/libsmartcols-sections.txt +++ b/libsmartcols/docs/libsmartcols-sections.txt @@ -24,6 +24,7 @@ scols_reset_cell
column libscols_column +scols_column_get_annotation scols_column_get_color scols_column_get_data_type scols_column_get_flags @@ -47,6 +48,7 @@ scols_column_is_strict_width scols_column_is_tree scols_column_is_trunc scols_column_is_wrap +scols_column_refer_annotation scols_column_set_cmpfunc scols_column_set_color scols_column_set_data_func diff --git a/libsmartcols/src/column.c b/libsmartcols/src/column.c index 5d5cb0aa6..a3a9d9fed 100644 --- a/libsmartcols/src/column.c +++ b/libsmartcols/src/column.c @@ -107,11 +107,13 @@ struct libscols_column *scols_copy_column(const struct libscols_column *cl) goto err; if (scols_cell_copy_content(&ret->header, &cl->header)) goto err; + if (scols_column_refer_annotation(ret, cl->annotation)) + goto err; - ret->width = cl->width; - ret->width_hint = cl->width_hint; - ret->flags = cl->flags; - ret->is_groups = cl->is_groups; + ret->width = cl->width; + ret->width_hint = cl->width_hint; + ret->flags = cl->flags; + ret->is_groups = cl->is_groups; memcpy(&ret->wstat, &cl->wstat, sizeof(cl->wstat)); @@ -319,6 +321,37 @@ const char *scols_column_get_name(struct libscols_column *cl) return scols_cell_get_data(&cl->header); } +/** + * scols_column_refer_annotation: + * @cl: a pointer to a struct libscols_column instance + * @annotation: column annotation + * + * Returns: 0, a negative value in case of an error. + * + * Since: 2.42 + */ +int scols_column_refer_annotation(struct libscols_column *cl, const char *annotation) +{ + if (!annotation) + return -1; + + cl->annotation = (char *) annotation; + return 0; +} + +/** + * scols_column_get_annotation: + * @cl: a pointer to a struct libscols_column instance + * + * Returns: A pointer to a column annotation, which is stored in column annotation + * + * Since: 2.42 + */ +const char *scols_column_get_annotation(struct libscols_column *cl) +{ + return cl->annotation; +} + /** * scols_column_set_headercolor: * @cl: a pointer to a struct libscols_column instance diff --git a/libsmartcols/src/libsmartcols.h.in b/libsmartcols/src/libsmartcols.h.in index 3fbe668d3..f36401d9d 100644 --- a/libsmartcols/src/libsmartcols.h.in +++ b/libsmartcols/src/libsmartcols.h.in @@ -267,6 +267,9 @@ extern const char *scols_column_get_name(struct libscols_column *cl); extern const char *scols_column_get_name_as_shellvar(struct libscols_column *cl); extern int scols_shellvar_name(const char *name, char **buf, size_t *bufsz); +extern int scols_column_refer_annotation(struct libscols_column *cl, const char *annotation); +extern const char *scols_column_get_annotation(struct libscols_column *cl); + extern int scols_column_set_properties(struct libscols_column *cl, const char *opts); extern int scols_column_set_cmpfunc(struct libscols_column *cl, diff --git a/libsmartcols/src/libsmartcols.sym b/libsmartcols/src/libsmartcols.sym index 1f782fdc6..c510f63ba 100644 --- a/libsmartcols/src/libsmartcols.sym +++ b/libsmartcols/src/libsmartcols.sym @@ -261,5 +261,7 @@ SMARTCOLS_2.42 { scols_filter_has_holder; scols_column_set_headercolor; scols_column_get_headercolor; + scols_column_refer_annotation; + scols_column_get_annotation; } SMARTCOLS_2.41; diff --git a/libsmartcols/src/print.c b/libsmartcols/src/print.c index cd2aa9611..fffbe6a7f 100644 --- a/libsmartcols/src/print.c +++ b/libsmartcols/src/print.c @@ -590,7 +590,7 @@ static int print_data(struct libscols_table *tb, struct ul_buffer *buf) struct libscols_cell *ce; size_t len = 0, i, width, bytes; char *data = NULL; - const char *name = NULL, *uri = NULL; + const char *name = NULL, *annot = NULL, *uri = NULL; int is_last; assert(tb); @@ -641,6 +641,9 @@ static int print_data(struct libscols_table *tb, struct ul_buffer *buf) if (cl->uri || ce->uri) uri = mk_cell_uri(cl, ce, buf); + if (cl->annotation) + annot = scols_column_get_annotation(cl); + /* Encode. Note that 'len' and 'width' are number of glyphs not bytes. */ if (scols_table_is_noencoding(tb)) @@ -700,8 +703,12 @@ static int print_data(struct libscols_table *tb, struct ul_buffer *buf) fputc(data[i], tb->out); } ul_fputs_hyperlink(uri, link, tb->out); - } else + } else if (!ln && annot && *annot) { + /* Printing the header with a column annotation as tooltip */ + ul_fputs_hyperlink(annot, data, tb->out); + } else { fputs(data, tb->out); + } } /* minout -- don't fill */ diff --git a/libsmartcols/src/smartcolsP.h b/libsmartcols/src/smartcolsP.h index 68b46886e..9ab7e9da5 100644 --- a/libsmartcols/src/smartcolsP.h +++ b/libsmartcols/src/smartcolsP.h @@ -125,6 +125,7 @@ struct libscols_column { int flags; char *color; /* default column color */ + char *annotation; /* column annotation */ char *uri; /* default column URI prefix */ struct ul_buffer uri_buf; /* temporary buffer to compose URIs */ char *safechars; /* do not encode this bytes */