|
DAS
3.1.6 - 18/09/2017
|
MGui (MORELLO Graphic User Interface) is a cross-platform graphical user interface written in ANSI C, also providing a C++ API via a frame library. It consists of a library, including all typical GUI objects as menu, push buttons, editable fields, lists etc... and a code generation tool (MGui Designer), which allows the user to create and maintain application window layouts using the mouse.
MGui makes it possible to create applications for Windows 3.1, Windows 95/98/2000/XP, Unix X-Window, DOS (Borland, Watcom and DJGPP) with no knowledge about the host system graphics API. You can simply use the MGui Designer code generator to create window layouts, and write your code to interact with the created Objects.
For its features, MGui is useful to everyone who wants to realize multi platform applications, with absolutely no GUI porting needs.It's ideal for use in DOS based embedded systems in both real mode and DPMI.
Note: MGui 4.0 is no longer supported under BGI real mode and Windows 3.1
MGUI is coded in ANSI C and consists currently of about 35.000 source code lines. A small portion (8% - 10%) is highly system dependent, while the remaing 90% - 92% is completely system independent. The system specific code implements the interface between the specific graphic environment and the library Objects. This design makes MGUI easy to evolve and easy to port in other environments.
MGUI programming is similar, at least in the flow control, to the Unix X-Toolkit environment, so Unix users should easily familiarize with MGUI.
There are four main functional blocks in the library structure:
-# System Event Management (SEM) -# Graphics Request Management (GRM) -# TopLevel Window Management (TWM) -# MGUI Objects (Widgets)
The first block handles all the system generated events:
-# mouse button press -# mouse button release -# mouse move -# keyboard -# timeout -# window move -# window resize -# window expose
When one of the above event occurs, the SEM block generates an event and passes it to the TWM block. The DOS implementation uses a polling tecnique to handle mouse events, so mouse clicks and moves occurring while the program is not waiting for input are lost.
The TWM block's major task is to handle all those events the system notifies to a window. Any system window owned by the application has a MGUI Object bound to, events are received by this Object (SHELL) and propagated to the destination Widget following the layout hierarchy. Since the DOS O.S. does not provide a Window Manager, the TWM block in the DOS implementation also handles window movement and focus delivery.
The GRM block offers the API for the display functions: color and font management and drawing primitives.
Last block, the greater and system independent one, contains the MGUI Widgets' API.
In the remainder of this guide details about Widgets are described as well as the programming tecnique for a strict MGUI application. Refer to MGUI C++ API or C API documentation for more details about all available library functions.
Color management reflects perfectly the philosophy of MGUI Library: it's simple, compact and offers a unique approach to the DOS, Windows and Unix systems!
A program can operate in a 'palette' color mode or in a 'static' color mode, depending on the presence of a modifiable color palette in the graphic system.
Palette mode is normally available when the number of colors simultaneusly viewable is small (typically 16 or 256), and the graphic card is capable of a wide range of selectable colors (256K in the standard VGA). When operating in this mode, the pixel value in the video memory is used as an index by the display adapter to address a table containing the actual R-G-B values of the pixel color. By using 8 bit per pixel (planes) it's possible to address 256 different entries in the table and any combination of R-G-B values (256K in the standard VGA) can be assigned to each entry (palette cell).
This mode is efficient because it permits you to select colors in a wide range of available ones. Moreover it makes it possible to realize color animation by simply changing R-G-B values in the palette.
In the static mode the graphic system operates with a fixed color palette. This can be achieved in 16 color mode under Windows or in HiColor mode which offers 15, 16 or 24 bit per pixel with respectively 32K, 64K or 16M colors. HiColor mode grants a superior photographic resolution, but reaches slower performances because it requires 2 or 3 byte to code a single pixel while the palette mode with 256 colors needs only one byte.
If the MGUI application does not require color animation, it can actually ignore both the number of available colors and the operating color mode (palette or static).
If the application wants to know some details about the graphic environment in which it operates, it can call the MPaletteMode() function which returns 'True' if the palette mode is on. The MGetNColors() function returns the number of simultaneously viewable colors in the system and MGetNPlanes() returns the number of color planes.
Before using a color, the program must allocate it in the library. There are several allocation functions, each returning the color identifier that can be used in the drawing functions or to set a new color to an Object. The MAllocColor() function allocates a color specified by the three argument values (in the range 0-255) identifying the R-G-B color components. When the color is no longer needed, it should be freed via a call to the function MFreeColor().
Palette Mode
When operating in palette mode, a copy of the video palette is hold in memory by the library with a counter and a status flags for each entry (color cell). If so, a color identifier is equivalent to a cell index. Each counter value is initially set to zero and the status flag to 'free'. As a color allocation request occurs, the following situations can be in effect:
MGUI library provides ten preallocated (static) fonts in any platform which are referenced in the source code via macros. There are four fixed picth fonts:
The others are proportional Times ed Helvetica (arial):
It's possible to load additional fonts via the MLoadFont() function call, specifying the font family, font size, bold and italic options. The font family is a case unsensitive string which specifies the font name. Since release 3.2 you can query MGUI to enumerate available font families (including ALL DOS versions) and load the desired font at run time.
The font size specifies the desired font height. The returned font can have an actual height smaller than the requested one if the system doesn't support scaleable fonts or the font itself is fixed size. An application can load up to 22 new fonts.
Note that, since any font loading request allocates an entry even if the the requested font has already been loaded before, it's highly recommended to unload unused font via the MUnloadFont() function call. If the MLoadFont() request cannot be satisfied, the function returns the predefined value DEFAULT_FONT as an error. This also offers the application the opportunity to continue without testing the returned font identifier since it's always valid.
Since release 1.9, the library provides support for resource handling in ascii text configuration file with standard .ini format under Windows and DOS, with standard . Xdefaults format under X11. A system configuration file, in the /mgui/sys directory, defines general resources as the resolution sensitive static fonts or the default background and foreground colors. The name of this file is system dependent: MGui under X11, mgui.ini under Windows and DOS. Under X11 colors are specified in the standard X format (eg: <yellow> or <#ffff00>). Three decimal values, separated by commas, are used instead in all other environments (eg: <255,255,0> for yellow).
Static fonts in the system configuration file are specified in the standard X format under X11 while under DOS and Windows the fonts are defined in the format <family,height,bold> (eg: <arial,20,1> for arial 20 points bold). Under DOS only the font file name (.mfn) can be used directly to define a static font.
Another resource file is used to determine the resources of a MGUI program. This file is located in same directory where the executable resides (in the user's home directory under Unix) and has the same name of the program, with the appropriate extension (.progname under Unix).
The application's resource database is constructed at program startup by merging all option definitions in the MGUI resource file and then those in the application's resource file. By defining in the application's resource file a resource already defined in the MGUI resource file, you overwrite its previous value.
A resource is identified by the combination of an object name and a resource (option) name. Valid resources for GUI object are the following attributes: background/foreground colors, font, text and shadow. The Object font resource must be expressed as a static font name (eg: TIMES_LARGE or FIXED_MEDIUM).
All resources are loaded at program startup, Object resources are enabled via the function call MObjectEnableOptions(), after the Object creation. For example, the code:
label = MCreateLabel(mainshell, "Ctrl+Shift+MouseClick here to customize", FIXED_MEDIUM);
MObjectEnableOptions(label, "label_1", MO_ALL);
will cause the Object label to be customized with all available resources for the object named label_1. Object resources, enabled via MObjectEnableOptions(), can be saved in the application's resource file at any time by using the call MObjectSaveOptions().
MGUI provides a run-time advanced feature that lets the user change, and optionally store in the application file, the resources enabled for a given Object. This can be done via a dialog window open by clicking the mouse button in an enabled Object while holding down the <Ctrl+Shift> keys.
The library API also lets the programmer load/save general application resources, by specifying arbitrary object and resource names.
Events are messages for MGUI Objects or timeouts that cause a callback call. A callback is a user defined function assigned to a particular event. As this event occurs, the library invokes that function as an action for the event.
Using the C API the application has the opportunity to join a void pointer to a callback at registering time. This pointer is supplied back to the callback as the third argument in the callback call.
Object events are:
Unlike many high level programming environments (like OSF/Motif or Windows) which require a system window for each Object, MGUI requires only a system window for each individual top-level window, whatever complex is the Object hierarchy.
System events are received by the library in each window owned by the MGUI application, despatched to the 'SHELL' Object (the only one bound to the system window) and then received by the destination Object via the object hierarchy.
Mouse events are normally despatched to the Object below the mouse pointer. Once an Object has received a 'mouse button press' event, it can 'grab' the mouse so it can receive all mouse events including the 'button release', even if the mouse is over another Object.
Keyboard events are reported by the system to the top-level window that owns the 'input focus'. This window is normally highlighted with a different color in the title bar.
When a MGUI top-level window receives the input focus, there is a single destination Object that can really process keyboard events and it is highlighted with a thin black border to indicate it. Input focus is shifted to other Objects by explicit user selection with the mouse, by a MSelectObject() function call in the program, or by spontaneous Object grant (as a result to the user pressing on arrow or tab keys. Up and left arrow keys (if not processed by the Object) cause the input focus transfer to the previous 'brother' Object. Similarly, down and right arrow keys cause the focus to be transferred to the next brother Object. Tab and <Shift+Tab> transfer the input focus (if not processed) respectively to the next 'cousin' and the previous cousin.
There are four MGUI Object categories:
The Root Object is the SHELL. Its main task is to redirect all system events received from the TopLevel Window Manager block (keyboard and mouse input, window move, resize and expose), to its descendent Objects.
SHELL is the only Object having no parent; it has only one direct child which is a FORM Object (created automatically by the SHELL).
The FORM belongs to the Manager Object category and it's the only one, except for the SHELL, that may contain other Objects as children (eventually other FORMs). It plays a fundamental role in the library architecture taking care of children resizing and positioning. In addition it despatches to the appropriate child any event, not processed by itself, received from its parent.
Besides the simple FORM Object are the 'Paged', the 'Clipped', the 'Scrolled', the 'Table' and the 'Tabbed' FORMs.
The first one lets you create several children series and manage then one by one.
The second one makes the visible Object area a portion of a larger virtual area. By using the MFormSetClip[XY]() function calls, the application can change the starting offset of the visible area.
The Scrolled FORM is a Clipped FORM with a vertical and an horizontal SCROLLBAR Objects that permit the user to easily change the visible portion of the FORM content.
The Table FORM has the capability to arrange its children in a matrix layout. You have to specify the number of desired columns at creation time; the Object will arrange children objects while you add, wrapping to a new row when the previously created child was located in last column.
The Tabbed FORM is a variant of the Paged FORM which allows page selection via Tab buttons located on the top.
Main terminal Objects are all the remaining not composite Objects:
Composite terminal Objects are composed by a Main terminal which needs the contribution of some Manager and some other Main terminal Object to operate.
This category includes the OptionEdit (a combobox), SpinEdit and all LIST varieties.
The Scrolled FORM is actually a Compound Manager because it's composed by a simple FORM containg a Clipped FORM and two SCROLLBARs.
Except for the SHELL, all Object creation functions require the 'parent' Object identifier as the first argument. It must be a FORM or a SHELL Object type (the SHELL actually redirects the creation to its FORM child).
After creation, Objects have generally a gray background and a black text color (even if not used). Since release 3.0 LABEL, TBUTTON and RBUTTON are actually transparent so they appear with same background set in their parent Object. These colors can be changed at any time via the MObjectSetColor(), MObjectSetBackgroundRGB() and MObjectSetForegroundRGB() function calls.
Objects have a default shadow that can be modified after creation via the MObjectSetShadow() function call. Allowed shadow types are those identified by the macros:
The library provides utility functions to help you tracing the program execution, giving the opportunity to write messages in a file and/or to show them at any time in a window, activated by the key sequence <Shift-Ctrl-F1>.
The optional filename must be specified in the call to MLogInit(), normally in the MGUIMain() function. MLogInit() sets also the initial tracing level, the log window geometry and the number of messages to hold in the buffer.
A log message is generated by the program via the call to Mlog(). The first argument specifies the message level, the remaining are a format string and the value list, with printf() syntax. The call to Mlog() will take effect only if the current tracing level is equal to or higher than the value of the first argument. For example, the call:
MLog(3, "this is line: %d", LINE);
will generate a log message only if the current tracing level is equal to or higher than 3.
The tracing level can be changed at any time by the program code via a call to the function MLogSetLevel(). The user can also change this level run-time, activating the control dialog with the key sequence <Shift-Ctrl-F2>.
A more sophisticated filtering can be obtained by using the function MMaskedLog(). The message will take effect if the current tracing level is equal to or higher than the level in the call and the current bit-mask has at least one bit in common with the mask specified in the call.