Virtual Window

You know that we can post or send a message to other windows which may run in another thread under MiniGUI-Threads. The MiniGUI messaging functions such as PostMessage(), SendMessage(), SendNotifyMessage(), and the window callback procedure provide a flexible, efficient, safe, and easy-to-use data transfer and synchronization mechanism for your multithreaded applications. More...

Functions
MG_EXPORT BOOL GUIAPI	GetThreadByWindow (HWND hWnd, pthread_t *thread)
	Get the thread identifier which a window belongs to. More...
MG_EXPORT BOOL GUIAPI	IsWindowInThisThread (HWND hWnd)
	Determine whether a window was created in this thread. More...
MG_EXPORT BOOL GUIAPI	VirtualWindowCleanup (HWND hVirtWnd)
	Cleanup the system resource associated with a virtual window. More...
MG_EXPORT HWND GUIAPI	CreateVirtualWindow (HWND hHosting, WNDPROC WndProc, const char *spCaption, LINT id, DWORD dwAddData)
	Create a virtual window. More...
MG_EXPORT BOOL GUIAPI	DestroyVirtualWindow (HWND hWnd)
	Destroy a virtual window. More...

Detailed Description

You know that we can post or send a message to other windows which may run in another thread under MiniGUI-Threads. The MiniGUI messaging functions such as PostMessage(), SendMessage(), SendNotifyMessage(), and the window callback procedure provide a flexible, efficient, safe, and easy-to-use data transfer and synchronization mechanism for your multithreaded applications.

For example, you can send or post a message to a window from a general purpose thread which may download a file from the remote server under MiniGUI-Threads.

But can we use the MiniGUI messaging mechanism under MiniGUI-Processes and MiniGUI-Standalone runtime modes for multithreading purpose? For example, we may download a file in a general thread and inform a window when the file is ready.

Furthermore, if we want to use the MiniGUI messaging mechanism in a general thread to handle messages from other threads, how to do this?

The virtual window provides a solution for the requirements above. A virtual window is a special window object which does not have a visible window area. But after you create a virtual window in a different thread, you can use the MiniGUI messaging mechanism to post or send messages between the current main window thread and the new thread.

In MiniGUI, we call a thread creating a main window as a GUI thread, and a thread creating a virtual window as a message thread.

It is important to know the following key points about virtual window:

• It is enabled automatically under MiniGUI-Threads runtime mode.
• It can be enabled by using the compile-time configuration option --enable-virtualwindow, or define _MGHAVE_VIRTUAL_WINDOW macro under MiniGUI-Processes and MiniGUI-Standalone runtime modes.
• You can create multiple GUI threads under MiniGUI-Threads, but you cannot create multiple GUI threads under MiniGUI-Processes and MiniGUI-Standalone runtime modes.
• Regardless of the runtime mode, you can create multiple message threads, and you can also create multiple virtual windows in one message thread.
• It is possible to create a virtual window in a GUI thread, although we do not encourage to do this. In other words, a GUI thread is also a message thread. On the other hand, you cannot create a main window in a message thread.
• Essentially, a virtual window is a simplified main window. It consumes very little memory space, but provides a complete MiniGUI messaging mechanism for a general multithreaded app.
• When virtual window is enabled (or under MiniGUI-Threads runtime mode), you can use the MiniGUI messaging facilities to post or send messages to a window, or notify a window from a general thread.

A virtual window will get the following system messages in its life life-cycle:

• MSG_CREATE: this message will be sent to the virtual window when you call CreateVirtualWindow function.
• MSG_CLOSE: this message will be sent to the virtual window when the system asks to close the virtual window.
• MSG_DESTROY: this message will be sent to the virtual window when the system tries to destroy the virtual window, or after you called DestroyVirtualWindow function.
• MSG_IDLE: When there is no any message in the message queue, all virtual windows living in the message thread will get this idle message.
• MSG_TIMER: When a timer expired after you call SetTimer to set up a timer for a virtual window.
• MSG_QUIT: quit the message loop.
• MSG_GETTEXT: Send to window procedure to get the caption.
• MSG_SETTEXT: Send to window procedure to set the caption.
• MSG_GETTEXTLENGTH: Send to window procedure to get the length of caption.
• MSG_FDEVENT: Send to window procedure when there is a read/write/except event on a listened file descriptor.

The following functions work for a virtual window:

• DefaultWindowProc
• GetWindowId
• SetWindowId
• GetThreadByWindow
• GetWindowAdditionalData
• SetWindowAdditionalData
• GetWindowAdditionalData2
• SetWindowAdditionalData2
• GetClassName: always returns 'VIRTWINDOW' for a virtual window.
• GetWindowCallbackProc
• SetWindowCallbackProc
• GetWindowCaption
• SetWindowCaption
• GetWindowTextLength
• GetWindowText
• SetWindowText
• GetNotificationCallback
• SetNotificationCallback
• SetWindowLocalData
• GetWindowLocalData
• RemoveWindowLocalData
• RegisterEventHookWindow
• UnregisterEventHookWindow
• RegisterKeyHookWindow
• RegisterMouseHookWindow
• RegisterListenFD
• UnregisterListenFD

Since 5.0.0.

Function Documentation

CreateVirtualWindow()

HWND GUIAPI CreateVirtualWindow	(	HWND	hHosting,
		WNDPROC	WndProc,
		const char *	spCaption,
		LINT	id,
		DWORD	dwAddData
	)

Create a virtual window.

This function creates a virtual window for the purpose of multi-thread messaging.

Parameters

hHosting	The hosting virutal window.
WndProc	The window callback procedure.
spCaption	The caption of the virtual window.
id	The long integer (pointer size) identifier of the virtual window.
dwAddData	The additional data for the window.

Returns

The handle to the new virtual window; HWND_INVALID indicates an error.

See also

VirtualWindowCleanup

Example:

/*
 * The following code creates a virtual window.
 */
static LRESULT
my_virt_wnd_proc (HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
{
    switch (message) {
        ...
    }
 
    return DefaultVirtualWinProc (hwnd, message, wparam, lparam);
}
 
...
 
    HWND new_wnd = CreateVirtualWindow (HWND_NULL, my_virt_wnd_proc,
            "A Virtual Window", 0, 0);
 
    if (new_wnd != HWND_INVALID) {
        // failed to create the virtual window.
    }
 
    // go on...
    ...

Since 5.0.0.

DestroyVirtualWindow()

BOOL GUIAPI DestroyVirtualWindow

(

HWND

hWnd

)

Destroy a virtual window.

This function destroys a virtual window.

Parameters

hWnd	The handle to the virtual window.

Returns

TRUE on success, FALSE on error.

See also

VirtualWindowCleanup

Example:

/*
 * The following code creates a virtual window.
 */
static LRESULT
my_virt_wnd_proc (HWND hwnd, UINT message, WPARAM wparam, LPARAM lparam)
{
    switch (message) {
        ...
    }
 
    return DefaultVirtualWinProc (hwnd, message, wparam, lparam);
}
 
...
 
    HWND new_wnd = CreateVirtualWindow (HWND_NULL, my_virt_wnd_proc,
            "A Virtual Window", 0, 0);
 
    if (new_wnd != HWND_INVALID) {
        // failed to create the virtual window.
    }
 
    // go on...
    ...

Since 5.0.0.

GetThreadByWindow()

BOOL GUIAPI GetThreadByWindow	(	HWND	hWnd,
		pthread_t *	thread
	)

Get the thread identifier which a window belongs to.

Parameters

hWnd	The handle to a window, which may be a main window, virtual window, or a control.
thread	The buffer to store the thread identifier.

Returns

TRUE on success, otherwise FALSE.

Since 5.0.0

IsWindowInThisThread()

BOOL GUIAPI IsWindowInThisThread

(

HWND

hWnd

)

Determine whether a window was created in this thread.

Parameters

hWnd	The handle to a window, which may be a main window, virtual window, or a control.

Returns

TRUE on success, otherwise FALSE.

Since 5.0.0

VirtualWindowCleanup()

BOOL GUIAPI VirtualWindowCleanup

(

HWND

hVirtWnd

)

Cleanup the system resource associated with a virtual window.

This function cleans up the system resource such as the message queue associated with the virual window hVirtWnd. DestroyVirtualWindow does not destroy all resource used by the virtual window, therefore, you should call this function after calling DestroyVirtualWindow and skipping out from the message loop. After calling this function, the virtual window object will be destroyed actually.

Parameters

hVirtWnd

The handle to the virtual window.

Returns

TRUE on success, otherwise FALSE.

See also

DestroyVirtualWindow

Since 5.0.0