---

Misc Utility

This group includes general purpose functions. More...

Functions
int	MGetKeyboardState (void)
	Returns the status of the keyboard modifier keys (Alt, Control, Shift).
void	MBeep (void)
	This function emits a beep sound using the system specific's default sound.
const char *	MGetSysDir (void)
	Returns a pointer to the MGUISYS directory.
const char *	MGetApplicationName (void)
void	MEnableCharBrowser (void)
	This function enables the running application to open the Character Browser dialog via <Ctrl+Shift+F10> for special input in Edit objects.
int	MPaletteMode (void)
	This function returns True if the calling program runs in 16 or 256 colors video mode.
int	MGetScreenWidth (void)
	Returns the screen width in pixel units.
int	MGetScreenHeight (void)
	Returns the screen height in pixel units.
int	MGetNPlanes (void)
	Returns the number of color planes in the display.
long	MGetNColors (void)
	Returns the number of colors in the display.
int	MTextCharX (const char *text, MTFont font, int x)
	Returns the x position (in pixels) of the character at a given position in a string array.
int	MTextHeight (const char *text, MTFont font)
	Returns the height of the string 'text' using the font 'font'.
int	MCharHeight (unsigned int ch, MTFont font)
	Returns the height of the character 'ch' using the font 'font'.
int	MTextWidth (const char *text, MTFont font)
	Returns the width of the null terminated string 'text' using the font 'font'.
int	MTextNWidth (const char *text, MTFont font, int len)
	Returns the width of the first 'n' characters in the string 'text' using the font 'font'.
int	MCharWidth (unsigned int ch, MTFont font)
	Returns the width of the character 'ch' using the font 'font'.
int	MMessageDialog (const char *title, const char *msg, const char *btn1, const char *btn2,...)
	Displays a modal message window.
int	MInputPrompt (const char *title, const char *msg, char *text, int len, const char *ok_btn, const char *canc_btn)
	Displays a modal prompt window for a single line text input.
char *	MTextPrompt (const char *title, const char *msg, const char *text, int w, int h, const char *ok_btn, const char *canc_btn)
	Displays a modal prompt window for a multi line text input.
int	MFileSelection (const char *title, const char *filter, char *fname, char *dname, int change_cur_dir)
	Displays a modal prompt window for a file name selection.
int	MFileBrowse (const char *title, const char *filter, char *fname, char *dname, int change_cur_dir)
	Displays a modal prompt window for a file name selection.
const char *	MGetCurrentDirectory (void)
	Returns the program's current directory.
void	MSetInputPromptRGB (int r, int g, int b)
	Sets the R-G-B components of the background color of the InputPrompt dialog.
void	MSetMessageDialogRGB (int r, int g, int b)
	Sets the R-G-B components of the background color of the Message dialog.
void	MSetFileSelectionRGB (int r, int g, int b)
	Sets the R-G-B components of the background color of the FileSelection dialog.
void	MSetInputPromptFgRGB (int r, int g, int b)
	Sets the R-G-B components of the foreground color of the InputPrompt dialog.
void	MSetMessageDialogFgRGB (int r, int g, int b)
	Sets the R-G-B components of the foreground color of the Message dialog.
void	MSetInputPromptFonts (MTFont text_font, MTFont edit_font, MTFont buttons_font)
	Sets the font for the message text, edit field and buttons in the InputPrompt and TextPrompt dialogs.
void	MSetMessageDialogFonts (MTFont text_font, MTFont buttons_font)
	Sets the message text and buttons' fonts in the Message dialog.
void	MGetInputPromptRGB (int *pr, int *pg, int *pb)
	Retrieves the R-G-B components of the background color used in the InputPrompt dialog.
void	MGetMessageDialogRGB (int *pr, int *pg, int *pb)
	Retrieves the R-G-B components of the background color used in the Message dialog.
void	MGetFileSelectionRGB (int *pr, int *pg, int *pb)
	Retrieves the R-G-B components of the background color used in the FileSelection dialog.
void	MGetMessageDialogFgRGB (int *pr, int *pg, int *pb)
	Retrieves the R-G-B components of the foreground color used in the Message dialog.
void	MGetInputPromptFgRGB (int *pr, int *pg, int *pb)
	Retrieves the R-G-B components of the foreground color used in the InputPrompt dialog.
void	MGetMessageDialogFonts (MTFont *text_font, MTFont *buttons_font)
	Retrieves the fonts used in the Message dialog for message text and buttons.
void	MGetInputPromptFonts (MTFont *text_font, MTFont *edit_font, MTFont *buttons_font)
	Retrieves the fonts used in the InputPrompt and TextPrompt dialogs for message text, edit and buttons.
void	MSetFileSelectionTextStrings (const char *file_list, const char *dir_list, const char *drive_list, const char *filter, const char *filename, const char *curr_dir, const char *ok_button, const char *close_button)
	Changes the text displayed in the labels and buttons in the FileSelection dialog.
int	MSpoolFile (const char *fname)
	Prints an ascii text file in the system printer.
int	MSpoolTempFile (const char *fname)
	Prints a temporary ascii text file in the system printer.
void	MWriteCARD8 (FILE *fp, CARD8 val)
void	MWriteCARD16 (FILE *fp, CARD16 val)
void	MWriteCARD32 (FILE *fp, CARD32 val)
CARD8	MReadCARD8 (FILE *fp)
CARD16	MReadCARD16 (FILE *fp)
CARD32	MReadCARD32 (FILE *fp)

---

Detailed Description

This group includes general purpose functions.

---

Function Documentation

void MBeep (  void    )

This function emits a beep sound using the system specific's default sound. Under Windows it calls 'MessageBeep(MB_ICONASTERISK)'. Under Unix X-Window it calls 'XBell(display, 100)'. Under any other console systems (DOS and Linux) it puts the bell character to the console.

int MCharHeight (  unsigned int    ch, MTFont    font )

Returns the height of the character 'ch' using the font 'font'. See also: MTextWidth, MTextNWidth, MTextHeight, MCharWidth

int MCharWidth (  unsigned int    ch, MTFont    font )

Returns the width of the character 'ch' using the font 'font'. See also: MTextWidth, MCharHeight

void MEnableCharBrowser (  void    )

This function enables the running application to open the Character Browser dialog via <Ctrl+Shift+F10> for special input in Edit objects.

int MFileBrowse (  const char *    title, const char *    filter, char *    fname, char *    dname, int    change_cur_dir )

Displays a modal prompt window for a file name selection. It allows the program to block its flow, waiting for the user input a file name. Uses the MTree object to display the directory structure in a graphic form. Parameters: title  The text displayed in the window's title bar. filter  Specifies the initial file filter value (may be defaulted to the empty string). On return it contains the last used value. fname  Specifies the initial file name (may be defaulted to the empty string). On return it contains the selected file name. dname  Specifies the initial directory name (may be defaulted to the empty string). On return it contains the selected directory name (including drive letter under DOS/Windows). change_cur_dir  Specifies whether the program's current directory should be changed according to the user's selection or not. Returns: The boolean False value (integer 0) is returned if the users selects the Cancel button or closes the dialog without choosing a file name, the True value (integer 1) is returned otherwise. See also: MFileSelection

int MFileSelection (  const char *    title, const char *    filter, char *    fname, char *    dname, int    change_cur_dir )

Displays a modal prompt window for a file name selection. It allows the program to block its flow, waiting for the user input a file name. Parameters: title  The text displayed in the window's title bar. filter  Specifies the initial file filter value (may be defaulted to the empty string). On return it contains the last used value. fname  Specifies the initial file name (may be defaulted to the empty string). On return it contains the selected file name. dname  Specifies the initial directory name (may be defaulted to the empty string). On return it contains the selected directory name (including drive letter under DOS/Windows). change_cur_dir  Specifies whether the program's current directory should be changed according to the user's selection or not. Returns: The boolean False value (integer 0) is returned if the users selects the Cancel button or closes the dialog without choosing a file name, the True value (integer 1) is returned otherwise. See also: MFileBrowse

const char* MGetApplicationName (  void    )

const char* MGetCurrentDirectory (  void    )

Returns the program's current directory. An ending directory separator character is included in the returned path ('/' under Unix, '\' under DOS/Windows). The drive letter and the ':' characters are also included at the beginning of the path under DOS/Windows. Returns: The returned value points to a static buffer that is used by this function on successive calls. Don't free it!

void MGetFileSelectionRGB (  int *    pr, int *    pg, int *    pb )

Retrieves the R-G-B components of the background color used in the FileSelection dialog. Parameters: pr  Points to the integer variable where to store the return red value in. pg  Points to the integer variable where to store the return green value in. pb  Points to the integer variable where to store the return blue value in. See also: MSetFileSelectionRGB, MFileSelection

void MGetInputPromptFgRGB (  int *    pr, int *    pg, int *    pb )

Retrieves the R-G-B components of the foreground color used in the InputPrompt dialog. Parameters: pr  Points to the integer variable where to store the return red value in. pg  Points to the integer variable where to store the return green value in. pb  Points to the integer variable where to store the return blue value in. See also: MSetInputPromptFgRGB, MInputPrompt

void MGetInputPromptFonts (  MTFont *    text_font, MTFont *    edit_font, MTFont *    buttons_font )

Retrieves the fonts used in the InputPrompt and TextPrompt dialogs for message text, edit and buttons. Parameters: text_font  Points to the variable where to store the font used for the message text. edit_font  Points to the variable where to store the font used for the edit text. buttons_font  Points to the variable where to store the font used for the buttons' text. See also: MSetInputPromptFonts, MInputPrompt, MTextPrompt

void MGetInputPromptRGB (  int *    pr, int *    pg, int *    pb )

Retrieves the R-G-B components of the background color used in the InputPrompt dialog. Parameters: pr  Points to the integer variable where to store the return red value in. pg  Points to the integer variable where to store the return green value in. pb  Points to the integer variable where to store the return blue value in. See also: MSetInputPromptRGB, MInputPrompt

int MGetKeyboardState (  void    )

Returns the status of the keyboard modifier keys (Alt, Control, Shift). The returned integer contains a bit mask of the currently pressed modifier keys. You can test each key by bitwise and-ing the returned value with the following macros (defined in mguidef.h): AltMask, ControlMask, ShiftMask.

void MGetMessageDialogFgRGB (  int *    pr, int *    pg, int *    pb )

Retrieves the R-G-B components of the foreground color used in the Message dialog. Parameters: pr  Points to the integer variable where to store the return red value in. pg  Points to the integer variable where to store the return green value in. pb  Points to the integer variable where to store the return blue value in. See also: MSetMessageDialogFgRGB, MMessageDialog

void MGetMessageDialogFonts (  MTFont *    text_font, MTFont *    buttons_font )

Retrieves the fonts used in the Message dialog for message text and buttons. Parameters: text_font  Points to the variable where to store the font used for the message text. buttons_font  Points to the variable where to store the font used for the buttons' text. See also: MSetMessageDialogFonts, MMessageDialog

void MGetMessageDialogRGB (  int *    pr, int *    pg, int *    pb )

Retrieves the R-G-B components of the background color used in the Message dialog. Parameters: pr  Points to the integer variable where to store the return red value in. pg  Points to the integer variable where to store the return green value in. pb  Points to the integer variable where to store the return blue value in. See also: MSetMessageDialogRGB, MMessageDialog

long MGetNColors (  void    )

Returns the number of colors in the display. Possible values are: 16, 256, 32K, 64K and 16M. They correspond to: 4, 8, 15, 16 and 24 planes.

int MGetNPlanes (  void    )

Returns the number of color planes in the display. Possible values are: 4, 8, 15, 16 and 24. They correspond to: 16, 256, 32K, 64K and 16M colors.

int MGetScreenHeight (  void    )

Returns the screen height in pixel units.

int MGetScreenWidth (  void    )

Returns the screen width in pixel units.

const char* MGetSysDir (  void    )

Returns a pointer to the MGUISYS directory. The MGUISYS directory is searched at startup by the MGUI init code that runs before calling the application code: MGUIMain(). This directory contains MGUI bitmaps (as scrollbar arrows), MGUI fonts for console systems (DOS and Linux console), MGUI resource files.

int MInputPrompt (  const char *    title, const char *    msg, char *    text, int    len, const char *    ok_btn, const char *    canc_btn )

Displays a modal prompt window for a single line text input. This dialog window allows the program to block its flow, waiting for the user input a single line text. Parameters: title  The text displayed in the window's title bar. msg  A multi line text string that will be displayed centered in the window. text  The intial text value displayed in the edit field. It will contain the input text on return. len  The text buffer len. ok_btn  The text to be displayed in the Ok-button. canc_btn  The text to be displayed in the Cnacel-button. Returns: The 0 value is returned if the users selects the Cancel button, 1 is returned otherwise.

int MMessageDialog (  const char *    title, const char *    msg, const char *    btn1, const char *    btn2, ...    )

Displays a modal message window. This dialog window allows the program to block its flow until the user selects one of the push buttons provided. The buttons are specified using a NULL terminated list of string pointers. At least one button must be specified, so, the argument 'btn1' describes the text of the first button and 'btn2' could be the NULL pointer or a pointer to string for the text of the second button. Parameters: title  The text displayed in the window's title bar. msg  A multi line text string that will be displayed centered in the window. btn1  The text displayed in the first button (mandatory, not NULL) btn2  The text displayed in the second button (mandatory, may be NULL to terminate a one-button list) Returns: The return value notifies the calling function which button the user has selected: 0 for the first button, 1 for the second and so on...

int MPaletteMode (  void    )

This function returns True if the calling program runs in 16 or 256 colors video mode. When running in PaletteMode it's possible to create color animation by changing the RGB values in the colormap cells.

CARD16 MReadCARD16 (  FILE *    fp )

CARD32 MReadCARD32 (  FILE *    fp )

CARD8 MReadCARD8 (  FILE *    fp )

void MSetFileSelectionRGB (  int    r, int    g, int    b )

Sets the R-G-B components of the background color of the FileSelection dialog. Parameters: r  The red component of the color. g  The green component of the color. b  The blue component of the color. See also: MGetFileSelectionRGB, MFileSelection

void MSetFileSelectionTextStrings (  const char *    file_list, const char *    dir_list, const char *    drive_list, const char *    filter, const char *    filename, const char *    curr_dir, const char *    ok_button, const char *    close_button )

Changes the text displayed in the labels and buttons in the FileSelection dialog. To reset a value to its default, pass the NULL pointer to the corresponding parameter. Parameters: file_list  Text for the file list (default: "File"). dir_list  Text for the directory list (default: "Directory"). drive_list  Text for the drive list (default: "Drive") DOS/Windows only. filter  Text for the file filter edit (default: "Filter"). filename  Text for the file name (default: "File"). curr_dir  Text for the current directory (default: "Current directory"). ok_button  Text for the Ok button (default: " &Ok "). close_button  Text for the Close button (default: " &Close "). See also: MFileSelection

void MSetInputPromptFgRGB (  int    r, int    g, int    b )

Sets the R-G-B components of the foreground color of the InputPrompt dialog. Parameters: r  The red component of the color. g  The green component of the color. b  The blue component of the color. See also: MGetInputPromptFgRGB, MInputPrompt

void MSetInputPromptFonts (  MTFont    text_font, MTFont    edit_font, MTFont    buttons_font )

Sets the font for the message text, edit field and buttons in the InputPrompt and TextPrompt dialogs. Parameters: text_font  The font used for the message text. edit_font  The font used for the editable text. buttons_font  The font used for the buttons' text. See also: MGetInputPromptFonts, MInputPrompt, MTextPrompt

void MSetInputPromptRGB (  int    r, int    g, int    b )

Sets the R-G-B components of the background color of the InputPrompt dialog. Parameters: r  The red component of the color. g  The green component of the color. b  The blue component of the color. See also: MGetInputPromptRGB, MInputPrompt

void MSetMessageDialogFgRGB (  int    r, int    g, int    b )

Sets the R-G-B components of the foreground color of the Message dialog. Parameters: r  The red component of the color. g  The green component of the color. b  The blue component of the color. See also: MGetMessageDialogFgRGB, MMessageDialog

void MSetMessageDialogFonts (  MTFont    text_font, MTFont    buttons_font )

Sets the message text and buttons' fonts in the Message dialog. Parameters: text_font  The font used for the message text. buttons_font  The font used for the buttons' text. See also: MGetMessageDialogFonts, MMessageDialog

void MSetMessageDialogRGB (  int    r, int    g, int    b )

Sets the R-G-B components of the background color of the Message dialog. Parameters: r  The red component of the color. g  The green component of the color. b  The blue component of the color. See also: MGetMessageDialogRGB, MMessageDialog

int MSpoolFile (  const char *    fname )

Prints an ascii text file in the system printer. The print dialog is displayed under Windows. The file is printed in background under DOS, provided that the program periodically gives control to one of the event loop functions. Parameters: fname  The name of the file to be printed. Returns: MSPOOL_OK on succesful spool starting. MSPOOL_FILE_ERR if an error occurs while opening the file to be spooled. MSPOOL_NOT_READY if the printer is not ready. MSPOOL_FULL_QUEUE if no space is found in the spooling queue. See also: MSpoolTempFile

int MSpoolTempFile (  const char *    fname )

Prints a temporary ascii text file in the system printer. The file is removed as the printing is done. The print dialog is displayed under Windows. The file is printed in background under DOS, provided that the program periodically gives control to one of the event loop functions. Parameters: fname  The name of the file to be printed and then removed. Returns: MSPOOL_OK on succesful spool starting. MSPOOL_FILE_ERR if an error occurs while opening the file to be spooled. MSPOOL_NOT_READY if the printer is not ready. MSPOOL_FULL_QUEUE if no space is found in the spooling queue. See also: MSpoolFile

int MTextCharX (  const char *    text, MTFont    font, int    x )

Returns the x position (in pixels) of the character at a given position in a string array. This function actually converts the position of a character in a string from array index 'i' to x position in pixels using the font 'font'. See also: MTextWidth, MTextNWidth, MTextHeight

int MTextHeight (  const char *    text, MTFont    font )

Returns the height of the string 'text' using the font 'font'. See also: MTextWidth, MCharHeight

int MTextNWidth (  const char *    text, MTFont    font, int    len )

Returns the width of the first 'n' characters in the string 'text' using the font 'font'. See also: MTextWidth, MCharWidth, MCharHeight

char* MTextPrompt (  const char *    title, const char *    msg, const char *    text, int    w, int    h, const char *    ok_btn, const char *    canc_btn )

Displays a modal prompt window for a multi line text input. This dialog window allows the program to block its flow, waiting for the user input a multi line text. The arguments 'w' and 'h' specify the width and height of the Edit field object in character units. Parameters: title  The text displayed in the window's title bar. msg  A multi line text string that will be displayed centered in the window. text  The intial text value displayed. w  The edit window width in character units. h  The edit window height in character units. ok_btn  Text to be displayed in the Ok-button. canc_btn  Text to be displayed in the Cnacel-button. Returns: The NULL value is returned if the users selects the Cancel button, a pointer to a new allocated buffer containing the input value is returned otherwise. The program is responsible for freeing this buffer using free().

int MTextWidth (  const char *    text, MTFont    font )

Returns the width of the null terminated string 'text' using the font 'font'. See also: MTextNWidth, MTextHeight, MCharWidth, MCharHeight

void MWriteCARD16 (  FILE *    fp, CARD16    val )

void MWriteCARD32 (  FILE *    fp, CARD32    val )

void MWriteCARD8 (  FILE *    fp, CARD8    val )

---