WinDom: Frame Library

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

# 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
WINDOW * | mt_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
WINDOW * | mt_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
WINDOW * | mt_FrameFind (APPvar *app, WINDOW *win, int x, int y)
| find a framed window
WINDOW * | mt_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.
Mode | Type window | Description/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.
Mode | Type 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