Request to handle the softkey service.

Required Header

#include <tzsh_softkey.h>

Overview

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

The TZSH Softkey is a library for softkey user applications that provides methods to retrieve and modify the status of the Softkey service application.
The TZSH Softkey library offers ways to create and delete tzsh_softkey handles. With this handle, user applications can obtain various states of the softkey service and modify specific status.
For instance, if you want to hide the softkey service window because your app displays information in the softkey service area, you may modify the expand state of the softkey service using this library.

Related Features

Thess APIs are related with the following feature:

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 these APIs 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.

An enumeration type that defines the expand state of a given tzsh softkey service window.

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.

An enumeration type that defines the transparency level of a given tzsh softkey service window.

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.

An enumeration type that defines the visibility state of a given tzsh softkey service window.

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.

This is the creator creator for handler of tzsh_softkey for softkey clients. It creates and returns a handler of the tzsh_softkey using the given tzsh handler and native window to use tzsh_softkey.

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.

Retrieves the expand state of the softkey service window. This is a system global value, so even if called from different softkey clients at the same time, it will return the same result.

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.

Hides the softkey service window. This applies system wide, so even if the active client switches to another softkey client, the softkey service window remains hidden. If the client wants to always show the softkey service window, check its visibility using tzsh_softkey_global_visible_state_get when resumed, then call tzsh_softkey_global_show if needed.

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.

Retrieves the opacity state of the softkey service window. This is a system global value, so even if called from different softkey clients at the same time, it will return the same result.

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.

Shows the softkey service window. This applies system wide, so even if the active client switches to another softkey client, the softkey service window remains shown. If the client wants to always hide the softkey service window, check its visibility using tzsh_softkey_global_visible_state_get when resumed, then call tzsh_softkey_global_hide if needed.

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