Tizen Native API  5.5
Tizen WS Shell Softkey

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:

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 using features in your application can be found in the 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

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.

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

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

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]tzshThe tzsh_h instance
[in]winThe native window
Returns:
tzsh_softkey_h object on success, NULL otherwise
Exceptions:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist
TZSH_ERROR_OUT_OF_MEMORYOut of memory
TZSH_ERROR_PERMISSION_DENIEDPermission denied
TZSH_ERROR_NOT_SUPPORTEDThe 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
        }
      ...
  }

Destroys the given tzsh_softkey_h object.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NOT_SUPPORTEDThe 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 = 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;
      ...
  }

Gets the global expand state of softkey service window.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object
[out]expandThe global expand state of the softkey service window
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

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]softkeyThe tzsh_softkey_h object
[in]expandThe global expand state of the softkey service window
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

Hides the global softkey service window.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

Gets the global opacity state of a softkey service window.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object
[out]opacityThe global opacity state of the softkey service window
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

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]softkeyThe tzsh_softkey_h object
[in]opacityThe global opacity state of the softkey service window
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

Shows the global softkey service window.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()

Gets the global visible state of a softkey service window.

Since :
5.5
Parameters:
[in]softkeyThe tzsh_softkey_h object
[out]visibleThe global visible state of the softkey service window
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
TZSH_ERROR_NO_SERVICEService does not exist or softkey is NULL
TZSH_ERROR_NOT_SUPPORTEDThe device cannot support this API
See also:
tzsh_create()