Main Page   Modules   Class Hierarchy   Data Structures   File List   Data Fields   Globals  

CmMGUI Class Reference

Base MGUI Class. More...

Inheritance diagram for CmMGUI:

CmAppl CmMenuLine CmObject CmSocketHandler CmTimeout CmTreeNode CmAbsMenuItem CmMenuSeparator CmAbsButton CmAbsEdit CmAbsList CmContainer CmDrawArea CmLabel CmMenu CmMenuBar CmPixmap CmScrollBar CmSFile CmSplitter CmStatusBar CmTree

Protected Methods

virtual void beep (void)
 This method emits a beep sound using the system specific's default sound.

int getKeyboardState (void)
 Returns the status of the keyboard modifier keys (Alt, Control, Shift).

const char * getSysDir (void)
 Returns a pointer to a constant string specifying the MGUISYS directory.

const char * getApplicationName (void)
 Returns a pointer to a const string containing the running application name.

int paletteMode (void)
 This function returns True if the calling program runs in 16 or 256 colors video mode.

int getScreenWidth (void)
 Returns the screen width in pixel units.

int getScreenHeight (void)
 Returns the screen height in pixel units.

int getNPlanes (void)
 Returns the number of color planes in the display.

long getNColors (void)
 Returns the number of colors in the display.

MTColor getBlackColor (void)
 Returns the color id of the black color.

MTColor getWhiteColor (void)
 Returns the color id of the white color.

void enableCustomizing (void)
 This function enables the run-time resource changing dialog.

char * getStringOption (const char *obj_name, const char *opt_name)
 Retrieves a generic string option from the resource database.

char * getTextOption (const char *obj_name)
 Retrieves a text option from the resource database.

int getIntOption (const char *obj_name, const char *opt_name, int *ret)
 Retrieves an integer option from the resource database.

int getFontOption (const char *obj_name, MTFont *ret)
 Retrieves a Font option from the resource database.

int getBGColorOption (const char *obj_name, int *pr, int *pg, int *pb)
 Retrieves a Background Color option from the resource database.

int getFGColorOption (const char *obj_name, int *pr, int *pg, int *pb)
 Retrieves a Foreground Color option from the resource database.

int getShadowOption (const char *obj_name, int *shadow, int *i_t, int *o_t)
 Retrieves a Shadow option from the resource database.

void setStringOption (const char *obj_name, const char *opt_name, const char *text)
 Stores a generic string option in the resource database.

void setTextOption (const char *obj_name, const char *text)
 Stores a text option in the resource database.

void setIntOption (const char *obj_name, const char *opt_name, int val)
 Stores an integer option in the resource database.

void setFontOption (const char *obj_name, MTFont font)
 Stores a Font option in the resource database.

void setBGColorOption (const char *obj_name, int r, int g, int b)
 Stores a Background Color option in the resource database.

void setFGColorOption (const char *obj_name, int r, int g, int b)
 Stores a Foreground Color option in the resource database.

void setShadowOption (const char *obj_name, int shadow, int in_t, int out_t)
 Stores a Shadow option in the resource database.

void saveOptions (void)
 Saves in the application's resource file all defined options.

void logInit (int level, int nr, int nvr, int nc, int nvc, const char *fname)
 Sets the log level, log window geometry and log filename.

void log (int level, const char *fmt,...)
 Prints a formatted log string in the log window (and the log file if enabled).

void maskedLog (int level, CARD32 mask, const char *fmt,...)
 Prints a formatted log string in the log window using the context mask.

void logSetLevel (int level)
 Sets the current log-level.

void logSetMask (CARD32 mask)
 Sets the current log mask.

CARD32 logGetMask (void)
 Retrieves the current log mask containing enabled log contexts.

void logSetMaskBits (CARD32 mask)
 Adds bits to the current log mask enabling more log contexts.

void logResetMaskBits (CARD32 mask)
 Clears bits in the current log mask disabling some log contexts.

void setTraceFileName (const char *fname)
 Sets the name of the file which to write low level tracing messages.

void logSetTimeFormat (const char *strftime_format)
void traceSetTimeFormat (const char *strftime_format)
void trace (const char *fmt,...)
 Prints a low level tracing message to the trace file.

void getDefaultBackgroundRGB (int *pr, int *pg, int *pb)
 Retrieves the R-G-B components of the default background color.

void setDefaultBackgroundRGB (int r, int g, int b)
 Sets the R-G-B components of the default background color.

void getDefaultForegroundRGB (int *pr, int *pg, int *pb)
 Retrieves the R-G-B components of the default foreground color.

void setDefaultForegroundRGB (int r, int g, int b)
 Sets the R-G-B components of the default foreground color.

int textCharX (const char *text, MTFont font, int i)
 Returns the x position (in pixels) of the character at a given position in a string array.

int textHeight (const char *text, MTFont font)
 Returns the height of the string 'text' using the font 'font'.

int charHeight (char ch, MTFont font)
 Returns the height of the character 'ch' using the font 'font'.

int textWidth (const char *text, MTFont font)
 Returns the width of the null terminated string 'text' using the font 'font'.

int textNWidth (const char *text, MTFont font, int n)
 Returns the width of the first 'n' characters in the string 'text' using the font 'font'.

int charWidth (char ch, MTFont font)
 Returns the width of the character 'ch' using the font 'font'.

int spoolFile (const char *fname)
 Prints an ascii text file in the system printer.

int spoolTempFile (const char *fname)
 Prints a temporary ascii text file in the system printer.

void mainLoop (void)
 Transfers control to the main MGUI event loop handler.

void loopWhileFlag (int *pflag, int value)
 Transfers control temporarily to a MGUI event loop handler.

void loopWhileEvents (int discard)
 Processes all pending events and then returns.

void nextEvent (MEvent *pe, int wait)
 Retrieves next available MGUI event waiting for it if desired.

void processEvent (MEvent *pe)
 Processes a MGUI event retrieved by nextEvent().

int messageDialog (const char *title, const char *msg, const char *btn1, const char *btn2,...)
 Displays a modal message window.

int inputPrompt (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 * textPrompt (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 fileSelection (const char *title, char *filter, char *fname, char *dname, int change_cur_dir)
 Displays a modal prompt window for a file name selection.

int fileBrowse (const char *title, char *filter, char *fname, char *dname, int change_cur_dir)
 Displays a modal prompt window for a file name selection.

const char * getCurrentDirectory (void)
 Returns the program's current directory.

void setInputPromptRGB (int r, int g, int b)
 Sets the R-G-B components of the background color of the InputPrompt dialog.

void setInputPromptFgRGB (int r, int g, int b)
void setInputPromptFonts (MTFont text_font, MTFont edit_font, MTFont buttons_font)
void setMessageDialogRGB (int r, int g, int b)
 Sets the R-G-B components of the background color of the Message dialog.

void setFileSelectionRGB (int r, int g, int b)
 Sets the R-G-B components of the background color of the FileSelection dialog.

void setMessageDialogFgRGB (int r, int g, int b)
void setMessageDialogFonts (MTFont text_font, MTFont buttons_font)
void getInputPromptRGB (int *pr, int *pg, int *pb)
 Retrieves the R-G-B components of the background color used in the InputPrompt dialog.

void getInputPromptFgRGB (int *pr, int *pg, int *pb)
void getInputPromptFonts (MTFont *text_font, MTFont *edit_font, MTFont *buttons_font)
void getMessageDialogRGB (int *pr, int *pg, int *pb)
 Retrieves the R-G-B components of the background color used in the Message dialog.

void getMessageDialogFgRGB (int *pr, int *pg, int *pb)
void getMessageDialogFonts (MTFont *text_font, MTFont *buttons_font)
void getFileSelectionRGB (int *pr, int *pg, int *pb)
 Retrieves the R-G-B components of the background color used in the FileSelection dialog.

void setFileSelectionTextStrings (char *file_list, char *dir_list, char *drive_list, char *filter, char *filename, char *curr_dir, char *ok_button, char *close_button)
 Changes the text displayed in the labels and buttons in the FileSelection dialog.

Detailed Description

Base MGUI Class.

This is an abstract class, with no data and no public methods. It contains all global MGUI functions as protected methods, so they can be called by any derived class.

Member Function Documentation

virtual void CmMGUI::beep (  void    )  [protected, virtual]
 

This method 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.

The global "C" function MBeep() is available for use from outside CmMGUI derived classes.

int CmMGUI::charHeight (  char    ch,
MTFont    font
)  [protected]
 

Returns the height of the character 'ch' using the font 'font'.

The global "C" function MCharHeight() is available for use from outside CmMGUI derived classes.

See also:
textWidth, textNWidth, textHeight, charWidth

int CmMGUI::charWidth (  char    ch,
MTFont    font
)  [protected]
 

Returns the width of the character 'ch' using the font 'font'.

The global "C" function MTextNWidth() is available for use from outside CmMGUI derived classes.

See also:
textWidth, charHeight

void CmMGUI::enableCustomizing (  void    )  [protected]
 

This function enables the run-time resource changing dialog.

You can set object properties as font, color, text and shadow using a run-time dialog window. If enableCustomizing() in your program, then pressing the right mouse button while holding down both Shift and Ctlr keys on an enabled object, the customizing dialog is open. The object must be enabled by calling the enableOptions() method, specifying the object name and the properties you want to be able to change at run-time. Via the customizing dialog you can optionally save the changes made in the application's resource file.

The global "C" function MEnableCustomizing() is available for use from outside CmMGUI derived classes.

See also:
saveOptions

int CmMGUI::fileBrowse (  const char *    title,
char *    filter,
char *    fname,
char *    dname,
int    change_cur_dir
)  [protected]
 

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.

The global "C" function MFileBrowse() is available for use from outside CmMGUI derived classes.

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.

int CmMGUI::fileSelection (  const char *    title,
char *    filter,
char *    fname,
char *    dname,
int    change_cur_dir
)  [protected]
 

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.

The global "C" function MFileSelection() is available for use from outside CmMGUI derived classes.

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.

const char* CmMGUI::getApplicationName (  void    )  [protected]
 

Returns a pointer to a const string containing the running application name.

The exe file extension is removed from the name if running under DOS or Windows.

The global "C" function MGetApplicationName() is available for use from outside CmMGUI derived classes.

int CmMGUI::getBGColorOption (  const char *    obj_name,
int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves a Background Color option from the resource database.

A Background Color option is stored in the application or the MGUI resource files using 'background' as the option name.

The global "C" function MGetBGColorOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return green value to.
pb Points to an integer variable which to store the return blue value to.
Returns:
If the option is found, a boolean value of 'True' is returned by the function and the RGB values are stored in the variables pointed to by 'pr', 'pg' and 'pb'. Otherwise the value 'False' is returned.
See also:
setBGColorOption

MTColor CmMGUI::getBlackColor (  void    )  [protected]
 

Returns the color id of the black color.

Black and white colors are pre-allocated by MGUI at startup. You can use this value instead of allocating the color.

The global "C" function MGetBlackColor() is available for use from outside CmMGUI derived classes.

const char* CmMGUI::getCurrentDirectory (  void    )  [protected]
 

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.

The global "C" function MGetCurrentDirectory() is available for use from outside CmMGUI derived classes.

Returns:
The returned value points to a static buffer that is used by this function on successive calls. Don't free it!

void CmMGUI::getDefaultBackgroundRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves the R-G-B components of the default background color.

This color is used to draw the background in many MGUI objects. The R, G and B values are returned respectively in the variables pointed to by: 'pr', 'pg' and 'pb'.

The global "C" function MGetDefaultBackgroundRGB() is available for use from outside CmMGUI derived classes.

Parameters:
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return red value to.
pb Points to an integer variable which to store the return red value to.
See also:
setDefaultBackgroundRGB, setDefaultForegroundRGB, getDefaultForegroundRGB, CmSharedColor

void CmMGUI::getDefaultForegroundRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves the R-G-B components of the default foreground color.

This color is used to draw the foreground in many MGUI objects. The R, G and B values are returned respectively in the variables pointed to by: 'pr', 'pg' and 'pb'.

The global "C" function MGetDefaultForegroundRGB() is available for use from outside CmMGUI derived classes.

Parameters:
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return red value to.
pb Points to an integer variable which to store the return red value to.
See also:
getDefaultBackgroundRGB, setDefaultBackgroundRGB, getDefaultBackgroundRGB, CmSharedColor

int CmMGUI::getFGColorOption (  const char *    obj_name,
int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves a Foreground Color option from the resource database.

A Foreground Color option is stored in the application or the MGUI resource files using 'foreground' as the option name.

The global "C" function MGetFGColorOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return green value to.
pb Points to an integer variable which to store the return blue value to.
Returns:
If the option is found, a boolean value of 'True' is returned by the function and the RGB values are stored in the variables pointed to by 'pr', 'pg' and 'pb'. Otherwise the value 'False' is returned.
See also:
setFGColorOption

void CmMGUI::getFileSelectionRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves the R-G-B components of the background color used in the FileSelection dialog.

The global "C" function MGetFileSelectionRGB() is available for use from outside CmMGUI derived classes.

Parameters:
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return red value to.
pb Points to an integer variable which to store the return red value to.
See also:
setFileSelectionRGB, fileSelection

int CmMGUI::getFontOption (  const char *    obj_name,
MTFont *    ret
)  [protected]
 

Retrieves a Font option from the resource database.

A Font option is stored in the application or the MGUI resource files using an option named "font". Only the following fonts are currently supported:

  • FIXED_SMALL
  • FIXED_MEDIUM
  • FIXED_LARGE
  • HELV_SMALL
  • HELV_MEDIUM
  • TIMES_SMALL
  • TIMES_MEDIUM
  • HELV_LARGE
  • TIMES_LARGE

The global "C" function MGetFontOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
ret Points to an integer variable that will contain the return value.
Returns:
If the option is found, a boolean value of 'True' is returned by the function and the MTFont value is stored in the variable pointed to by 'ret'. Otherwise the value 'False' is returned.
See also:
setFontOption

void CmMGUI::getInputPromptFgRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

void CmMGUI::getInputPromptFonts (  MTFont *    text_font,
MTFont *    edit_font,
MTFont *    buttons_font
)  [protected]
 

void CmMGUI::getInputPromptRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves the R-G-B components of the background color used in the InputPrompt dialog.

The global "C" function MGetInputPromptRGB() is available for use from outside CmMGUI derived classes.

Parameters:
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return red value to.
pb Points to an integer variable which to store the return red value to.
See also:
setInputPromptRGB, inputPrompt

int CmMGUI::getIntOption (  const char *    obj_name,
const char *    opt_name,
int *    ret
)  [protected]
 

Retrieves an integer option from the resource database.

The integer option is identified by two names: the object name and the option name. Both names are free, the application can retrieve integer options manually defined in the application and the MGUI resource files or stored previously (in the application resource file) via saveOptions .

The global "C" function MGetIntOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
opt_name Specifies the name of the option. Option names in the DOS and Windows resource file appear after an object definition. The option is followed by the '=' character and the option value.
ret Points to an integer variable that will contain the return value.
Returns:
If the option is found, a boolean value of 'True' will be returned by the function and the integer value is stored in the variable pointed to by 'ret'. Otherwise the value 'False' is returned.
See also:
setIntOption

int CmMGUI::getKeyboardState (  void    )  [protected]
 

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.

The global "C" function MGetKeyboardState() is available for use from outside CmMGUI derived classes.

void CmMGUI::getMessageDialogFgRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

void CmMGUI::getMessageDialogFonts (  MTFont *    text_font,
MTFont *    buttons_font
)  [protected]
 

void CmMGUI::getMessageDialogRGB (  int *    pr,
int *    pg,
int *    pb
)  [protected]
 

Retrieves the R-G-B components of the background color used in the Message dialog.

The global "C" function MGetMessageDialogRGB() is available for use from outside CmMGUI derived classes.

Parameters:
pr Points to an integer variable which to store the return red value to.
pg Points to an integer variable which to store the return red value to.
pb Points to an integer variable which to store the return red value to.
See also:
setMessageDialogRGB, messageDialog

long CmMGUI::getNColors (  void    )  [protected]
 

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.

The global "C" function MGetNColors() is available for use from outside CmMGUI derived classes.

int CmMGUI::getNPlanes (  void    )  [protected]
 

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.

The global "C" function MGetNPlanes() is available for use from outside CmMGUI derived classes.

int CmMGUI::getScreenHeight (  void    )  [protected]
 

Returns the screen height in pixel units.

The global "C" function MGetScreenHeight() is available for use from outside CmMGUI derived classes.

int CmMGUI::getScreenWidth (  void    )  [protected]
 

Returns the screen width in pixel units.

The global "C" function MGetScreenWidth() is available for use from outside CmMGUI derived classes.

int CmMGUI::getShadowOption (  const char *    obj_name,
int *    shadow,
int *    i_t,
int *    o_t
)  [protected]
 

Retrieves a Shadow option from the resource database.

A Shadow option is stored in the application or the MGUI resource files using an option named "shadow".

The global "C" function MGetShadowOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
shadow Points to a variable that will contain the shadow type on return.
i_t Points to a variable that will contain the internal thickness on return.
o_t Points to a variable that will contain the out thickness on return.
Returns:
If the option is found, a boolean value of 'True' is returned by the function and the Shadow values are stored in the variables pointed to by the appropriate parameters. Otherwise the value 'False' is returned.
See also:
setShadowOption

char* CmMGUI::getStringOption (  const char *    obj_name,
const char *    opt_name
)  [protected]
 

Retrieves a generic string option from the resource database.

The string option is identified by two names: the object name and the option name. Both names are free, the application can retrieve string options manually defined in the application or the MGUI resource files or stored (in the application resource file) via saveOptions .

The global "C" function MGetStringOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
opt_name Specifies the name of the option. Option names in the DOS and Windows resource file appear after an object definition. The option is followed by the '=' character and the option value.
Returns:
The string value is returned in a new allocated buffer. The application is responsible for freeing the memory, using free(), when the value is no longer needed. The NULL pointer is returned if the option is not found.
See also:
setStringOption

const char* CmMGUI::getSysDir (  void    )  [protected]
 

Returns a pointer to a constant string specifying the MGUISYS directory.

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

The global "C" function MGetSysDir() is available for use from outside CmMGUI derived classes.

char* CmMGUI::getTextOption (  const char *    obj_name )  [protected]
 

Retrieves a text option from the resource database.

The text option is identified by only one name: the object name. A text option is stored in the application or the MGUI resource files using an option named "text".

The global "C" function MGetTextOption() is available for use from outside CmMGUI derived classes.

Returns:
The value is returned in a new allocated buffer. The application is responsible for freeing the memory, using free(), when the value is no longer needed. The NULL pointer is returned if the option is not found.
See also:
setTextOption, getStringOption, setStringOption

MTColor CmMGUI::getWhiteColor (  void    )  [protected]
 

Returns the color id of the white color.

Black and white colors are pre-allocated by MGUI at startup. You can use this value instead of allocating the color.

The global "C" function MGetWhiteColor() is available for use from outside CmMGUI derived classes.

int CmMGUI::inputPrompt (  const char *    title,
const char *    msg,
char *    text,
int    len,
const char *    ok_btn,
const char *    canc_btn
)  [protected]
 

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.

The global "C" function MInputPrompt() is available for use from outside CmMGUI derived classes.

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.

void CmMGUI::log (  int    level,
const char *    fmt,
...   
)  [protected]
 

Prints a formatted log string in the log window (and the log file if enabled).

You can call this function anywhere in your MGUI program, provided your calling method belongs to a class that inherits from CmMGUI.

The global "C" function MLog() is available for use from outside CmMGUI derived classes.

Parameters:
level Log level associated with the call. The log string is actually printed only if this value is higher than or equal to the current log-level.
fmt A format string with sprintf syntax.
See also:
logInit, logSetLevel, maskedLog, logSetMask

CARD32 CmMGUI::logGetMask (  void    )  [protected]
 

Retrieves the current log mask containing enabled log contexts.

The global "C" function MLogGetMask() is available for use from outside CmMGUI derived classes.

See also:
logInit, logSetMask, logSetMaskBits, logResetMaskBits

void CmMGUI::logInit (  int    level,
int    nr,
int    nvr,
int    nc,
int    nvc,
const char *    fname
)  [protected]
 

Sets the log level, log window geometry and log filename.

MGUI provides a run time log printing both to a window and optionally to a file. Logging is filtered using a threshold level and an optional context mask. By default the context mask is disabled. The first argument enstablishes the starting log-level. All log requests, made later by the program and having a level lower than this, are ignored.

The global "C" function MLogInit() is available for use from outside CmMGUI derived classes.

Parameters:
level Starting log level.
nr Desired number of rows you want to be saved in the log window.
nvr Desired number of visible rows (this value should be lower or equal to nr).
nc Desired number of columns you want to use in the log window.
nvc Desired number of visible columns (this value should be lower than or equal to nc).
fname Specifies the name of the file which you want to write log messages to. If you don't want to log to file, simply pass a NULL pointer.
See also:
log, logSetLevel, logSetMask

void CmMGUI::logResetMaskBits (  CARD32    mask )  [protected]
 

Clears bits in the current log mask disabling some log contexts.

The current log mask is obtained by 'and-ing' the old mask with the negated new one specified as argument.

The global "C" function MLogResetMaskBits() is available for use from outside CmMGUI derived classes.

Parameters:
mask Mask containing the contexts to be disabled. You can specify up to 32 different contexts for log masking.
See also:
logInit, logSetMask, logGetMask, logSetMaskBits

void CmMGUI::logSetLevel (  int    level )  [protected]
 

Sets the current log-level.

The global "C" function MLogSetLevel() is available for use from outside CmMGUI derived classes.

Parameters:
level New log level.
See also:
logInit, log

void CmMGUI::logSetMask (  CARD32    mask )  [protected]
 

Sets the current log mask.

The old mask is replaced by the new one specified as argument.

The global "C" function MLogSetMask() is available for use from outside CmMGUI derived classes.

Parameters:
mask New log mask. You can specify up to 32 different contexts for log masking.
See also:
logGetMask, logInit, logSetMaskBits, logResetMaskBits

void CmMGUI::logSetMaskBits (  CARD32    mask )  [protected]
 

Adds bits to the current log mask enabling more log contexts.

The old mask is or-ed with the new one specified as argument.

The global "C" function MLogSetMaskBits() is available for use from outside CmMGUI derived classes.

Parameters:
mask Mask containing the contexts to be enabled. You can specify up to 32 different contexts for log masking.
See also:
logInit, logSetMask, logGetMask, logResetMaskBits

void CmMGUI::logSetTimeFormat (  const char *    strftime_format )  [protected]
 

void CmMGUI::loopWhileEvents (  int    discard )  [protected]
 

Processes all pending events and then returns.

The argument 'discard' is a bolean value specifying whether the function has to discard all pending events or process them normally. It's highly recommended not to discard events. The main purpose of this function is to provide a way to poll for MGUI events, allowing event processing. This function is useful if your application has its own event loop and wants to process MGUI events without blocking into the MGUI loop.

The global "C" function MLoopWhileEvents() is available for use from outside CmMGUI derived classes.

See also:
nextEvent, processEvent, loopWhileFlag, mainLoop

void CmMGUI::loopWhileFlag (  int *    pflag,
int    value
)  [protected]
 

Transfers control temporarily to a MGUI event loop handler.

This function acts exactly as mainLoop while the value of the integer pointed to by 'pflag' equals 'value'. When such values differ, the function returns control to the calling program. The main purpose of this function is to provide a way to stop the program flow, allowing event processing, and then to resume it after a particular condition occurs (*pflag becomes different from 'value'). Many utility dialogs provided by MGUI use this function to stop execution and return to the calling program when the desired user input is available (See messageDialog , fileSelection , inputPrompt , textPrompt

The global "C" function MLoopWhileFlag() is available for use from outside CmMGUI derived classes.

See also:
nextEvent, processEvent, loopWhileEvents, mainLoop

void CmMGUI::mainLoop (  void    )  [protected]
 

Transfers control to the main MGUI event loop handler.

This function never returns. It puts the program in an infinite loop allowing the program to get and then process any external MGUI event. External events are:

  • keyboard and mouse input
  • window expose, resize and move
  • timeouts
The global "C" function MMainLoop() is available for use from outside CmMGUI derived classes.

See also:
nextEvent, processEvent, loopWhileEvents, loopWhileFlag

void CmMGUI::maskedLog (  int    level,
CARD32    mask,
const char *    fmt,
...   
)  [protected]
 

Prints a formatted log string in the log window using the context mask.

You can call this function anywhere in your MGUI program, provided your calling method belongs to a class that inherits from CmMGUI. The log string is actually printed only if conditions for both the log-level and the context mask are satisfied.

The global "C" function MMaskedLog() is available for use from outside CmMGUI derived classes.

Parameters:
level Log level associated with the call. For the string to be printed this value must be higher than or equal to the current log-level.
mask Context mask associated with the call. You can specify up to 32 different contexts for log masking. For the string to be printed this value must contain at least one bit of the current log-mask.
fmt A format string with sprintf syntax.
See also:
logInit, logSetLevel, log, logSetMask, logSetMaskBits, logResetMaskBits

int CmMGUI::messageDialog (  const char *    title,
const char *    msg,
const char *    btn1,
const char *    btn2,
...   
)  [protected]
 

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.

The global "C" function MMessageDialog() is available for use from outside CmMGUI derived classes.

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...

void CmMGUI::nextEvent (  MEvent *    pe,
int    wait
)  [protected]
 

Retrieves next available MGUI event waiting for it if desired.

The event is returned in the buffer pointed to by 'pe'. This structure must be allocated by the calling function. The second argument specifies, with a boolean value, whether the caller wants to wait for an event or not. If no pending event is found and 'wait' equals 0, the function returns immediately and sets the 'type' field of the MEvent structure to E_NO_EVENT.

The global "C" function MNextEvent() is available for use from outside CmMGUI derived classes.

See also:
processEvent, loopWhileEvents, loopWhileFlag, mainLoop

int CmMGUI::paletteMode (  void    )  [protected]
 

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.

The global "C" function MPaletteMode() is available for use from outside CmMGUI derived classes.

void CmMGUI::processEvent (  MEvent *    pe )  [protected]
 

Processes a MGUI event retrieved by nextEvent().

The mainLoop() function uses nextEvent() and this function to realize the blocking MGUI loop.

The global "C" function MProcessEvent() is available for use from outside CmMGUI derived classes.

See also:
processEvent, loopWhileEvents, loopWhileFlag, mainLoop

void CmMGUI::saveOptions (  void    )  [protected]
 

Saves in the application's resource file all defined options.

The file is entirely rewritten using option values read at startup from the same file and all options eventually defined at run time using:

The global "C" function MSaveOptions() is available for use from outside CmMGUI derived classes.
See also:
CmObject::saveOptions

Reimplemented in CmObject.

void CmMGUI::setBGColorOption (  const char *    obj_name,
int    r,
int    g,
int    b
)  [protected]
 

Stores a Background Color option in the resource database.

A Background Color option is stored in the application or the MGUI resource files using an option named "background". The RGB values 'r', 'g', and 'b' are stored as the color definition.

The global "C" function MSetBGColorOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
r The red component of the color to store.
g The green component of the color to store.
b The blue component of the color to store.
See also:
getBGColorOption

void CmMGUI::setDefaultBackgroundRGB (  int    r,
int    g,
int    b
)  [protected]
 

Sets the R-G-B components of the default background color.

This setting does not affect MGUI objects already created. The R, G and B values 'r', 'g' and 'pb' are used to set respectively the red, green and blue components of the new default background color.

The global "C" function MSetDefaultBackgroundRGB() is available for use from outside CmMGUI derived classes.

Parameters:
r The red component of the color.
g The green component of the color.
b The blue component of the color.
See also:
getDefaultBackgroundRGB, setDefaultForegroundRGB, getDefaultForegroundRGB, CmSharedColor

void CmMGUI::setDefaultForegroundRGB (  int    r,
int    g,
int    b
)  [protected]
 

Sets the R-G-B components of the default foreground color.

This setting does not affect MGUI objects already created. The R, G and B values 'r', 'g' and 'pb' are used to set respectively the red, green and blue components of the new default foreground color.

The global "C" function MSetDefaultForegroundRGB() is available for use from outside CmMGUI derived classes.

Parameters:
r The red component of the color.
g The green component of the color.
b The blue component of the color.
See also:
getDefaultBackgroundRGB, getDefaultForegroundRGB, setDefaultBackgroundRGB, CmSharedColor

void CmMGUI::setFGColorOption (  const char *    obj_name,
int    r,
int    g,
int    b
)  [protected]
 

Stores a Foreground Color option in the resource database.

A Foreground Color option is stored in the application or the MGUI resource files using an option named "foreground". The RGB values 'r', 'g', and 'b' are stored as the color definition.

The global "C" function MSetFGColorOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
r The red component of the color to store.
g The green component of the color to store.
b The blue component of the color to store.
See also:
getFGColorOption

void CmMGUI::setFileSelectionRGB (  int    r,
int    g,
int    b
)  [protected]
 

Sets the R-G-B components of the background color of the FileSelection dialog.

The global "C" function MSetFileSelectionRGB() is available for use from outside CmMGUI derived classes.

Parameters:
r The red component of the color.
g The green component of the color.
b The blue component of the color.
See also:
getFileSelectionRGB, fileSelection

void CmMGUI::setFileSelectionTextStrings (  char *    file_list,
char *    dir_list,
char *    drive_list,
char *    filter,
char *    filename,
char *    curr_dir,
char *    ok_button,
char *    close_button
)  [protected]
 

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.

The global "C" function MSetFileSelectionTextStrings() is available for use from outside CmMGUI derived classes.

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:
fileSelection

void CmMGUI::setFontOption (  const char *    obj_name,
MTFont    font
)  [protected]
 

Stores a Font option in the resource database.

A Font option is stored in the application or the MGUI resource files using an option named "font". Only the following fonts are currently supported:

  • FIXED_SMALL
  • FIXED_MEDIUM
  • FIXED_LARGE
  • HELV_SMALL
  • HELV_MEDIUM
  • TIMES_SMALL
  • TIMES_MEDIUM
  • HELV_LARGE
  • TIMES_LARGE
The global "C" function MSetFontOption() is available for use from outside CmMGUI derived classes.
Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
font The MTFont value to be stored.
See also:
getFontOption

void CmMGUI::setInputPromptFgRGB (  int    r,
int    g,
int    b
)  [protected]
 

void CmMGUI::setInputPromptFonts (  MTFont    text_font,
MTFont    edit_font,
MTFont    buttons_font
)  [protected]
 

void CmMGUI::setInputPromptRGB (  int    r,
int    g,
int    b
)  [protected]
 

Sets the R-G-B components of the background color of the InputPrompt dialog.

The global "C" function MSetInputPromptRGB() is available for use from outside CmMGUI derived classes.

Parameters:
r The red component of the color.
g The green component of the color.
b The blue component of the color.
See also:
getInputPromptRGB, inputPrompt

void CmMGUI::setIntOption (  const char *    obj_name,
const char *    opt_name,
int    val
)  [protected]
 

Stores an integer option in the resource database.

The integer option is identified by two names: the object name and the option name. Both names are free, the application can store integer options manually defining them in the application or the MGUI resource files or via saveOptions (in the application resource file only).

The global "C" function MSetIntOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
opt_name Specifies the name of the option. Option names in the DOS and Windows resource file appear after an object definition. The option is followed by the '=' character and the option value.
val The integer value to be stored.
See also:
getIntOption

void CmMGUI::setMessageDialogFgRGB (  int    r,
int    g,
int    b
)  [protected]
 

void CmMGUI::setMessageDialogFonts (  MTFont    text_font,
MTFont    buttons_font
)  [protected]
 

void CmMGUI::setMessageDialogRGB (  int    r,
int    g,
int    b
)  [protected]
 

Sets the R-G-B components of the background color of the Message dialog.

The global "C" function MSetMessageDialogRGB() is available for use from outside CmMGUI derived classes.

Parameters:
r The red component of the color.
g The green component of the color.
b The blue component of the color.
See also:
getMessageDialogRGB, messageDialog

void CmMGUI::setShadowOption (  const char *    obj_name,
int    shadow,
int    in_t,
int    out_t
)  [protected]
 

Stores a Shadow option in the resource database.

A Shadow option is stored in the application or the MGUI resource files using an option named "shadow". The Shadow values are stored in the database using the variables 'shadow', 'in_t' and 'out_t' (respectively: 'shadow type', 'internal thickness' and 'out thickness').

The global "C" function MSetShadowOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
shadow The shadow type (WS_NONE, WS_SHADOW_IN, WS_SHADOW_OUT, WS_ETCHED_IN, WS_ETCHED_OUT).
in_t The internal thickness.
out_t The out thickness.
See also:
getShadowOption

void CmMGUI::setStringOption (  const char *    obj_name,
const char *    opt_name,
const char *    text
)  [protected]
 

Stores a generic string option in the resource database.

The string option is identified by two names: the object name and the option name. Both names are free, the application can store string options manually defining them in the application or the MGUI resource files or via saveOptions (in the application resource file only). The value is stored in a new allocated buffer.

The global "C" function MSetStringOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
opt_name Specifies the name of the option. Option names in the DOS and Windows resource file appear after an object definition. The option is followed by the '=' character and the option value.
text The text value to be stored.
See also:
getStringOption

void CmMGUI::setTextOption (  const char *    obj_name,
const char *    text
)  [protected]
 

Stores a text option in the resource database.

The text option is identified by only one name: the object name. A text option is stored in the application or the MGUI resource files using an option named "text". The value is stored in a new allocated buffer.

The global "C" function MSetTextOption() is available for use from outside CmMGUI derived classes.

Parameters:
obj_name Specifies the name of the object. An object in the DOS and Windows resource file is defined by enclosing its name in brackets and it is followed by option definitions.
text The text value to be stored.
See also:
getTextOption

void CmMGUI::setTraceFileName (  const char *    fname )  [protected]
 

Sets the name of the file which to write low level tracing messages.

The global "C" function MSetTraceFileName() is available for use from outside CmMGUI derived classes.

Parameters:
fname The name of the file to be created for low level tracing messages.
See also:
trace, log, maskedLog

int CmMGUI::spoolFile (  const char *    fname )  [protected]
 

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.

The global "C" function MSpoolFile() is available for use from outside CmMGUI derived classes.

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:
spoolTempFile

int CmMGUI::spoolTempFile (  const char *    fname )  [protected]
 

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.

The global "C" function MSpoolFile() is available for use from outside CmMGUI derived classes.

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:
spoolFile

int CmMGUI::textCharX (  const char *    text,
MTFont    font,
int    i
)  [protected]
 

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'.

The global "C" function MTextCharX() is available for use from outside CmMGUI derived classes.

See also:
textWidth

int CmMGUI::textHeight (  const char *    text,
MTFont    font
)  [protected]
 

Returns the height of the string 'text' using the font 'font'.

The global "C" function MTextHeight() is available for use from outside CmMGUI derived classes.

See also:
textWidth, charHeight

int CmMGUI::textNWidth (  const char *    text,
MTFont    font,
int    n
)  [protected]
 

Returns the width of the first 'n' characters in the string 'text' using the font 'font'.

The global "C" function MTextNWidth() is available for use from outside CmMGUI derived classes.

See also:
textWidth, charWidth, charHeight

char* CmMGUI::textPrompt (  const char *    title,
const char *    msg,
const char *    text,
int    w,
int    h,
const char *    ok_btn,
const char *    canc_btn
)  [protected]
 

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.

The global "C" function MTextPrompt() is available for use from outside CmMGUI derived classes.

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 CmMGUI::textWidth (  const char *    text,
MTFont    font
)  [protected]
 

Returns the width of the null terminated string 'text' using the font 'font'.

The global "C" function MTextWidth() is available for use from outside CmMGUI derived classes.

See also:
textNWidth, textHeight, charWidth, charHeight

void CmMGUI::trace (  const char *    fmt,
...   
)  [protected]
 

Prints a low level tracing message to the trace file.

Messages printed via this function are not directed to the log window. Rather they go directly to the trace file (default name is trace.log) created in the current directory of the program. The trace file is open, written and closed at any call to this function, so it's recommended to use it only for low level debugging in case the log() function is not suitable.

The global "C" function Trace() is available for use from outside CmMGUI derived classes.

Parameters:
fmt A format string with sprintf syntax.
See also:
setTraceFileName, log, maskedLog

void CmMGUI::traceSetTimeFormat (  const char *    strftime_format )  [protected]
 

Generated on Sun Jun 29 13:03:08 2003 for MGui API by doxygen1.3-rc2