Class Rubygame::TTF
In: ext/rubygame/rubygame_mixer.c
Parent: Object

TTF provides an interface to SDL_ttf, allowing TrueType Font files to be loaded and used to render text to Surfaces.

The TTF class must be initialized with the setup method before any TTF objects can be created or used.

This class is only usable if Rubygame was compiled with the SDL_ttf library. You may test if this feature is available with the usable? method. If you need more flexibility, you can check the library version that Rubygame was compiled against with the version method.

Methods

ascent   b   b=   bold   bold=   descent   height   i   i=   italic   italic=   line_skip   new   quit   render   render_unicode   render_utf8   setup   size_text   size_unicode   size_utf8   u   u=   underline   underline=  

Public Class methods

Create a new TTF object, which can render text to a Surface with a particular font style and size.

This function takes these arguments:

file:filename of the TrueType font to use. Should be a TTF or FON file.
size:point size (based on 72DPI). (That means the height in pixels from the bottom of the descent to the top of the ascent.)

[Source]

/*
 *  call-seq:
 *    new( file, size )  ->  TTF
 *
 *  Create a new TTF object, which can render text to a Surface with a
 *  particular font style and size.
 *
 *  This function takes these arguments:
 *  file:: filename of the TrueType font to use. Should be a +TTF+ or 
 *         +FON+ file.
 *  size:: point size (based on 72DPI). (That means the height in pixels from
 *         the bottom of the descent to the top of the ascent.)
 */
VALUE rbgm_ttf_new(VALUE class, VALUE vfile, VALUE vsize)
{
        VALUE self;
        TTF_Font *font;
        
        if(!TTF_WasInit())
                rb_raise(eSDLError,"Font module must be initialized before making new font.");
        font = TTF_OpenFont(StringValuePtr(vfile), NUM2INT(vsize));
        if(font == NULL)
                rb_raise(eSDLError,"could not load font: %s",TTF_GetError());

        self = Data_Wrap_Struct(cTTF,0,TTF_CloseFont,font);
        return self;
}

Clean up and quit SDL_ttf, making the TTF class unusable as a result (until it is setup again). This does not need to be called before Rubygame exits, as it will be done automatically.

[Source]

/*
 *  call-seq:
 *    quit  ->  nil
 *
 *  Clean up and quit SDL_ttf, making the TTF class unusable as a result
 *  (until it is setup again). This does not need to be called before Rubygame
 *  exits, as it will be done automatically.
 */
VALUE rbgm_ttf_quit(VALUE module)
{
        if(TTF_WasInit())
                TTF_Quit();
        return Qnil;
}

Attempt to setup the TTF class for use by initializing SDL_ttf. This must be called before the TTF class can be used. Raises SDLError if there is a problem initializing SDL_ttf.

[Source]

/*
 *  call-seq:
 *    setup  ->  nil
 *
 *  Attempt to setup the TTF class for use by initializing SDL_ttf.
 *  This *must* be called before the TTF class can be used.
 *  Raises SDLError if there is a problem initializing SDL_ttf.
 */
VALUE rbgm_ttf_setup(VALUE module)
{
        if(!TTF_WasInit() && TTF_Init()!=0)
                rb_raise(eSDLError,"could not setup TTF class: %s",TTF_GetError());
        return Qnil;
}

Public Instance methods

Return the biggest ascent (baseline to top; in pixels) of all glyphs in the font.

[Source]

/*  call-seq:
 *    ascent  ->  Integer
 *
 *  Return the biggest ascent (baseline to top; in pixels) of all glyphs in 
 *  the font.
 */
VALUE rbgm_ttf_ascent(VALUE self)
{
        TTF_Font *font;
        Data_Get_Struct(self,TTF_Font,font);
        return INT2NUM(TTF_FontAscent(font));
}
b()

Alias for bold

b=(p1)

Alias for bold=

True if bolding is enabled for the font.

[Source]

/*  call-seq:
 *    bold  ->  Bool
 *
 *  True if bolding is enabled for the font.
 */
VALUE rbgm_ttf_getbold(VALUE self)
{
        return RBGM_ttf_get_style(self, TTF_STYLE_BOLD); 
}

Set whether bolding is enabled for this font. Returns the old value.

[Source]

/*  call-seq:
 *    bold = value  ->  Bool
 *
 *  Set whether bolding is enabled for this font. Returns the old value.
 */
VALUE rbgm_ttf_setbold(VALUE self, VALUE bold)
{
        return RBGM_ttf_set_style(self, bold, TTF_STYLE_BOLD); 
}

Return the biggest descent (baseline to bottom; in pixels) of all glyphs in the font.

[Source]

/*  call-seq:
 *    descent  ->  Integer
 *
 *  Return the biggest descent (baseline to bottom; in pixels) of all glyphs in
 *  the font.
 */
VALUE rbgm_ttf_descent(VALUE self)
{
        TTF_Font *font;
        Data_Get_Struct(self,TTF_Font,font);
        return INT2NUM(TTF_FontDescent(font));
}

Return the biggest height (bottom to top; in pixels) of all glyphs in the font.

[Source]

/*  call-seq:
 *    height  ->  Integer
 *
 *  Return the biggest height (bottom to top; in pixels) of all glyphs in the 
 *  font.
 */
VALUE rbgm_ttf_height(VALUE self)
{
        TTF_Font *font;
        Data_Get_Struct(self,TTF_Font,font);
        return INT2NUM(TTF_FontHeight(font));
}
i()

Alias for italic

i=(p1)

Alias for italic=

True if italicizing is enabled for the font.

[Source]

/*  call-seq:
 *    italic  ->  Bool
 *
 *  True if italicizing is enabled for the font.
 */
VALUE rbgm_ttf_getitalic(VALUE self)
{
        return RBGM_ttf_get_style(self, TTF_STYLE_ITALIC); 
}

Set whether italicizing is enabled for this font. Returns the old value.

[Source]

/*  call-seq:
 *    italic = value  ->  Bool
 *
 *  Set whether italicizing is enabled for this font. Returns the old value.
 */
VALUE rbgm_ttf_setitalic(VALUE self,VALUE italic)
{
        return RBGM_ttf_set_style(self, italic, TTF_STYLE_ITALIC); 
}

Return the recommended distance (in pixels) from a point on a line of text to the same point on the line of text below it.

[Source]

/*  call-seq:
 *    lineskip  ->  Integer
 *
 *  Return the recommended distance (in pixels) from a point on a line of text
 *  to the same point on the line of text below it.
 */
VALUE rbgm_ttf_lineskip(VALUE self)
{
        TTF_Font *font;
        Data_Get_Struct(self,TTF_Font,font);
        return INT2NUM(TTF_FontLineSkip(font));
}

Renders a string to a Surface with the font‘s style and the given color(s).

This method takes these arguments:

string:the text string to render
aa:Use anti-aliasing if true. Enabling this makes the text look much nicer (smooth curves), but is much slower.
fg:the color to render the text, in the form [r,g,b]
bg:the color to use as a background for the text. This option can be omitted to have a transparent background.

[Source]

/*  call-seq:
 *    render(string, aa, fg, bg)  ->  Surface
 *
 *  Renders a string to a Surface with the font's style and the given color(s).
 *
 *  This method takes these arguments:
 *  string:: the text string to render
 *  aa::     Use anti-aliasing if true. Enabling this makes the text
 *           look much nicer (smooth curves), but is much slower.
 *  fg::     the color to render the text, in the form [r,g,b]
 *  bg::     the color to use as a background for the text. This option can
 *           be omitted to have a transparent background.
 */
VALUE rbgm_ttf_render(int argc, VALUE *argv, VALUE self)
{
        SDL_Surface *surf;
        TTF_Font *font;
        SDL_Color fore, back; /* foreground and background colors */
        VALUE vstring, vaa, vfg, vbg;

        rb_scan_args(argc, argv, "31", &vstring, &vaa, &vfg, &vbg);

        Data_Get_Struct(self,TTF_Font,font);

        fore = make_sdl_color(vfg);

        if( RTEST(vbg) )
        {
                back = make_sdl_color(vbg);
        }

        if( RTEST(vaa) ) /* anti-aliasing enabled */
        {
                if( RTEST(vbg) ) /* background color provided */
                        surf = TTF_RenderText_Shaded(font,StringValuePtr(vstring),fore,back);
                else /* no background color */
                        surf = TTF_RenderText_Blended(font,StringValuePtr(vstring),fore);
        }
        else /* anti-aliasing not enabled */
        {
                if( RTEST(vbg) ) /* background color provided */      
                {
                        /* remove colorkey, set color index 0 to background color */
                        surf = TTF_RenderText_Solid(font,StringValuePtr(vstring),fore);
                        SDL_SetColors(surf,&back,0,1);
                        SDL_SetColorKey(surf,0,0);
                }
                else /* no background color */
                {
                        surf = TTF_RenderText_Solid(font,StringValuePtr(vstring),fore);
                }
        }

        if(surf==NULL)
                rb_raise(eSDLError,"could not render font object: %s",TTF_GetError());
        return Data_Wrap_Struct(cSurface,0,SDL_FreeSurface,surf);
}

Renders a string to a Surface with the font‘s style and the given color(s).

This method takes these arguments:

string:the text string to render
aa:Use anti-aliasing if true. Enabling this makes the text look much nicer (smooth curves), but is much slower.
fg:the color to render the text, in the form [r,g,b]
bg:the color to use as a background for the text. This option can be omitted to have a transparent background.

[Source]

/*  call-seq:
 *    render_unicode(string, aa, fg, bg)  ->  Surface
 *
 *  Renders a string to a Surface with the font's style and the given color(s).
 *
 *  This method takes these arguments:
 *  string:: the text string to render
 *  aa::     Use anti-aliasing if true. Enabling this makes the text
 *           look much nicer (smooth curves), but is much slower.
 *  fg::     the color to render the text, in the form [r,g,b]
 *  bg::     the color to use as a background for the text. This option can
 *           be omitted to have a transparent background.
 */
VALUE rbgm_ttf_render_unicode(int argc, VALUE *argv, VALUE self)
{
        /* TODO:... ->unicode */
        SDL_Surface *surf;
        TTF_Font *font;
        SDL_Color fore, back; /* foreground and background colors */
        VALUE vstring, vaa, vfg, vbg;
 
        rb_scan_args(argc, argv, "31", &vstring, &vaa, &vfg, &vbg);
 
        Data_Get_Struct(self,TTF_Font,font);

        fore = make_sdl_color(vfg);

        if( RTEST(vbg) )
        {
                back = make_sdl_color(vbg);
        }
 
        if( RTEST(vaa) ) /* anti-aliasing enabled */
        {
                if( RTEST(vbg) ) /* background color provided */
                        surf = TTF_RenderUNICODE_Shaded(font,(Uint16*)StringValuePtr(vstring),fore,back);
                else /* no background color */
                        surf = TTF_RenderUNICODE_Blended(font,(Uint16*)StringValuePtr(vstring),fore);
        }
        else /* anti-aliasing not enabled */
        {
                if( RTEST(vbg) ) /* background color provided */     
                {
                        /* remove colorkey, set color index 0 to background color */
                        surf = TTF_RenderUNICODE_Solid(font,(Uint16*)StringValuePtr(vstring),fore);
                        SDL_SetColors(surf,&back,0,1);
                        SDL_SetColorKey(surf,0,0);
                }
                else /* no background color */
                {
                        surf = TTF_RenderUNICODE_Solid(font,(Uint16*)StringValuePtr(vstring),fore);
                }
        }
 
        if(surf==NULL)
                rb_raise(eSDLError,"could not render font object: %s",TTF_GetError());
        return Data_Wrap_Struct(cSurface,0,SDL_FreeSurface,surf);
}

Renders a string to a Surface with the font‘s style and the given color(s).

This method takes these arguments:

string:the text string to render
aa:Use anti-aliasing if true. Enabling this makes the text look much nicer (smooth curves), but is much slower.
fg:the color to render the text, in the form [r,g,b]
bg:the color to use as a background for the text. This option can be omitted to have a transparent background.

[Source]

/*  call-seq:
 *    render_utf8(string, aa, fg, bg)  ->  Surface
 *
 *  Renders a string to a Surface with the font's style and the given color(s).
 *
 *  This method takes these arguments:
 *  string:: the text string to render
 *  aa::     Use anti-aliasing if true. Enabling this makes the text
 *           look much nicer (smooth curves), but is much slower.
 *  fg::     the color to render the text, in the form [r,g,b]
 *  bg::     the color to use as a background for the text. This option can
 *           be omitted to have a transparent background.
 */
VALUE rbgm_ttf_render_utf8(int argc, VALUE *argv, VALUE self)
{
        SDL_Surface *surf;
        TTF_Font *font;
        SDL_Color fore, back; /* foreground and background colors */
        VALUE vstring, vaa, vfg, vbg;
 
        rb_scan_args(argc, argv, "31", &vstring, &vaa, &vfg, &vbg);
 
        Data_Get_Struct(self,TTF_Font,font);
 
        fore = make_sdl_color(vfg);

        if( RTEST(vbg) )
        {
                back = make_sdl_color(vbg);
        }

        if( RTEST(vaa) ) /* anti-aliasing enabled */
        {
                if( RTEST(vbg) ) /* background color provided */
                        surf = TTF_RenderUTF8_Shaded(font,StringValuePtr(vstring),fore,back);
                else /* no background color */
                        surf = TTF_RenderUTF8_Blended(font,StringValuePtr(vstring),fore);
        }
        else /* anti-aliasing not enabled */
        {
                if( RTEST(vbg) ) /* background color provided */     
                {
                        /* remove colorkey, set color index 0 to background color */
                        surf = TTF_RenderUTF8_Solid(font,StringValuePtr(vstring),fore);
                        SDL_SetColors(surf,&back,0,1);
                        SDL_SetColorKey(surf,0,0);
                }
                else /* no background color */
                {
                        surf = TTF_RenderUTF8_Solid(font,StringValuePtr(vstring),fore);
                }
        }
 
        if(surf==NULL)
                rb_raise(eSDLError,"could not render font object: %s",TTF_GetError());
        return Data_Wrap_Struct(cSurface,0,SDL_FreeSurface,surf);
}

The width and height the text would be if it were rendered, without the overhead of actually rendering it.

[Source]

/*
 * call-seq:
 *   size_text(text) -> [ width, height ]
 * 
 * The width and height the text would be if
 * it were rendered, without the overhead of
 * actually rendering it.
 */
VALUE rbgm_ttf_sizetext(VALUE self, VALUE string)
{
        TTF_Font *font;
        int w;
        int h;
        VALUE result;
        Data_Get_Struct(self, TTF_Font,font);
        result = rb_ary_new();
        
        TTF_SizeText(font,StringValuePtr(string),&w,&h);
        
        rb_ary_push(result, INT2NUM(w));
        rb_ary_push(result, INT2NUM(h));
        
        return result;
}

The width and height the UNICODE encoded text would be if it were rendered, without the overhead of actually rendering it.

[Source]

/*
 * call-seq:
 *   size_unicode(text) -> [ width, height ]
 * 
 * The width and height the UNICODE encoded text would be if
 * it were rendered, without the overhead of
 * actually rendering it.
 */
 
VALUE rbgm_ttf_size_unicode(VALUE self, VALUE string)
{
        TTF_Font *font;
        int w;
        int h;
        VALUE result;
        Data_Get_Struct(self, TTF_Font,font);
        result = rb_ary_new();
        TTF_SizeUNICODE(font,(Uint16*)StringValuePtr(string),&w,&h);
        
        rb_ary_push(result, INT2NUM(w));
        rb_ary_push(result, INT2NUM(h));
        
        return result;
}

The width and height the UTF-8 encoded text would be if it were rendered, without the overhead of actually rendering it.

[Source]

/*
 * call-seq:
 *   size_utf8(text) -> [ width, height ]
 * 
 * The width and height the UTF-8 encoded text would be if
 * it were rendered, without the overhead of
 * actually rendering it.
 */
 
VALUE rbgm_ttf_size_utf8(VALUE self, VALUE string)
{
        TTF_Font *font;
        int w;
        int h;
        VALUE result;
        Data_Get_Struct(self, TTF_Font,font);
        result = rb_ary_new();
        
        TTF_SizeUTF8(font,StringValuePtr(string),&w,&h);
        
        rb_ary_push(result, INT2NUM(w));
        rb_ary_push(result, INT2NUM(h));
        
        return result;
}
u()

Alias for underline

u=(p1)

Alias for underline=

True if underlining is enabled for the font.

[Source]

/*  call-seq:
 *    underline  ->  Bool
 *
 *  True if underlining is enabled for the font.
 */
VALUE rbgm_ttf_getunderline(VALUE self)
{
        return RBGM_ttf_get_style(self, TTF_STYLE_UNDERLINE); 
}

Set whether underlining is enabled for this font. Returns the old value.

[Source]

/*  call-seq:
 *    underline = value  ->  Bool
 *
 *  Set whether underlining is enabled for this font. Returns the old value.
 */
VALUE rbgm_ttf_setunderline(VALUE self, VALUE underline)
{
        return RBGM_ttf_set_style(self, underline, TTF_STYLE_UNDERLINE); 
}

[Validate]