µC/GUI Window Manager
You are here : Micrium
: Products : µC/GUI :
Window Manager
The window manager supplies a set of routines which allow you to easily create, move, resize, and otherwise manipulate any number of windows. It also provides lower-level support by managing the layering of windows on the display and by alerting your application to display changes that affect its windows.
Terminology
Windows are rectangular in shape, defined by their origin (the X- and Y-coordinates of the upper left corner) as well as their X- and Y-sizes (width and height, respectively). A µC/GUI window:
- is rectangular.
- has a Z-position.
- may be hidden or shown.
- may have valid and/or invalid areas.
- may or may not have transparency.
- may or may not have a callback routine.
Active window
The window which is currently being used for drawing operations is referred to as the active window. It is not necessarily the same as the topmost window.
Callback routines
Callback routines are defined by the user program, instructing the graphic system to call a specific function when a specific event occurs. Normally they are used to automatically redraw a window when its content has changed.
Child/parent windows, siblings
A child window is one that is defined relative to another window, called the parent. Whenever a parent window moves, its child or children move correspondingly. A child window is always completely contained within its parent, and will be clipped if necessary. Multiple child windows with the same parent are considered "siblings" to one another.
Client areaThe client area of a window is simply its usable area. If a window contains a frame or title bar, then the client area is the rectangular inner area. If there is no such frame, then the coordinates of the client area are identical to those of the window itself.
Clipping, clip area
Clipping is the process of limiting output to a window or part of it. The clip area of a window is its visible area. This is the window area minus the area obstructed by siblings of higher Z-order, minus any part that does not fit into the visible area of the parent window.
Client area
The client area of a window is simply its usable area. If a window contains a frame or title bar, then the client area is the rectangular inner area. If there is no such frame, then the coordinates of the client area are identical to those of the window itself.
Desktop window
The desktop window is automatically created by the window manager, and always covers the entire display area. It is always the bottommost window, and when no other window has been defined, it is the default (active) window. All windows are descendants (children, grandchildren, etc.) of the desktop window.
Handle
When a new window is created, the WM assigns it a unique identifier called a handle. The handle is used in any further operations performed on that particular window.
Hiding/showing windows
A hidden window is not visible, although it still exists (has a handle). When a window is created, it is hidden by default if no create flag is specified. Showing a window makes it visible; hiding it makes it invisible.
Transparency
A window that has transparency contains areas that are not redrawn with the rest of the window. These areas operate as though the window behind "shows through" them. In this case, it is important that the window behind is redrawn before the win- dow with transparency. The WM automatically handles redrawal in the correct order.
Transparency
A window that has transparency contains areas that are not redrawn with the rest of the window. These areas operate as though the window behind "shows through" them. In this case, it is important that the window behind is redrawn before the window with transparency. The WM automatically handles redrawing in the correct order.
Validation/invalidation
A valid window is a fully updated window which does not need redrawing.
An invalid window does not yet reflect all updates and therefore needs to be redrawn, either completely or partially. When changes are made that affect a particular window, the WM marks that window as invalid. The next time the window is redrawn (either manually or by a callback routine) it will be validated.
Z-position, bottom/top
Although a window is displayed on a two-dimensional screen in terms of X and Y, the WM also manages what is known as a Z-position, or depth coordinate -- a position in a virtual third dimension which determines its placement from background to fore- ground. Windows can therefore appear on top of or beneath one another. Setting a window to the bottom will place it "underneath" all of its sibling windows (if any); setting it to the top will place it "on top of" its siblings. When a window is created, it is set to the top by default if no create flag is specified.
Callback mechanism of the window manager
The WM may be used with or without callback routines. In most cases, using call- backs is preferable.
Philosophy behind the callback mechanism
The idea behind the callback mechanism that µC/GUI offers for windows and window objects (widgets) is that of an event-driven system. As in most windowing systems, the principle is that the flow of control is not just from the user program to the graphic system, but also from the user program to the graphic system and back up to the user program by means of the callback routines provided by the user program. This mechanism -- often characterized as the Hollywood principle ("Don't call us, we'll call you!") -- is needed by the window manager mainly in order to trigger the redrawing of windows. This contrasts with classical programming, but it makes it possible to exploit the invalidation logic of the window manager.
Not using callbacks
You do not have to use callback routines, but in doing so, the WM loses the ability to manage redrawing (updating) of the windows. It is also possible to mix; for example, having some windows use callbacks and others not. However, if a window does not use the callback mechanism, your application is responsible for updating its contents.
API reference: WM
The following table lists the available µC/GUI functions of the window manager API. All functions are listed in alphabetical order within their respective categories:
| Function |
Description |
Basic functions |
| WM_CreateWindow |
Create a window. |
| WM_CreateWindowAsChild |
Create a child window. |
| WM_DeleteWindow |
Delete a window. |
| WM_ExecIdle |
Redraw invalid windows by executing callbacks. |
| WM_GetClientRect |
Return the size of the active window. |
| WM_GetDialogItem |
Return the window handle of a dialog box item (widget). |
| WM_GetOrgX |
Return the origin in X of the active window. |
| WM_GetOrgY |
Return the origin in Y of the active window. |
| WM_GetWindowOrgX |
Return the origin in X of a window. |
| WM_GetWindowOrgY |
Return the origin in Y of a window. |
| WM_GetWindowRect |
Return the screen coordinates of the active window. |
| WM_GetWindowSizeX |
Return the horizontal size (width) of a window. |
| WM_GetWindowSizeY |
Return the vertical size (height) of a window. |
| WM_HideWindow |
Make a window invisible. |
| WM_InvalidateArea |
Invalidate a certain section of the display. |
| WM_InvalidateRect |
Invalidate part of a window. |
| WM_InvalidateWindow |
Invalidate a window. |
| WM_MoveTo |
Set the position of a window. |
| WM_MoveWindow |
Move a window to another position. |
| WM_Paint |
Draw or redraw a window immediately. |
| WM_ResizeWindow |
Change window size. |
| WM_SelectWindow |
Set the active window to be used for for drawing operations. |
| WM_ShowWindow |
Make a window visible. |
Advanced functions |
| WM_Activate |
Activate the window manager. |
| WM_BringToBottom |
Place a window behind its siblings. |
| WM_BringToTop |
Place a window in front of its siblings. |
| WM_ClrHasTrans |
Clear the has transparency flag. |
| WM_Deactivate |
Deactivate the window manager. |
| WM_DefaultProc |
Default routine to handle messages. |
| WM_GetActiveWindow |
Return handle of the active window. |
| WM_GetDesktopWindow |
Return handle of the desktop window. |
| WM_GetFirstChild |
Return handle of a window's first child window. |
| WM_GetNextSibling |
Return handle of a window's next sibling. |
| WM_GetHasTrans |
Return current value of the has transparency flag. |
| WM_GetParent |
Return handle of a window's parent window. |
| WM_Init |
Initialize window manager. No longer necessary; done by GUI_Init(). |
| WM_IsWindow |
Determine whether a specified handle is a valid window handle. |
| WM_SendMessage |
Send a message to a window. |
| WM_SetDesktopColor |
Set desktop window color. |
| WM_SetCallback |
Set the callback routine for a window. |
| WM_SetCreateFlags |
Sets the flags to be used as default when creating new windows |
| WM_SetHasTrans |
Set the has transparency flag. |
| WM_SetUserClipRect |
Temporarily reduce the clipping area. |
| WM_ValidateRect |
Validate parts of a window. |
| WM_ValidateWindow |
Validate a window. |
Memory device support (optional) |
| WM_DisableMemdev |
Disable usage of memory devices for redrawing. |
| WM_EnableMemdev |
Enable usage of memory devices for redrawing. |
|
