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.

Explanation of terms

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:

• 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 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.

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.

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.

Validation/invalidation

Validation/invalidation

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.

API reference: WM

The following table lists the available routines of the emWin window manager API. All functions are listed in alphabetical order within their respective categories:

Routine	Explanation
Basic functions
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
Memory devices support (optional)
WM_DisableMemdev	Disables usage of memory devices for redrawing
WM_EnableMemdev	Enables usage of memory devices for redrawing
Time related
WM_CreateTimer	Creates a timer which sends a WM_TIMER message to a window
WM_DeleteTimer	Deletes a timer
WM_RestartTimer	Restarts a timer
Widget related functions
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

Callback mechanism of the window manager

The WM may be used with or without callback routines. In most cases, using callbacks is preferable.

Philosophy behind the callback mechanism

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.

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.