Data Structures
struct	_MAINWINCREATE

Macros
#define	HWND_DESKTOP __mg_hwnd_desktop
	Desktop window handle. More...

#define	HWND_NULL ((HWND)0)
	Null window handle. More...

#define	HWND_INVALID ((HWND)-1)
	Invalid window handle. More...

#define	DefaultMainWinProc (__mg_def_proc[0])
	Is the default main window callback procedure. More...

#define	DefaultDialogProc (__mg_def_proc[1])
	The default dialog box procedure. More...

#define	DefaultControlProc (__mg_def_proc[2])
	The default control callback procedure. More...

#define	DefaultVirtualWinProc (__mg_def_proc[3])
	The default window callback procedure for virtual windows. More...

Typedefs
typedef struct _MAINWINCREATE	MAINWINCREATE

Functions
static pthread_t GUIAPI	GetMainWinThread (HWND hMainWnd)
	Get the thread identifier which main window belongs to. More...

MG_EXPORT int GUIAPI	WaitMainWindowClose (HWND hWnd, void **returnval)
	Suspend execution of the calling thread which main window belongs to until the target thread terminates, unless the target thread has already terminated. More...

MG_EXPORT BOOL GUIAPI	MainWindowCleanup (HWND hMainWnd)
	Cleans up system resource associated with a main window. More...

static BOOL	MainWindowThreadCleanup (HWND hMainWnd)
	Cleanup the main window. More...

MG_EXPORT HWND GUIAPI	CreateMainWindowEx2 (PMAINWINCREATE create_info, LINT id, const char werdr_name, const WINDOW_ELEMENT_ATTR we_attrs, unsigned int surf_flag, DWORD bkgnd_color, int compos_type, DWORD ct_arg)
	Creates a main window with specified compositing type and identifier. More...

static HWND GUIAPI	CreateMainWindowEx (PMAINWINCREATE pCreateInfo, const char werdr_name, const WINDOW_ELEMENT_ATTR we_attrs, const char window_name, const char layer_name)
	Creates a main window. More...

static HWND GUIAPI	CreateMainWindow (PMAINWINCREATE pCreateInfo)
	A simplified version of CreateMainWindowEx. More...

MG_EXPORT BOOL GUIAPI	DestroyMainWindow (HWND hWnd)
	Destroys a main window. More...

MG_EXPORT BOOL GUIAPI	SetWindowLocalData (HWND hwnd, const char *data_name, DWORD local_data, CB_FREE_LOCAL_DATA cb_free)
	Set the local data bound with a name for a window. More...

MG_EXPORT BOOL GUIAPI	RemoveWindowLocalData (HWND hwnd, const char *data_name)
	Remove the local data bound with a name for a window. More...

MG_EXPORT BOOL GUIAPI	SetWindowMask (HWND hWnd, const MYBITMAP *mask)
	Set window (a main window, or a child window which is also known as "control")'s Mask Rect with MYBITMAP data. More...

MG_EXPORT BOOL GUIAPI	SetWindowMaskEx (HWND hWnd, HDC hdc, const BITMAP *mask)
	Set window (a main window, or a child window which is also known as "control")'s Mask Rect with BITMAP data,. More...

MG_EXPORT BOOL GUIAPI	SetMainWindowAlwaysTop (HWND hWnd, BOOL fSet)
	Set or cancel a main window being always top. More...

MG_EXPORT BOOL GUIAPI	SetMainWindowGestureFlags (HWND hWnd, DWORD dwFlags)
	Set the gesture flags of a main window. More...

BOOL GUIAPI	SetWindowRegion (HWND hWnd, const CLIPRGN *region)
	Set window's Mask Rect with CLIPRGN data. More...

BOOL GUIAPI	GetWindowRegion (HWND hWnd, CLIPRGN *region)
	The function obtains a copy of the window region of a window. More...

MG_EXPORT LRESULT GUIAPI	DefaultWindowProc (HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
	The default window callback procedure. More...

Variables
MG_EXPORT WNDPROC	__mg_def_proc [4]
	The default window callback procedure array. More...

Detailed Description

Macro Definition Documentation

◆ DefaultControlProc

#define DefaultControlProc (__mg_def_proc[2])

The default control callback procedure.

This function is the default control callback procedure. You should call this function for all messages, you do not want to handle in your own control procedure.

Parameters

hWnd	The handle to the window.
message	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Definition at line 7416 of file window.h.

◆ DefaultDialogProc

#define DefaultDialogProc (__mg_def_proc[1])

The default dialog box procedure.

This function is the default dialog box procedure. You should call this function in your dialog box procedure to process the unhandled messages.

Parameters

hWnd	The handle to the window.
message	The message identifier.
wParam	The first message parameter.
lParam	The second message parameter.

Returns: The return value of the message handler.

Definition at line 7401 of file window.h.

◆ DefaultMainWinProc

#define DefaultMainWinProc (__mg_def_proc[0])

Is the default main window callback procedure.

This function is the default main window callback procedure. You should call this function for all messages, you do not want to handle in your main window procedure.

Parameters

hWnd	The handle to the window.
message	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Definition at line 7383 of file window.h.

◆ DefaultVirtualWinProc

#define DefaultVirtualWinProc (__mg_def_proc[3])

The default window callback procedure for virtual windows.

This function is the default window callback procedure for virtual windows. You should call this function for any message which you do not want to handle in your own callback procedure.

Parameters

hWnd	The handle to the window.
message	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

Definition at line 7432 of file window.h.

◆ HWND_DESKTOP

#define HWND_DESKTOP __mg_hwnd_desktop

Desktop window handle.

Definition at line 6742 of file window.h.

◆ HWND_INVALID

#define HWND_INVALID ((HWND)-1)

Invalid window handle.

Definition at line 6754 of file window.h.

◆ HWND_NULL

#define HWND_NULL ((HWND)0)

Null window handle.

Definition at line 6748 of file window.h.

Typedef Documentation

◆ MAINWINCREATE

typedef struct _MAINWINCREATE MAINWINCREATE

Structure defines a main window.

Function Documentation

◆ CreateMainWindow()

HWND GUIAPI CreateMainWindow ( PMAINWINCREATE pCreateInfo )

inlinestatic

A simplified version of CreateMainWindowEx.

This function creates a main window by calling CreateMainWindow function and passing NULL for werdr_name, we_attrs, window_name, and layer_name parameters.

See also: CreateMainWindowEx

Definition at line 7046 of file window.h.

◆ CreateMainWindowEx()

HWND GUIAPI CreateMainWindowEx	(	PMAINWINCREATE	pCreateInfo,
		const char *	werdr_name,
		const WINDOW_ELEMENT_ATTR *	we_attrs,
		const char *	window_name,
		const char *	layer_name
	)

inlinestatic

Creates a main window.

This function creates a main window by using some information, and returns the handle to the main window.

Parameters

pCreateInfo	The pointer to a MAINWINCREATE structure.
werdr_name	The name of window element renderer. NULL for default renderer.
we_attrs	The pointer to window element attribute table. NULL for default window attribute table.
window_name	The window name, ignored currently.
layer_name	The layer name, ignored currently.

Returns: The handle to the new main window; HWND_INVALID indicates an error.

See also: CreateMainWindow, MAINWINCREATE, Window styles

Note

Since 5.0.0, this function is implemented as an inline function calling CreateMainWindowEx2. When calling CreateMainWindowEx2:

We pass 0 for the identifier.
We pass 0xFFFFFFFFUL for the background color.
We discard the values passed to window_name and layer_name.

Example:

/*
 * The following code initializes a MAINWINCREATE struct and then
 * creates a main window.
 */
{
    MAINWINCREATE CreateInfo;
    HWND hWnd;
 
    /* Initialize the MAINWINCREATE structure. */
    CreateInfo.dwStyle = WS_VISIBLE | WS_VSCROLL | WS_HSCROLL | WS_CAPTION;
    CreateInfo.spCaption= "MiniGUI step three";
    CreateInfo.dwExStyle = WS_EX_NONE;
    CreateInfo.hMenu = createmenu();
    CreateInfo.hCursor = GetSystemCursor(0);
    CreateInfo.hIcon = 0;
    CreateInfo.MainWindowProc = MainWinProc;
    CreateInfo.lx = 0;
    CreateInfo.ty = 0;
    CreateInfo.rx = 640;
    CreateInfo.by = 480;
    CreateInfo.iBkColor = COLOR_lightwhite;
    CreateInfo.dwAddData = 0;
    CreateInfo.hHosting = HWND_DESKTOP;
 
    /* Create the main window. */
    hWnd = CreateMainWindow(&CreateInfo);
    if (hWnd == HWND_INVALID)
        return 0;
}

See also: CreateMainWindowEx2

Definition at line 7028 of file window.h.

◆ CreateMainWindowEx2()

HWND GUIAPI CreateMainWindowEx2	(	PMAINWINCREATE	create_info,
		LINT	id,
		const char *	werdr_name,
		const WINDOW_ELEMENT_ATTR *	we_attrs,
		unsigned int	surf_flag,
		DWORD	bkgnd_color,
		int	compos_type,
		DWORD	ct_arg
	)

Creates a main window with specified compositing type and identifier.

This function creates a main window by using information and the specified compositing type and identifier, then returns the handle to the main window.

Parameters

create_info	The pointer to a MAINWINCREATE structure.
werdr_name	The name of window element renderer. NULL for default renderer.
we_attrs	The pointer to window element attribute table. NULL for default window attribute table.
id	The window identifier.
surf_flag	The flag for the surface of the main window under compositing schema. The value of this argument can be one of the following values: ST_PIXEL_DEFAULT Creating a surface which compliant to HDC_SCREEN. ST_PIXEL_ARGB4444 Creating a surface for this main window with the pixel format ARGB4444. ST_PIXEL_ARGB1555 Creating a surface for this main window with the pixel format ARGB1555. ST_PIXEL_ARGB8888 Creating a surface for this main window with the pixel format ARGB8888.
bkgnd_color	The background color of the main window if you specify the main window's surface type other than the default. In this case, you must use this argument to specify the background color of the main window instead of the pixel value of the field (iBkColor) in MAINWINCREATE structure. The value of this field is a 32-bit RGBA quadruple essentially. You can use a value returned by MakeRGBA macro for this argument. Note that if you use the surface type ST_PIXEL_DEFAULT when creating the main window, you can still use the pixel values specified in MAINWINCREATE structure which is compliant to HDC_SCREEN, e.g., a value in SysPixelIndex array.
compos_type	The compositing type of the main window.
ct_arg	The compositing argument of the main window.

Returns: The handle to the new main window; HWND_INVALID indicates an error.

Note: Note When you specify a surface type other than ST_PIXEL_DEFAULT, you must use bkgnd_color to specify the background color of the main window.

See also: CreateMainWindowEx, CreateMainWindow, MAINWINCREATE, Window styles

Example:

/*
 * The following code initializes a MAINWINCREATE struct and then
 * creates a main window.
 */
{
    MAINWINCREATE CreateInfo;
    HWND hWnd;
 
    /* Initialize the MAINWINCREATE structure. */
    CreateInfo.dwStyle = WS_VISIBLE | WS_VSCROLL | WS_HSCROLL | WS_CAPTION;
    CreateInfo.spCaption= "MiniGUI step three";
    CreateInfo.dwExStyle = WS_EX_NONE;
    CreateInfo.hMenu = createmenu();
    CreateInfo.hCursor = GetSystemCursor(0);
    CreateInfo.hIcon = 0;
    CreateInfo.MainWindowProc = MainWinProc;
    CreateInfo.lx = 0;
    CreateInfo.ty = 0;
    CreateInfo.rx = 640;
    CreateInfo.by = 480;
    CreateInfo.iBkColor = COLOR_lightwhite;
    CreateInfo.dwAddData = 0;
    CreateInfo.hHosting = HWND_DESKTOP;
 
    /* Create the main window. */
    hWnd = CreateMainWindow(&CreateInfo);
    if (hWnd == HWND_INVALID)
        return 0;
}

◆ DefaultWindowProc()

LRESULT DefaultWindowProc	(	HWND	hWnd,
		UINT	message,
		WPARAM	wParam,
		LPARAM	lParam
	)

The default window callback procedure.

This window procedure can be used for main windows, dialog boxes, and child windows.

This function is the default window callback procedure. You should call this function for all messages you do not want to handle in your window procedure.

Parameters

hWnd	The handle to the window.
message	The message identifier.
wParam	The first parameter of the message.
lParam	The second parameter of the message.

◆ DestroyMainWindow()

BOOL GUIAPI DestroyMainWindow ( HWND hWnd )

Destroys a main window.

This function destroys the main window specified by hWnd. It does not release all system resource used by the main window. You should call MainWindowThreadCleanup to destroy the main window actually.

Parameters

hWnd	The handle to the main window.

Returns: TRUE on success, FALSE on error.

See also: MainWindowThreadCleanup

Example:

/*
 * The following code destroies all resource used by the main window
 * and then destroies the main window itself.
 */
        case MSG_CLOSE:
            /* Destroy the resource used by the main window. */
            DestroyLogFont (logfont1);
            DestroyLogFont (logfont2);
            DestroyLogFont (logfont3);
 
            /* Destroy the child windows. */
            DestroyWindow(hWndButton);
            DestroyWindow(hWndEdit);
 
            /* Destroy the main window. */
            DestroyMainWindow (hWnd);
 
            /* Send a MSG_QUIT message to quit the message loop. */
            PostQuitMessage(hWnd);
            return 0;

◆ GetMainWinThread()

pthread_t GUIAPI GetMainWinThread ( HWND hMainWnd )

inlinestatic

Get the thread identifier which main window belongs to.

Parameters

hMainWnd The handle to the main window.

Returns: The thread identifier.

Note: Deprecated; use GetThreadByWindow() instead.

Definition at line 6838 of file window.h.

◆ GetWindowRegion()

BOOL GUIAPI GetWindowRegion	(	HWND	hWnd,
		CLIPRGN *	region
	)

The function obtains a copy of the window region of a window.

This function obtains a copy of the window region of a window. The window region of a window is set by calling the SetWindowRegion or SetWindowMaskEx function. The window region determines the area within the window where the system permits drawing. The system does not display any portion of a window that lies outside of the window region.

Parameters

hWnd	Handle to the window whose window region is to be obtained.
region	Pointer to the region which will be modified to represent the window region.

Returns: return TRUE on success, otherwise FALSE.

See also: SetWindowRegion, SetWindowMaskEx

◆ MainWindowCleanup()

BOOL GUIAPI MainWindowCleanup ( HWND hMainWnd )

Cleans up system resource associated with a main window.

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

Parameters

hMainWnd The handle to the main window.

Returns: TRUE on success, otherwise FALSE.

See also: DestroyMainWindow

Note: Since 5.0.0, this function returns a BOOL value. If you try to clean up a main window in a thread other than it belongs to, the function will fail.

Referenced by MainWindowThreadCleanup().

◆ MainWindowThreadCleanup()

BOOL MainWindowThreadCleanup ( HWND hMainWnd )

inlinestatic

Cleanup the main window.

Parameters

hMainWnd The handle to the main window.

Returns: TRUE on success, otherwise FALSE.

Note: Deprecated; please use MainWindowCleanup() instead.

See also: MainWindowCleanup

Definition at line 6908 of file window.h.

References MainWindowCleanup().

◆ RemoveWindowLocalData()

BOOL GUIAPI RemoveWindowLocalData	(	HWND	hwnd,
		const char *	data_name
	)

Remove the local data bound with a name for a window.

This function removes the local data which is bound with the name data_name for the specified window hwnd. When you pass NULL for data_name, this function will remove all local data of the window. Note that this function will call the callback procedure for releasing the local data, if you had set it, when removing the local data.

Parameters

hwnd	The handle to the window, which can be a main window, a virtual window or a control.
data_name	The name for the local data.

Returns: TRUE on success, FALSE on error.

See also: SetWindowLocalData, GetWindowLocalData

Since 5.0.0

◆ SetMainWindowAlwaysTop()

BOOL GUIAPI SetMainWindowAlwaysTop	(	HWND	hWnd,
		BOOL	fSet
	)

Set or cancel a main window being always top.

This function set or cancel a main window being always top on others. If it succeed, the main window will have the style WS_ALWAYSTOP.

Parameters

hWnd	The handle to the window.
fSet	Set or cancel the always top style; TRUE to set, FALSE to cancel.

Returns: TRUE on success, otherwise FALSE.

See also: GetWindowStyle, WS_ALWAYSTOP

Since 5.0.0

◆ SetMainWindowGestureFlags()

BOOL GUIAPI SetMainWindowGestureFlags	(	HWND	hWnd,
		DWORD	dwFlags
	)

Set the gesture flags of a main window.

This function sets the gesture flags of a specific main window.

Generally, a main window which needs a specific gesture should handle MSG_GESTURETEST and call this function to set the correct gesture flags for the main window.

The MiniGUI Core will send the MSG_GESTURETEST message as a notification to a main window when it tries to handle a gesture globally. If the main window sets the flag of the gesture in a specific time, e.g. 100ms, MiniGUI Core will pass the gesture events to the main window other than handle the gesture by itself.

Parameters

hWnd	The handle to the main window.
dwFlags	The new gesture flags, can be OR'd with the following values: GF_SWIPE_HORZ The main window handles horizontal swipe gesture. GF_SWIPE_VERT The main window handles vertical swipe gesture.

Returns: TRUE on success, otherwise FALSE.

See also: MSG_GESTURETEST

Since 5.0.6

◆ SetWindowLocalData()

BOOL GUIAPI SetWindowLocalData	(	HWND	hwnd,
		const char *	data_name,
		DWORD	local_data,
		CB_FREE_LOCAL_DATA	cb_free
	)

Set the local data bound with a name for a window.

This function sets the local data as local_data which is bound with the name data_name for the specified window hwnd. If you passed a non-NULL function pointer for cb_free, the system will call this function to free the local data when you destroy the window, remove the local data, or when you call this function to overwrite the old local data for the name.

Parameters

hwnd	The handle to the window, which can be a main window, a virtual window or a control.
data_name	The name of the local data.
local_data	The value of the local data.
cb_free	A callback function which will be called automatically by the system to free the local data when the window is being destroyed or the local data is being removed or overwritten. If it is NULL, the system does nothing to the local data.

Returns: TRUE on success, FALSE on error.

See also: GetWindowLocalData, RemoveWindowLocalData

Since 5.0.0

◆ SetWindowMask()

BOOL GUIAPI SetWindowMask	(	HWND	hWnd,
		const MYBITMAP *	mask
	)

Set window (a main window, or a child window which is also known as "control")'s Mask Rect with MYBITMAP data.

Parameters

hWnd	The handle to the window.
mask	The mask of the window which indicate the transparency of each pixel on this window.

Returns: return TRUE on success, otherwise FALSE.

See also: SetWindowRegion

◆ SetWindowMaskEx()

BOOL GUIAPI SetWindowMaskEx	(	HWND	hWnd,
		HDC	hdc,
		const BITMAP *	mask
	)

Set window (a main window, or a child window which is also known as "control")'s Mask Rect with BITMAP data,.

Parameters

hWnd	The handle to the window.
hdc	The reference dc which indicate the colorformat of the mask.
mask	The mask of the window which indicate the transparency of each pixel on this window.

Returns: return TRUE on success, otherwise FALSE.

See also: SetWindowRegion

◆ SetWindowRegion()

BOOL GUIAPI SetWindowRegion	(	HWND	hWnd,
		const CLIPRGN *	region
	)

Set window's Mask Rect with CLIPRGN data.

Parameters

hWnd	The handle to the window.
region	The region to indicate which part of the window is visible.

Returns: return TRUE on success, otherwise FALSE.

◆ WaitMainWindowClose()

int GUIAPI WaitMainWindowClose	(	HWND	hWnd,
		void **	retval
	)

Suspend execution of the calling thread which main window belongs to until the target thread terminates, unless the target thread has already terminated.

This function waits for the terminate of the thread which the main window hWnd belongs to by calling the system POSIX thread function pthread_join().

Parameters

hWnd	The handle to the main window.
retval	The buffer used to return the exit code of the target thread.

Returns: The return value of pthread_join (0 on success).

Note: Deprecated; use GetThreadByWindow() and pthread_join() instead.

See also: GetThreadByWindow

Variable Documentation

◆ __mg_def_proc

WNDPROC __mg_def_proc[]

The default window callback procedure array.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ DefaultControlProc

◆ DefaultDialogProc

◆ DefaultMainWinProc

◆ DefaultVirtualWinProc

◆ HWND_DESKTOP

◆ HWND_INVALID

◆ HWND_NULL

Typedef Documentation

◆ MAINWINCREATE

Function Documentation

◆ CreateMainWindow()

◆ CreateMainWindowEx()

◆ CreateMainWindowEx2()

◆ DefaultWindowProc()

◆ DestroyMainWindow()

◆ GetMainWinThread()

◆ GetWindowRegion()

◆ MainWindowCleanup()

◆ MainWindowThreadCleanup()

◆ RemoveWindowLocalData()

◆ SetMainWindowAlwaysTop()

◆ SetMainWindowGestureFlags()

◆ SetWindowLocalData()

◆ SetWindowMask()

◆ SetWindowMaskEx()

◆ SetWindowRegion()

◆ WaitMainWindowClose()

Variable Documentation

◆ __mg_def_proc