src/lib/elm_fonts.h

   1 /**
   2  * @defgroup Fonts Elementary Fonts
   3  *
   4  * These are functions dealing with font rendering, selection and the
   5  * like for Elementary applications. One might fetch which system
   6  * fonts are there to use and set custom fonts for individual classes
   7  * of UI items containing text (text classes).
   8  *
   9  * @{
  10  */
  11
  12 typedef struct _Elm_Text_Class
  13 {
  14    const char *name;
  15    const char *desc;
  16 } Elm_Text_Class;
  17
  18 typedef struct _Elm_Font_Overlay
  19 {
  20    const char    *text_class;
  21    const char    *font;
  22    Evas_Font_Size size;
  23 } Elm_Font_Overlay;
  24
  25 typedef struct _Elm_Font_Properties
  26 {
  27    const char *name;
  28    Eina_List  *styles;
  29 } Elm_Font_Properties;
  30
  31 /**
  32  * Get Elementary's list of supported text classes.
  33  *
  34  * @return The text classes list, with @c Elm_Text_Class blobs as data.
  35  * @ingroup Fonts
  36  *
  37  * Release the list with elm_text_classes_list_free().
  38  */
  39 EAPI const Eina_List *elm_text_classes_list_get(void);
  40
  41 /**
  42  * Free Elementary's list of supported text classes.
  43  *
  44  * @ingroup Fonts
  45  *
  46  * @see elm_text_classes_list_get().
  47  */
  48 EAPI void             elm_text_classes_list_free(const Eina_List *list);
  49
  50 /**
  51  * Get Elementary's list of font overlays, set with
  52  * elm_font_overlay_set().
  53  *
  54  * @return The font overlays list, with @c Elm_Font_Overlay blobs as
  55  * data.
  56  *
  57  * @ingroup Fonts
  58  *
  59  * For each text class, one can set a <b>font overlay</b> for it,
  60  * overriding the default font properties for that class coming from
  61  * the theme in use. There is no need to free this list.
  62  *
  63  * @see elm_font_overlay_set() and elm_font_overlay_unset().
  64  */
  65 EAPI const Eina_List *elm_font_overlay_list_get(void);
  66
  67 /**
  68  * Set a font overlay for a given Elementary text class.
  69  *
  70  * @param text_class Text class name
  71  * @param font Font name and style string
  72  * @param size Font size
  73  *
  74  * @ingroup Fonts
  75  *
  76  * @p font has to be in the format returned by
  77  * elm_font_fontconfig_name_get(). @see elm_font_overlay_list_get()
  78  * and elm_font_overlay_unset().
  79  */
  80 EAPI void             elm_font_overlay_set(const char *text_class, const char *font, Evas_Font_Size size);
  81
  82 /**
  83  * Unset a font overlay for a given Elementary text class.
  84  *
  85  * @param text_class Text class name
  86  *
  87  * @ingroup Fonts
  88  *
  89  * This will bring back text elements belonging to text class
  90  * @p text_class back to their default font settings.
  91  */
  92 EAPI void             elm_font_overlay_unset(const char *text_class);
  93
  94 /**
  95  * Apply the changes made with elm_font_overlay_set() and
  96  * elm_font_overlay_unset() on the current Elementary window.
  97  *
  98  * @ingroup Fonts
  99  *
 100  * This applies all font overlays set to all objects in the UI.
 101  */
 102 EAPI void             elm_font_overlay_apply(void);
 103
 104 /**
 105  * Apply the changes made with elm_font_overlay_set() and
 106  * elm_font_overlay_unset() on all Elementary application windows.
 107  *
 108  * @ingroup Fonts
 109  *
 110  * This applies all font overlays set to all objects in the UI.
 111  */
 112 // XXX: deprecate and replace with elm_config_all_flush()
 113 EAPI void             elm_font_overlay_all_apply(void);
 114
 115 /**
 116  * Translate a font (family) name string in fontconfig's font names
 117  * syntax into an @c Elm_Font_Properties struct.
 118  *
 119  * @param font The font name and styles string
 120  * @return the font properties struct
 121  *
 122  * @ingroup Fonts
 123  *
 124  * @note The reverse translation can be achived with
 125  * elm_font_fontconfig_name_get(), for one style only (single font
 126  * instance, not family).
 127  */
 128 EAPI Elm_Font_Properties *
 129                       elm_font_properties_get(const char *font)
 130 EINA_ARG_NONNULL(1);
 131
 132 /**
 133  * Free font properties return by elm_font_properties_get().
 134  *
 135  * @param efp the font properties struct
 136  *
 137  * @ingroup Fonts
 138  */
 139 EAPI void             elm_font_properties_free(Elm_Font_Properties *efp) EINA_ARG_NONNULL(1);
 140
 141 /**
 142  * Translate a font name, bound to a style, into fontconfig's font names
 143  * syntax.
 144  *
 145  * @param name The font (family) name
 146  * @param style The given style (may be @c NULL)
 147  *
 148  * @return the font name and style string
 149  *
 150  * @ingroup Fonts
 151  *
 152  * @note The reverse translation can be achived with
 153  * elm_font_properties_get(), for one style only (single font
 154  * instance, not family).
 155  */
 156 EAPI const char      *elm_font_fontconfig_name_get(const char *name, const char *style) EINA_ARG_NONNULL(1);
 157
 158 /**
 159  * Free the font string return by elm_font_fontconfig_name_get().
 160  *
 161  * @param name the font properties struct
 162  *
 163  * @ingroup Fonts
 164  */
 165 EAPI void             elm_font_fontconfig_name_free(const char *name) EINA_ARG_NONNULL(1);
 166
 167 /**
 168  * Create a font hash table of available system fonts.
 169  *
 170  * One must call it with @p list being the return value of
 171  * evas_font_available_list(). The hash will be indexed by font
 172  * (family) names, being its values @c Elm_Font_Properties blobs.
 173  *
 174  * @param list The list of available system fonts, as returned by
 175  * evas_font_available_list().
 176  * @return the font hash.
 177  *
 178  * @ingroup Fonts
 179  *
 180  * @note The user is supposed to get it populated at least with 3
 181  * default font families (Sans, Serif, Monospace), which should be
 182  * present on most systems.
 183  */
 184 EAPI Eina_Hash       *elm_font_available_hash_add(Eina_List *list);
 185
 186 /**
 187  * Free the hash return by elm_font_available_hash_add().
 188  *
 189  * @param hash the hash to be freed.
 190  *
 191  * @ingroup Fonts
 192  */
 193 EAPI void             elm_font_available_hash_del(Eina_Hash *hash);
 194
 195 /**
 196  * @}
 197  */