WinDom: Utility Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# Utility Library
[Reference documentation]

Group of usefull and diverse functions. More...

## Functions
void | mt_give_iconifyxywh (APPvar *app, INT16 *x, INT16 *y, INT16 *w, INT16 *h)
| give a valid position where iconify a window
void | mt_snd_rdw (APPvar *app, WINDOW *win)
| send a WM_REDRAW message for the work area of this window
void | mt_snd_arrw (APPvar *app, WINDOW *win, int msg)
| send a WM_ARROWED message
void | mt_snd_msg (APPvar *app, WINDOW *win, int msg, int par1, int par2, int par3, int par4)
| send a message to itself.
void | rc_set (GRECT *, int, int, int, int)
| Initialize a GRECT data.
void | rc_lset (LGRECT *, long, long, long, long)
| Initialize a LGRECT data.
void | w_getpal (APPvar *app, WINDOW *win)
| save in a buffer the current screen color palette
void | w_setpal (APPvar *app, WINDOW *win)
| restore a screen color palette
int | w_get_hndl (APPvar *app, WINDOW *win)
| Returns the WINDOW's real AES handle.
void | w_get_bkgr (APPvar *app, int of_x, int of_y, int of_w, int of_h, MFDB *img)
| save a screen area
void | w_put_bkgr (APPvar *app, int of_x, int of_y, int of_w, int of_h, MFDB *img)
| Restore a saved screen area.
int | keybd2ascii (int keybd, int shift)
| get the ascii code of a keyboard event
char * | conv_path (char *)
| convert a file name between TOS and MiNT formats
int | mt_ShelHelp (APPvar *app, char *file, char *chapter)
| Interface to the AES helper service.
int | mt_ShelWrite (APPvar *app, char *prg, char *cmd, void *env, int av, int single)
| Launch GEM or TOS applications.
void | mt_DebugWindom (APPvar *app, const char *format,...)
| print formated string to debug output
void * | Galloc (long size)
| Allocate memory in global mode.
void | mt_GrectCenter (APPvar *app, int w, int h, INT16 *x, INT16 *y)
| Centering an area on screen.
void | mt_ClipOn (APPvar *app, W_GRAFPORT *graf, GRECT *r)
| set clipping area for drawing
void | mt_ClipOff (APPvar *app, W_GRAFPORT *graf)
| unset clipping area for drawing
void | rc_lgrect2grect (GRECT *, const LGRECT *)
| Convert the LGRECT values to GRECT.
void | rc_grect2lgrect (LGRECT *, const GRECT *)
| Convert the GRECT values to LGRECT.
short | rc_lintersect (const LGRECT *r1, LGRECT *r2)
| Compute the interesection of two LGRECT rectangles.

## Detailed Description

Group of usefull and diverse functions.

## Function Documentation

char* conv_path | ( | char * | p | ) |

  | convert a file name between TOS and MiNT formats Parameters:
  | p | buffer containing the path to convert
Returns: p conv_path() converts a TOS filename o pathname in MiNT (Unix) format and inversly. Absolute or relative path are converted. Concerning the TOS convertion (MiNT to TOS), the root path (/ in Unix) is converted to U:\ except disk paths (/x/) which are converted into x:\ format. Some examples: `folder\dum.cnf` is converted in `folder/dum`.cnf `/c/multitos/mint`.cnf" is converted in `c:\multitos\mint.cnf` `/etc/passwd"` is converted to `U:\etc\passwd` `/u/etc/passwd"` is converted in `u:\etc\passwd` `/etc/passwd"` is converted in `U:\etc\passwd`

void* Galloc | ( | long | size | ) |

  | Allocate memory in global mode. Parameters:
  | size | memory size required (in byte),
  Returns: pointer to allocated buffer or NULL if memory is exhausted. Galloc() reserves global memory, i.e. memory which can be shared with other applications. This function is used for GEM message interprocess : all data shared between application should be declared in global memory (or shared memory). Only MiNT with memory protection is concerned. For managing GEM message event pointing on shared data, WinDom reserves a buffer for this purpose (WinDom kernel can use it for special message) : the variable app->pipe (or gl_appvar.pipe) points to a 256-byte buffer allocated with Galloc(). Attention: Galloc() is not a performant memory manager as malloc(), it makes a direct call to Malloc()/Mxalloc() and has the same limitation of these functions. Example
      // Safe example
      #include <av.h> // For VA_START constant

      void send_file_to_qed( char *file) {
        char *path = Galloc( strlen(file) + 1);

        strcpy( path, file);
        ApplWrite( appl_find( "QED     "), VA_START, ADR(path), 0, 0, 0);
        Mfree( path);
      }
      // Same example, shorter but less safe
      #define SEND_FILE_TO_QED(file)  AppWrite( appl_find( "QED     "), VA_START, ADR(strcpy(app.pipe,file), 0, 0, 0)

int keybd2ascii | ( | int | keybd,
|  | int | shift
| ) |

  | get the ascii code of a keyboard event Parameters:
  | keybd | keyboard scancode provides by evnt_keybd() or MU_KEYBD event,
  | shift | should be set to 1 if the shift key is depressed, 0 else
  Returns: the ascii code associated to the event keybd2ascii() identify the real ascii code of a keyboard event even the shift, control and alternate keys are depressed. When these keys are used, the ascii code in the scancode (value returned by a keyboard event) are different. Moreover, the scancode depends on the country of the keyboard. This function gets the real ascii code of the key pressed and can be used for keyboard shortcut. Example:
      #include <windom.h>
      #include <scancode.h> // definition of keyboard scancodes

      void ex_keybd( WINDOW *win) {
          char key =  keybd2ascii( evnt.keybd, evnt.mkstate & (K_LSHIFT|K_RSHIFT));
          switch( key) {
          case 'w':
          case 'W':
              // key w
              if( evnt.mkstate & K_CTRL)
                  ; // key Control-w
              break;
          // ...
          default:
              // Some keys have no ascii code (function key, numeric pad, ...).
              // These keys can be identified by their scancode.
              switch( evnt.keybd>>8) {
              case SC_HELP:
                  // HELP key
                  break;
              // ...
              }
          }
      }

void mt_ClipOff | ( | APPvar * | app,
|  | W_GRAFPORT * | graf
| ) |

  | unset clipping area for drawing Parameters:
  | app | application descriptor
  | graf | grafport which contain the VDI handle
reverse action of mt_ClipOn(). As for mt_ClipOn(), for most applications this function should not be use

void mt_ClipOn | ( | APPvar * | app,
|  | W_GRAFPORT * | graf,
|  | GRECT * | r
| ) |

  | set clipping area for drawing Parameters:
  | app | application descriptor
  | graf | grafport which contain the VDI handle
  | r | the area to clip
This function will set a clipping for the area for the VDI workstation of graf. This function is useless for most applications. Most of the time, application draw stuff to the screen only after a WM_REDRAW message, and in that case windom has already set the clipping area before inoking the callback function attached to the WM_REDRAW message.

void mt_DebugWindom | ( | APPvar * | app,
|  | const char * | format,
|  |  | ...
| ) |

  | print formated string to debug output Parameters:
  | app | application descriptor
  | format | formatted string (similar to printf)
  | ... | paramters of format (similar to printf)
This function writes the string to the windom debug output. The windom debug output is defined by the windom.debug variable. It may be : a standard AES form alert (if windom.debug is "alert") a AP_DEBUG AES message sent to the "DEBUG" application (if windom.debug is "debug") a file if windom.debug is "log". The second value of windom.debug is then the path of the log file to create.

void mt_give_iconifyxywh | ( | APPvar * | app,
|  | INT16 * | x,
|  | INT16 * | y,
|  | INT16 * | w,
|  | INT16 * | h
| ) |

  | give a valid position where iconify a window Parameters:
  | app | application descriptor
  | x,y,w,h | position and size of the icon window
This function can be used if one wants iconify artificially a window. The function give valid parameters for mt_WindSet() with the WF_ICONIFY mode :
        {
            short x,y,w,h;
            give_iconify( win, &x, &y, &w, &h);
            WindSet( win, WF_ICONFY, x, y, w, h);
        }
Depending the OS, the way to compute the iconify position is different: with AES older then 4.1, WinDom uses its own icon position. Icon placement is local to the application. with system handling iconify (AES >= 4.1, MagiC), give_iconifyxywh() returns special values (-1 for each component). These values, given to WindSet(WF_ICONIFY), forces the screen manager to place itself the icon. With PlainTOS, it is not necessary to have an iconify mechanism because mt_EvntWindom() offers to the user to iconify a window when the smaller widget is not present (by shift-clicking the closer widget).

void mt_GrectCenter | ( | APPvar * | app,
|  | int | w,
|  | int | h,
|  | INT16 * | x,
|  | INT16 * | y
| ) |

  | Centering an area on screen. Parameters:
  | app | application descriptor,
  | w,h | size of area to center,
  | x,y | at return, contain coordinate of the centered area.
mt_GrectCenter() computes the coordinates of an area in order to centering it on the screen (more precisely, on destop workspace). This function is used by mt_WindOpen(), window formular and classic formular functions to centered the window or the formular at screen. mt_GrectCenter() replaces the AES function form_center(). User can change the way mt_GrectCenter() centers the areas by editing the variable windom.window.center in the WinDom configuration file. Windows and formulars can be centered at screen or in a corner, centered on the mouse sprite, one can leave the OS decide ... See also: mt_WindOpen(), mt_FormCreate(), mt_WindFormBegin(), mt_FormBegin().

int mt_ShelHelp | ( | APPvar * | app,
|  | char * | file,
|  | char * | chapter
| ) |

  | Interface to the AES helper service. Parameters:
  | app | application descriptor
  | file | help file to display (or any regular file)
  | chapter | string to find in file
  Returns: 1 if no error 0 otherwise. mt_ShelHelp() uses shel_help() function to call the AES helper program if this service is available (NAES). Otherwise, mt_ShelHelp() checks the environ variable $STGUIDE then which should point to the st-Guide program (full path) or an equivalent program. Examples (with ST-Guide as helper service):
          // Display in ST-Guide a simple text file
          ShelWrite( "C:\\NEWDESK.INF", "");
          // Find the WINDOM.HYP file in ST-Guide paths and display it
          ShellWrite( "*:\\WINDOM.HYP", "");
          // Find in the WINDOM.HYP file the ShelWrite() reference and display it
          ShelWrite( "*:\\WINDOM.HYP", "ShelWrite()");
          // Find in the ST-Guide indexes a simple reference
          ShelWrite( "", "A simple reference");
Todo: an emulation of shel_help() when service is not available rather than use ST-GUIDE.

int mt_ShelWrite | ( | APPvar * | app,
|  | char * | prg,
|  | char * | cmd,
|  | void * | env,
|  | int | av,
|  | int | single
| ) |

  | Launch GEM or TOS applications. Parameters:
  | app | application descriptor,
  | prg | full or relative path of program to execute,
  | cmd | command line or NULL,
  | env | environ string or NULL,
  | av | if TRUE, try to send a VA_START if possible,
  | single | if TRUE, execute in single mode,
Returns: the id process of the application launched or a negative code error (-1 : execution failed, -2: AV_STARTED message not received (only if av parameter is set to TRUE). Precondition: pathname of program to execute must be in TOS format (with \ and x: for disc unit). mt_ShelWrite() launches application in a easy way. Applications can be GEM application or TOS application. mt_ShelWrite() uses the file name extension to identify the type of application (TOS programs have TOS or TTP suffix and GEM programs have APP, PRG or GTP suffix). In a multitask environnment, applications are launched in parallel. With the parameter single set to TRUE, applications are lauched in single mode. If the parameter av is set to TRUE, a VA_START message is sent to the GEM application if it is running. Otherwise, a FALSE value has the consequent to create multiple application. Note : if an VA_START is sent, one waits for AV_STARTED message, as stated by the AV-protocol and the function returns -2 if this message is not received. The parameter cmd describe the command line given to the application. The format is different of Pexec() or mt_shel_write() (ie the first character does not contain the lenght of the string). Bug: The ARGV protocol is not handled. Desktop accessories can not be launched.

void mt_snd_arrw | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | type
| ) |

  | send a WM_ARROWED message Parameters:
  | app | application descriptor
  | win | window which will be the target of the WM_ARROWED message
  | type | one of the WA_xxx constants defined by gemlib

void mt_snd_msg | ( | APPvar * | app,
|  | WINDOW * | win,
|  | int | msg,
|  | int | par1,
|  | int | par2,
|  | int | par3,
|  | int | par4
| ) |

  | send a message to itself. Parameters:
  | app | application descriptor
  | win | target of the message (used for element buff[1] of the message)
  | msg | id buff[0] of the message
  | par1,par2,par3,par4 | are buff[4..7] of the message.

void mt_snd_rdw | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | send a WM_REDRAW message for the work area of this window Parameters:
  | app | application descriptor
  | win | window to redraw
This will send a WM_REDRAW for the whole work area of win.

void rc_grect2lgrect | ( | LGRECT * | l,
|  | const GRECT * | r
| ) |

  | Convert the GRECT values to LGRECT. Parameters:
  | l | output rectangle
  | r | input rectangle
copy a GRECT rectangle r to a LGRECT rectangle l.

void rc_lgrect2grect | ( | GRECT * | r,
|  | const LGRECT * | l
| ) |

  | Convert the LGRECT values to GRECT. Parameters:
  | r | output rectangle
  | l | input rectangle
copy a LGRECT rectangle l to a GRECT rectangle r. Note: coordinates and sizes in l are 32 bits integers. The conversion to 16 bits integers (for GRECT structure) may lead to a saturation of the data to SHRT_MIN and SHRT_MAX.

short rc_lintersect | ( | const LGRECT * | r1,
|  | LGRECT * | r2
| ) |

  | Compute the interesection of two LGRECT rectangles. Parameters:
  | r1 | the first rectangle
  | r2 | the other rectangle. The intersection area will be returned in `r2`.
Returns: 0 if theses rectangle don't have any common area, any other value value if the intersection exist. Then, `r2` will contain the common area.

void rc_lset | ( | LGRECT * | rect,
|  | long | x,
|  | long | y,
|  | long | w,
|  | long | h
| ) |

  | Initialize a LGRECT data. Parameters:
  | rect | the LGRECT structure to initialize
  | x,y,w,h | values to put in rect

void rc_set | ( | GRECT * | rect,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h
| ) |

  | Initialize a GRECT data. Parameters:
  | rect | the GRECT structure to initialize
  | x,y,w,h | values to put in rect

void w_get_bkgr | ( | APPvar * | app,
|  | int | of_x,
|  | int | of_y,
|  | int | of_w,
|  | int | of_h,
|  | MFDB * | img
| ) |

  | save a screen area Parameters:
  | app | application descriptor
  | of_x,of_y,of_w,of_h | coordinate and size of the area to save
  | img | a valid MFDB structure will containing the screen area saved
It is a sub function of mt_FormBegin(). The screen area is copied in memory. A valid structure MFDB should be given to w_get_bkgr() but the memory required to save the screen area is reserved by the function. To release the memory, w_put_bkgr() should be call. See also: w_put_bkgr()

int w_get_hndl | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | Returns the WINDOW's real AES handle. To be used when sending a message to a WINDOW instance containing AES window handle (like e.g. snd_rdw()). Parameters:
  | app | application descriptor,
  | win | target window (or NULL for application scope),
Returns: WINDOW's real AES handle. It traverses up to the top-level WINDOW instance so that it returns valid AES value.

void w_getpal | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | save in a buffer the current screen color palette Parameters:
  | app | application descriptor
  | win | window descriptor or NULL
Get the AES set of colors, and store them in app (if win is NULL), or in win (if win is not NULL) for futur use. Note: the palet is saved in the GRAF_PORT data of win or app. By default, every windows use the application graf port, and so w_getpal(app,win) is equivalent to w_getpal(app,NULL) in most cases. See also: w_setpal()

void w_put_bkgr | ( | APPvar * | app,
|  | int | of_x,
|  | int | of_y,
|  | int | of_w,
|  | int | of_h,
|  | MFDB * | img
| ) |

  | Restore a saved screen area. Parameters:
  | app | application descriptor
  | of_x,of_y,of_w,of_h | coordinate and size of the area to restore
  | img | a valid MFDB structure containing the screen area saved.
It is a sub function of mt_FormEnd(). The screen area to restore should be previously saved by w_get_bkgr(). After the call, the memory is released, so the function can be called only one time with the same MFDB structure. See also: w_get_bkgr()

void w_setpal | ( | APPvar * | app,
|  | WINDOW * | win
| ) |

  | restore a screen color palette Parameters:
  | app | application descriptor
  | win | window descriptor or NULL
apply the set of color to the virtual workstation of the window (if not NULL) or application (otherwise). See also: w_getpal()