Tizen Native API  3.0
Tizen WS Shell Quickpanel

Request to handle the quickpanel service.

Required Header

#include <tzsh_quickpanel.h>

Overview

The Tizen WS Shell Quickpanel API provides functions to handle the quickpanel service.

Functions

tzsh_quickpanel_h tzsh_quickpanel_create (tzsh_h tzsh, tzsh_window win)
 Creates a tzsh_quickpanel_h object which handles the quickpanel service.
int tzsh_quickpanel_destroy (tzsh_quickpanel_h quickpanel)
 Destroys the given tzsh_quickpanel_h object.
int tzsh_quickpanel_show (tzsh_quickpanel_h quickpanel)
 Shows the quickpanel service window if it is currently scrollable.
int tzsh_quickpanel_hide (tzsh_quickpanel_h quickpanel)
 Hides the quickpanel service window.
int tzsh_quickpanel_visible_get (tzsh_quickpanel_h quickpanel, tzsh_quickpanel_state_visible_e *visible)
 Gets the visible state of the quickpanel.
int tzsh_quickpanel_scrollable_set (tzsh_quickpanel_h quickpanel, bool scrollable)
 Sets the scrollable state of a quickpanel service window.
int tzsh_quickpanel_scrollable_get (tzsh_quickpanel_h quickpanel, tzsh_quickpanel_state_scrollable_e *scrollable)
 Checks if the quickpanel service window is scrollable.
int tzsh_quickpanel_orientation_get (tzsh_quickpanel_h quickpanel, tzsh_quickpanel_state_orientation_e *orientation)
 Gets the orientation of the quickpanel.
tzsh_quickpanel_event_handler_h tzsh_quickpanel_event_handler_add (tzsh_quickpanel_h quickpanel, int type, tzsh_quickpanel_event_cb func, void *user_data)
 Adds an event handler.
int tzsh_quickpanel_event_handler_del (tzsh_quickpanel_h quickpanel, tzsh_quickpanel_event_handler_h event_handler)
 Removes the registered event handler.
int tzsh_quickpanel_event_visible_get (tzsh_quickpanel_event_info_h event_info, tzsh_quickpanel_state_visible_e *visible)
 Gets the visible state from given event info.
int tzsh_quickpanel_event_orientation_get (tzsh_quickpanel_event_info_h event_info, tzsh_quickpanel_state_orientation_e *orientation)
 Gets the orientation state from given event info.

Typedefs

typedef struct _tzsh_quickpanel_s * tzsh_quickpanel_h
 Handle for the Tizen quickpanel client.
typedef struct
_tzsh_event_handler_s * 
tzsh_quickpanel_event_handler_h
 Handle for the event handler of the quickpanel.
typedef struct
_tzsh_quickpanel_event_info_s * 
tzsh_quickpanel_event_info_h
 Handle for the event information of the quickpanel.
typedef void(* tzsh_quickpanel_event_cb )(int type, tzsh_quickpanel_event_info_h event_info, void *user_data)
 Called when a quickpanel event occurs.

Typedef Documentation

typedef void(* tzsh_quickpanel_event_cb)(int type, tzsh_quickpanel_event_info_h event_info, void *user_data)

Called when a quickpanel event occurs.

Since :
3.0
Remarks:
The event handle is only valid until the callbacks exits. After the callback exits, the event_info handle is not valid and should not be used.
Parameters:
[in]typeThe event type (TZSH_QUICKPANEL_EVENT_VISIBLE, TZSH_QUICKPANEL_EVENT_ORIENTATION)
[in]event_infoThe tzsh_quickpanel_event_info_h handle
[in]user_dataThe user data
Example
  #include <tzsh_quickpanel.h>

  tzsh_quickpanel_h qp = NULL;
  tzsh_quickpanel_event_handler_h handler[2] = {NULL, NULL};

  static void _cb_vis_changed (int type, tzsh_quickpanel_event_info_h ev_info, void *data)
  {
      tzsh_quickpanel_state_visible_e state;

      if (type != TZSH_QUICKPANEL_EVENT_VISIBLE)
      {
          return;
      }

      tzsh_quickpanel_event_visible_get(ev_info, &state);
      if (state == TZSH_QUICKPANEL_STATE_VISIBLE_SHOWN)
      {
          // quick panel is shown
      }
      else if (state == TZSH_QUICKPANEL_STATE_VISIBLE_HIDDEN)
      {
          // quick panel is hidden
      }
      else
      {
          // quick panel's state is unknown
      }
  }

  static void _cb_orientation_changed(int type, tzsh_quickpanel_event_info_h ev_info, void *data)
  {
      tzsh_quickpanel_state_orientation_e state;

      if (type != TZSH_QUICKPANEL_EVENT_ORIENTATION)
      {
          return;
      }

      tzsh_quickpanel_event_orientation_get(ev_info, &state);
      switch (state)
      {
          case TZSH_QUICKPANEL_STATE_ORIENTATION_0:
              // quickpanel is 0 degree
              break;

          case TZSH_QUICKPANEL_STATE_ORIENTATION_90:
              // quickpanel is 90 degree
              break;

          case TZSH_QUICKPANEL_STATE_ORIENTATION_180:
              // quickpanel is 180 degree
              break;

          case TZSH_QUICKPANEL_STATE_ORIENTATION_270:
              // quickpanel is 270 degree
              break;

          default:
              // quickpanel's degree is unknown
              break;
      }
  }

  void create_window(void)
  {
      ...

      qp = tzsh_quickpanel_create(tzsh, tz_win);
      ...

     handler[0] = tzsh_quickpanel_event_handler_add(qp, TZSH_QUICKPANEL_EVENT_VISIBLE, _cb_vis_changed, NULL);
     handler[1] = tzsh_quickpanel_event_handler_add(qp, TZSH_QUICKPANEL_EVENT_ORIENTATION, _cb_orientation_changed, NULL);
     ...
  }
typedef struct _tzsh_event_handler_s* tzsh_quickpanel_event_handler_h

Handle for the event handler of the quickpanel.

Since :
3.0
typedef struct _tzsh_quickpanel_event_info_s* tzsh_quickpanel_event_info_h

Handle for the event information of the quickpanel.

Since :
3.0
See also:
tzsh_quickpanel_event_visible_get
tzsh_quickpanel_event_orientation_get
typedef struct _tzsh_quickpanel_s* tzsh_quickpanel_h

Handle for the Tizen quickpanel client.

Since :
3.0

Enumeration Type Documentation

Enumeration for orientation state of quickpanel.

Since :
3.0
Enumerator:
TZSH_QUICKPANEL_STATE_ORIENTATION_UNKNOWN 

Unknown state. There is no quickpanel service.

TZSH_QUICKPANEL_STATE_ORIENTATION_0 

0

TZSH_QUICKPANEL_STATE_ORIENTATION_90 

90

TZSH_QUICKPANEL_STATE_ORIENTATION_180 

180

TZSH_QUICKPANEL_STATE_ORIENTATION_270 

270

Enumeration for scrollable state of quickpanel.

Since :
3.0
Enumerator:
TZSH_QUICKPANEL_STATE_SCROLLABLE_UNKNOWN 

Unknown state. There is no quickpanel service.

TZSH_QUICKPANEL_STATE_SCROLLABLE_SET 

Scrollable state.

TZSH_QUICKPANEL_STATE_SCROLLABLE_UNSET 

Not scrollable state.

Enumeration for visible state of quickpanel.

Since :
3.0
Enumerator:
TZSH_QUICKPANEL_STATE_VISIBLE_UNKNOWN 

Unknown state. There is no quickpanel service.

TZSH_QUICKPANEL_STATE_VISIBLE_SHOWN 

Shown state.

TZSH_QUICKPANEL_STATE_VISIBLE_HIDDEN 

Hidden state.


Function Documentation

Creates a tzsh_quickpanel_h object which handles the quickpanel service.

Since :
3.0
Remarks:
The returned handle should be released using tzsh_quickpanel_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_quickpanel_h object on success, NULL otherwise
Exceptions:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
You have to create a tzsh_h instance using tzsh_create() before calling this API. You can get the tzsh_window instance using the toolkit API such as elm_win_window_id_get().
See also:
tzsh_create()
tzsh_quickpanel_destroy()
Example
  #include <tzsh_quickpanel.h>

  tzsh_h tzsh = NULL;
  tzsh_quickpanel_h qp = 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);
      ...

      qp = tzsh_quickpanel_create(tzsh, tz_win);
      ...
  }

Destroys the given tzsh_quickpanel_h object.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
See also:
tzsh_quickpanel_create()
Example
  #include <tzsh_quickpanel.h>

  tzsh_h tzsh = NULL;
  tzsh_quickpanel_h qp = 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);
      ...

      qp = tzsh_quickpanel_create(tzsh, tz_win);
      ...
  }

  void destroy_window(void)
  {
      ...
      tzsh_quickpanel_destroy(qp);
      qp = NULL;
      ...
  }

Adds an event handler.

Since :
3.0
Remarks:
The returned tzsh_quickpanel_event_handler_h object should be released using tzsh_quickpanel_event_handler_del(). The type parameter is the integer of the event type that will trigger this callback to be called. The callback func is called when this event is processed and will be passed the event type, a pointer to the private event structure that is specific to that event type, and a data pointer that is provided in this call as the user_data parameter.
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[in]typeThe event type (TZSH_QUICKPANEL_EVENT_VISIBLE, TZSH_QUICKPANEL_EVENT_ORIENTATION)
[in]funcThe callback function to be called
[in]user_dataThe data passed to the callback function
Returns:
tzsh_quickpanel_event_handler_h instance on success, NULL otherwise
Precondition:
tzsh_quickpanel_create() should be called, to generate event type IDs
See also:
TZSH_QUICKPANEL_EVENT_VISIBLE
TZSH_QUICKPANEL_EVENT_ORIENTATION
tzsh_quickpanel_event_cb()
tzsh_quickpanel_event_handler_del()

Removes the registered event handler.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[in]event_handlerThe tzsh_quickpanel_event_handler_h object
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
See also:
tzsh_quickpanel_event_handler_add()

Gets the orientation state from given event info.

Since :
3.0
Remarks:
This will be used in the event handler for the TZSH_QUICKPANEL_EVENT_ORIENTATION event.
Parameters:
[in]event_infoThe tzsh_quickpanel_event_info_h object
[out]orientationThe orientation state of quickpanel
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
See also:
TZSH_QUICKPANEL_EVENT_ORIENTATION

Gets the visible state from given event info.

Since :
3.0
Remarks:
This will be used in the event handler for the TZSH_QUICKPANEL_EVENT_VISIBLE event.
Parameters:
[in]event_infoThe tzsh_quickpanel_event_info_h object
[out]visibleThe visible state of quickpanel
Returns:
0 on success, otherwise a negative error value
Return values:
TZSH_ERROR_NONESuccessful
TZSH_ERROR_INVALID_PARAMETERInvalid parameter
See also:
TZSH_QUICKPANEL_EVENT_VISIBLE

Hides the quickpanel service window.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_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

Gets the orientation of the quickpanel.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[out]orientationThe orientation of the quickpanel 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

Checks if the quickpanel service window is scrollable.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[out]scrollableThe scrollable state of the quickpanel 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
int tzsh_quickpanel_scrollable_set ( tzsh_quickpanel_h  quickpanel,
bool  scrollable 
)

Sets the scrollable state of a quickpanel service window.

This API is useful when the application does not need to show the quickpanel service window. If the application set the scrollable to false, the quickpanel service window does not show on the display as long as the application window is shown. Default scrollable state of the window is true.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[in]scrollableThe scrollable state
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

Shows the quickpanel service window if it is currently scrollable.

Since :
3.0
Remarks:
If the quickpanel is not scrollable, nothing will happen.
Parameters:
[in]quickpanelThe tzsh_quickpanel_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

Gets the visible state of the quickpanel.

Since :
3.0
Parameters:
[in]quickpanelThe tzsh_quickpanel_h object
[out]visibleThe visible state of the quickpanel 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

Variable Documentation

Tizen event type for the quickpanel orientation.

Since :
3.0
Remarks:
This event occurs when the orientation of the quickpanel service window is changed. The value identifying this event type is generated and written to the TZSH_QUICKPANEL_EVENT_ORIENTATION global variable upon tzsh_quickpanel_create() call. Then this variable can be used to identify a type when setting a callback and checking event type in a callback.

Tizen event type for the quickpanel visible state.

Since :
3.0
Remarks:
This event occurs when the visible state of the quickpanel service window is changed. The value identifying this event type is generated and written to the TZSH_QUICKPANEL_EVENT_VISIBLE global variable upon tzsh_quickpanel_create() call. Then this variable can be used to identify a type when setting a callback and checking event type in a callback.