Widget functions

Functions
MAWidgetHandle	maWidgetCreate (const char *widgetType)
int	maWidgetDestroy (MAWidgetHandle widget)
int	maWidgetAddChild (MAWidgetHandle parent, MAWidgetHandle child)
int	maWidgetInsertChild (MAWidgetHandle parent, MAWidgetHandle child, int index)
int	maWidgetRemoveChild (MAWidgetHandle child)
int	maWidgetModalDialogShow (MAWidgetHandle dialogHandle)
int	maWidgetModalDialogHide (MAWidgetHandle dialogHandle)
int	maWidgetScreenShow (MAWidgetHandle screenHandle)
int	maWidgetScreenShowWithTransition (MAWidgetHandle screenHandle, MAWScreenTransitionType screenTransitionType, int screenTransitionDuration)
int	maWidgetStackScreenPush (MAWidgetHandle stackScreen, MAWidgetHandle newScreen)
int	maWidgetStackScreenPop (MAWidgetHandle stackScreen)
int	maWidgetSetProperty (MAWidgetHandle widget, const char *property, const char *value)
int	maWidgetGetProperty (MAWidgetHandle widget, const char *property, char *value, int bufSize)
int	maWidgetScreenAddOptionsMenuItem (MAWidgetHandle widget, const char *title, const char *iconPath, int iconPredefined)

---

Detailed Description

The set of functions available for the Widget API.

---

Function Documentation

MAWidgetHandle maWidgetCreate

(

const char *

widgetType

)

Creates a new widget of the specified type.

Note:

See Widget types for the available widget types.

Parameters:

widgetType

A String representing the type of the widget to create.

Returns:

A handle to the widget, or any of the following result codes:

• MAW_RES_ERROR if the widget could not be created.
• MAW_RES_INVALID_TYPE_NAME if the widget type was not available.
• MAW_RES_FEATURE_NOT_AVAILABLE if the widget type is not supported by the curent framework version.

References maIOCtl().

int maWidgetDestroy

(

MAWidgetHandle

widget

)

Frees the memory and resources held by the given widget. Destryoing a widget with children will also cause its children to be destroyed. Once a handle has been destroyed it cannot be referenced by the maWidget* functions.

Note:

If the given widget has a parent, the widget will be removed from its parent.

Parameters:

widget

A handle to the widget to be destroyed.

Returns:

Any of the following result codes:

• MAW_RES_OK if the widget was destroyed.
• MAW_RES_INVALID_HANDLE if the handle was invalid.

References maIOCtl().

int maWidgetAddChild	(	MAWidgetHandle	parent,
		MAWidgetHandle	child
	)

Adds a widget to the given parent as a child. Letting the parent widget layout the child.

Parameters:

parent	The widget layout to which the child will be added.
child	The widget that will be added to the parent.

Returns:

Any of the following result codes:

• MAW_RES_OK if the child could be added to the parent.
• MAW_RES_INVALID_HANDLE if any of the handles were invalid.
• MAW_RES_INVALID_LAYOUT if the widget was added to a non-layout.
• MAW_RES_CANNOT_INSERT_DIALOG if the child is a modal dialog.
• MAW_RES_ERROR if it could not be added for some other reason.

References maIOCtl().

int maWidgetInsertChild	(	MAWidgetHandle	parent,
		MAWidgetHandle	child,
		int	index
	)

Inserts a widget to the given parent as a child at an index. Letting the parent widget layout the child.

Parameters:

parent	The widget layout in which the child will be inserted.
child	The widget that will be added to the parent.
index	The index where the widget should be inserted (-1 means last)

Returns:

Any of the following result codes:

• MAW_RES_OK if the child could be added to the parent.
• MAW_RES_INVALID_HANDLE if any of the handles were invalid.
• MAW_RES_INVALID_INDEX if the index was out of bounds.
• MAW_RES_INVALID_LAYOUT if the widget was added to a non-layout.
• MAW_RES_CANNOT_INSERT_DIALOG if the child is a modal dialog.
• MAW_RES_ERROR if it could not be added for some other reason.

References maIOCtl().

int maWidgetRemoveChild

(

MAWidgetHandle

child

)

Removes a child widget from its parent (but does not destroy it). Removing a currently visible top-level widget causes the MoSync view to become visible.

Returns:

Any of the following result codes:

• MAW_RES_OK if the child could be removed from the parent.
• MAW_RES_INVALID_HANDLE if the handle was invalid.
• MAW_RES_ERROR otherwise.

References maIOCtl().

int maWidgetModalDialogShow

(

MAWidgetHandle

dialogHandle

)

Shows a dialog widget.

Parameters:

dialogHandle

The handle of the dialog that will be shown.

Returns:

Any of the following result codes:

• MAW_RES_OK if the child could be removed from the parent.
• MAW_RES_INVALID_HANDLE if the handle was invalid.
• MAW_RES_ERROR otherwise.

References maIOCtl().

int maWidgetModalDialogHide

(

MAWidgetHandle

dialogHandle

)

Hides/Dismisses a currently displayed dialog.

Parameters:

dialogHandle

The handle of the dialog that will be hidden.

Returns:

Any of the following result codes:

• MAW_RES_OK if the child could be removed from the parent.
• MAW_RES_INVALID_HANDLE if the handle was invalid.
• MAW_RES_ERROR otherwise.

References maIOCtl().

int maWidgetScreenShow

(

MAWidgetHandle

screenHandle

)

Shows a screen. If native UI hasn't been initialized, it is also initialized and disables regular MoSync drawing.

Parameters:

screenHandle

The handle to the screen.

Returns:

Any of the following result codes:

• MAW_RES_OK if the screen could be shown.
• MAW_RES_INVALID_HANDLE if the screenHandle is invalid.
• MAW_RES_INVALID_SCREEN if the screenHandle is not a handle to a screen.

References maIOCtl().

int maWidgetScreenShowWithTransition	(	MAWidgetHandle	screenHandle,
		MAWScreenTransitionType	screenTransitionType,
		int	screenTransitionDuration
	)

Shows a screen with a transition. If native UI hasn't been initialized, it is also initialized and disables regular MoSync drawing.

Parameters:

screenHandle	The handle to the screen.
screenTransitionType	The transition of the screen. See available screen transitions types here .
screenTransitionDuration	The duration of the transition in milliseconds. This argument is not used on the Windows Phone platform due to the constant duration of the WP screen transitions.

Returns:

Any of the following result codes:

• MAW_RES_OK if the screen could be shown.
• MAW_RES_INVALID_HANDLE if the screenHandle is invalid.
• MAW_RES_INVALID_SCREEN if the screenHandle is not a handle to a screen.
• MAW_RES_INVALID_SCREEN_TRANSITION_TYPE if the screen transition type is not available on the running platform.
• MAW_RES_INVALID_SCREEN_TRANSITION_DURATION if the value representing the duration of the screen transition is invalid. This error code is not returned on the Windows Phone platform due to the constant duration of the WP screen transitions.

References maIOCtl().

int maWidgetStackScreenPush	(	MAWidgetHandle	stackScreen,
		MAWidgetHandle	newScreen
	)

Pushes a screen to the given screen stack, hides the current screen and shows the pushed screen it. Pushing it to the stack will make it automatically go back to the previous screen when popped.

Parameters:

stackScreen	A handle to a MAW_STACK_SCREEN.
newScreen	A handle to either a MAW_SCREEN or a MAW_TAB_SCREEN. The handle cannot exist in the stack already.

Returns:

Any of the following result codes:

• MAW_RES_OK if the given screen could be pushed.
• MAW_RES_INVALID_HANDLE if either the screenStack or newScreen handle was invalid.
• MAW_RES_ERROR if something else than a screen stack was passed, or if the handle already exists in the stack.

References maIOCtl().

int maWidgetStackScreenPop

(

MAWidgetHandle

stackScreen

)

Pops a screen from a screen stack, hides the current screen and shows the popped screen before the If there is no previous screen in the screen stack, an empty screen will be shown.

Parameters:

stackScreen

A handle to a MAW_STACK_SCREEN to pop from.

Returns:

Any of the following result codes:

• MAW_RES_OK if the given screen could be popped.
• MAW_RES_INVALID_HANDLE if the screen stack does not exist.
• MAW_RES_ERROR if something else than a screen stack was passed.

References maIOCtl().

int maWidgetSetProperty	(	MAWidgetHandle	widget,
		const char *	property,
		const char *	value
	)

Sets a specified property on the given widget.

Parameters:

widget	Handle to the widget.
property	A string representing which property to set.
value	The value which will be assigned to the property.

Note:

May be synchronous or asynchronous depending on the property.

See Widget properties for the available properties.

Returns:

Any of the following result codes:

• MAW_RES_OK if the property could be set.
• MAW_RES_INVALID_HANDLE if the handle was invalid.
• MAW_RES_INVALID_PROPERTY_NAME if the property name was invalid.
• MAW_RES_INVALID_PROPERTY_VALUE if the property value was invalid.
• MAW_RES_FEATURE_NOT_AVAILABLE if the property is not supported by the curent framework version.
• MAW_RES_ERROR otherwise.

References maIOCtl().

int maWidgetGetProperty	(	MAWidgetHandle	widget,
		const char *	property,
		char *	value,
		int	bufSize
	)

Retrieves a specified property from the given widget.

Parameters:

widget	Handle to the widget.
property	A string representing which property to set.
value	A buffer that will hold the value of the property, represented as a string.
bufSize	Size of the buffer.

Returns:

The number of bytes copied on success, or any of the following result codes:

• MAW_RES_INVALID_HANDLE if the handle was invalid.
• MAW_RES_INVALID_PROPERTY_NAME if the property name was invalid.
• MAW_RES_INVALID_PROPERTY_VALUE if the property value was invalid.
• MAW_RES_INVALID_STRING_BUFFER_SIZE if the buffer size was to small.
• MAW_RES_FEATURE_NOT_AVAILABLE if the property is not supported by the curent framework version.
• MAW_RES_ERROR otherwise.

References maIOCtl().

int maWidgetScreenAddOptionsMenuItem	(	MAWidgetHandle	widget,
		const char *	title,
		const char *	iconPath,
		int	iconPredefined
	)

Add an item to the Options Menu associated to a screen. Available on Android and WP7. The options menu is where you should include actions and other options that are relevant to the current activity context, such as "Search," "Compose email," or "Settings". When opened, the first visible portion is the icon menu, which holds up to six menu items. If your menu includes more than six items, Android places the sixth item and the rest into the overflow menu, which the user can open by selecting More. Those items do not display icons.

Parameters:

widget	Handle to the screen widget.
title	The title associated for the new item. Can be left null.
iconPath	The path to an image or a predefined icon, one of the MAW_OPTIONS_MENU_ICON_CONSTANT_ADD constants. Note that for Windows phone 7 the option menu icons must be added under the following folder structure "/ApplicationBarIcons/". The function is called with the name of the icon file. e.g. maWidgetScreenAddOptionsMenuItem(ScreenHandle, "test", "optionsMenuItemIcon.png", 0); where the file optionsMenuItemIcon.png is found in the folder "/ApplicationBarIcons". Can be left null. On windows phone 7 a null icon means that the item will be a part of the extendable menu item list from the native Application Bar. Specifies if the icon is a project resource, or one of the predefined Android icons. By default it's value is 0.

Returns:

The the item index on success, or any of the following result codes:

• MAW_RES_ERROR
• MAW_RES_INVALID_HANDLE NOTE: Android no longer requires a dedicated Menu button, some devices don’t have one, and you should migrate away from using it. Use #maActionBarAddMenuItem() syscall instead.

References maIOCtl().