# HG changeset patch
# User Pantxo Diribarne <pantxo.diribarne@gmail.com>
# Date 1590997988 -7200
#      Mon Jun 01 09:53:08 2020 +0200
# Node ID 70f63b9761629dd4693d4a683ad9e462e0b950f8
# Parent  d4194f15ea2275247950adf1d484315e6b32ab8a
New function "listfonts" (bug #58476)

* listfonts.m: New function file.

* NEWS: anounce new function.

* gui.txi: add dicstring in the utility functions paragraph.

* uisetfont.m (doc): Add listfonts in @seealso and add paragraph about how
  to update the font cache on non linux systems.

diff -r d4194f15ea22 -r 70f63b976162 NEWS
--- a/NEWS	Mon Jun 01 09:53:06 2020 +0200
+++ b/NEWS	Mon Jun 01 09:53:08 2020 +0200
@@ -100,6 +100,7 @@
 ### Alphabetical list of new functions added in Octave 7
 
 * `getpixelposition`
+* `listfonts`
 * `endsWith`
 * `memory`
 * `rng`
diff -r d4194f15ea22 -r 70f63b976162 doc/interpreter/gui.txi
--- a/doc/interpreter/gui.txi	Mon Jun 01 09:53:06 2020 +0200
+++ b/doc/interpreter/gui.txi	Mon Jun 01 09:53:08 2020 +0200
@@ -143,6 +143,8 @@
 
 @DOCSTRING(getpixelposition)
 
+@DOCSTRING(listfonts)
+
 @DOCSTRING(movegui)
 
 @DOCSTRING(openvar)
diff -r d4194f15ea22 -r 70f63b976162 scripts/gui/listfonts.m
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/gui/listfonts.m	Mon Jun 01 09:53:08 2020 +0200
@@ -0,0 +1,93 @@
+########################################################################
+##
+## Copyright (C) 2020 The Octave Project Developers
+##
+## See the file COPYRIGHT.md in the top-level directory of this
+## distribution or <https://octave.org/copyright/>.
+##
+## This file is part of Octave.
+##
+## Octave is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 3 of the License, or
+## (at your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <https://www.gnu.org/licenses/>.
+##
+########################################################################
+
+## -*- texinfo -*-
+## @deftypefn  {} {fonts = } listfonts ()
+## @deftypefnx {} {fonts = } listfonts (@var{h})
+## List system fonts.
+##
+## If a handle to a graphics object @var{h} is provided, also include
+## the objects fontname in the list.
+##
+## @strong{Note:} On systems that don't use FontConfig natively (all
+## but linux) the font cache is built when Octave is installed.
+## You will need to run @code{system ("fc-cache -fv")} manually after installing
+## new fonts.
+##
+## @seealso{uisetfont, text, axes, uicontrol}
+## @end deftypefn
+
+function fonts = listfonts (h = [])
+
+  persistent sysfonts = get_fonts (h);
+
+  if (nargin > 1)
+    print_usage ();
+  elseif (! isempty (h)
+          && (! ishghandle (h) || ! isprop (h, "fontname")))
+    error (["listfonts: expect a handle to a graphics object ", ...
+            "with a \"fontname\" property"]);
+  endif
+
+  fonts = sysfonts;
+
+  if (! isempty (h))
+    font = get (h, "fontname");
+    if (! strcmp (font, "*"))
+      fonts = unique ([fonts font]);
+    endif
+  endif
+
+endfunction
+
+function fonts = get_fonts ()
+
+  fontfiles = __get_system_fonts__ ();
+
+  fonts = unique ([{fontfiles.family}, "FreeSans"]);
+
+endfunction
+
+
+## Test input validation
+%!test
+%! [msg, id] = lasterr ();
+%! unwind_protect
+%!   lasterr ("", "");
+%!   try
+%!     listfonts (1, 2, 3);
+%!   catch
+%!   end_try_catch
+%!   [~, id] = lasterr ();
+%!   assert (id, "Octave:invalid-fun-call");
+%! unwind_protect_cleanup
+%!   lasterr (msg, id);
+%! end_unwind_protect
+
+%!error <expect a handle to a graphics object with a \"fontname\" property>
+%!  s = listfonts (0);
+
+%!error <expect a handle to a graphics object with a \"fontname\" property>
+%!  s = listfonts (struct ());
diff -r d4194f15ea22 -r 70f63b976162 scripts/gui/module.mk
--- a/scripts/gui/module.mk	Mon Jun 01 09:53:06 2020 +0200
+++ b/scripts/gui/module.mk	Mon Jun 01 09:53:08 2020 +0200
@@ -23,6 +23,7 @@
   %reldir%/helpdlg.m \
   %reldir%/inputdlg.m \
   %reldir%/isappdata.m \
+  %reldir%/listfonts.m \
   %reldir%/listdlg.m \
   %reldir%/movegui.m \
   %reldir%/msgbox.m \
diff -r d4194f15ea22 -r 70f63b976162 scripts/gui/uisetfont.m
--- a/scripts/gui/uisetfont.m	Mon Jun 01 09:53:06 2020 +0200
+++ b/scripts/gui/uisetfont.m	Mon Jun 01 09:53:08 2020 +0200
@@ -45,7 +45,12 @@
 ## structure is returned.  Otherwise, the font information is displayed
 ## onscreen.
 ##
-## @seealso{text, axes, uicontrol}
+## @strong{Note:} On systems that don't use FontConfig natively (all
+## but linux) the font cache is built when Octave is installed.
+## You will need to run @code{system ("fc-cache -fv")} manually after installing
+## new fonts.
+##
+## @seealso{listfonts, text, axes, uicontrol}
 ## @end deftypefn
 
 function varargout = uisetfont (varargin)
