class CmMGUI

Base MGUI Class

Inheritance:

CmMGUI


Protected Methods

virtual inline 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 the MGUISYS directory
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 trace(const char *fmt, ...)
Prints a low level tracing message to the trace file
void setTraceFileName(const char *fname)
Sets the name of the file which to write low level tracing messages
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 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'
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
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 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 getInputPromptRGB(int *pr, int *pg, int *pb)
Retrieves the R-G-B components of the background color used in the InputPrompt dialog
void getMessageDialogRGB(int *pr, int *pg, int *pb)
Retrieves the R-G-B components of the background color used in the Message dialog
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

Documentation

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.
virtual inline void beep(void)
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 getKeyboardState(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.

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

const char* getSysDir(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: 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.

int paletteMode(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.

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

int getScreenWidth(void)
Returns the screen width in pixel units. The global "C" function MGetScreenWidth() is available for use from outside CmMGUI derived classes.

int getScreenHeight(void)
Returns the screen height in pixel units. The global "C" function MGetScreenHeight() is available for use from outside CmMGUI derived classes.

int getNPlanes(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.

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

long getNColors(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.

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

MTColor getBlackColor(void)
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.

MTColor getWhiteColor(void)
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.

void enableCustomizing(void)
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

char* getStringOption(const char *obj_name, const char *opt_name)
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.

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.
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.
See Also:
setStringOption

char* getTextOption(const char *obj_name)
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

int getIntOption(const char *obj_name, const char *opt_name, int *ret)
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.

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.
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.
See Also:
setIntOption

int getFontOption(const char *obj_name, MTFont *ret)
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:

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

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.
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.
See Also:
setFontOption

int getBGColorOption(const char *obj_name, int *pr, int *pg, int *pb)
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.

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.
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.
See Also:
setBGColorOption

int getFGColorOption(const char *obj_name, int *pr, int *pg, int *pb)
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.

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.
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.
See Also:
setFGColorOption

int getShadowOption(const char *obj_name, int *shadow, int *i_t, int *o_t)
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.

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.
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.
See Also:
setShadowOption

void setStringOption(const char *obj_name, const char *opt_name, const char *text)
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 setTextOption(const char *obj_name, const char *text)
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 setIntOption(const char *obj_name, const char *opt_name, int val)
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 setFontOption(const char *obj_name, MTFont font)
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: 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 setBGColorOption(const char *obj_name, int r, int g, int b)
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 setFGColorOption(const char *obj_name, int r, int g, int b)
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 setShadowOption(const char *obj_name, int shadow, int in_t, int out_t)
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 saveOptions(void)
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

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. 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 log(int level, const char *fmt, ...)
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

void maskedLog(int level, CARD32 mask, const char *fmt, ...)
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

void logSetLevel(int level)
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 logSetMask(CARD32 mask)
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

CARD32 logGetMask(void)
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 logSetMaskBits(CARD32 mask)
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 logResetMaskBits(CARD32 mask)
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 trace(const char *fmt, ...)
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 setTraceFileName(const char *fname)
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 spoolFile(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.

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

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.
Parameters:
fname - The name of the file to be printed.
See Also:
spoolTempFile

int spoolTempFile(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.

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

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.
Parameters:
fname - The name of the file to be printed and then removed.
See Also:
spoolFile

void getDefaultBackgroundRGB(int *pr, int *pg, int *pb)
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 setDefaultBackgroundRGB(int r, int g, int b)
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 getDefaultForegroundRGB(int *pr, int *pg, int *pb)
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

void setDefaultForegroundRGB(int r, int g, int b)
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

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. 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 textHeight(const char *text, MTFont font)
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 charHeight(char ch, MTFont font)
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 textWidth(const char *text, MTFont font)
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

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'. The global "C" function MTextNWidth() is available for use from outside CmMGUI derived classes.

See Also:
textWidth, charWidth, charHeight

int charWidth(char ch, MTFont font)
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 mainLoop(void)
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 loopWhileFlag(int *pflag, int value)
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 loopWhileEvents(int discard)
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 nextEvent(MEvent *pe, int wait)
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

void processEvent(MEvent *pe)
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

int messageDialog(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.

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

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

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

Returns:
The 0 value is returned if the users selects the Cancel button, 1 is returned otherwise.
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.

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

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

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

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

char* getCurrentDirectory(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.

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 setInputPromptRGB(int r, int g, int b)
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 setMessageDialogRGB(int r, int g, int b)
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 setFileSelectionRGB(int r, int g, int b)
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 getInputPromptRGB(int *pr, int *pg, int *pb)
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

void getMessageDialogRGB(int *pr, int *pg, int *pb)
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

void getFileSelectionRGB(int *pr, int *pg, int *pb)
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

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


Direct child classes:
CmTimeout
CmObject
CmMenuLine
CmAppl

alphabetic index hierarchy of classes


MGUI Copyright 1996-2000 Vincenzo Morello

generated by doc++