C++ bindings for cgul_bdf More...

#include <cgul_bdf_cxx.h>

Collaboration diagram for cgul_bdf_cxx:

Public Member Functions
	cgul_bdf_cxx ()

virtual	~cgul_bdf_cxx ()

void	load (const char *font_list)

virtual void	load_explicit (const char bdf_file_name, const char index_file_name=NULL)

virtual void	unload ()

virtual unsigned long int	get_cache_size () const

virtual void	set_cache_size (unsigned long int cache_size)

virtual void	get_utf8_extents (const char utf8, size_t utf8_length, int substitute, unsigned int width, unsigned int *height) const

virtual void	get_utf32_extents (const cgul_wchar_t utf32, size_t utf32_length, int substitute, unsigned int width, unsigned int *height) const

virtual cgul_bdf_glyph_cxx *	get_glyph (cgul_wchar_t encoding, int substitute) const

virtual void	shift_right ()

virtual void	pad_left ()

virtual void	write (const char *bdf_file_name)

virtual void	write_file (FILE *f)

virtual void	write_index (const char *index_file_name)

virtual void	write_index_file (FILE *f)

virtual unsigned int	get_ascent () const

virtual unsigned int	get_descent () const

virtual unsigned int	get_height () const

virtual const char *	get_font_list () const

virtual const char *	get_font_name () const

virtual unsigned int	get_font_size () const

virtual unsigned int	get_dpi_x () const

virtual unsigned int	get_dpi_y () const

virtual unsigned int	get_bb_width () const

virtual unsigned int	get_bb_height () const

virtual int	get_bb_x_offset () const

virtual int	get_bb_y_offset () const

virtual unsigned long int	get_char_count () const

virtual cgul_bdf_t	get_obj () const

virtual cgul_bdf_t	take_obj ()

virtual void	set_obj (cgul_bdf_t rhs)

Detailed Description

This class provides the C++ bindings for C cgul_bdf objects. The main purpose of this class is to convert the C-style function calls and exception handling in cgul_bdf into C++-style function calls and exception handling.

Constructor & Destructor Documentation

§ cgul_bdf_cxx()

cgul_bdf_cxx::cgul_bdf_cxx ( )

inline

Construct a new bdf object. To load a font into the newly created object, call load() or load_explicit(). If an error occurs, an exception is thrown.

References cgul_bdf__new().

Referenced by set_obj().

§ ~cgul_bdf_cxx()

virtual cgul_bdf_cxx::~cgul_bdf_cxx ( )

inlinevirtual

This method frees all internally allocated resources for the object.

References cgul_bdf__delete().

Member Function Documentation

§ load()

void cgul_bdf_cxx::load ( const char * font_list )

inline

This method splits font_list into individual fonts and tries to load and merge each font in turn by repeatedly calling load_explicit(). The end result is that when the client calls get_glyph(), the fonts will be searched in order and the first matching glyph will be returned.

The font_list can be just a single font or can have multiple fonts separated with the "|" character. A trailing ".bdf" extension in the names of the fonts is optional:

    "foo-14|bar-14|baz-14"

When calling load_explicit(), this method first tries to load the font along with its BDF index file by appending an "i" character to the BDF file name. Only if this does not succeed will the method try to load the BDF file without an index. If different behavior is needed, the client should call load_explicit() directly.

Parameters

[in] font_list font list

References cgul_bdf__load().

§ load_explicit()

virtual void cgul_bdf_cxx::load_explicit	(	const char *	bdf_file_name,
		const char *	index_file_name = `NULL`
	)

inlinevirtual

This methods loads a BDF font from bdf_file_name. If a font is already loaded, the new font will be merged into the existing font. To manually unload the existing font first, call unload().

If an error occurs, an exception is thrown, and the cgul_bdf_cxx object will be in an undefined state. In this case, the client should delete the object and start over after correcting the problem.

The index_file_name parameter is optional. It specifies the BDF index file (which should have been generated earlier using write_index()). The BDF index file contains information on where to find each glyph in the BDF file. All fonts must be loaded with an index file in order for cache expiration to be enabled; otherwise, there would be no good way to reload any arbitrary glyph that expires. (See set_cache_size()).

If index_file_name is NULL the entire font will be loaded from file including all of the glyphs. If index_file_name is not NULL, only the meta information for the font will be loaded. The glyphs for the font will be loaded on demand by get_glyph() using the index information contained in index_file_name.

Whether to use an index file or not depends on how the object will be used. If the object will be used to lookup glyph information in large fonts for characters in random strings, using an index file will probably give the best performance; however, if the object needs to process each glyph once like when writing a new BDF file or when writing a BDF index file, loading the BDF without an index file will give the best performance by a wide margin.

The advantages of using an index file is that your program will start much faster and will only load the glyphs that are used thereby saving time and memory. The disadvantages are that the index file can be large and can potentially get out of sync with the BDF file. Also, the first time you try to access a glyph, it has to be loaded from disk which is a relatively slow operation, but subsequent accesses will retrieve the glyph from the cache.

If the DEFAULT_CHAR property is present in the BDF font, the glyph for that character will be used when the user requests a glyph which is not present in the font. If the DEFAULT_CHAR property is missing, this method will generate a glyph that looks like an empty box to use instead.

Parameters

[in]	bdf_file_name	bdf file name
[in]	index_file_name	index file name

References cgul_bdf__load_explicit().

§ unload()

virtual void cgul_bdf_cxx::unload ( )

inlinevirtual

This method unloads the font and frees internally allocated resources.

References cgul_bdf__unload().

§ get_cache_size()

virtual unsigned long int cgul_bdf_cxx::get_cache_size ( ) const

inlinevirtual

Get the current limit on the size of the internal glyph cache. By convention, a cache size of 0 means the cache can grow without limit.

Returns: cache size

References cgul_bdf__get_cache_size().

§ set_cache_size()

virtual void cgul_bdf_cxx::set_cache_size ( unsigned long int cache_size )

inlinevirtual

This method sets the maximum size of the internal cache that stores glyphs. The cache size is only relevant if index files are specified for each BDF when load() or load_explicit() is called. If index files are specified, it means the glyphs can be reloaded from file later so it is safe to remove them from the internal cache.

By default, cache_size is set to 0 which, by convention, means glyphs never expire. If the caller sets cache_size to a positive value, the least-recently used (LRU) glyphs will be expired first.

If glyph expiration is enabled, the client must be careful not to cache glyphs itself because they could expire at any moment. Instead, the client must make sure cache_size is large enough for the task at hand and must call get_glyph() to get the glyph each time it is used so that bdf can keep its LRU list up to date so that glyphs can be expired in the correct order.

Calling this method has the potential of cause glyphs to expire immediately.

Parameters

[in] cache_size cache size

References cgul_bdf__set_cache_size().

§ get_utf8_extents()

virtual void cgul_bdf_cxx::get_utf8_extents	(	const char *	utf8,
		size_t	utf8_length,
		int	substitute,
		unsigned int *	width,
		unsigned int *	height
	)		const

inlinevirtual

This method returns the width and height in pixels of the smallest rectangle that can contain the image of the text in the UTF-8 string utf8. The width and height are returned in width and height provided they are not set to NULL.

No attempt is made by this method to trim white space. Thus, if white space characters appear at the end of a line, their width will be added to the width that is returned. Likewise, if there are multiple trailing line breaks, the extra ones will add to the height that is returned. If this is not the behavior you want, you need to trim utf8 before passing it into this method.

It is also important to understand that the cgul_bdf_cxx class does not draw text. Instead, it loads fonts and makes the information for each glyph available so that drawing libraries you write can draw text. Providing your drawing library spaces each character using the value returned by cgul_bdf_glyph_cxx::get_dwidth_x() and providing your drawing library spaces each line using the value returned by cgul_bdf_cxx::get_height(), this method will return accurate values for width and height.

It is also important to understand that the width for each line of text is not simply the sum of the "dwidth_x" properties of each character. It is slightly more complicated than this because some glyphs have pixels that intrude on the character cell to the left or right. If this happens for the first or last character, these extra pixels will be added to the width of those lines.

This method treats the "\n" character as the only character that causes a line break. If you want to treat "\r\n" or "\r" as line breaks, the correct solution is to use cgul_crlf_file to read in your text because it handles DOS, Mac, and Unix text files allowing you to properly set the standard C new line character for these different formats.

If an error occurs, an exception is thrown. Errors can occur because utf8 has an invalid encoding or because utf8 has a character for which there is no glyph in the bdf font and substitute is not set. Errors can also occur if an index file is being used to load glyphs on demand, and an error occurs during the loading process.

Parameters

[in]	utf8	UTF-8 string
[in]	utf8_length	number of bytes (not characters) in `utf8`
[in]	substitute	whether to substitute missing glyphs with the default
[out]	width	width of `utf8` in pixels
[out]	height	height of `utf8` in pixels

References cgul_bdf__get_utf8_extents().

§ get_utf32_extents()

virtual void cgul_bdf_cxx::get_utf32_extents	(	const cgul_wchar_t *	utf32,
		size_t	utf32_length,
		int	substitute,
		unsigned int *	width,
		unsigned int *	height
	)		const

inlinevirtual

This method returns the width and height in pixels of the smallest rectangle that can contain the image of the text in the UTF-32 string utf32. The width and height are returned in width and height provided they are not set to NULL.

No attempt is made by this method to trim white space. Thus, if white space characters appear at the end of a line, their width will be added to the width that is returned. Likewise, if there are multiple trailing line breaks, the extra ones will add to the height that is returned. If this is not the behavior you want, you need to trim utf8 before passing it into this method.

It is also important to understand that the cgul_bdf_cxx class does not draw text. Instead, it loads fonts and makes the information for each glyph available so that drawing libraries you write can draw text. Providing your drawing library spaces each character using the value returned by cgul_bdf_glyph_cxx::get_dwidth_x() and providing your drawing library spaces each line using the value returned by cgul_bdf_cxx::get_height(), this method will return accurate values for width and height.

It is also important to understand that the width for each line of text is not simply the sum of the "dwidth_x" properties of each character. It is slightly more complicated than this because some glyphs have pixels that intrude on the character cell to the left or right. If this happens for the first or last character, these extra pixels will be added to the width of those lines.

This method treats the "\n" character as the only character that causes a line break. If you want to treat "\r\n" or "\r" as line breaks, the correct solution is to use cgul_crlf_file to read in your text because it handles DOS, Mac, and Unix text files allowing you to properly set the standard C new line character for these different formats.

If an error occurs, an exception is thrown. Errors can occur because utf8 has an invalid encoding or because utf8 has a character for which there is no glyph in the bdf font and substitute is not set. Errors can also occur if an index file is being used to load glyphs on demand, and an error occurs during the loading process.

Parameters

[in]	utf32	UTF-32 string
[in]	utf32_length	number of characters (not bytes) in `utf32`
[in]	substitute	whether to substitute missing glyphs with the default
[out]	width	width of `utf32` in pixels
[out]	height	height of `utf32` in pixels

References cgul_bdf__get_utf32_extents().

§ get_glyph()

virtual cgul_bdf_glyph_cxx* cgul_bdf_cxx::get_glyph	(	cgul_wchar_t	encoding,
		int	substitute
	)		const

inlinevirtual

Get the glyph for a particular code point. The code point is called encoding to match its BDF name. If substitute is set, the default character glyph is returned when no glyph is present for encoding; otherwise, NULL is returned when no glyph is present.

The returned glyph is still owned by the object so the client must not attempt to delete it. The client is free however to make a copy using cgul_bdf_glyph_cxx::copy().

Errors can happen if an index file is being used to load glyphs on demand, and an error occurs during the loading process. If an error occurs, an exception is thrown.

Parameters

[in]	encoding	code point for the glyph that is returned
[in]	substitute	whether to substitute missing glyphs with the default

Returns: glyph

References cgul_bdf__get_glyph().

§ shift_right()

virtual void cgul_bdf_cxx::shift_right ( )

inlinevirtual

Shift each glyph in the object the same minimal number of pixels to the right so that no glyph has a negative x-offset. For efficiency, this method requires that all BDF files be loaded without specifying an index file.

virtual unsigned int cgul_bdf_cxx::get_ascent ( ) const

inlinevirtual

Get the ascent of the font.

Returns: ascent

References cgul_bdf__get_ascent().

§ get_descent()

virtual unsigned int cgul_bdf_cxx::get_descent ( ) const

inlinevirtual

Get the descent of the font.

Returns: descent

References cgul_bdf__get_descent().

§ get_height()

virtual unsigned int cgul_bdf_cxx::get_height ( ) const

inlinevirtual

This method returns the height of the font. This is simply the sum of the ascent and the descent. The height of the font is typically the value used as the spacing between lines.

Returns: height

References cgul_bdf__get_height().

§ get_font_list()

virtual const char* cgul_bdf_cxx::get_font_list ( ) const

inlinevirtual

Get the list of fonts that have been loaded and merged into the object. The font list has the same format as the font list passed into load(). If no font is currently loaded, an empty string is returned. The caller must not attempt to free the pointer returned by this method.

Returns: font list

References cgul_bdf__get_font_list().

§ get_font_name()

virtual const char* cgul_bdf_cxx::get_font_name ( ) const

inlinevirtual

Get the name of the font as given on the FONT line. If no font is currently loaded, NULL is returned. The caller must not attempt to free the pointer returned by this method.

Returns: BDF font name

References cgul_bdf__get_font_name().

§ get_font_size()

virtual unsigned int cgul_bdf_cxx::get_font_size ( ) const

inlinevirtual

Get the size of the font in points.

Returns: font size

References cgul_bdf__get_font_size().

§ get_dpi_x()

virtual unsigned int cgul_bdf_cxx::get_dpi_x ( ) const

inlinevirtual

Get the x-resolution of the font in dots per inch.

Returns: x-resolution of the font in dots per inch

References cgul_bdf__get_dpi_x().

§ get_dpi_y()

virtual unsigned int cgul_bdf_cxx::get_dpi_y ( ) const

inlinevirtual

Get the y-resolution of the font in dots per inch.

Returns: y-resolution of the font in dots per inch

References cgul_bdf__get_dpi_y().

§ get_bb_width()

virtual unsigned int cgul_bdf_cxx::get_bb_width ( ) const

inlinevirtual

Get the width of the font's bounding box.

Returns: width of the font's bounding box

References cgul_bdf__get_bb_width().

§ get_bb_height()

virtual unsigned int cgul_bdf_cxx::get_bb_height ( ) const

inlinevirtual

Get the height of the font's bounding box.

Returns: height of the font's bounding box

References cgul_bdf__get_bb_height().

§ get_bb_x_offset()

virtual int cgul_bdf_cxx::get_bb_x_offset ( ) const

inlinevirtual

Get the x-offset of the lower-left corner of the font's bounding box.

Returns: x-offset of the lower-left corner of the font's bounding box

References cgul_bdf__get_bb_x_offset().

§ get_bb_y_offset()

virtual int cgul_bdf_cxx::get_bb_y_offset ( ) const

inlinevirtual

Get the y-offset of the lower-left corner of the font's bounding box.

Returns: y-offset of the lower-left corner of the font's bounding box

References cgul_bdf__get_bb_y_offset().

§ get_char_count()

virtual unsigned long int cgul_bdf_cxx::get_char_count ( ) const

inlinevirtual

Get the number of characters in the font. This function throws an exception if more than one BDF file is loaded unless all the BDF files are loaded without index files. The reason for this is that it is hard to know how many characters are in a merged BDF font when index files are being used because the actual merging of glyphs is delayed until get_glyph() is called, and even then, the merging only occurs for the requested encoding.

Returns: number of characters in the font

References cgul_bdf__get_char_count().

§ get_obj()

virtual cgul_bdf_t cgul_bdf_cxx::get_obj ( ) const

inlinevirtual

Get the underlying cgul_bdf object.

Returns: underlying object

Referenced by cgul_line_wrapper_cxx::wrap_utf32_at_width(), and cgul_line_wrapper_cxx::wrap_utf8_at_width().

§ take_obj()

virtual cgul_bdf_t cgul_bdf_cxx::take_obj ( )

inlinevirtual

Take the underlying cgul_bdf object. This means the underlying object will not be deleted when the wrapper goes out of scope. Also, because you have taken the underlying object, no other methods should be called on this wrapper's instance. Lastly, after taking the underlying object, it is the caller's responsibility to delete the underlying object by calling cgul_bdf__delete().

Returns: underlying object

§ set_obj()

virtual void cgul_bdf_cxx::set_obj ( cgul_bdf_t rhs )

inlinevirtual

Set the new underlying object to rhs. This causes the old underlying object to be deleted which invalidates any outstanding pointers to or iterators for the old underlying object.

This instance takes ownership of rhs which means rhs will be automatically deleted when the C++ wrapper is deleted. To prevent automatic deletion of rhs, call take_obj() when the C++ wrapper is no longer needed.

Parameters

[in] rhs right-hand side

References cgul_bdf__delete(), and cgul_bdf_cxx().

The documentation for this class was generated from the following file:

cgul_bdf_cxx.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

§ cgul_bdf_cxx()

§ ~cgul_bdf_cxx()

Member Function Documentation

§ load()

§ load_explicit()

§ unload()

§ get_cache_size()

§ set_cache_size()

§ get_utf8_extents()

§ get_utf32_extents()

§ get_glyph()

§ shift_right()

§ pad_left()

§ write()

§ write_file()

§ write_index()

§ write_index_file()

§ get_ascent()

§ get_descent()

§ get_height()

§ get_font_list()

§ get_font_name()

§ get_font_size()

§ get_dpi_x()

§ get_dpi_y()

§ get_bb_width()

§ get_bb_height()

§ get_bb_x_offset()

§ get_bb_y_offset()

§ get_char_count()

§ get_obj()

§ take_obj()

§ set_obj()