7. Other classes

7.1 mglParse class

Class for parsing and executing MGL script. This class is defined in #include <mgl/mgl_parse.h>.

Class mglParse is the interpreter for MGL scripts (see section MGL language). The main function of mglParse class is Parse(). Exactly this function parses and executes the script string-by-string. Also there are two subservient functions for the finding and creation of a variable. These functions can be useful for displaying values of variables (arrays) in some external program (in window, for example). The variable DataList contains full list of variables in script. Flag AllowSetSize allows one to prevent changing the size of the picture inside the script (forbids the MGL command setsize).

Note an important feature – if user defines function func in variable then it will be called before the destroying of this variable (see section mglVar class).

Method on mglParse (C++, Python): mglParse (bool setsize=false)

C function: HMPR mgl_create_parser ()

Constructor initializes all values with zero and set AllowSetSize value.

Method on mglParse (C++, Python): ~mglParse ()

C function: void mgl_delete_parser (HMPR p)

Destructor delete parser

Method on mglParse (C++, Python): int Parse (mglGraph *gr, const char *str, long pos=0)

Method on mglParse (C++): int Parse (mglGraph *gr, const wchar_t *str, long pos=0)

C function: int mgl_parse (HMGL gr, HMPR p, const char *str, int pos)

C function: int mgl_parsew (HMGL gr, HMPR p, const wchar_t *str, int pos)

Main function in the class. It parses the string str and executes it by using gr as a graphics plotter. Returns the value depending on an error presence in the string str: 0 – no error, 1 – wrong command argument(s), 2 – unknown command, 3 – string is too long. Optional argument pos allows to save the string position in the document (or file) for using for|next command.

Method on mglParse (C++): int Export (wchar_t cpp_out[1024], mglGraph *gr, const wchar_t *str)

Function parses the string str, executes it by using gr as a graphics plotter and exports it to C++ code. Returns the value depending on an error presence in the string str: 0 – no error, 1 – wrong command argument(s), 2 – unknown command, 3 – string is too long. Output C++ text will be placed in out variable. If string str have options (defined after ’;’ symbol) then the corresponding C++ texts are placed in variables op1, op2.

Method on mglParse (C++): void Execute (mglGraph *gr, FILE *fp, bool print=false)

Function parse and execute line-by-line MGL script in file fp. If print=true then all warnings and information will be printed in stdout. Also this function support the for|next MGL commands.

Method on mglParse (C++): void Execute (mglGraph *gr, int num, const wchar_t **text, void (* error )(int line, int kind)=NULL)

Function parse and execute line-by-line MGL script in array text. If error is not NULL then this function will be called for all warnings, information and other messages. Also this function support the for|next MGL commands.

Method on mglParse (C++, Python): void Execute (mglGraph *gr, const char *text, void (* error )(int line, int kind)=NULL)

Method on mglParse (C++): void Execute (mglGraph *gr, const wchar_t *text, void (* error )(int line, int kind)=NULL)

C function: void mgl_parse_text (HMGL gr, HMPR p, const char *text)

C function: void mgl_parsew_text (HMGL gr, HMPR p, const wchar_t *text)

Function parse and execute line-by-line MGL script in string text. Lines are separated by ‘\n’ symbol as usual. If error is not NULL then this function will be called for all warnings, information and other messages. Also this function support the for|next MGL commands.

Method on mglParse (C++, Python): bool AddParam (int n, const char *str, bool isstr=true)

Method on mglParse (C++): bool AddParam (int n, const wchar_t *str, bool isstr=true)

C function: void mgl_add_param (HMPR p, int id, const char *val)

C function: void mgl_add_paramw (HMPR p, int id, const wchar_t *val)

Function set the value of n-th parameter as string str (n=0, 1 ... 9). It return true for success.

Method on mglParse (C++, Python): mglVar * FindVar (const char *name)

Method on mglParse (C++): mglVar * FindVar (const wchar_t *name)

C function: const HMDT mgl_find_var (HMPR p, const char *name)

Function returns the pointer to variable with name name or zero if variable is absent. Use this function to put external data array to the script or get the data from the script.

Method on mglParse (C++, Python): mglVar * AddVar (const char *name)

Method on mglParse (C++): mglVar * AddVar (const wchar_t *name)

C function: const HMDT mgl_add_var (HMPR p, const char *name)

Function returns the pointer to variable with name name. If variable is absent then new variable is created with name name. Use this function to put external data array to the script or get the data from the script.

Method on mglParse (C++): void DeleteVar (mglVar *v)

Method on mglParse (C++): void DeleteVar (const char *name)

Method on mglParse (C++): void DeleteVar (const wchar_t *name)

Function delete the variable specified by its name or by its pointer.

Method on mglParse (C++, Python): inline void RestoreOnce ()

C function: void mgl_restore_once (HMPR p)

Restore Once flag.

Method on mglParse (Python): void AllowSetSize (bool a)

C function: void mgl_parser_allow_setsize (HMPR p, int a)

Allow to parse ’setsize’ command or not.

Method on mglParse (C++): void AddCommand (mglCommand *cmd, int num=0)

Add num commands cmd to the defined MGL commands list. Parameter cmd is array of mglCommand structures. If parameter num=0 then it will be determined automatically. At this, array cmd must have last element with name=L""

Option of mglParse: mglVar * DataList

List of variables defined in script.

Option of mglParse: bool AllowSetSize

Flag which allows/forbids the command setsize in scripts.

Option of mglParse: bool Stop

Flag which interrupt script execution.

Option of mglParse: mglCommand * Cmd

Table (array) of recognizable MGL commands (can be changed by user). Items in the table MUST be sorted by name field !!! Last items must have empty name (i.e. L"").

Option of mglParse: wchar_t * op1

These strings contain command options and should be placed before the command. These variables are used for MGL->C++ (or other language) conversion.

Option of mglParse: wchar_t * op2

These strings contain command options and should be placed after the command. These variables are used for MGL->C++ (or other language) conversion.

7.2 mglFormula class

Class for evaluating of formula specified by the string. This class is defined in #include <mgl/mgl_eval.h>.

It is the fast variant of formula evaluation. At creation it will be recognized and compiled to tree-like internal code. At evaluation stage only fast calculations are performed. There is no difference between lower or upper case in formulas. If argument value lie outside the range of function definition then function returns NaN. See section Textual formulas.

Method on mglFormula: mglFormula (const char *str)

Parses the formula str and creates formula-tree. Constructor recursively parses the formula and creates a tree-like structure containing functions and operators for fast further evaluating by Calc() or CalcD() functions.

Method on mglFormula: float Calc (float x, float y=0, float z=0, float u=0)

Evaluates the formula for 'x','r'=x, 'y','n'=y, 'z','t'=z, 'a','u'=u. Error code (if one) can be obtained from function GetError().

Method on mglFormula: float Calc (float x, float y, float z, float u, float v, float w)

Evaluates the formula for 'x'=x, 'y'=y, 'z'=z, 'u'=u, 'v'=v, 'w'=w. Error code (if one) can be obtained from function GetError().

Method on mglFormula: float Calc (float var['z'-'a'+1])

Evaluates the formula for variables in array var[’z’-’a’]. Error code (if one) can be obtained from function GetError().

Method on mglFormula: float CalcD (float var['z'-'a'+1], char diff)

Evaluates the formula derivation respect to diff for variables in array var[’z’-’a’]. Error code (if one) can be obtained from function GetError().

Method on mglFormula: int GetError ()

Returns error code: 0 means no error; ERR_LOG means error in logarithm or power functions; ERR_ARC means error in inverse functions (like asin); ERR_SQRT means error in sqrt function.

7.3 mglFont class

Class for working with font: load, get metrics, parse and draw strings. This class is defined in #include <mgl/mgl_font.h>.

The class is based on loading and drawing of vector Hershey font. There are two styles of specifying of the font type and aligning: by integer parameters or by string.

The string can be any combination of characters: ‘rbiLCRwou’. The font types are: ‘r’ – roman font, ‘i’ – italic style, ‘b’ – bold style. By default roman font (that is ‘’ or ‘r’) is used. The align types are: ‘L’ – align left (default), ‘C’ – align center, ‘R’ – align right. Additional font effects are: ‘w’ – wire, ‘o’ – over-lined, ‘u’ – underlined. Parsing of the string to special (TeX-like) commands will be done if variable parse is true (it’s default). See also see section Font styles.

The over way of font and alignment setting is the using of the integer constant. Integer font Id can be one of predefined constants: MGL_FONT_ITAL, MGL_FONT_BOLD, MGL_FONT_BOLD_ITAL = MGL_FONT_ITAL+MGL_FONT_BOLD. Default font is MGL_FONT_ROMAN. Also there are flags MGL_FONT_ULINE, MGL_FONT_OLINE, MGL_FONT_WIRE for additional font effects. Align parameter controls the text alignment: 0 – align left, 1 – align center, 2 – align right.

Method on mglFont: mglFont (const char *name=MGL_DEF_FONT_NAME, const char *path=NULL)

Initialize the font and load data from file name (default name is "STIX" for Linux and MacOS) or if name=NULL limited data from memory (default for Windows).

Method on mglFont: bool Load (const char * base, const char *path=NULL)

Load font from file path/base into the memory. The font may contain 4 files: base.vfm, base_b.vfm, base_i.vfm, base_bi.vfm. Appendix contain detailed description of font format.

Method on mglFont: void Restore ()

Restore default font.

Method on mglFont: void (mglFont * fnt)

Copy data from other font instance.

Method on mglFont: void Clear ()

Clear memory by deleting the loaded font.

Method on mglFont: inline unsigned GetNumGlyph ()

Return the number of glyphs in the font.

Method on mglFont: inline bool Ready ()

Return true if font is loaded and ready for use.

Method on mglFont: float Height (int font)

Gets height of text for font specified by integer constant.

Method on mglFont: float Puts (const char *str, int font=0, int align=0)

Prints 8-bit text string for font specified by integer constant.

Method on mglFont: float Width (const char *str, int font=0)

Gets width of 8-bit text string for font specified by integer constant.

Method on mglFont: float Puts (const wchar_t *str, int font=0, int align=0)

Prints Unicode text string for font specified by integer constant.

Method on mglFont: float Width (const wchar_t *str, int font=0)

Gets width of Unicode text string for font specified by integer constant.

Method on mglFont: float Height (const char *how)

Gets height of text for font specified by string.

Method on mglFont: float Puts (const char *str, const char *how)

Prints 8-bit text string for font specified by string.

Method on mglFont: float Width (const char *str, const char *how)

Gets width of 8-bit text string for font specified by string.

Method on mglFont: float Puts (const wchar_t *str, const char *how)

Prints Unicode text string for font specified by string.

Method on mglFont: float Width (const wchar_t *str, const char *how)

Gets width of Unicode text string for font specified by string.

Parameter of mglFont: mglGraph * gr

Instance of mglGraph class which is used for character drawing.

Parameter of mglFont: bool parse

Flag for switching on/off the parsing of TeX commands. Default value is true.

7.3.1 Format of font files

Starting from v.1.6 the MathGL library uses new font files. The font is defined in 4 files with suffixes ‘*.vfm’, ‘*_b.vfm’, ‘*_i.vfm’, ‘*_bi.vfm’. These files are text files containing the data for roman font, bold font, italic font and bold italic font. The files (or some symbols in the files) for bold, italic or bold italic fonts can be absent. In this case the roman glyph will be used for them. By analogy, if the bold italic font is absent but the bold font is present then bold glyph will be used for bold italic. You may create these font files by yourself from *.ttf, *.otf files with the help of program font_tools. This program can be found at MathGL home site.

The format of font files (*.vfm – vector font for MathGL) is the following.

1. First string contains human readable comment and is always ignored.
2. Second string contains 3 numbers, delimited by space or tabulation. The order of numbers is the following: numg – the number of glyphs in the file (integer), fact – the factor for glyph sizing (float), size – the size of buffer for glyph description (integer).
3. After it numg-th strings with glyphs description are placed. Each string contains 6 positive numbers, delimited by space of tabulation. The order of numbers is the following: Unicode glyph ID, glyph width, number of lines in glyph, position of lines coordinates in the buffer (length is 2*number of lines), number of triangles in glyph, position of triangles coordinates in the buffer (length is 6*number of triangles).
4. The end of file contains the buffer with point coordinates at lines or triangles vertexes. The size of buffer (the number of integer) is size.

Each font file can be compressed by gzip.

Note: the closing contour line is done automatically (so the last segment may be absent). For starting new contour use a point with coordinates {0x3fff, 0x3fff}.

7.4 mglColor class

Structure for working with colors. This structure is defined in #include <mgl/mgl.h>.

There are two ways to set the color in MathGL. First one is using of float values of red, green and blue channels for precise color definition. The second way is the using of character id. There are a set of characters specifying frequently used colors. Normally capital letter gives more dark color than lowercase one. See section Line styles.

Parameter of mglVar: float r, g, b

Reg, green and blue component of color.

Method on mglColor: mglColor (float R, float G, float B)

Constructor sets the color by float values of Red, Green and Blue channels.

Method on mglColor: mglColor (char c='k')

Constructor sets the color from character id. The black color is used by default.

Method on mglColor: void Set (float R, float G, float B)

Sets color from values of Red, Green and Blue channels. This values should be in interval [0,1].

Method on mglColor: void Set (mglColor c, float bright=1)

Sets color as “lighted” version of color c.

Method on mglColor: void Set (char p)

Sets color from symbolic id.

Method on mglColor: bool Valid ()

Checks correctness of the color.

Method on mglColor: float Norm ()

Gets maximal of spectral component.

Method on mglColor: bool operator== (const mglColor &c)

Compare with another color

Library Function: inline mglColor operator+ (const mglColor &a, const mglColor &b)

Adds colors by its RGB values.

Library Function: inline mglColor operator- (const mglColor &a, const mglColor &b)

Subtracts colors by its RGB values.

Library Function: inline mglColor operator* (const mglColor &a, float b)

Multiplies color by number.

Library Function: inline mglColor operator* (float a, const mglColor &b)

Multiplies color by number.

Library Function: inline mglColor operator/ (const mglColor &a, float b)

Divide color by number.

Library Function: inline mglColor operator! (const mglColor &a)

Return inverted color.

7.5 mglPoint class

Structure describes point in space. This structure is defined in #include <mgl/mgl.h>

Parameter of mglVar: float x, y, z

Point coordinates. By default all values are zero.

Library Function: inline mglPoint operator+ (const mglPoint &a, const mglPoint &b)

Point of summation (summation of vectors).

Library Function: inline mglPoint operator- (const mglPoint &a, const mglPoint &b)

Point of difference (difference of vectors).

Library Function: inline mglPoint operator* (float a, const mglPoint &b)

Multiplies (scale) points by number.

Library Function: inline mglPoint operator* (const mglPoint &a, float b)

Multiplies (scale) points by number.

Library Function: inline mglPoint operator/ (const mglPoint &a, float b)

Multiplies (scale) points by number 1/b.

Library Function: inline float operator- (const mglPoint &a, const mglPoint &b)

Scalar product of vectors.

Library Function: inline mglPoint operator^ (const mglPoint &a, const mglPoint &b)

Cross-product of vectors.

Library Function: inline mglPoint operator& (const mglPoint &a, const mglPoint &b)

The part of a which is perpendicular to vector b.

Library Function: inline mglPoint operator| (const mglPoint &a, const mglPoint &b)

The part of a which is parallel to vector b.

Library Function: inline mglPoint operator! (const mglPoint &a)

Return vector perpendicular to vector a.

Library Function: inline bool Norm (const mglPoint &a)

Return the norm |a|^2 of vector a.

Library Function: inline bool operator== (const mglPoint &a, const mglPoint &b)

Return true if points are the same.

Library Function: inline bool operator!= (const mglPoint &a, const mglPoint &b)

Return true if points are different.

7.6 mglVar class

Structure describes variable of type mglData and its name in MGL script. This structure is used by mglParse and is defined in #include <mgl/mgl_parse.h>.

Parameter of mglVar: mglData d

Data itself

Parameter of mglVar: wchar_t s[256]

Data name

Parameter of mglVar: void * o

Pointer to external object for function func.

Parameter of mglVar: mglVar * next

Pointer to next instance in list

Parameter of mglVar: mglVar * prev

Pointer to prev instance in list

Parameter of mglVar: bool temp

Flag for temporar variable. Temporal variables will be destroyed after script execution.

Parameter of mglVar: void (* func )(void *)

Callback function for destroying non-temporal variable.

Method on mglVar: void MoveAfter (mglVar *var)

Move variable after var and copy func from var (if func is not 0)

7.7 mglCommand class

Structure describes MGL command, its name, short description, executable and export functions. The structure is used by mglParse and is defined in #include <mgl/mgl_parse.h>.

Parameter of mglCommand: const wchar_t * name

Name of command.

Parameter of mglCommand: const wchar_t * desc

Short command description (can be NULL).

Parameter of mglCommand: const wchar_t * form

Format of command arguments (can be NULL).

Parameter of mglCommand: int (* exec )(mglGraph *gr, long n, mglArg *a, int k[10])const wchar_t *

Function for executing (plotting) the command using grapher gr and having n-th arguments a. Function must return 0 if all is OK; or 1 if arguments are wrong.

Parameter of mglCommand: void (* save )(wchar_t out[1024], long n, mglArg *a, int k[10])const wchar_t *

Function for exporting in C++ (can be NULL).

7.8 mglArg class

Structure describes arguments of functions in the stucture mglCommand. It is defined in #include <mgl/mgl_parse.h>.

Parameter of mglArg: int type

Type of argument: 0-data, 1-string, 2-number.

Parameter of mglArg: mglData * d

Pointer to data (used if type=0).

Parameter of mglArg: wchar_t w[2048]

String with parameters (used if type=1 or if type=0 as variable name).

Parameter of mglArg: char s[2048]

String with parameters (used if type=1).

Parameter of mglArg: float v

Numerical value (used if type==2)

This document was generated by Alexey Balakin on May 2, 2013 using texi2html 1.82.