RFC: Better Text Rendering for cairo / lua

.github/workflows/build-and-test-linux.yaml

@@ -46,6 +46,9 @@ jobs:
             libpango1.0-dev \
             libcurl4-gnutls-dev \
             libdbus-glib-1-dev \
+            libfreetype-dev \
+            libfreetype6-dev \
+            libstdc++6 \
             libglib2.0-dev \
             libical-dev \
             libimlib2-dev \
@@ -114,6 +117,7 @@ jobs:
             -DBUILD_LUA_CAIRO_XLIB=ON            \
             -DBUILD_LUA_IMLIB2=ON                \
             -DBUILD_LUA_RSVG=${RSVG_ENABLED}     \
+            -DBUILD_LUA_TEXT=ON                  \
             -DBUILD_MYSQL=ON                     \
             -DBUILD_NVIDIA=ON                    \
             -DBUILD_PULSEAUDIO=ON                \

.github/workflows/codeql.yml

@@ -39,6 +39,9 @@ jobs:
             libcairo2-dev \
             libcurl4-gnutls-dev \
             libdbus-glib-1-dev \
+            libfreetype-dev \
+            libfreetype6-dev \
+            libstdc++6 \
             libglib2.0-dev \
             libical-dev \
             libimlib2-dev \

.github/workflows/publish-appimage.yml

@@ -45,6 +45,9 @@ jobs:
             libcairo2-dev \
             libcurl4-gnutls-dev \
             libdbus-glib-1-dev \
+            libfreetype-dev \
+            libfreetype6-dev \
+            libstdc++6 \
             libfuse2 \
             libglib2.0-dev \
             libical-dev \

AUTHORS

@@ -314,6 +314,9 @@ Mikko Sysikaski <sisu at users dot sourceforge dot net>
 Sceptik <sceptik at users dot sourceforge dot net>
   --quiet patch
 
+Simon Lees <sflees at suse dot de>
+  lua text
+
 Stepan Zastupov <redchrom at gmail dot com>
   WiFi signal level detection support on FreeBSD
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:noble AS builder
+FROM ubuntu:jammy AS builder
 
 RUN apt-get update \
   && DEBIAN_FRONTEND=noninteractive \
@@ -18,6 +18,9 @@ RUN apt-get update \
   libcairo2-dev \
   libcurl4-openssl-dev \
   libdbus-glib-1-dev \
+  libfontconfig-dev \
+  libfreetype-dev \
+  libharfbuzz-dev \
   libical-dev \
   libimlib2-dev \
   libircclient-dev \
@@ -40,11 +43,25 @@ RUN apt-get update \
   libxml2-dev \
   libxmmsclient-dev \
   libxnvctrl-dev \
+  make \
   ninja-build \
   patch \
   && apt-get clean \
   && rm -rf /var/lib/apt/lists/*
 
+# Compile CMake, we need the latest because the bug here (for armv7 builds):
+# https://gitlab.kitware.com/cmake/cmake/-/issues/20568
+WORKDIR /cmake
+ENV CMAKE_VERSION 3.25.1
+RUN curl -Lq https://github.com/Kitware/CMake/releases/download/v${CMAKE_VERSION}/cmake-${CMAKE_VERSION}.tar.gz -o cmake-${CMAKE_VERSION}.tar.gz \
+  && tar xf cmake-${CMAKE_VERSION}.tar.gz \
+  && cd cmake-${CMAKE_VERSION} \
+  && CC=clang CXX=clang++ CFLAGS="-D_FILE_OFFSET_BITS=64" CXXFLAGS="-D_FILE_OFFSET_BITS=64" ./bootstrap --system-libs --parallel=5 \
+  && make -j5 \
+  && make -j5 install \
+  && cd \
+  && rm -rf /cmake
+
 COPY . /conky
 WORKDIR /conky/build
 
@@ -65,6 +82,7 @@ RUN sh -c 'if [ "$X11" = "yes" ] ; then \
   -DBUILD_LUA_CAIRO_XLIB=ON \
   -DBUILD_LUA_IMLIB2=ON \
   -DBUILD_LUA_RSVG=ON \
+  -DBUILD_LUA_TEXT=ON \
   -DBUILD_MYSQL=ON \
   -DBUILD_NVIDIA=ON \
   -DBUILD_PULSEAUDIO=ON \
@@ -87,6 +105,7 @@ RUN sh -c 'if [ "$X11" = "yes" ] ; then \
   -DBUILD_LUA_CAIRO=ON \
   -DBUILD_LUA_IMLIB2=ON \
   -DBUILD_LUA_RSVG=ON \
+  -DBUILD_LUA_TEXT=ON \
   -DBUILD_MYSQL=ON \
   -DBUILD_PULSEAUDIO=ON \
   -DBUILD_RSS=ON \
@@ -110,6 +129,9 @@ RUN apt-get update \
   libcairo2 \
   libcurl4t64 \
   libdbus-glib-1-2 \
+  libfontconfig1 \
+  libfreetype6 \
+  libharfbuzz-gobject0 \
   libical3t64 \
   libimlib2t64 \
   libircclient1 \

appimage/build.sh

@@ -51,6 +51,7 @@ cmake -G Ninja                         \
   -DBUILD_LUA_CAIRO=ON                 \
   -DBUILD_LUA_IMLIB2=ON                \
   -DBUILD_LUA_RSVG=${ENABLE_RSVG}      \
+  -DBUILD_LUA_TEXT=ON                  \
   -DBUILD_MYSQL=ON                     \
   -DBUILD_NVIDIA=ON                    \
   -DBUILD_PULSEAUDIO=ON                \

cmake/ConkyBuildOptions.cmake

@@ -26,15 +26,15 @@ if(NOT CMAKE_BUILD_TYPE)
     set(
       CMAKE_BUILD_TYPE Debug
       CACHE
-      STRING
-      "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."
+        STRING
+        "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."
       FORCE)
   else(MAINTAINER_MODE)
     set(
       CMAKE_BUILD_TYPE RelWithDebInfo
       CACHE
-      STRING
-      "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."
+        STRING
+        "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."
       FORCE)
   endif(MAINTAINER_MODE)
 endif(NOT CMAKE_BUILD_TYPE)
@@ -74,12 +74,12 @@ option(BUILD_COLOUR_NAME_MAP "Include mappings of colour name -> RGB (i.e., red
 
 if(BUILD_I18N)
   set(LOCALE_DIR "${CMAKE_INSTALL_PREFIX}/share/locale"
-    CACHE STRING "Directory containing the locales")
+      CACHE STRING "Directory containing the locales")
 endif(BUILD_I18N)
 
 # Some standard options
 set(SYSTEM_CONFIG_FILE "/etc/conky/conky.conf"
-  CACHE STRING "Default system-wide Conky configuration file")
+    CACHE STRING "Default system-wide Conky configuration file")
 
 # use FORCE below to make sure this changes when CMAKE_INSTALL_PREFIX is
 # modified
@@ -88,8 +88,8 @@ if(NOT LIB_INSTALL_DIR)
 endif(NOT LIB_INSTALL_DIR)
 
 set(PACKAGE_LIBRARY_DIR "${LIB_INSTALL_DIR}/conky"
-  CACHE STRING "Package library path (where Lua bindings are installed"
-  FORCE)
+    CACHE STRING "Package library path (where Lua bindings are installed"
+    FORCE)
 set(DEFAULTNETDEV "eno1" CACHE STRING "Default networkdevice")
 
 # Mac only override
@@ -98,13 +98,13 @@ if(OS_DARWIN)
 endif(OS_DARWIN)
 
 set(XDG_CONFIG_FILE "$HOME/.config/conky/conky.conf"
-  CACHE STRING "Configfile of the user (XDG)")
+    CACHE STRING "Configfile of the user (XDG)")
 set(CONFIG_FILE "$HOME/.conkyrc" CACHE STRING "Configfile of the user")
 set(MAX_USER_TEXT_DEFAULT "16384"
-  CACHE STRING
-  "Default maximum size of config TEXT buffer, i.e. below TEXT line.")
+    CACHE STRING
+          "Default maximum size of config TEXT buffer, i.e. below TEXT line.")
 set(DEFAULT_TEXT_BUFFER_SIZE "256"
-  CACHE STRING "Default size used for temporary, static text buffers")
+    CACHE STRING "Default size used for temporary, static text buffers")
 set(MAX_NET_INTERFACES "256" CACHE STRING "Maximum number of network devices")
 
 # Platform specific options Linux only
@@ -142,7 +142,7 @@ option(BUILD_BUILTIN_CONFIG "Enable builtin default configuration" true)
 option(BUILD_IOSTATS "Enable disk I/O stats" true)
 
 option(BUILD_OLD_CONFIG "Enable support for the old syntax of configurations"
-  true)
+       true)
 
 option(BUILD_MATH "Enable math support" true)
 
@@ -227,6 +227,9 @@ dependent_option(BUILD_LUA_IMLIB2 "Build Imlib2 bindings for Lua" false
 dependent_option(BUILD_LUA_RSVG "Build rsvg bindings for Lua" false
   "BUILD_GUI" false
   "RSVG Lua bindings depend on BUILD_GUI")
+dependent_option(BUILD_LUA_TEXT "Build Fontconfig Freetype and Harfbuzz for Lua" false
+  "BUILD_GUI" false
+  "Text Lua bindings depend on BUILD_GUI")
 
 option(BUILD_AUDACIOUS "Build audacious (music player) support" false)
 
@@ -263,13 +266,13 @@ option(BUILD_ICONV "Enable iconv support" false)
 option(BUILD_CMUS "Enable support for cmus music player" true)
 
 option(BUILD_JOURNAL "Enable support for reading from the systemd journal"
-  false)
+       false)
 
 option(BUILD_PULSEAUDIO
-  "Enable support for Pulseaudio's default sink and source" false)
+       "Enable support for Pulseaudio's default sink and source" false)
 
 option(BUILD_INTEL_BACKLIGHT
-  "Enable support for Intel backlight" false)
+       "Enable support for Intel backlight" false)
 
 run_dependency_checks()
 
@@ -287,6 +290,6 @@ message(STATUS "CMAKE_CXX_FLAGS_RELEASE: " ${CMAKE_CXX_FLAGS_RELEASE})
 
 message(STATUS "CMAKE_C_FLAGS_RELWITHDEBINFO: " ${CMAKE_C_FLAGS_RELWITHDEBINFO})
 message(STATUS "CMAKE_CXX_FLAGS_RELWITHDEBINFO: "
-  ${CMAKE_CXX_FLAGS_RELWITHDEBINFO})
+               ${CMAKE_CXX_FLAGS_RELWITHDEBINFO})
 
 message(STATUS "CMAKE_BUILD_TYPE: " ${CMAKE_BUILD_TYPE})

cmake/ConkyPlatformChecks.cmake

@@ -375,12 +375,7 @@ if(BUILD_X11)
 
     # check for Xft
     if(BUILD_XFT)
-      if(FREETYPE_INCLUDE_DIR_freetype2)
-        set(FREETYPE_FOUND true)
-        set(conky_includes ${conky_includes} ${FREETYPE_INCLUDE_DIR_freetype2})
-      else(FREETYPE_INCLUDE_DIR_freetype2)
-        message(FATAL_ERROR "Unable to find freetype library")
-      endif(FREETYPE_INCLUDE_DIR_freetype2)
+      find_package(Freetype REQUIRED)
 
       if(NOT X11_Xft_FOUND)
         message(FATAL_ERROR "Unable to find Xft library")
@@ -499,32 +494,32 @@ set(conky_libs ${conky_libs} ${LUA_LIBRARIES})
 set(conky_includes ${conky_includes} ${LUA_INCLUDE_DIR})
 include_directories(3rdparty/toluapp/include)
 
-# Check for libraries used by Lua bindings
-if(BUILD_LUA_CAIRO)
+  # Check for libraries used by Lua bindings
+  if(BUILD_LUA_CAIRO)
   pkg_check_modules(CAIRO REQUIRED cairo>=1.14)
-  set(luacairo_libs ${CAIRO_LIBRARIES} ${LUA_LIBRARIES})
-  set(luacairo_includes ${CAIRO_INCLUDE_DIRS} ${LUA_INCLUDE_DIR})
+    set(luacairo_libs ${CAIRO_LIBRARIES} ${LUA_LIBRARIES})
+    set(luacairo_includes ${CAIRO_INCLUDE_DIRS} ${LUA_INCLUDE_DIR})
 
   if(BUILD_LUA_CAIRO_XLIB)
     pkg_check_modules(CAIROXLIB REQUIRED cairo-xlib)
     set(luacairo_libs ${CAIROXLIB_LIBRARIES} ${luacairo_libs})
     set(luacairo_includes ${CAIROXLIB_INCLUDE_DIRS} ${luacairo_includes})
   endif(BUILD_LUA_CAIRO_XLIB)
 
-  find_program(APP_PATCH patch)
+    find_program(APP_PATCH patch)
 
-  if(NOT APP_PATCH)
-    message(FATAL_ERROR "Unable to find program 'patch'")
-  endif(NOT APP_PATCH)
-endif(BUILD_LUA_CAIRO)
+    if(NOT APP_PATCH)
+      message(FATAL_ERROR "Unable to find program 'patch'")
+    endif(NOT APP_PATCH)
+  endif(BUILD_LUA_CAIRO)
 
 if(BUILD_LUA_IMLIB2)
-  pkg_search_module(IMLIB2 REQUIRED imlib2 Imlib2)
-  set(luaimlib2_libs ${IMLIB2_LIBS} ${IMLIB2_LDFLAGS} ${LUA_LIBRARIES})
-  set(luaimlib2_includes
-    ${IMLIB2_INCLUDE_DIRS}
-    ${LUA_INCLUDE_DIR}
-    ${X11_INCLUDE_DIR})
+    pkg_search_module(IMLIB2 REQUIRED imlib2 Imlib2)
+    set(luaimlib2_libs ${IMLIB2_LIBS} ${IMLIB2_LDFLAGS} ${LUA_LIBRARIES})
+    set(luaimlib2_includes
+      ${IMLIB2_INCLUDE_DIRS}
+      ${LUA_INCLUDE_DIR}
+      ${X11_INCLUDE_DIR})
 endif(BUILD_LUA_IMLIB2)
 
 if(BUILD_LUA_RSVG)
@@ -533,6 +528,14 @@ if(BUILD_LUA_RSVG)
   set(luarsvg_includes ${RSVG_INCLUDE_DIRS} ${LUA_INCLUDE_DIR})
 endif(BUILD_LUA_RSVG)
 
+if(BUILD_LUA_TEXT)
+  find_package(Freetype REQUIRED)
+  PKG_CHECK_MODULES(FONTCONFIG REQUIRED fontconfig)
+  PKG_CHECK_MODULES(HARFBUZZ REQUIRED harfbuzz)
+  set(luatext_libs ${FREETYPE_LIBRARIES} ${FONTCONFIG_LIBRARIES} ${HARFBUZZ_LIBRARIES} ${LUA_LIBRARIES})
+  set(luatext_includes ${FREETYPE_INCLUDE_DIR_freetype2} ${FONTCONFIG_INCLUDE_DIRS} ${HARFBUZZ_INCLUDE_DIRS} ${LUA_INCLUDE_DIRS})
+endif(BUILD_LUA_TEXT)
+
 if(BUILD_AUDACIOUS)
   set(WANT_GLIB true)
   pkg_check_modules(NEW_AUDACIOUS audacious>=1.4.0)

cmake/config.h.in

@@ -132,6 +132,8 @@
 
 #cmakedefine BUILD_LUA_RSVG 1
 
+#cmakedefine BUILD_LUA_TEXT 1
+
 #cmakedefine BUILD_IBM 1
 
 #cmakedefine BUILD_RSS 1

doc/lua.yaml

@@ -12,8 +12,7 @@
 ---
 desc: |-
   Conky features a Lua Programming API, and also ships with Lua bindings
-  for some useful libraries. Note that the bindings require tolua++, which
-  currently only compiles against Lua 5.1.
+  for some useful libraries. Note that the bindings require tolua++.
 
   To use Lua Conky, you first need to make sure you have a version of
   Conky with Lua support enabled (`conky -v` will report this).
@@ -205,7 +204,41 @@ values:
       | cs                  | The `cairo_surface_t` to render to.                                                  |
       | x,y                 | Position to render the image.                                                        |
       | scale_x, scale_y    | The amount to scale the image, 1.0 provides no scaling, 2.0 for twice the size and   |
-      |                     | 0.5 for half size etc.                                                               |
-      |                     | Default value: No Scaling (1.0,1.0)                                                  |
+      |                     | 0.5 for half size etc. <br/>Default value: No Scaling (1.0,1.0)                      |
 
       require('cairo_imlib2_helper') in your lua file.
+
+  - name: cairo_text_hp_show(cr, x, y, text, font, font_size, alignment, language, script, direction)
+    desc: |-
+      Renders text to a cairo_t using harfbuzz and freetype, this provides significantly
+      better text rendering then using cairo's inbuilt functions.
+
+      | Argument            | Description                                                                          |
+      |---------------------|--------------------------------------------------------------------------------------|
+      | cr                  | The `cairo_t` to render to.                                                          |
+      | x,y                 | Position to render the text.                                                         |
+      | text                | The text to render.                                                                  |
+      | font                | The name of the font to be used, `Fontconfig` is used to search for the font.        |
+      | font_size           | The font size.                                                                       |
+      | alignment           | One of `CAIRO_TEXT_ALIGN_LEFT`, `CAIRO_TEXT_ALIGN_RIGHT`, `CAIRO_TEXT_ALIGN_CENTER`.<br/>Default value: `CAIRO_TEXT_ALIGN_LEFT` |
+      | language            | A string containing a BCP 47 language tag.<br/>Default value: `en`                   |
+      | script              | A string containing a ISO 15924 script tag.<br/>Default value: auto-detect from text |
+      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`<br/>Default value: auto-detect from text otherwise `LTR` |
+  - name: width,height:cairo_text_hp_text_size(text, font, font_size, language, script, direction)
+    desc: |-
+      Used to calculate how many pixels will be required to render a string with
+      `cairo_text_hp_show` returns a pair of int's with `width` and `height`.
+
+      | Argument            | Description                                                                          |
+      |---------------------|--------------------------------------------------------------------------------------|
+      | cr                  | The `cairo_t` to render to.                                                          |
+      | text                | The text to render.                                                                  |
+      | font                | The name of the font to be used, `Fontconfig` is used to search for the font.        |
+      | font_size           | The font size.                                                                       |
+      | language            | A string containing a BCP 47 language tag.<br/>Default value: `en`                   |
+      | script              | A string containing a ISO 15924 script tag.<br/>Default value: auto-detect from text |
+      | direction           | A string representing text direction eg `LTR`, `RTL` or `TTB`<br/> Default value: auto-detect from text otherwise `LTR` |
+  - name: cairo_text_hp_delete_fonts()
+    desc: |-
+      `cairo_text_hp_show` and `cairo_text_hp_text_size` both cache internal font details,
+      this function clears those caches.