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

Generated on Thu Jun 22 11:45:29 2006 for WinDom by  doxygen 1.4.6