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.
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 window in emWin:
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
The following table lists the available routines of the emWin window
manager API. All functions are listed in alphabetical order within their
respective categories:
| WM_Activate | Activates the window manager |
| WM_AttachWindow | Attaches a window to a new parent window |
| WM_AttachWindowAt | Attaches a window to a new parent window at the given position |
| WM_BroadcastMessage | Sends a message to all existing windows |
| WM_BringToBottom | Places a window behind its siblings |
| WM_BringToTop | Places a window in front of its siblings |
| WM_ClrHasTrans | Clears the has transparency flag |
| WM_CreateWindow | Creates a window |
| WM_CreateWindowAsChild | Creates a child window |
| WM_Deactivate | Deactivates the window manager |
| WM_DefaultProc | Default routine to handle messages |
| WM_DeleteWindow | Deletes a window |
| WM_DetachWindow | Detaches a window from its parent window |
| WM_DisableWindow | Sets the widget state to disabled |
| WM_EnableWindow | Sets the window state to enabled (default) |
| WM_Exec | Redraws invalid windows by executing callbacks (all jobs) |
| WM_Exec1 | Redraws one invalid window by executing one callback (one job only) |
| WM_ForEachDesc | Iterates over all descendants of a window |
| WM_GetActiveWindow | Returns handle of the active window |
| WM_GetCallback | Returns a pointer to the callback function of a window |
| WM_GetClientRect | Returns the size of the active window |
| WM_GetClientRectEx | Returns the size of a window |
| WM_GetDesktopWindow | Returns the window handle of the desktop window
|
| WM_GetDesktopWindowEx | Returns the window handle of the specified desktop window
|
| WM_GetDialogItem | Returns the window handle of a dialog box item (widget) |
| WM_GetFirstChild | Returns handle of a window™s first child window |
| WM_GetFocussedWindow | Returns the handle of the window with the input focus |
| WM_GetHasTrans | Returns current value of the has transparency flag |
| WM_GetInvalidRect | Returns the invalid rectangle of the given window |
| WM_GetNextSibling | Returns the handle of a window™s next sibling |
| WM_GetOrgX | Returns the origin in X of the active window |
| WM_GetOrgY | Returns the origin in Y of the active window |
| WM_GetParent | Returns handle of a window™s parent window |
| WM_GetPrevSibling | Returns the handle of a window™s previous sibling |
| WM_GetStayOnTop | Returns current value of the stay on top flag |
| WM_GetUserData | Retrieves the user data of a window
|
| WM_GetWindowOrgX | Returns the origin in X of a window |
| WM_GetWindowOrgY | Returns the origin in Y of a window |
| WM_GetWindowRect | Returns the screen coordinates of the active window |
| WM_GetWindowRectEx | Returns the screen coordinates of a window |
| WM_GetWindowSizeX | Returns the horizontal size (width) of a window |
| WM_GetWindowSizeY | Returns the vertical size (height) of a window |
| WM_HasCaptured | Checks if the given window has captured mouse- and touch screen-input |
| WM_HasFocus | Checks if the given window has the input focus |
| WM_HideWindow | Makes a window invisible |
| WM_InvalidateArea | Invalidates a certain section of the display |
| WM_InvalidateRect | Invalidates a part of a window |
| WM_InvalidateWindow | Invalidates a window |
| WM_IsCompletelyCovered | Checks if a window is completely covered or not |
| WM_IsCompletelyVisible | Checks if a window is completely visible or not |
| WM_IsEnabled | Returns if a window is enabled or not |
| WM_IsVisible | Returns if a window is visible or not |
| WM_IsWindow | Determine whether a specified handle is a valid window handle |
| WM_MakeModal | Changes the window to a ™modal™ window |
| WM_MoveChildTo | Sets the position of a window in window coordinates |
| WM_MoveTo | Sets the position of a window in desktop coordinates |
| WM_MoveWindow | Moves a window to another position |
| WM_NotifyParent | Sends a WM_NOTIFY_PARENT message to the parent of the given window |
| WM_Paint | Draws or redraws a window immediately |
| WM_PaintWindowAndDescs | Draws a given window and all descendant windows immediately |
| WM_ReleaseCapture | Stops capturing mouse- and touch screen-input |
| WM_ResizeWindow | Changes window size |
| WM_SelectWindow | Sets the active window to be used for drawing operations |
| WM_SendMessage | Sends a message to a window |
| WM_SendMessageNoPara | Sends a message without parameters to a window |
| WM_SendToParent | Sends the given message to the parent window of the given window |
| WM_SetDesktopColor | Sets desktop window color |
| WM_SetDesktopColorEx | Sets desktop window color of the given desktop |
| WM_SetCallback | Sets the callback routine for a window |
| WM_SetCapture | Starts capturing mouse- and touch screen-input |
| WM_SetCreateFlags | Sets the flags to be used as default when creating new windows
|
| WM_SetFocus | Sets input focus to a specified window |
| WM_SetHasTrans | Sets the has transparency flag |
| WM_SetId | Sends a WM_SET_ID message to the given window |
| WM_SetpfPollPID | Sets a function to be called by the WM for polling the PID |
| WM_SetSize | Sets the new size of a window |
| WM_SetWindowPos | Sets size and position of a window |
| WM_SetXSize | Sets the new X-size of a window |
| WM_SetYSize | Sets the new Y-size of a window |
| WM_SetStayOnTop | Sets the stay on top flag |
| WM_SetTransState | Sets or clears the WM_CF_HASTRANS and WM_CF_CONST_OUTLINE flags |
| WM_SetUserClipRect | Temporarily reduce the clipping area |
| WM_SetUserData | Sets the user data of the given window |
| WM_ShowWindow | Makes a window visible |
| WM_Update | Draws the invalid part of the given window |
| WM_UpdateWindowAndDescs | Draws the invalid part of a given window and the invalid part of all descendant windows |
| WM_ValidateRect | Validates parts of a window |
| WM_ValidateWindow | Validates a window |
| WM_DisableMemdev | Disables usage of memory devices for redrawing |
| WM_EnableMemdev | Enables usage of memory devices for redrawing |
| WM_CreateTimer | Creates a timer which sends a WM_TIMER message to a window |
| WM_DeleteTimer | Deletes a timer |
| WM_RestartTimer | Restarts a timer |
| WM_GetClientWindow | Returns the handle of the client window |
| WM_GetId | Returns the ID of a widget |
| WM_GetInsideRect | Returns the size of the active window less the border |
| WM_GetInsideRectEx | Returns the size of a window less the border |
| WM_GetScrollPosH | Returns the scroll position of the windows horizontal scroll bar |
| WM_GetScrollPosV | Returns the scroll position of the windows vertical scroll bar |
| WM_GetScrollState | Gets the state of a scroll bar widget |
| WM_SetScrollPosH | Sets the scroll position of the windows horizontal scroll bar |
| WM_SetScrollPosV | Sets the scroll position of the windows vertical scroll bar |
| WM_SetScrollState | Sets the state of a scroll bar widget |
The WM may be used with or without callback routines.
In most cases, using callbacks is preferable.
The idea behind the callback mechanism that emWin 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.
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.
emWin: Window Manager
