Layer operations
[MiniGUI-Processes specific functions]

Defines

• #define NAME_SELF_LAYER   ""

  The name of the self layer.
  

• #define NAME_TOPMOST_LAYER   ""

  The name of the topmost layer.
  

• #define NAME_DEF_LAYER   "mginit"

  The default name of the layer.
  

Functions

• MG_EXPORT GHANDLE GUIAPI JoinLayer (const char *layer_name, const char *client_name, int max_nr_topmosts, int max_nr_normals)

  Joins to a layer.
  

• MG_EXPORT GHANDLE GUIAPI GetLayerInfo (const char *layer_name, int *nr_clients, BOOL *is_topmost, int *cli_active)

  Gets information of a layer by a client.
  

• MG_EXPORT BOOL GUIAPI SetTopmostLayer (BOOL handle_name, GHANDLE handle, const char *name)

  Brings a layer to be the topmost one.
  

• MG_EXPORT BOOL GUIAPI DeleteLayer (BOOL handle_name, GHANDLE handle, const char *layer_name)

  Deletes a specific layer.
  

---

Detailed Description

A client in MiniGUI-Processes can create a new layer or join an existed layer.

Example:

/* 
 * This program tries to create a new layer named "vcongui" if
 * there is no such layer. If there is already a layer named "vcongui",
 * this program brings the layer to be the topmost one.
 */
int MiniGUIMain (int args, const char* arg[])
{
    GHANDLE layer;

    layer = GetLayerInfo ("vcongui", NULL, NULL, NULL);
    if (layer != INV_LAYER_HANDLE) {
        SetTopmostLayer (TRUE, layer, NULL);
        return 0;
    }

    if (JoinLayer ("vcongui", "vcongui", 0, 0) == INV_LAYER_HANDLE) {
        printf ("JoinLayer: invalid layer handle.\n");
        return 1;
    }

    ...

    return 0;
}

---

Define Documentation

#define NAME_DEF_LAYER   "mginit"

The default name of the layer.

Definition at line 398 of file minigui.h.

#define NAME_SELF_LAYER   ""

The name of the self layer.

Definition at line 386 of file minigui.h.

#define NAME_TOPMOST_LAYER   ""

The name of the topmost layer.

Definition at line 392 of file minigui.h.

---

Function Documentation

BOOL GUIAPI DeleteLayer	(	BOOL	handle_name,
		GHANDLE	handle,
		const char *	layer_name
	)

Deletes a specific layer.

Parameters:

	handle_name	The way specifing the layer; TRUE for handle of the layer, FALSE for name.
	handle	The handle to the layer.
	layer_name	The name of the layer. You can use NAME_SELF_LAYER to specify the layer to which the calling client belongs.

Returns:

TRUE for success, FALSE on error.

Note:

Only call this function in clients of MiniGUI-Processes.

See also:

JoinLayer

GHANDLE GUIAPI GetLayerInfo	(	const char *	layer_name,
		int *	nr_clients,
		BOOL *	is_topmost,
		int *	cli_active
	)

Gets information of a layer by a client.

You can get the information of a layer through this function. The information will be returned through the pointer arguments if the specific pointer is not NULL.

Parameters:

	layer_name	The name of the layer. You can use NAME_SELF_LAYER to specify the layer the calling client belongs to.
	nr_clients	The number of clients in the layer will be returned through this pointer.
	is_topmost	A boolean which indicates whether the layer is the topmost layer will be returned.
	cli_active	The identifier of the active client in the layer.

Returns:

Returns the handle to the layer on success, INV_LAYER_HANDLE on error.

Note:

Only call this function in clients of MiniGUI-Processes.

See also:

JoinLayer

GHANDLE GUIAPI JoinLayer	(	const char *	layer_name,
		const char *	client_name,
		int	max_nr_topmosts,
		int	max_nr_normals
	)

Joins to a layer.

This function should be called by clients before calling any other MiniGUI functions. You can call GetLayerInfo to get the layer information. If the layer to be joined does not exist, the server, i.e. mginit, will try to create a new one. If you passed a NULL pointer or a null string for layer_name, the client will join to the default layer.

If the client want to create a new layer, you should specify the maximal number of topmost frame objects (max_nr_topmosts) and the maximal number of normal frame objects (max_nr_normals) in the new layer. Passing zero to max_nr_topmosts and max_nr_normals will use the default values, and the default values are specified by ServerStartup.

Note that the server will create a default layer named "mginit".

Parameters:

	layer_name	The name of the layer.You can use NAME_TOPMOST_LAYER to specify the current topmost layer.
	client_name	The name of the client.
	max_nr_topmosts	The maximal number of topmost z-order nodes in the new layer.
	max_nr_normals	The maximal number of normal z-order nodes in the new layer.

Returns:

The handle to the layer on success, INV_LAYER_HANDLE on error.

Note:

Only call this function in clients of MiniGUI-Processes.

See also:

GetLayerInfo, ServerStartup, ServerCreateLayer

BOOL GUIAPI SetTopmostLayer	(	BOOL	handle_name,
		GHANDLE	handle,
		const char *	name
	)

Brings a layer to be the topmost one.

This function brings the specified layer handle to be the topmost layer.

Parameters:

	handle_name	The way specifing the layer; TRUE for handle of the layer, FALSE for name.
	handle	The handle to the layer.
	name	The name of the layer. You can use NAME_SELF_LAYER to specify the layer to which the calling client belongs.

Returns:

TRUE on success, otherwise FALSE.

Note:

Only call this function in clients of MiniGUI-Processes.