Frame Library
[Reference documentation]

Divide windows into hierachical and independante frames. More...

Functions

void mt_FrameInit (APPvar *app)
 Initialization of the frame environment.
void mt_FrameExit (APPvar *app)
 release the frame environment
WINDOWmt_FrameCreate (APPvar *app, int attrib)
 Create a frame window.
void mt_FrameAttach (APPvar *app, WINDOW *win, WINDOW *src, int line, int col, int w, int h, int mode)
 attach a framed window in a window
WINDOWmt_FrameRemove (APPvar *app, WINDOW *win, WINDOW *child, int line, int col)
 Remove a framed window from a root window.
void mt_FrameSet (APPvar *app, WINDOW *win, int mode,...)
 Frame settings.
void mt_FrameGet (APPvar *app, WINDOW *win, int mode,...)
 get frame related informations
WINDOWmt_FrameFind (APPvar *app, WINDOW *win, int x, int y)
 find a framed window
WINDOWmt_FrameSearch (APPvar *app, WINDOW *win, int line, int col)
 Find a frame by cell reference.
int mt_FrameCalc (APPvar *app, WINDOW *win, int mode, INT16 *x, INT16 *y, INT16 *w, INT16 *h)
 get the framed window work area
void FrameSet (WINDOW *win, int mode,...)
 see mt_FrameSet()
void FrameGet (WINDOW *win, int mode,...)
 see mt_FrameGet()

Detailed Description

Divide windows into hierachical and independante frames.


Function Documentation

void FrameGet WINDOW win,
int  mode,
  ...
 

see mt_FrameGet()

void FrameSet WINDOW win,
int  mode,
  ...
 

see mt_FrameSet()

void mt_FrameAttach APPvar app,
WINDOW win,
WINDOW src,
int  line,
int  col,
int  w,
int  h,
int  flags
 

attach a framed window in a window

Parameters:
app application descriptor
win window descriptor of the root window
src window descriptor of the window to attach
line,col cell which will contain the frame
w,h size of the frame
flags bit field of special frame features (see mt_FramSet()).
This function attaches a window in a root window. The attached window becomes a framed window. The framed window is created like a standard window. It can be a formular or any custom user window. The window descriptor of the framed window is removed from the list of window and the WS_FRAME bit of the window descriptor status field is set to 1.

Frames inside a window are organized by line of cells. Each line can contain variable cells. The line and col parameters defines the order of the frame in the window. The real coordinates of a frame inside the work area of the root window depend on the frame sizes. And these sizes can be eventually changed by the user. The w and h parameters define the initial size of the frame.

The flags parameter defines special feature of the frame. See mt_FrameSet() for a complet description of this parameter.

The frame uses the GEM widget of the window. Possible attributs for a frame are INFO, SIZER, HSLIDE, VSLIDE, UPARROW, DNARROW, LFARROW and RTARROW. Other widgets are ignored.

See also:
mt_FrameCreate(), mt_FrameSet(), mt_FrameRemove().

int mt_FrameCalc APPvar app,
WINDOW win,
int  mode,
INT16 *  _x,
INT16 *  _y,
INT16 *  _w,
INT16 *  _h
 

get the framed window work area

Parameters:
app application descriptor
win framed window descriptor
mode global area (1) or work area (0)
_x,_y,_w,_h position and size of the work area,
Returns:
0 (success) or a negative error code.
mt_FrameCalc() computes the coordinates and size of the work area of a framed window. Widgets are take in consideration. This function is a sub-function of mt_WindGet(). In fact, mt_WindGet(WF_WORKXYWH) works correctly with framed window. The WF_CURRXYWH mode is supported too. It better to use mt_WindGet(), specially in event functions because these windows can be used as normal window or as framed window.

There is an important remark to do here. When you use mt_WindSet() and mt_WindGet() with the mode WF_WORKXYWH on a framed window descriptor, these function compute the frame work area size and not the window area size. Thus, mt_WindGet( ..., WF_WORKXYWH, ...) is identical to mt_FrameCalc(). This feature allows us to use directly event function initially written for window. So, prefined window, such as dialog box, can be framed.

WINDOW* mt_FrameCreate APPvar app,
int  attrib
 

Create a frame window.

Parameters:
app application descriptor
attrib GEM widget of the window (frame)
Returns:
window descriptor (NULL if failed)
mt_FrameCreate() just creates a window descriptor whose will host framed windows. The window created is not opened at screen as for mt_WindCreate(). Optional parameters can be set with mt_WindSet() for general window options and mt_FrameSet() for specific frame options.

The window created by mt_FrameCreate() has the WS_FRAME_ROOT bit of status window descriptor field set to 1. A FRAME structure is attached as data to the window with a WD_WFRA reserved magic number.

The method used to handle frame window is very simple. A frame window is seen like a set of framed windows. A framed window is not a real GEM window but is identified by a window descriptor. The frame window, i.e. the root window holding the list of framed window, and the standard event functions of the frame window use the standard event function of the framed window. Some events are applied to the active frame, such as a button event. The active frame may be defined by mt_FrameSet().

Bug:
sliders of framed window are not correctly initialized
Bug:
the vertical frame resizing widget are not supported
See also:
mt_FrameAttach(), mt_FrameSet().
Deprecated:
To be replaced by COMPONENTs

void mt_FrameExit APPvar app  ) 
 

release the frame environment

Parameters:
app application descriptor
This function release the memory used by the frame environment.

See also:
mt_FrameInit()

WINDOW* mt_FrameFind APPvar app,
WINDOW win,
int  x,
int  y
 

find a framed window

Parameters:
app application descriptor
win root frame window descriptor
x,y coordinates in desktop
Returns:
framed window descriptor found or NULL
mt_FrameFind() finds the framed window pointed by the x, y coordinates in the win root frame window. A NULL value returned indicates the frame is not found.

See also:
mt_FrameSearch()

void mt_FrameGet APPvar app,
WINDOW win,
int  mode,
  ...
 

get frame related informations

Parameters:
app application descriptor
win window descriptor (of a root frame window of a framed window),
mode parameter to get
... new values depending on mode
From WinDom version 1.20, frame sub structures in window descriptor have been hidden to improve portability with futur extensions. To compense the loss of information, the function mt_FrameGet() has been introduced. Currently, only one mode is available.

ModeType windowDescription/Parameters
FRAME_CELL framed window returns cellule reference:
  • par1 is the line position (int value)
  • par2 is the col position (int value)

void mt_FrameInit APPvar app  ) 
 

Initialization of the frame environment.

Parameters:
app application descriptor
This function initializes the frame environment. The frame environ should be released with mt_FrameExit().

See also:
mt_FrameExit()

WINDOW* mt_FrameRemove APPvar app,
WINDOW win,
WINDOW child,
int  line,
int  col
 

Remove a framed window from a root window.

Parameters:
app application descriptor
win root window descriptor
child framed window descriptor or NULL
line,col cell coordinate of the framed window
Returns:
window descriptor of the frame removed
mt_FrameRemove() removes a framed window from a root window. The removed frame becomes a normal window. If the frame parameter has a NULL value, the line and col cell coordinates are used to locate the framed window to remove.

See also:
mt_FrameAttach()

WINDOW* mt_FrameSearch APPvar app,
WINDOW win,
int  line,
int  col
 

Find a frame by cell reference.

Parameters:
app application descriptor
win frame root window descriptor
line,col framed window cell coordinates
Returns:
framed window descripteur found
Returns the framed window descriptor of the line, col cell in the win root frame window. A NULL value returned indicates the frame is not found.

See also:
mt_FrameFind()

void mt_FrameSet APPvar app,
WINDOW win,
int  mode,
  ...
 

Frame settings.

Parameters:
app application descriptor
win window descriptor (of a root frame window of a framed window),
mode parameter to set
... new values depending on mode
This function sets the special features of frame windows. The table below lists and comments the different modes of the function.

ModeType window"..." Parameters
FRAME_BORDER root window border size of frames (int value). Values in pixel unit
FRAME_COLOR root window color of border of frames (int value). Color is the VDI color index
FRAME_KEYBD root window dispatching of keyboard event. may be one of the following (int) values:
  • MOUSE_WINDOW : event sent to the frame pointed by the mouse
  • FRONT_WINDOW : event sent to the active frame
FRAME_ACTIVE root window the frame (WINDOW* value) to set as the new active frame
FRAME_TOPPED_ACTIV root window TRUE (int value) if topped frame should become active, or FALSE otherwise.
FRAME_SIZE framed window width and height (int values) of the new framed window size. These values depends on FRAME_FLAGS values
FRAME_FLAGS framed window type of flag (int value) and value TRUE/FALSE of the flag (int value).

Here is the list of the flags:

  • FRAME_HSCALE : The framed window height is defined proportionaly to the window root work area height (0..100).
  • FRAME_WSCALE : The framed window width is defined proportionaly to the window root work area width (0..100).
  • FRAME_HFIX : The framed window height is an absolute value (in pixel).
  • FRAME_WFIX : The framed window width is an absolute value (in pixel).
  • FRAME_NOBORDER : The framed window has no borders
  • FRAME_SELECT : The framed windows is activable


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