/*  $Id: font.h,v 1.50 2004/01/02 15:42:43 mbn Exp $
**
**  ClanLib Game SDK
**  Copyright (C) 2003  The ClanLib Team
**  For a total list of contributers see the file CREDITS.
**
**  This library is free software; you can redistribute it and/or
**  modify it under the terms of the GNU Lesser General Public
**  License as published by the Free Software Foundation; either
**  version 2.1 of the License, or (at your option) any later version.
**
**  This library is distributed in the hope that it will be useful,
**  but WITHOUT ANY WARRANTY; without even the implied warranty of
**  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
**  Lesser General Public License for more details.
**
**  You should have received a copy of the GNU Lesser General Public
**  License along with this library; if not, write to the Free Software
**  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
**
*/

//! clanDisplay="Fonts"
//! header=display.h

#ifndef header_font
#define header_font

#if _MSC_VER > 1000
#pragma once
#endif

#ifdef _MSC_VER
#pragma warning( disable : 4786)
#endif

#include <string>
#include <utility> //For std::pair

#include "../Core/Math/origin.h"
#include "blend_func.h"
#include "color.h"
#include "../Core/Math/rect.h"
#include "../Core/Math/point.h"
#include "../Core/Math/size.h"
#include "../Core/Resources/resource.h"
#include "../Core/System/lazycopyptr.h"
#include "../Core/System/clonable.h"

class CL_GlyphBuffer;
class CL_Sprite;
class CL_TextStyler;
class CL_Font_Generic;
class CL_GraphicContext;
class CL_ResourceManager;

//: Draws text using system fonts or glyph sprites.
//- !group=Display/Fonts!
//- !header=display.h!
//- <p>A font can be constructed either from a CL_Sprite (aka a bitmap font) or from a system
//- font A bitmap font uses a CL_Sprite as the source for the font
//- glyphs (letters), where each frame frame in the sprite
//- represents one glyph. A string (<i>letter_chars</i>) is then
//- describing which character each glyph corresponds to. If the
//- sprite contains the letters ABCZXY123 in that order, then the
//- string should be "ABCZXY123". A system font uses the underlaying windowing system to create
//- the font glyphs. This means that in Windows you can choose any
//- TTF font, and same applies to X11 if the font server supports
//- it.</p>
//- <p>Newlines always have a width of zero.
//- Other than that, characters for which glyphs weren't specified have the width of a space.</p>
//- <p>Unlike CL_Surface and CL_Sprite, scaling affects the calculation
//- of any bounding rectangles (such as the result returned
//- by draw(), bounding_rect(), or get_size(), or the rectangle calculated internally by
//- draw() for alignment). This is because scaling
//- the CL_Font is effectively just changing the point size of the glyphs,
//- and that affects all sorts of things, such as word wrapping.</p>
//- <p>Word wrapping works automatically whenever you pass CL_Font a destination rectangle
//- or size with non-zero width. CL_Font uses the delims string (which can be changed
//- using the set_delims() method)
//- to determine where divisions between words are. Word wrapping does allow
//- blank characters (characters for which there isn't a glyph supplied)
//- to extend over the border line; this helps wrapped text to remain flush.</p>
class CL_Font
{
//! Construction:
public:
	//: Constructs a font.
	//- <p>If spacelen is unspecified, CL_Font attempts to resolve
	//- it itself. First, it looks to see if you have specified a
	//- space character in letter_chars: if you have, it uses that
	//- glyph's width as the space width (as well as using it
	//- to actually draw the space). If it does not find a space
	//- glyph, then it will look at every glyph's width and make
	//- the space width the average of that.</p>
	//param resource_id: Font resource name.
	//param manager: Resource manager used to load font.
	//param glyphs: CL_Sprite containing the letters of a bitmap font.
	//param letters: String mapping each frame of the bitmap font sprite to letters.
	//param spacelen: Width in pixels of the space glyph. If -1, uses the average of all glyph widths.
	//param monospace: If true, treats all glyphs as being the same width.
	//param font_name: System font name (eg. "Arial").
	//param letter_chars: The characters to include in the font (if a sprite font, must be in frame order).
	//param height: Height of font in pixels.
	//param width: Width of font in pixels. If 0, uses best fitting width for the specified height.
	//param bold: If true, will use bold font.
	//param italic: If true, will use italic font.
	//param underline: If true, will use underlined font.
	//param strikeout: If true, will use striked out font.
	CL_Font();
	
	CL_Font(const CL_Font &copy);
	
	CL_Font(
		const std::string &resource_id,
		CL_ResourceManager *manager);
	
	CL_Font(
		const CL_Sprite &glyphs,
		const std::string &letters,
		int spacelen = -1,
		bool monospace = false);
	
	CL_Font(
		const std::string &font_name,
		const std::string &letters,
		int height,
		int width = 0,
		bool bold = false,
		bool italic = false,
		bool underline = false,
		bool strikeout = false);
	
	CL_Font(
		const std::string &font_name,
		int height,
		int width = 0,
		bool bold = false,
		bool italic = false,
		bool underline = false,
		bool strikeout = false);
	
	virtual ~CL_Font();

//! Attributes:
public:
	//: Returns delimiters string.
	//- <p> This string contains characters (other than newline) that divide words apart.
	//- Do not include newline in this string, it's an implicit delimiter.</p>
	std::string get_delims() const;
	
	//: Returns width offset.
	//- <p> The width offset can be used to kern glyphs together or spread them apart. </p> 
	int get_width_offset() const;
	
	//: Returns height offset.
	//- <p> The height offset can be used to create space between lines, or to merge them together. </p> 
	int get_height_offset() const;
	
	//: Returns current scale.
	//- <p> 1.0f is normal scale, 2.0f is twice the size, etc. </p>
	void get_scale(float &x, float &y) const;

	//: Returns current alpha.
	//- <p> 0.0f is full transparency, and 1.0f is full visibility. </p>
	float get_alpha() const;

	//: Returns current color.
	//- <p> Alpha 0.0f is full transparency, and 1.0f is full visibility (solid). </p>
	void get_color(float &red, float &green, float &blue, float &alpha) const;
	CL_Color get_color() const {float r,g,b,a; get_color(r,g,b,a); return CL_Color(int(r*255.0f),int(g*255.0f),int(b*255.0f),int(a*255.0f));}

	//: Returns blending functions.
	void get_blend_func(CL_BlendFunc &src, CL_BlendFunc &dest) const;
	
	//: Returns glyph rotation hotspot.
	//- <p> This is for the optional angle parameter to draw_glyphs(). </p>
	void get_glyph_rot_hotspot(CL_Origin &origin, int &x, int &y) const;
	
	//: Returns translation hotspot.
	void get_alignment(CL_Origin &origin, int &x, int &y) const;
	
	//: Returns the drawn height of the entire font or a string.
	//return: The height in pixels.
	//param str: String to get the height of.
	//param start: A starting iterator, inclusive.
	//param end: An ending iterator, exclusive.
	//param max_size: Same effect as the size of the dest rectangle passed to draw(), for word wrapping and height truncating.
	//- <p> The height of the entire font is the height of the tallest glyph in the font; this
	//- is what is returned if you specify no arguments. The point of having the height functions
	//- accept a string is to compensate for strings spanning multiple lines. Generally, get_height(" ") will return zero, since usually 
	//- the space glyph isn't given in the font, and so it has a height and width of zero. </p>
	int get_height() const;
	
	int get_height(
		const std::string &str,
		CL_Size max_size = CL_Size(0,0)) const
		{return get_size(str, max_size).height;}
	
	int get_height(
		std::string::const_iterator start,
		std::string::const_iterator end,
		CL_Size max_size = CL_Size(0,0)) const
		{return get_size(start, end, max_size).height;}
	
	//: Returns the drawn width of a character or string.
	//return: The width in pixels.
	//param letter: Character to get the width of.