interface/fontenum.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        fontenum.h
   3 // Purpose:     documentation for wxFontEnumerator class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFontEnumerator
  11     @wxheader{fontenum.h}
  12
  13     wxFontEnumerator enumerates either all available fonts on the system or only
  14     the ones with given attributes - either only fixed-width (suited for use in
  15     programs such as terminal emulators and the like) or the fonts available in
  16     the given encoding.
  17
  18     To do this, you just have to call one of EnumerateXXX() functions - either
  19     wxFontEnumerator::EnumerateFacenames or
  20     wxFontEnumerator::EnumerateEncodings and the
  21     corresponding callback (wxFontEnumerator::OnFacename or
  22     wxFontEnumerator::OnFontEncoding) will be called
  23     repeatedly until either all fonts satisfying the specified criteria are
  24     exhausted or the callback returns @false.
  25
  26     @library{wxcore}
  27     @category{FIXME}
  28
  29     @seealso
  30     @ref overview_wxfontencodingoverview "Font encoding overview", @ref
  31     overview_samplefont "Font sample", wxFont, wxFontMapper
  32 */
  33 class wxFontEnumerator
  34 {
  35 public:
  36     /**
  37         Call OnFontEncoding() for each
  38         encoding supported by the given font - or for each encoding supported by at
  39         least some font if @e font is not specified.
  40     */
  41     virtual bool EnumerateEncodings(const wxString& font = "");
  42
  43     /**
  44         Call OnFacename() for each font which
  45         supports given encoding (only if it is not wxFONTENCODING_SYSTEM) and is of
  46         fixed width (if @e fixedWidthOnly is @true).
  47
  48         Calling this function with default arguments will result in enumerating all
  49         fonts available on the system.
  50     */
  51     virtual bool EnumerateFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM,
  52                                     bool fixedWidthOnly = @false);
  53
  54     /**
  55         Return array of strings containing all encodings found by
  56         EnumerateEncodings().
  57     */
  58     static wxArrayString GetEncodings(const wxString& facename = "");
  59
  60     /**
  61         Return array of strings containing all facenames found by
  62         EnumerateFacenames().
  63     */
  64     static wxArrayString GetFacenames(wxFontEncoding encoding = wxFONTENCODING_SYSTEM,
  65                                       bool fixedWidthOnly = @false);
  66
  67     /**
  68         Returns @true if the given string is valid face name, i.e. it's the face name
  69         of an installed
  70         font and it can safely be used with wxFont::SetFaceName.
  71     */
  72     static bool IsValidFacename(const wxString & facename);
  73
  74     /**
  75         Called by EnumerateFacenames() for
  76         each match. Return @true to continue enumeration or @false to stop it.
  77     */
  78     virtual bool OnFacename(const wxString& font);
  79
  80     /**
  81         Called by EnumerateEncodings() for
  82         each match. Return @true to continue enumeration or @false to stop it.
  83     */
  84     virtual bool OnFontEncoding(const wxString& font,
  85                                 const wxString& encoding);
  86 };