gml_TextRender.h

Go to the documentation of this file.
00001 /**
00002  * @file gml_TextRender.h
00003  *
00004  *  Renders texts into bitmaps.
00005  *
00006  *  Uses Tcl/Tk text rendering services, which provides multi-platform, unicode
00007  *  text rendering. The Tcl/Tk interface is entirely hidden in the implementation
00008  *  (ie. it is not visible in this interface file).
00009  *
00010  *  Copyright (c) 2004 CLIPS-IMAG
00011  *
00012  *  See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00013  *  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00014  *
00015  *  February 8, 2004 (FB)
00016  *    Isolated from gmlTcl_TextRender.cc.
00017  *    Switched interface from C++ to C.
00018  *    Removed any reference to tcl/tk in interface.
00019  *
00020  *  Created on Nov. 3, 2003 (FB).
00021  */
00022 
00023 #ifndef __GML_TEXTRENDER__
00024 #define __GML_TEXTRENDER__
00025 
00026 #include "gml/base/gml_Errors.h"
00027 #include "gml/image/gml_Bitmap.h"
00028 #include "gml/image/gml_RGBColor.h"
00029 
00030 
00031 
00032 /**
00033  * gml_TTextRender_Justify --
00034  *
00035  *  Possible ways to align texts to region borders.
00036  */
00037 typedef enum {
00038     gml_cTextRender_JustifyLeft,
00039     gml_cTextRender_JustifyRight,
00040     gml_cTextRender_JustifyCenter,
00041     gml_cTextRender_JustifyFill
00042 } gml_TTextRender_Justify;
00043 
00044 
00045 /*
00046  * Default text rendering options.
00047  */
00048 extern char                     gml_gTextRender_DefaultText[];      /*    = "";                               */
00049 extern char                     gml_gTextRender_DefaultFont[];      /*    = "Helvetica 18";                   */
00050 extern int                      gml_gTextRender_DefaultWrapWidth;   /*    = 120;                              */
00051 extern gml_TTextRender_Justify  gml_gTextRender_DefaultJustify;     /*    = gml_cTextRender_JustifyLeft;      */
00052 extern gml_TRGBColor            gml_gTextRender_DefaultFgColor;     /*    = { 0xffff, 0xffff, 0xffff };       */
00053 extern gml_TRGBColor            gml_gTextRender_DefaultBgColor;     /*    = { 0x0000, 0x0000, 0x0000 };       */
00054 
00055 
00056 
00057 /**
00058  * gml_TTextRender --
00059  *
00060  *  An opaque type to represent the class of text rendering objects.
00061  */
00062 typedef void* gml_TTextRender;
00063 
00064 
00065 struct Tcl_Interp;
00066 
00067 /**
00068  * gml_TextRender_New --
00069  *
00070  *  Create a new gml_TTextRender object and store a pointer to it in <tr>.
00071  *
00072  *    The caller can pass a Tcl_Interp* in <tcl_interp> if it already has
00073  *    an initialized Tcl interpreter with Tk loaded. Otherwise, pass NULL.
00074  */
00075 GML_EXTERN_C
00076 gml_TError gml_TextRender_New (gml_TTextRender*  tr,
00077                                Tcl_Interp*       tcl_interp);
00078 
00079 
00080 
00081 /**
00082  * gml_TextRender_Dispose --
00083  *
00084  *  Free any resources associated with the gml_TTextRender object <tr> and frees the object itself.
00085  */
00086 GML_EXTERN_C
00087 void gml_TextRender_Dispose (gml_TTextRender tr);
00088 
00089 
00090 
00091 /**
00092  * gml_TextRender_Render --
00093  *
00094  *  Render the <text> to the bitmap in <tr>. Any parameter that is <NULL> will conserve its
00095  *    value from the previous call for this <tr> instance, or its default value if it is the first call.
00096  */
00097 GML_EXTERN_C
00098 gml_TError gml_TextRender_Render  (
00099     gml_TTextRender           tr,         /**< the text-rendering object */
00100     char*                     text,       /**< text to be rendered. Must exist during the lifetime of the gml_TTextRender object */
00101     char*                     font,       /**< string that names the font to be used (family and size, e.g. "Helvetica 12").
00102                                                Refer to the Tk "font" command manual page for a description of accepted font names. */
00103     int*                      wrapWidth,  /**< width (pixels) of the bitmap in which to render the text. If 0, the bitmap will
00104                                                be large enough to hold the entire text on one single line. */
00105     gml_TTextRender_Justify*  justify,    /**< how to align the text on the bitmap's border. */
00106     gml_TRGBColor*            fgColor,    /**< color of the foreground (letters of the text). */
00107     gml_TRGBColor*            bgColor     /**< color of the background. */
00108   );
00109 
00110 
00111 
00112 /**
00113  * gml_TextRender_Bitmap --
00114  *
00115  *  Return a reference to the gml_TTextRender bitmap.
00116  */
00117 GML_EXTERN_C
00118 gml_TBitmap* gml_TextRender_Bitmap  (gml_TTextRender tr);
00119 
00120 
00121 
00122 #endif