Request to handle the softkey service.

Required Header

#include <tzsh_softkey.h>

Overview

The Tizen WS Shell Softkey API provides functions to handle the softkey service.

Related Features

This API is related with the following features:

http://tizen.org/feature/ui_service.softkey

It is recommended to design applications with regard to features, for reliability.

You can check if a device supports the related features for this API by using System Information, and control your application's actions accordingly.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions
tzsh_softkey_h	tzsh_softkey_create (tzsh_h tzsh, tzsh_window win)
	Creates a tzsh_softkey_h object which handle for the softkey client.
int	tzsh_softkey_destroy (tzsh_softkey_h softkey)
	Destroys the given tzsh_softkey_h object.
int	tzsh_softkey_global_show (tzsh_softkey_h softkey)
	Shows the global softkey service window.
int	tzsh_softkey_global_hide (tzsh_softkey_h softkey)
	Hides the global softkey service window.
int	tzsh_softkey_global_visible_state_get (tzsh_softkey_h softkey, tzsh_softkey_state_visible_e *visible)
	Gets the global visible state of a softkey service window.
int	tzsh_softkey_global_expand_state_set (tzsh_softkey_h softkey, tzsh_softkey_state_expand_e expand)
	Sets the global expand state of a softkey service window.
int	tzsh_softkey_global_expand_state_get (tzsh_softkey_h softkey, tzsh_softkey_state_expand_e *expand)
	Gets the global expand state of softkey service window.
int	tzsh_softkey_global_opacity_state_set (tzsh_softkey_h softkey, tzsh_softkey_state_opacity_e opacity)
	Sets the global opacity state of a softkey service window.
int	tzsh_softkey_global_opacity_state_get (tzsh_softkey_h softkey, tzsh_softkey_state_opacity_e *opacity)
	Gets the global opacity state of a softkey service window.
Typedefs
typedef struct _tzsh_softkey_s *	tzsh_softkey_h
	Handle for the Tizen softkey.

Typedef Documentation

typedef struct _tzsh_softkey_s* tzsh_softkey_h

Handle for the Tizen softkey.

Since :: 5.5

Enumeration Type Documentation

enum tzsh_softkey_state_expand_e

Enumeration for expand state of softkey.

Since :: 5.5

Enumerator:

TZSH_SOFTKEY_STATE_EXPAND_UNKNOWN	Unknown state. There is no softkey service.
TZSH_SOFTKEY_STATE_EXPAND_ON	The softkey window is expandable.
TZSH_SOFTKEY_STATE_EXPAND_OFF	The softkey window is not expandable.

enum tzsh_softkey_state_opacity_e

Enumeration for opacity state of softkey.

Since :: 5.5

Enumerator:

TZSH_SOFTKEY_STATE_OPACITY_UNKNOWN	Unknown state. There is no softkey service.
TZSH_SOFTKEY_STATE_OPACITY_OPAQUE	The softkey window is opaque
TZSH_SOFTKEY_STATE_OPACITY_TRANSPARENT	The softkey window is transparent

enum tzsh_softkey_state_visible_e

Enumeration for visible state of softkey.

Since :: 5.5

Enumerator:

TZSH_SOFTKEY_STATE_VISIBLE_UNKNOWN	Unknown state. There is no softkey service.
TZSH_SOFTKEY_STATE_VISIBLE_SHOW	The softkey window is shown.
TZSH_SOFTKEY_STATE_VISIBLE_HIDE	The softkey window is hidden.

Function Documentation

tzsh_softkey_h tzsh_softkey_create	(	tzsh_h	tzsh,
		tzsh_window	win
	)

Creates a tzsh_softkey_h object which handle for the softkey client.

Warning:: This is not for use by third-party applications.

Since :: 5.5

Privilege Level:: platform

Privilege:: http://tizen.org/privilege/windowsystem.admin

Remarks:: The returned handle should be released using tzsh_softkey_destroy(). The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.

Parameters:

[in]	tzsh	The tzsh_h instance
[in]	win	The native window

Returns:: tzsh_softkey_h object on success, NULL otherwise

Exceptions:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist
TZSH_ERROR_OUT_OF_MEMORY	Out of memory
TZSH_ERROR_PERMISSION_DENIED	Permission denied
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

Precondition:: You have to create a tzsh_h instance using tzsh_create() before calling this function. You can get the tzsh_window instance using the toolkit API such as elm_win_window_id_get().

See also:: tzsh_create(); tzsh_softkey_destroy()

Example

  #include <tzsh_softkey.h>

  tzsh_h tzsh = NULL;
  tzsh_softkey_h tz_softkey = NULL;
  Evas_Object *win;

  void init_tzsh(void)
  {
      tzsh = tzsh_create(TZSH_TOOLKIT_TYPE_EFL);
      ...
  }

  void create_window(void)
  {
      tzsh_window tz_win;

      win = elm_win_add(NULL, "sample", ELM_WIN_BASIC);
      ...

      tz_win = elm_win_window_id_get(win);
      ...

      tz_softkey = tzsh_softkey_create(tzsh, tz_win);
      if (tz_softkey == NULL)
        {
           if (get_last_result() == TZSH_ERROR_PERMISSION_DENIED)
             {
                ... // error control code
             }
           else if (get_last_result() == TZSH_ERROR_NOT_SUPPORTED)
             {
                ... // error control code
             }
           ... // other error control code
        }
      ...
  }

int tzsh_softkey_destroy ( tzsh_softkey_h softkey )

Destroys the given tzsh_softkey_h object.

Since :: 5.5

Parameters:

[in] softkey The tzsh_softkey_h object to be destroyed

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_softkey_create()

Example

  #include <tzsh_softkey.h>

  tzsh_h tzsh = NULL;
  tzsh_softkey_h tzsh_softkey = NULL;
  Evas_Object *win;

  void create_window(void)
  {
      tzsh_window tz_win;

      win = elm_win_add(NULL, "sample", ELM_WIN_BASIC);
      ...

      tz_win = (tzsh_window)elm_win_window_id_get(win);
      ...

      tzsh_softkey = tzsh_softkey_create(tzsh, tz_win);
      ...
  }

  void destroy_window(void)
  {
      ...
      tzsh_softkey_destroy(tzsh_softkey);
      tzsh_softkey = NULL;
      ...
  }

int tzsh_softkey_global_expand_state_get	(	tzsh_softkey_h	softkey,
		tzsh_softkey_state_expand_e *	expand
	)

Gets the global expand state of softkey service window.

Since :: 5.5

Parameters:

[in]	softkey	The tzsh_softkey_h object
[out]	expand	The global expand state of the softkey service window

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_expand_state_set	(	tzsh_softkey_h	softkey,
		tzsh_softkey_state_expand_e	expand
	)

Sets the global expand state of a softkey service window.

This function lets the application controls the softkey service window's global expand status. If expand is set to TZSH_SOFTKEY_STATE_EXPAND_OFF, then the softkey service window does not show the expand button. When the expand state is changed to TZSH_SOFTKEY_STATE_EXPAND_ON, the softkey service window shows its expand button and can expand or minimize the softkey service window. This function affects all applications because it sets global expand state. The default expand state of the window is TZSH_SOFTKEY_STATE_EXPAND_ON.

Since :: 5.5

Parameters:

[in]	softkey	The tzsh_softkey_h object
[in]	expand	The global expand state of the softkey service window

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_hide ( tzsh_softkey_h softkey )

Hides the global softkey service window.

Since :: 5.5

Parameters:

[in] softkey The tzsh_softkey_h object

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_opacity_state_get	(	tzsh_softkey_h	softkey,
		tzsh_softkey_state_opacity_e *	opacity
	)

Gets the global opacity state of a softkey service window.

Since :: 5.5

Parameters:

[in]	softkey	The tzsh_softkey_h object
[out]	opacity	The global opacity state of the softkey service window

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_opacity_state_set	(	tzsh_softkey_h	softkey,
		tzsh_softkey_state_opacity_e	opacity
	)

Sets the global opacity state of a softkey service window.

This function can control transparency of the softkey service window.

If opacity is set to TZSH_SOFTKEY_STATE_OPACITY_TRANSPARENT, the softkey service window becomes transparent like a 32-bit color window.

When the opacity state is changed to TZSH_SOFTKEY_STATE_OPACITY_OPAQUE, the softkey service window is shown as an opaque window.

This function affects all applications because it sets global opacity state.

The default opacity state of the window is TZSH_SOFTKEY_STATE_OPACITY_OPAQUE.

Since :: 5.5

Parameters:

[in]	softkey	The tzsh_softkey_h object
[in]	opacity	The global opacity state of the softkey service window

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_show ( tzsh_softkey_h softkey )

Shows the global softkey service window.

Since :: 5.5

Parameters:

[in] softkey The tzsh_softkey_h object

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

int tzsh_softkey_global_visible_state_get	(	tzsh_softkey_h	softkey,
		tzsh_softkey_state_visible_e *	visible
	)

Gets the global visible state of a softkey service window.

Since :: 5.5

Parameters:

[in]	softkey	The tzsh_softkey_h object
[out]	visible	The global visible state of the softkey service window

Returns:: 0 on success, otherwise a negative error value

Return values:

TZSH_ERROR_NONE	Successful
TZSH_ERROR_INVALID_PARAMETER	Invalid parameter
TZSH_ERROR_NO_SERVICE	Service does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTED	The device cannot support this API

See also:: tzsh_create()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation