Window manipulation
MX-Windows Help

Window Manipulation


 

What is a Window?

A window (of type Window) is a rectangular bitmap area of the screen. Each window maintains a standard bitmap content, although it does not contain a BITMAP structure. A window can be a part of another window and it can contain other windows. Windows may overlap each other. Each window accepts a set of events and must react to each event at the order they arive. The whole I/O comes into play through the window reactions to events. The programmer may draw something temporary into a window but that will be erased when another window overlaps it and then exposes it. Each window has a position local to its parent (i.e. it is measured from its parent viewport) and a global position relative to 0, 0 pixel on the screen. Each window has a border of a certain width that defines the children windows viewport : its children are visible only into the rectangle that is defined by its position minus the border width; for example, if a window is at position x = 10, y = 10, width = 100, height = 100 with border width = 3, then its global position will be x1 = 10, y1 = 10, x2 = 109, y2 = 109 and its viewport will be x1 = 13, y1 = 13, x2 = 106, y2 = 106; its children will always start from pixel (13, 13 ). Each window has an event handler that defines its behaviour when it is drawn, when a mouse button is pressed over it, when the mouse pointer enters, leaves and moves over the window and when a key is pressed when that window has the keyboard control.
 
 

The windows tree model

Windows are organized into a tree. The highest window, the window that fills the whole screen, the window that does not have any parent is called the root window. There can be as many root windows as you like; only one of them will be drawn on the screen; The root window is the first window that receives any events that happen. Then events are propagated down the window tree according to the position of the mouse pointer or the child window that has grabbed events. Its window output is confined through its parent's viewport. All window geometry is considered relative to its parent(and measured in pixels) : if a window's x == 10 that does not mean that the physical output of the window starts at pixel 10; it may be at pixel 500, due to its parent position; Although when a window is exposed you may use Allegro functions to draw at absolute position on the screen(for further explanation see the events section).
 

Example :
 

|-----------------------------------------------------------------------------------------------|
|screen                                                                                         |
|                                                                                               |
|           |---|-----------------------------------------------|---|                           |
|    CLOSE->| X |window caption                                 | O |<-MAXIMIZE                 |
|           |   |                                               |   |                           |
|           |---|-----------------------------------------------|---|                           |
|           |   |window client area                             |   |                           |
|           |   |                                               |   |                           |
|           |   |   |----------------------------------|        |   |                           |
|           |   |   |form                              |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   |                                  |        |   |                           |
|           |   |   | |----------|   |---------------| |        |   |                           |
|           |   |   | |OK BUTTON |   |CANCEL BUTTON  | |        |   |                           |
|           |   |   | |----------|   |---------------| |        |   |                           |
|           |   |   |----------------------------------|        |   |                           |
|           |   |                                               |   |                           |
|           |   |                                               |   |                           |
|           |---|-----------------------------------------------|---|                           |
|                                                                                               |
|                                                                                               |
|                                                                                               |
|                                                                                               |
|TASK BAR                                                                                       |
|-----------------------------------------------------------------------------------------------|
|START BUTTON | ICON AREA                                                        | SYSTEM TRAY  |
|-----------------------------------------------------------------------------------------------|
 

In the above example we may observe a typical example of a nowadays most often seen gui screen. The window tree is the following one :
 

SCREEN
  |---APPLICATION WINDOW
  |     |---CLOSE BUTTON
  |     |---MAXIMIZE BUTTON
  |     |---WINDOW CAPTION
  |     |---WINDOW CLIENT AREA
  |           |---FORM
  |                 |---OK BUTTON
  |                 |---CANCEL BUTTON
  |---TASKBAR
        |---START BUTTON
        |---ICON AREA
        |---SYSTEM TRAY
 
 
 

Creating and destroying windows

A window is created with the following function :

    Window CreateWindow(
       Window parent,
       void *extension,
       void (*event_handler)(WindowInfo *, Event *),
       int x,
       int y,
       int width,
       int height,
       int border_width,
       int processed_events,
       int propagated_events);
 

The newly created window is inserted on top of any other windows of the given parent; If the parent has not been drawn until that time then the window is also not drawn, although it is inserted into the window tree.

Once a window is created, it can be destroyed with the following function :

    void DestroyWindow(Window *window);

The parameter is the window handle; you must pass a pointer to it so as that the variable that the window handle is stored in is NULLed. When a window is destroyed, it is also removed from the parent's list; if the parent was drawn, then the window removal causes some areas of the screen to be exposed; lower windows and its parent receive a series of expose events.
 
 

Inserting and removing windows

Since a window can be created with no parent it can later be inserted into some window tree; if the new parent is drawn then it gets drawn too :

    Bool InsertWindow(Window window, Window parent, int pos);

The pos parameter is the depth (or z-order) of the window: A positive value from 1 to n (n is maximum positive 32-bit integer) means the biggest the value the deepest into the screen the window will be inserted; a value of 1 means 'insert on top'; a value of 2 means 'insert just under the top window' and so on;
 

              POSITION

    VIEWER ---->  1  -->  2  -->  3  -->  4  -->  5  -->  6 ...
 

If pos is a negative number greater than zero then the order is inverted :
 

              POSITION

    VIEWER ---->  ... -6  -->  -5  -->  -4  -->  -3  -->  -2  -->  -1

Therefore if you would like to insert a window at the lowest posible position then use the value -1.

A window can be removed from the screen (but not destroyed) with the function :

    Bool RemoveWindow(Window window);

Root  windows (windows with no parent) can not be removed so in that case the function returns FALSE.
If you do not like a window's depth then you could use the following function to change it :

    Bool SetWindowZOrder(Window window, int pos);

The rools  about pos mentioned above also apply here. If the new depth brings the window closer to the screen plane then some areas of the window are exposed; If the new depth pushes the window away from the screen plane then some windows or top of it are exposed.
 
 
 

Changing window geometry

Since there are numerous ways to redefine a window's geometry (for example you wish to extend the window only from its left side or make it fill the whole screen or blah blah blah) the following set of functions hint the library to the possible values of each window geometry attribute:

    void SetWindowX(Window window, int val);
    void SetWindowY(Window window, int val);
    void SetWindowWidth(Window window, int val);
    void SetWindowHeight(Window window, int val);
    void SetWindowBorderWidth(Window window, int val);

If you wish to see the changes on the screen then the following function does all the needed changes on the screen (if neccessary) by re-calculating the physical position of each window in the given window tree and exposing or hiding any modified areas:

    void UpdateWindowGeometry(Window window);
 
 
 

Painting in a window

    The way the screen is redrawn is similar to the X-Windows mechanism : each window is accompanied by a dynamic list of rectangles that represent the visible areas of it. When a window is drawn for the first time, that list is calculated and then for each visible area the window receives an expose event. For subsequent redraws the list is not re-calculated; it is only changed when another window overlaps it or is moved away from it. You can refresh a window tree content with the following function :

    Bool RefreshWindow(Window window);

But if you would like to refresh just a window and not its children then you may use the function :

    Bool PaintWindow(Window window);

These functions return TRUE if any change on the screen has been made; if the window is not visible then they return FALSE.
These functions redraw whatever you have program the window to draw in response to an expose event. If you would like to draw something temporary in a window then you may use the function :

    Bool DoWindowDrawing(Window window, Bool overwrite_children, void (*paint_function)(WindowInfo *, ExposeEvent *));

This function returns FALSE if the window was not visible; The passed function uses the passed parameters to draw by using Allegro functions just like when the window receives an expose event. Unfortunately you must use external variables to control the drawing since the drawing is totally user - defined. The drawing may appear on top of the window's children or below them.
 

back to top
back to start page