include/opencascade/Font_FontMgr.hxx

0001 // Created on: 2008-01-20
0002 // Created by: Alexander A. BORODIN
0003 // Copyright (c) 2008-2014 OPEN CASCADE SAS
0004 //
0005 // This file is part of Open CASCADE Technology software library.
0006 //
0007 // This library is free software; you can redistribute it and/or modify it under
0008 // the terms of the GNU Lesser General Public License version 2.1 as published
0009 // by the Free Software Foundation, with special exception defined in the file
0010 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0011 // distribution for complete text of the license and disclaimer of any warranty.
0012 //
0013 // Alternatively, this file may be used under the terms of Open CASCADE
0014 // commercial license or contractual agreement.
0015
0016 #ifndef _Font_FontMgr_HeaderFile
0017 #define _Font_FontMgr_HeaderFile
0018
0019 #include <Standard.hxx>
0020 #include <Standard_Transient.hxx>
0021 #include <Font_NListOfSystemFont.hxx>
0022 #include <Font_StrictLevel.hxx>
0023 #include <Font_UnicodeSubset.hxx>
0024 #include <NCollection_DataMap.hxx>
0025 #include <NCollection_IndexedMap.hxx>
0026 #include <NCollection_Shared.hxx>
0027 #include <TColStd_SequenceOfHAsciiString.hxx>
0028
0029 class TCollection_HAsciiString;
0030 class NCollection_Buffer;
0031
0032 DEFINE_STANDARD_HANDLE(Font_FontMgr, Standard_Transient)
0033
0034 //! Collects and provides information about available fonts in system.
0035 class Font_FontMgr : public Standard_Transient
0036 {
0037   DEFINE_STANDARD_RTTIEXT(Font_FontMgr, Standard_Transient)
0038 public:
0039   //! Return global instance of font manager.
0040   Standard_EXPORT static Handle(Font_FontMgr) GetInstance();
0041
0042   //! Return font aspect as string.
0043   static const char* FontAspectToString(Font_FontAspect theAspect)
0044   {
0045     switch (theAspect)
0046     {
0047       case Font_FontAspect_UNDEFINED:
0048         return "undefined";
0049       case Font_FontAspect_Regular:
0050         return "regular";
0051       case Font_FontAspect_Bold:
0052         return "bold";
0053       case Font_FontAspect_Italic:
0054         return "italic";
0055       case Font_FontAspect_BoldItalic:
0056         return "bold-italic";
0057     }
0058     return "invalid";
0059   }
0060
0061   //! Return flag to use fallback fonts in case if used font does not include symbols from specific
0062   //! Unicode subset; TRUE by default.
0063   Standard_EXPORT static Standard_Boolean& ToUseUnicodeSubsetFallback();
0064
0065 public:
0066   //! Return the list of available fonts.
0067   void AvailableFonts(Font_NListOfSystemFont& theList) const
0068   {
0069     for (Font_FontMap::Iterator aFontIter(myFontMap); aFontIter.More(); aFontIter.Next())
0070     {
0071       theList.Append(aFontIter.Value());
0072     }
0073   }
0074
0075   //! Return the list of available fonts.
0076   Font_NListOfSystemFont GetAvailableFonts() const
0077   {
0078     Font_NListOfSystemFont aList;
0079     AvailableFonts(aList);
0080     return aList;
0081   }
0082
0083   //! Returns sequence of available fonts names
0084   Standard_EXPORT void GetAvailableFontsNames(TColStd_SequenceOfHAsciiString& theFontsNames) const;
0085
0086   //! Returns font that match given parameters.
0087   //! If theFontName is empty string returned font can have any FontName.
0088   //! If theFontAspect is Font_FA_Undefined returned font can have any FontAspect.
0089   //! If theFontSize is "-1" returned font can have any FontSize.
0090   Standard_EXPORT Handle(Font_SystemFont) GetFont(
0091     const Handle(TCollection_HAsciiString)& theFontName,
0092     const Font_FontAspect                   theFontAspect,
0093     const Standard_Integer                  theFontSize) const;
0094
0095   //! Returns font that match given name or NULL if such font family is NOT registered.
0096   //! Note that unlike FindFont(), this method ignores font aliases and does not look for fall-back.
0097   Standard_EXPORT Handle(Font_SystemFont) GetFont(const TCollection_AsciiString& theFontName) const;
0098
0099   //! Tries to find font by given parameters.
0100   //! If the specified font is not found tries to use font names mapping.
0101   //! If the requested family name not found -> search for any font family with given aspect and
0102   //! height. If the font is still not found, returns any font available in the system. Returns NULL
0103   //! in case when the fonts are not found in the system.
0104   //! @param[in] theFontName           font family to find or alias name
0105   //! @param[in] theStrictLevel        search strict level for using aliases and fallback
0106   //! @param[in][out] theFontAspect    font aspect to find (considered only if family name is not
0107   //! found);
0108   //!                                  can be modified if specified font alias refers to another
0109   //!                                  style (compatibility with obsolete aliases)
0110   //! @param[in] theDoFailMsg          put error message on failure into default messenger
0111   Standard_EXPORT Handle(Font_SystemFont) FindFont(
0112     const TCollection_AsciiString& theFontName,
0113     Font_StrictLevel               theStrictLevel,
0114     Font_FontAspect&               theFontAspect,
0115     Standard_Boolean               theDoFailMsg = Standard_True) const;
0116
0117   //! Tries to find font by given parameters.
0118   Handle(Font_SystemFont) FindFont(const TCollection_AsciiString& theFontName,
0119                                    Font_FontAspect&               theFontAspect) const
0120   {
0121     return FindFont(theFontName, Font_StrictLevel_Any, theFontAspect);
0122   }
0123
0124   //! Tries to find fallback font for specified Unicode subset.
0125   //! Returns NULL in case when fallback font is not found in the system.
0126   //! @param[in] theSubset      Unicode subset
0127   //! @param[in] theFontAspect  font aspect to find
0128   Standard_EXPORT Handle(Font_SystemFont) FindFallbackFont(Font_UnicodeSubset theSubset,
0129                                                            Font_FontAspect    theFontAspect) const;
0130
0131   //! Read font file and retrieve information from it (the list of font faces).
0132   Standard_EXPORT Standard_Boolean
0133     CheckFont(NCollection_Sequence<Handle(Font_SystemFont)>& theFonts,
0134               const TCollection_AsciiString&                 theFontPath) const;
0135
0136   //! Read font file and retrieve information from it.
0137   Standard_EXPORT Handle(Font_SystemFont) CheckFont(const Standard_CString theFontPath) const;
0138
0139   //! Register new font.
0140   //! If there is existing entity with the same name and properties but different path
0141   //! then font will be overridden or ignored depending on theToOverride flag.
0142   Standard_EXPORT Standard_Boolean RegisterFont(const Handle(Font_SystemFont)& theFont,
0143                                                 const Standard_Boolean         theToOverride);
0144
0145   //! Register new fonts.
0146   Standard_Boolean RegisterFonts(const NCollection_Sequence<Handle(Font_SystemFont)>& theFonts,
0147                                  const Standard_Boolean                               theToOverride)
0148   {
0149     Standard_Boolean isRegistered = Standard_False;
0150     for (NCollection_Sequence<Handle(Font_SystemFont)>::Iterator aFontIter(theFonts);
0151          aFontIter.More();
0152          aFontIter.Next())
0153     {
0154       isRegistered = RegisterFont(aFontIter.Value(), theToOverride) || isRegistered;
0155     }
0156     return isRegistered;
0157   }
0158
0159 public:
0160   //! Return flag for tracing font aliases usage via Message_Trace messages; TRUE by default.
0161   Standard_Boolean ToTraceAliases() const { return myToTraceAliases; }
0162
0163   //! Set flag for tracing font alias usage; useful to trace which fonts are actually used.
0164   //! Can be disabled to avoid redundant messages with Message_Trace level.
0165   void SetTraceAliases(Standard_Boolean theToTrace) { myToTraceAliases = theToTrace; }
0166
0167   //! Return font names with defined aliases.
0168   //! @param[out] theAliases  alias names
0169   Standard_EXPORT void GetAllAliases(TColStd_SequenceOfHAsciiString& theAliases) const;
0170
0171   //! Return aliases to specified font name.
0172   //! @param[out] theFontNames  font names associated with alias name
0173   //! @param[in] theAliasName   alias name
0174   Standard_EXPORT void GetFontAliases(TColStd_SequenceOfHAsciiString& theFontNames,
0175                                       const TCollection_AsciiString&  theAliasName) const;
0176
0177   //! Register font alias.
0178   //!
0179   //! Font alias allows using predefined short-cuts like Font_NOF_MONOSPACE or Font_NOF_SANS_SERIF,
0180   //! and defining several fallback fonts like Font_NOF_CJK ("cjk") or "courier" for fonts,
0181   //! which availability depends on system.
0182   //!
0183   //! By default, Font_FontMgr registers standard aliases, which could be extended or replaced by
0184   //! application basing on better knowledge of the system or basing on additional fonts packaged
0185   //! with application itself. Aliases are defined "in advance", so that they could point to
0186   //! non-existing fonts, and they are resolved dynamically on request - first existing font is
0187   //! returned in case of multiple aliases to the same name.
0188   //!
0189   //! @param[in] theAliasName  alias name or name of another font to be used as alias
0190   //! @param[in] theFontName   font to be used as substitution for alias
0191   //! @return FALSE if alias has been already registered
0192   Standard_EXPORT bool AddFontAlias(const TCollection_AsciiString& theAliasName,
0193                                     const TCollection_AsciiString& theFontName);
0194
0195   //! Unregister font alias.
0196   //! @param[in] theAliasName  alias name or name of another font to be used as alias;
0197   //!                          all aliases will be removed in case of empty name
0198   //! @param[in] theFontName   font to be used as substitution for alias;
0199   //!                          all fonts will be removed in case of empty name
0200   //! @return TRUE if alias has been removed
0201   Standard_EXPORT bool RemoveFontAlias(const TCollection_AsciiString& theAliasName,
0202                                        const TCollection_AsciiString& theFontName);
0203
0204 public:
0205   //! Collects available fonts paths.
0206   Standard_EXPORT void InitFontDataBase();
0207
0208   //! Clear registry. Can be used for testing purposes.
0209   Standard_EXPORT void ClearFontDataBase();
0210
0211   //! Return DejaVu font as embed a single fallback font.
0212   //! It can be used in cases when there is no own font file.
0213   //! Note: result buffer is readonly and should not be changed,
0214   //!       any data modification can lead to unpredictable consequences.
0215   Standard_EXPORT static Handle(NCollection_Buffer) EmbedFallbackFont();
0216
0217 private:
0218   //! Creates empty font manager object
0219   Standard_EXPORT Font_FontMgr();
0220
0221 private:
0222   struct FontHasher
0223   {
0224     size_t operator()(const Handle(Font_SystemFont)& theFont) const noexcept
0225     {
0226       return std::hash<TCollection_AsciiString>{}(theFont->FontKey());
0227     }
0228
0229     bool operator()(const Handle(Font_SystemFont)& theFont1,
0230                     const Handle(Font_SystemFont)& theFont2) const
0231     {
0232       return theFont1->IsEqual(theFont2);
0233     }
0234   };
0235
0236   //! Map storing registered fonts.
0237   class Font_FontMap : public NCollection_IndexedMap<Handle(Font_SystemFont), FontHasher>
0238   {
0239   public:
0240     //! Empty constructor.
0241     Font_FontMap() {}
0242
0243     //! Try finding font with specified parameters or the closest one.
0244     //! @param[in] theFontName  font family to find (or empty string if family name can be ignored)
0245     //! @return best match font or NULL if not found
0246     Handle(Font_SystemFont) Find(const TCollection_AsciiString& theFontName) const;
0247   };
0248
0249   //! Structure defining font alias.
0250   struct Font_FontAlias
0251   {
0252     TCollection_AsciiString FontName;
0253     Font_FontAspect         FontAspect;
0254
0255     Font_FontAlias(const TCollection_AsciiString& theFontName,
0256                    Font_FontAspect                theFontAspect = Font_FontAspect_UNDEFINED)
0257         : FontName(theFontName),
0258           FontAspect(theFontAspect)
0259     {
0260     }
0261
0262     Font_FontAlias()
0263         : FontAspect(Font_FontAspect_UNDEFINED)
0264     {
0265     }
0266   };
0267
0268   //! Sequence of font aliases.
0269   typedef NCollection_Shared<NCollection_Sequence<Font_FontAlias>> Font_FontAliasSequence;
0270
0271   //! Register font alias.
0272   void addFontAlias(const TCollection_AsciiString&        theAliasName,
0273                     const Handle(Font_FontAliasSequence)& theAliases,
0274                     Font_FontAspect                       theAspect = Font_FontAspect_UNDEFINED);
0275
0276 private:
0277   Font_FontMap                                                                 myFontMap;
0278   NCollection_DataMap<TCollection_AsciiString, Handle(Font_FontAliasSequence)> myFontAliases;
0279   Handle(Font_FontAliasSequence)                                               myFallbackAlias;
0280   Standard_Boolean                                                             myToTraceAliases;
0281 };
0282
0283 #endif // _Font_FontMgr_HeaderFile