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 <cgoesc2@wgu.edu>

diff --git a/include/ttyutils.h b/include/ttyutils.h
index 46df3cddd218964fb30f955392d85d12e56879b8..38b891b6245c13e5018b5f3d756194f743cdf6b8 100644 (file)
--- 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 da4b8c8f42abfd11c7641a588aa4e5beb8047c90..b386f7959af546c266b236497b551da192814a28 100644 (file)
--- a/libsmartcols/docs/libsmartcols-sections.txt
+++ b/libsmartcols/docs/libsmartcols-sections.txt
@@ -24,6 +24,7 @@ scols_reset_cell
 <SECTION>
 <FILE>column</FILE>
 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 5d5cb0aa6c9b5d16e0987db2d9c890ea3110642b..a3a9d9fed327196f582ebc1aabb0d7aa259c5180 100644 (file)
--- 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 3fbe668d3f0666752b5d3bdd152570115fa64788..f36401d9d290de008a082021849909b09662dca8 100644 (file)
--- 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 1f782fdc6c55272c95494607ebeda1fd68d2e0ff..c510f63ba8a9da055b56cbaf30e9a75b551f8f50 100644 (file)
--- 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 cd2aa96113ce86903a8e6d1396b10e4884efd3f8..fffbe6a7fad822c184eea9472b07e30086bc6d25 100644 (file)
--- 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 68b46886e7989fb6e9e3110bfbb70465567d9aff..9ab7e9da565432b29c5c47f91a60721adb70fe24 100644 (file)
--- 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 */