# HG changeset patch
# User Pantxo Diribarne <pantxo.diribarne@gmail.com>
# Date 1590997988 -7200
# Node ID c126a60b0d52e2be5a3bcbc1d520ff6551dbf332
# Parent  f3200b8cff193e39b84a2df3914187d126b4554f
listfonts.m: New function (bug #58476).

* listfonts.m: New function file.

* NEWS: Announce new function.

* gui.txi: Add docstring in the utility functions paragraph.

* uisetfont.m: Add listfonts to @seealso links, and add paragraph about how
to update the font cache on non-Linux systems.

* __unimplemented__.m: Remove listfonts from unimplemented list.

diff -r f3200b8cff19 -r c126a60b0d52 NEWS
--- a/NEWS	Mon Jun 01 11:33:39 2020 -0700
+++ b/NEWS	Mon Jun 01 09:53:08 2020 +0200
@@ -91,7 +91,7 @@
     * "legend" (not yet implemented)
     * "nextseriesindex" (read-only, used by `scatter` graphics objects)
     * "positionconstraint" (replacement for "activepositionproperty"
-      which is now a hidden property. No plans for removal.)
+      which is now a hidden property.  No plans for removal.)
     * "toolbar" (not yet implemented)
     * "xaxis" (not yet implemented)
     * "yaxis" (not yet implemented)
@@ -101,6 +101,7 @@
 
 * `getpixelposition`
 * `endsWith`
+* `listfonts`
 * `memory`
 * `rng`
 * `startsWith`
diff -r f3200b8cff19 -r c126a60b0d52 doc/interpreter/gui.txi
--- a/doc/interpreter/gui.txi	Mon Jun 01 11:33:39 2020 -0700
+++ 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 f3200b8cff19 -r c126a60b0d52 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,78 @@
+########################################################################
+##
+## 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
+## font from the object's @qcode{"FontName"} property in the list.
+##
+## Programming 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)
+
+  if (nargin > 1)
+    print_usage ();
+  endif
+
+  if (! isempty (h) && (! ishghandle (h) || ! isprop (h, "fontname")))
+    error (['listfonts: H must be a handle to a graphics object ', ...
+            'with a "fontname" property']);
+  endif
+
+  persistent sysfonts = get_fonts ();
+  fonts = sysfonts;
+
+  if (nargin == 1 && ! 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
+%!error listfonts (0, 0)
+%!error <H must be a handle to a graphics object with a "fontname" property>
+%! s = listfonts (0);
+%!error <H must be a handle to a graphics object>
+%! s = listfonts (struct ());
diff -r f3200b8cff19 -r c126a60b0d52 scripts/gui/module.mk
--- a/scripts/gui/module.mk	Mon Jun 01 11:33:39 2020 -0700
+++ 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 f3200b8cff19 -r c126a60b0d52 scripts/gui/uisetfont.m
--- a/scripts/gui/uisetfont.m	Mon Jun 01 11:33:39 2020 -0700
+++ b/scripts/gui/uisetfont.m	Mon Jun 01 09:53:08 2020 +0200
@@ -45,7 +45,11 @@
 ## structure is returned.  Otherwise, the font information is displayed
 ## onscreen.
 ##
-## @seealso{text, axes, uicontrol}
+## Programming 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)
diff -r f3200b8cff19 -r c126a60b0d52 scripts/help/__unimplemented__.m
--- a/scripts/help/__unimplemented__.m	Mon Jun 01 11:33:39 2020 -0700
+++ b/scripts/help/__unimplemented__.m	Mon Jun 01 09:53:08 2020 +0200
@@ -966,7 +966,6 @@
   "libpointer",
   "libstruct",
   "linkdata",
-  "listfonts",
   "loadlibrary",
   "lsqminnorm",
   "lsqr",