|
Packit Service |
e3b512 |
/* Copyright (C) 2005 The cairomm Development Team
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This library is free software; you can redistribute it and/or
|
|
Packit Service |
e3b512 |
* modify it under the terms of the GNU Library General Public
|
|
Packit Service |
e3b512 |
* License as published by the Free Software Foundation; either
|
|
Packit Service |
e3b512 |
* version 2 of the License, or (at your option) any later version.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This library is distributed in the hope that it will be useful,
|
|
Packit Service |
e3b512 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit Service |
e3b512 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit Service |
e3b512 |
* Library General Public License for more details.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* You should have received a copy of the GNU Library General Public
|
|
Packit Service |
e3b512 |
* License along with this library; if not, write to the Free Software
|
|
Packit Service |
e3b512 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
Packit Service |
e3b512 |
* 02110-1301, USA.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#ifndef __CAIROMM_FONTFACE_H
|
|
Packit Service |
e3b512 |
#define __CAIROMM_FONTFACE_H
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#include <string>
|
|
Packit Service |
e3b512 |
#include <vector>
|
|
Packit Service |
e3b512 |
#include <cairomm/enums.h>
|
|
Packit Service |
e3b512 |
#include <cairomm/types.h>
|
|
Packit Service |
e3b512 |
#include <cairomm/refptr.h>
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#include <cairo.h>
|
|
Packit Service |
e3b512 |
#ifdef CAIRO_HAS_FT_FONT
|
|
Packit Service |
e3b512 |
#include <cairo-ft.h>
|
|
Packit Service |
e3b512 |
#endif //CAIRO_HAS_FT_FONT
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
namespace Cairo
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
class ScaledFont;
|
|
Packit Service |
e3b512 |
class Context;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* A FontFace represents a particular font at a particular weight, slant, and
|
|
Packit Service |
e3b512 |
* other characteristic but no size, transformation, or size.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Font faces are created using font-backend-specific constructors or implicitly
|
|
Packit Service |
e3b512 |
* using the toy text API by way of Context::select_font_face(). The resulting
|
|
Packit Service |
e3b512 |
* face can be accessed using Context::get_font_face().
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
class FontFace
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
//TODO?: FontFace(cairo_font_face_t *target);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
/** Create a C++ wrapper for the C instance. This C++ instance should then be given to a RefPtr.
|
|
Packit Service |
e3b512 |
* @param cobject The C instance.
|
|
Packit Service |
e3b512 |
* @param has_reference Whether we already have a reference. Otherwise, the constructor will take an extra reference.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
explicit FontFace(cairo_font_face_t* cobject, bool has_reference = false);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
FontFace(const FontFace&) = delete;
|
|
Packit Service |
e3b512 |
FontFace& operator=(const FontFace&) = delete;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
virtual ~FontFace();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/* Don't wrap these until we know what they are good for.
|
|
Packit Service |
e3b512 |
void* get_user_data(const cairo_user_data_key_t *key);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
void set_user_data(const cairo_user_data_key_t *key, void *user_data, cairo_destroy_func_t destroy);
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Returns the type of the backend used to create a font face
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
FontType get_type() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
typedef cairo_font_face_t cobject;
|
|
Packit Service |
e3b512 |
inline cobject* cobj() { return m_cobject; }
|
|
Packit Service |
e3b512 |
inline const cobject* cobj() const { return m_cobject; }
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#ifndef DOXYGEN_IGNORE_THIS
|
|
Packit Service |
e3b512 |
///For use only by the cairomm implementation.
|
|
Packit Service |
e3b512 |
inline ErrorStatus get_status() const
|
|
Packit Service |
e3b512 |
{ return cairo_font_face_status(const_cast<cairo_font_face_t*>(cobj())); }
|
|
Packit Service |
e3b512 |
#endif //DOXYGEN_IGNORE_THIS
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
void reference() const;
|
|
Packit Service |
e3b512 |
void unreference() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
cobject* m_cobject;
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** @example toy-text.cc
|
|
Packit Service |
e3b512 |
* A relatively simple example of using Cairo::ToyFontFace
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* A simple font face used for the cairo 'toy' font API.
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
class ToyFontFace : public FontFace
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Creates a font face from a triplet of family, slant, and weight. These font
|
|
Packit Service |
e3b512 |
* faces are used in implementation of the the Context "toy" font API.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* If family is the zero-length string "", the platform-specific default
|
|
Packit Service |
e3b512 |
* family is assumed. The default family then can be queried using
|
|
Packit Service |
e3b512 |
* get_family().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The Context::select_font_face() function uses this to create font faces.
|
|
Packit Service |
e3b512 |
* See that function for limitations of toy font faces.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param family a font family name, encoded in UTF-8.
|
|
Packit Service |
e3b512 |
* @param slant the slant for the font.
|
|
Packit Service |
e3b512 |
* @param weight the weight for the font.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
static RefPtr<ToyFontFace> create(const std::string& family, FontSlant slant, FontWeight weight);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Gets the familly name of a toy font.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
std::string get_family() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Gets the slant a toy font.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
FontSlant get_slant() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/**
|
|
Packit Service |
e3b512 |
* Gets the weight a toy font.
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
FontWeight get_weight() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
ToyFontFace(const std::string& family, FontSlant slant, FontWeight weight);
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** @example user-font.cc
|
|
Packit Service |
e3b512 |
* A relatively simple example of using Cairo::UserFontFace
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Font support with font data provided by the user.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The user-font feature allows the cairo user to provide drawings for glyphs in
|
|
Packit Service |
e3b512 |
* a font. This is most useful in implementing fonts in non-standard formats,
|
|
Packit Service |
e3b512 |
* like SVG fonts and Flash fonts, but can also be used by games and other
|
|
Packit Service |
e3b512 |
* application to draw "funky" fonts.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* To use user fonts, you must derive from this class and implement the virtual
|
|
Packit Service |
e3b512 |
* functions below. The only virtual function that absolutely must be
|
|
Packit Service |
e3b512 |
* implemented is render_glyph(). You should make the constructor protected and
|
|
Packit Service |
e3b512 |
* provide a factory function that returns a new object in a RefPtr since it is
|
|
Packit Service |
e3b512 |
* a refcounted object
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @code
|
|
Packit Service |
e3b512 |
* class MyUserFont : public UserFontFace {
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* public:
|
|
Packit Service |
e3b512 |
* static Cairo::RefPtr<MyUserFont> create() {
|
|
Packit Service |
e3b512 |
* return Cairo::RefPtr<MyUserFont>(new MyUserFont);
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* protected:
|
|
Packit Service |
e3b512 |
* // implement render_glyph() and any other virtual functions you want to override
|
|
Packit Service |
e3b512 |
* ErrorStatus render_glyph(const RefPtr<ScaledFont>& scaled_font,
|
|
Packit Service |
e3b512 |
* unsigned long glyph,
|
|
Packit Service |
e3b512 |
* const RefPtr<Context>& cr,
|
|
Packit Service |
e3b512 |
* TextExtents& metrics) {
|
|
Packit Service |
e3b512 |
* // render the glyph into cr here
|
|
Packit Service |
e3b512 |
* }
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* MyUserFont() : UserFontFace() {
|
|
Packit Service |
e3b512 |
* // constructor implementation
|
|
Packit Service |
e3b512 |
* }
|
|
Packit Service |
e3b512 |
* };
|
|
Packit Service |
e3b512 |
* @endcode
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @warning
|
|
Packit Service |
e3b512 |
* Because of a design flaw in cairomm, it is currently necessary to keep the
|
|
Packit Service |
e3b512 |
* the UserFontFace object around until as long as you are rendering text with
|
|
Packit Service |
e3b512 |
* the user font. The following code illustrates the issue:
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @code
|
|
Packit Service |
e3b512 |
* {
|
|
Packit Service |
e3b512 |
* auto face = MyUserFont::create();
|
|
Packit Service |
e3b512 |
* cr->set_font_face(face);
|
|
Packit Service |
e3b512 |
* } // scope for demonstration purposes
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* // the following call will cause a crash because your user font is no longer
|
|
Packit Service |
e3b512 |
* // in scope but it needs to call the virtual functions in face
|
|
Packit Service |
e3b512 |
* cr->show_text("hello, world");
|
|
Packit Service |
e3b512 |
* @endcode
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The preceding is obviously a very contrived example, but the important thing
|
|
Packit Service |
e3b512 |
* to know is that you *must* cache all userfont objects yourself as long as you
|
|
Packit Service |
e3b512 |
* intend to render text with that font. A future release of cairomm will fix
|
|
Packit Service |
e3b512 |
* this requirement, but that will require ABI-incompatible changes.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
class UserFontFace : public FontFace
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
virtual ~UserFontFace();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/*
|
|
Packit Service |
e3b512 |
static RefPtr<UserFontFace> create();
|
|
Packit Service |
e3b512 |
static RefPtr<UserFontFace> create(cairo_font_face_t* cobject, bool has_reference = false);
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function is called when a scaled-font needs to be created for a user
|
|
Packit Service |
e3b512 |
* font-face.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The Context @a cr is not used by the caller, but is prepared in font space,
|
|
Packit Service |
e3b512 |
* similar to what the cairo contexts passed to the render_glyph method will
|
|
Packit Service |
e3b512 |
* look like. The callback can use this context for extents computation for
|
|
Packit Service |
e3b512 |
* example. After the callback is called, @a cr is checked for any error status.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The @a extents argument is where the user font sets the font extents for
|
|
Packit Service |
e3b512 |
* scaled_font. It is in font space, which means that for most cases its
|
|
Packit Service |
e3b512 |
* ascent and descent members should add to 1.0. @a extents is preset to hold a
|
|
Packit Service |
e3b512 |
* value of 1.0 for ascent, height, and max_x_advance, and 0.0 for descent and
|
|
Packit Service |
e3b512 |
* max_y_advance members.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The default implementation sets the font extents as described in the
|
|
Packit Service |
e3b512 |
* previous paragraph. If you need different extents, you can override this
|
|
Packit Service |
e3b512 |
* function in your derived class.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Note that @a scaled_font is not fully initialized at this point and trying
|
|
Packit Service |
e3b512 |
* to use it for text operations in the callback will result in deadlock.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param scaled_font the scaled-font being created
|
|
Packit Service |
e3b512 |
* @param cr cairo context, in font space
|
|
Packit Service |
e3b512 |
* @param extents extents to fill in, in font space
|
|
Packit Service |
e3b512 |
* @return CAIRO_STATUS_SUCCESS upon success, or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
virtual ErrorStatus init(const RefPtr<ScaledFont>& scaled_font,
|
|
Packit Service |
e3b512 |
const RefPtr<Context>& cr,
|
|
Packit Service |
e3b512 |
FontExtents& extents);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function is called to convert an input Unicode character to a single
|
|
Packit Service |
e3b512 |
* glyph. This is used by the Context::show_text() operation.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This function is used to provide the same functionality as the
|
|
Packit Service |
e3b512 |
* text_to_glyphs callback does but has much less control on the output, in
|
|
Packit Service |
e3b512 |
* exchange for increased ease of use. The inherent assumption to using this
|
|
Packit Service |
e3b512 |
* callback is that each character maps to one glyph, and that the mapping is
|
|
Packit Service |
e3b512 |
* context independent. It also assumes that glyphs are positioned according
|
|
Packit Service |
e3b512 |
* to their advance width. These mean no ligatures, kerning, or complex
|
|
Packit Service |
e3b512 |
* scripts can be implemented using this callback.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The default implementation of this function is an identity mapping from
|
|
Packit Service |
e3b512 |
* Unicode code-points to glyph indices. If you need different behavior, you
|
|
Packit Service |
e3b512 |
* may override this virtual function in your derived class.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Note: While cairo does not impose any limitation on glyph indices, some
|
|
Packit Service |
e3b512 |
* applications may assume that a glyph index fits in a 16-bit unsigned
|
|
Packit Service |
e3b512 |
* integer. As such, it is advised that user-fonts keep their glyphs in the 0
|
|
Packit Service |
e3b512 |
* to 65535 range. Furthermore, some applications may assume that glyph 0 is a
|
|
Packit Service |
e3b512 |
* special glyph-not-found glyph. User-fonts are advised to use glyph 0 for
|
|
Packit Service |
e3b512 |
* such purposes and do not use that glyph value for other purposes.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param scaled_font the scaled-font being created
|
|
Packit Service |
e3b512 |
* @param unicode input unicode character code-point
|
|
Packit Service |
e3b512 |
* @param glyph_index output glyph index
|
|
Packit Service |
e3b512 |
* @return CAIRO_STATUS_SUCCESS upon success, or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
virtual ErrorStatus unicode_to_glyph(const RefPtr<ScaledFont>& scaled_font,
|
|
Packit Service |
e3b512 |
unsigned long unicode,
|
|
Packit Service |
e3b512 |
unsigned long& glyph);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function is called when a user scaled-font needs to render a
|
|
Packit Service |
e3b512 |
* glyph.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* You must implement this in your derived class, and it is expected to draw
|
|
Packit Service |
e3b512 |
* the glyph with code @a glyph to the Context @a cr. @a cr is prepared such
|
|
Packit Service |
e3b512 |
* that the glyph drawing is done in font space. That is, the matrix set on @a
|
|
Packit Service |
e3b512 |
* cr is the scale matrix of @a scaled_font, The @a extents argument is where
|
|
Packit Service |
e3b512 |
* the user font sets the font extents for scaled_font. However, if user
|
|
Packit Service |
e3b512 |
* prefers to draw in user space, they can achieve that by changing the matrix
|
|
Packit Service |
e3b512 |
* on @a cr. All cairo rendering operations to @a cr are permitted, however,
|
|
Packit Service |
e3b512 |
* the result is undefined if any source other than the default source on @a
|
|
Packit Service |
e3b512 |
* cr is used. That means, glyph bitmaps should be rendered using
|
|
Packit Service |
e3b512 |
* Context::mask() instead of Context::paint().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Other non-default settings on @a cr include a font size of 1.0 (given that
|
|
Packit Service |
e3b512 |
* it is set up to be in font space), and font options corresponding to @a
|
|
Packit Service |
e3b512 |
* scaled_font.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The @a extents argument is preset to have x_bearing, width, and y_advance
|
|
Packit Service |
e3b512 |
* of zero, y_bearing set to -font_extents.ascent, height to
|
|
Packit Service |
e3b512 |
* font_extents.ascent+font_extents.descent, and x_advance to
|
|
Packit Service |
e3b512 |
* font_extents.max_x_advance. The only field user needs to set in majority of
|
|
Packit Service |
e3b512 |
* cases is x_advance. If the width field is zero upon this function returning
|
|
Packit Service |
e3b512 |
* (which is its preset value), the glyph extents are automatically computed
|
|
Packit Service |
e3b512 |
* based on the drawings done to @a cr. This is in most cases exactly what the
|
|
Packit Service |
e3b512 |
* desired behavior is. However, if for any reason this function sets the
|
|
Packit Service |
e3b512 |
* extents, it must be ink extents, and include the extents of all drawing
|
|
Packit Service |
e3b512 |
* done to @a cr.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param scaled_font user scaled-font
|
|
Packit Service |
e3b512 |
* @param glyph glyph code to render
|
|
Packit Service |
e3b512 |
* @param cr Context to draw to, in font space
|
|
Packit Service |
e3b512 |
* @param extents glyph extents to fill in, in font space
|
|
Packit Service |
e3b512 |
* @return CAIRO_STATUS_SUCCESS upon success, or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
virtual ErrorStatus render_glyph(const RefPtr<ScaledFont>& scaled_font,
|
|
Packit Service |
e3b512 |
unsigned long glyph,
|
|
Packit Service |
e3b512 |
const RefPtr<Context>& cr,
|
|
Packit Service |
e3b512 |
TextExtents& metrics) = 0;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** This function is called to convert input text to an array of glyphs. This
|
|
Packit Service |
e3b512 |
* is used by the Context::show_text() operation.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Using this function, the user-font has full control on glyphs and their
|
|
Packit Service |
e3b512 |
* positions. That means, it allows for features like ligatures and kerning,
|
|
Packit Service |
e3b512 |
* as well as complex shaping required for scripts like Arabic and Indic.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* This function should populate the glyph indices and positions (in font
|
|
Packit Service |
e3b512 |
* space) assuming that the text is to be shown at the origin.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* If clusters is not empty, cluster mapping should be computed.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* If you do not override this virtual function in your derived class,
|
|
Packit Service |
e3b512 |
* the unicode_to_glyph function is used instead.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Note: While cairo does not impose any limitation on glyph indices, some
|
|
Packit Service |
e3b512 |
* applications may assume that a glyph index fits in a 16-bit unsigned
|
|
Packit Service |
e3b512 |
* integer. As such, it is advised that user-fonts keep their glyphs in the 0
|
|
Packit Service |
e3b512 |
* to 65535 range. Furthermore, some applications may assume that glyph 0 is a
|
|
Packit Service |
e3b512 |
* special glyph-not-found glyph. User-fonts are advised to use glyph 0 for
|
|
Packit Service |
e3b512 |
* such purposes and do not use that glyph value for other purposes.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param scaled_font the scaled-font being created
|
|
Packit Service |
e3b512 |
* @param utf8 a string of text encoded in UTF-8
|
|
Packit Service |
e3b512 |
* @param glyphs array of glyphs to fill, in font space
|
|
Packit Service |
e3b512 |
* @param clusters array of cluster mapping information to fill
|
|
Packit Service |
e3b512 |
* @param cluster_flags a variable to set the cluster flags corresponding to the output clusters
|
|
Packit Service |
e3b512 |
* @return CAIRO_STATUS_SUCCESS upon success, or CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
virtual ErrorStatus text_to_glyphs(const RefPtr<ScaledFont>& scaled_font,
|
|
Packit Service |
e3b512 |
const std::string& utf8,
|
|
Packit Service |
e3b512 |
std::vector<Glyph>& glyphs,
|
|
Packit Service |
e3b512 |
std::vector<TextCluster>& clusters,
|
|
Packit Service |
e3b512 |
TextClusterFlags& cluster_flags);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
UserFontFace();
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
private:
|
|
Packit Service |
e3b512 |
static cairo_status_t
|
|
Packit Service |
e3b512 |
init_cb(cairo_scaled_font_t* scaled_font,
|
|
Packit Service |
e3b512 |
cairo_t *cr,
|
|
Packit Service |
e3b512 |
cairo_font_extents_t* metrics);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
static cairo_status_t
|
|
Packit Service |
e3b512 |
unicode_to_glyph_cb(cairo_scaled_font_t *scaled_font,
|
|
Packit Service |
e3b512 |
unsigned long unicode,
|
|
Packit Service |
e3b512 |
unsigned long *glyph);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
static cairo_status_t
|
|
Packit Service |
e3b512 |
render_glyph_cb(cairo_scaled_font_t *scaled_font,
|
|
Packit Service |
e3b512 |
unsigned long glyph,
|
|
Packit Service |
e3b512 |
cairo_t *cr,
|
|
Packit Service |
e3b512 |
cairo_text_extents_t *metrics);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
static cairo_status_t
|
|
Packit Service |
e3b512 |
text_to_glyphs_cb (cairo_scaled_font_t *scaled_font,
|
|
Packit Service |
e3b512 |
const char *utf8,
|
|
Packit Service |
e3b512 |
int utf8_len,
|
|
Packit Service |
e3b512 |
cairo_glyph_t **glyphs,
|
|
Packit Service |
e3b512 |
int *num_glyphs,
|
|
Packit Service |
e3b512 |
cairo_text_cluster_t **clusters,
|
|
Packit Service |
e3b512 |
int *num_clusters,
|
|
Packit Service |
e3b512 |
cairo_text_cluster_flags_t *cluster_flags);
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
// font system support
|
|
Packit Service |
e3b512 |
#ifdef CAIRO_HAS_FT_FONT
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
class FtFontFace : public FontFace
|
|
Packit Service |
e3b512 |
{
|
|
Packit Service |
e3b512 |
public:
|
|
Packit Service |
e3b512 |
/** Creates a new font face for the FreeType font backend from a pre-opened
|
|
Packit Service |
e3b512 |
* FreeType face. This font can then be used with Context::set_font_face() or
|
|
Packit Service |
e3b512 |
* FtScaledFont::create().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* As an example, here is how one might correctly couple the lifetime of the
|
|
Packit Service |
e3b512 |
* FreeType face object to the FtFontFace:
|
|
Packit Service |
e3b512 |
* @code
|
|
Packit Service |
e3b512 |
* static const cairo_user_data_key_t key;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
* font_face = cairo_ft_font_face_create_for_ft_face (ft_face, 0);
|
|
Packit Service |
e3b512 |
* status = cairo_font_face_set_user_data (font_face, &key,
|
|
Packit Service |
e3b512 |
* ft_face, (cairo_destroy_func_t) FT_Done_Face);
|
|
Packit Service |
e3b512 |
* if (status) {
|
|
Packit Service |
e3b512 |
* cairo_font_face_destroy (font_face);
|
|
Packit Service |
e3b512 |
* FT_Done_Face (ft_face);
|
|
Packit Service |
e3b512 |
* return ERROR;
|
|
Packit Service |
e3b512 |
* }
|
|
Packit Service |
e3b512 |
* @endcode
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param face A FreeType face object, already opened. This must be kept
|
|
Packit Service |
e3b512 |
* around until the face's ref_count drops to zero and it is freed. Since the
|
|
Packit Service |
e3b512 |
* face may be referenced internally to Cairo, the best way to determine when
|
|
Packit Service |
e3b512 |
* it is safe to free the face is to pass a cairo_destroy_func_t to
|
|
Packit Service |
e3b512 |
* cairo_font_face_set_user_data().
|
|
Packit Service |
e3b512 |
* @param load_flags flags to pass to FT_Load_Glyph when loading glyphs from
|
|
Packit Service |
e3b512 |
* the font. These flags are OR'ed together with the flags derived from the
|
|
Packit Service |
e3b512 |
* cairo_font_options_t passed to cairo_scaled_font_create(), so only a few
|
|
Packit Service |
e3b512 |
* values such as FT_LOAD_VERTICAL_LAYOUT, and FT_LOAD_FORCE_AUTOHINT are
|
|
Packit Service |
e3b512 |
* useful. You should not pass any of the flags affecting the load target,
|
|
Packit Service |
e3b512 |
* such as FT_LOAD_TARGET_LIGHT.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
static RefPtr<FtFontFace> create(FT_Face face, int load_flags);
|
|
Packit Service |
e3b512 |
//TODO: Add a suitable default value for load_flags?
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#ifdef CAIRO_HAS_FC_FONT
|
|
Packit Service |
e3b512 |
/** Creates a new font face for the FreeType font backend based on a
|
|
Packit Service |
e3b512 |
* fontconfig pattern. This font can then be used with Context::set_font_face()
|
|
Packit Service |
e3b512 |
* or FtScaledFont::create().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* Font rendering options are represented both here and when you call
|
|
Packit Service |
e3b512 |
* FtScaledFont::create(). Font options that have a representation in a
|
|
Packit Service |
e3b512 |
* FcPattern must be passed in here; to modify FcPattern appropriately to
|
|
Packit Service |
e3b512 |
* reflect the options in a FontOptions, call FontOptions::substitute().
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* The pattern's FC_FT_FACE element is inspected first and if that is set,
|
|
Packit Service |
e3b512 |
* that will be the FreeType font face associated with the returned cairo font
|
|
Packit Service |
e3b512 |
* face. Otherwise the FC_FILE and FC_INDEX elements of pattern are used to
|
|
Packit Service |
e3b512 |
* load a font face from file.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* If the FC_FT_FACE element of pattern is set, the user is responsible for
|
|
Packit Service |
e3b512 |
* making sure that the referenced FT_Face remains valid for the life time of
|
|
Packit Service |
e3b512 |
* the returned FtFontFace. See FtFontFace::create() for an exmaple of how to
|
|
Packit Service |
e3b512 |
* couple the life time of the FT_Face to that of the cairo font-face.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param pattern A fully resolved fontconfig pattern. A pattern can be
|
|
Packit Service |
e3b512 |
* resolved, by, among other things, calling FcConfigSubstitute(),
|
|
Packit Service |
e3b512 |
* FcDefaultSubstitute(), then FcFontMatch(). Cairo will call
|
|
Packit Service |
e3b512 |
* FcPatternReference() on this pattern, so you should not further modify the
|
|
Packit Service |
e3b512 |
* pattern, but you can release your reference to the pattern with
|
|
Packit Service |
e3b512 |
* FcPatternDestroy() if you no longer need to access it.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.8
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
static RefPtr<FtFontFace> create(FcPattern* pattern);
|
|
Packit Service |
e3b512 |
#endif // CAIRO_HAS_FC_FONT
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Sets synthesis options to control how FreeType renders the glyphs for a
|
|
Packit Service |
e3b512 |
* particular font face. The given options are ORed with the currently active
|
|
Packit Service |
e3b512 |
* options.
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param synth_flags A set of synthesis options to enable
|
|
Packit Service |
e3b512 |
* @since 1.12
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void set_synthesize(FtSynthesize synth_flags);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Unsets the specified FreeType glypth synthesis options
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @param synth_flags A set of synthesis options to disable
|
|
Packit Service |
e3b512 |
* @since 1.12
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
void unset_synthesize(FtSynthesize synth_flags);
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
/** Returns currently activy FreeType glyph synthesis options
|
|
Packit Service |
e3b512 |
*
|
|
Packit Service |
e3b512 |
* @since 1.12
|
|
Packit Service |
e3b512 |
*/
|
|
Packit Service |
e3b512 |
FtSynthesize get_synthesize() const;
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
protected:
|
|
Packit Service |
e3b512 |
FtFontFace(FT_Face face, int load_flags);
|
|
Packit Service |
e3b512 |
#ifdef CAIRO_HAS_FC_FONT
|
|
Packit Service |
e3b512 |
FtFontFace(FcPattern* pattern);
|
|
Packit Service |
e3b512 |
#endif // CAIRO_HAS_FC_FONT
|
|
Packit Service |
e3b512 |
};
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#endif // CAIRO_HAS_FT_FONT
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
} // namespace Cairo
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
#endif //__CAIROMM_FONTFACE_H
|
|
Packit Service |
e3b512 |
|
|
Packit Service |
e3b512 |
// vim: ts=2 sw=2 et
|