include/maps_view.h

   1 /*
   2  * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __MAPS_VIEW_H__
  18 #define __MAPS_VIEW_H__
  19
  20 #include <Evas.h>
  21 #include <maps_types.h>
  22 #include <maps_view_event_data.h>
  23 #include <maps_view_snapshot.h>
  24
  25 /**
  26  *
  27  * @ingroup CAPI_MAPS_SERVICE_MODULE
  28  * @defgroup CAPI_MAPS_VIEW_MODULE View
  29  * @addtogroup CAPI_MAPS_VIEW_MODULE
  30  * @{
  31  * @file maps_view.h
  32  * @if WEARABLE
  33  * @section CAPI_MAPS_SERVICE_MODULE_FEATURE Related Features
  34  * This API is related with the following features:\n
  35  *  - http://tizen.org/feature/network.internet\n
  36  * It is recommended to design feature related codes in your application for reliability.\n
  37  * You can check if a device supports the related features for this API by using
  38  * @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
  39  * To ensure your application is only running on the device with specific features,
  40  * please define the features in your manifest file using the manifest editor in the SDK.\n
  41  * More details on featuring your application can be found from
  42  * <a href="https://developer.tizen.org/development/getting-started/native-application/understanding-tizen-programming/application-filtering"><b>Feature List</b>.</a>
  43  * @endif
  44  * @brief This file contains the top level functions of View API.
  45  * @brief This provides APIs related to operations, used in View.
  46  * @details Supported View API features include:
  47  *          * Creating and destroying the View port, moving and resizing it
  48  *          * Changing zoom, and orientation
  49  *          * Changing properties: theme (day, satellite, terrain),
  50  *            language (English, Russian, Chinese, Italian, German, Spanish, etc.)
  51  *          * Converting screen coordinates to geographical and vise versa
  52  *          * Managing user's gestures: receiving user's gesture events, enabling or
  53  *            disabling specified user gestures, assigning View actions, which must be
  54  *            taken in response on user gestures.
  55  */
  56
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62
  63 /**
  64  * @brief Enumeration for View types (themes).
  65  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  66  */
  67 typedef enum _maps_view_type_e {
  68         MAPS_VIEW_TYPE_NORMAL, /**< Indicates the normal street theme */
  69         MAPS_VIEW_TYPE_SATELLITE, /**< Indicates the satellite theme */
  70         MAPS_VIEW_TYPE_TERRAIN, /**< Indicates the terrain theme */
  71         MAPS_VIEW_TYPE_HYBRID, /**< Indicates the hybrid theme, which is the satellite and normal street theme */
  72 } maps_view_type_e;
  73
  74
  75 /**
  76  * @brief Called when requesting the list of visual objects of the View.
  77  * @details This callback is invoked while iterating through the list of visual objects added to the View.
  78  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  79  * @param[in] index The current index of the visual object starts from 0
  80  * @param[in] total The total amount of visual objects
  81  * @param[in] object The visual object
  82  * @param[in] user_data The user data pointer passed from maps_view_foreach_object()
  83  * @return @c true to continue with the next iteration of the loop, \n
  84  *         @c false to break out of the loop
  85  * @pre maps_view_foreach_object() will invoke this callback.
  86  * @see #maps_view_object_h
  87  * @see maps_view_foreach_object()
  88  */
  89 typedef bool(*maps_view_object_cb) (int index, int total, maps_view_object_h object, void *user_data);
  90
  91
  92 /**
  93  * @brief Called when the View event occurs.
  94  * @details The View Panel invokes this callback when the map event occurs.
  95  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  96  * @remarks @a event_data will be released automatically after this callback is terminated.\n
  97  *          To use @a event_data outside this function, clone it with maps_view_event_data_clone().
  98  * @param[in] type The new type of callback, listed in #maps_view_event_type_e
  99  * @param[in] event_data The event data
 100  * @param[in] user_data The user data pointer registered in maps_view_set_event_cb()
 101  * @pre maps_view_set_event_cb() sets the callback.
 102  * @pre maps_view_set_center(),
 103  *      maps_view_set_zoom_level(),
 104  *      maps_view_set_orientation(),
 105  *      invoke the callback with the type #MAPS_VIEW_EVENT_ACTION.
 106  * @see maps_view_set_event_cb()
 107  * @see maps_view_set_center()
 108  * @see maps_view_set_zoom_level()
 109  * @see maps_view_set_orientation()
 110  */
 111 typedef void(*maps_view_on_event_cb) (maps_view_event_type_e type, maps_view_event_data_h event_data, void *user_data);
 112
 113 /* ----------------------CREATE AND DESTROY-----------------------------------*/
 114
 115
 116 /**
 117  * @brief Creates the View and link it to the instance of maps service.
 118  * @details This function creates a new View widget, allocates all needed
 119  *          resources and issues its handle.\n
 120  *          The newly created View is linked to the specified map's service.\n
 121  *          The View by default is resized to fill whole parent area.\n
 122  *          To center the map on a specific geographical coordinates with a desired
 123  *          zoom level and rotation angle, use maps_view_set_center(),
 124  *          maps_view_set_zoom_level(), and maps_view_set_orientation() respectively.\n
 125  *          To change View theme, size, and visibility properties, use
 126  *          maps_view_set_type() and maps_view_set_visibility() respectively.
 127  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 128  * @privlevel public
 129  * @privilege %http://tizen.org/privilege/mapservice
 130  * @remarks The @a View must be released using maps_view_destroy().
 131  * @param[in] maps The maps service handle
 132  * @param[in] obj The evas object to be drawn
 133  * @param[out] view The handle pointer to a maps_view_h, in which to store the newly created View handle
 134  * @return @c 0 on success,
 135  *         otherwise a negative error value
 136  * @retval #MAPS_ERROR_NONE Successful
 137  * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 138  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 139  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 140  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 141  * @pre @a maps is created using maps_service_create().
 142  * @pre @a obj is recommended using a smart object.
 143  * @see maps_view_destroy()
 144  * @see maps_service_create()
 145  * @see maps_view_set_center()
 146  * @see maps_view_set_zoom_level()
 147  * @see maps_view_set_orientation()
 148  * @see maps_view_set_type()
 149  * @see maps_view_set_visibility()
 150  * @see elm_layout_add()
 151  */
 152 int maps_view_create(maps_service_h maps, Evas_Object *obj, maps_view_h *view);
 153
 154
 155 /**
 156  * @brief Destroys the View.
 157  * @details This function destroys the View, releases its handle and
 158  *          all allocated resources, unlinks the View from the instance of maps service.
 159  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 160  * @privlevel public
 161  * @privilege %http://tizen.org/privilege/mapservice
 162  * @param[in] view The View handle to destroy
 163  * @return @c 0 on success,
 164  *         otherwise a negative error value
 165  * @retval #MAPS_ERROR_NONE Successful
 166  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 167  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 168  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 169  * @pre @a View is created using maps_view_create().
 170  * @see maps_view_create()
 171  */
 172 int maps_view_destroy(maps_view_h view);
 173
 174
 175 /*----------------------MAP ZOOM, ROTATE, SET CENTER--------------------------*/
 176
 177
 178 /**
 179  * @brief Centers the map on a given geographical coordinates.
 180  * @details This function centers the map on a given geographical coordinates using current zoom and orientation.
 181  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 182  * @privlevel public
 183  * @privilege %http://tizen.org/privilege/mapservice \n
 184  *            %http://tizen.org/privilege/internet \n
 185  *            %http://tizen.org/privilege/network.get
 186  * @param[in] view The view handle
 187  * @param[in] coordinates The geographical coordinates of the position to be centered on the View
 188  * @return @c 0 on success,
 189  *          otherwise a negative error value
 190  * @retval #MAPS_ERROR_NONE Successful
 191  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 192  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 193  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 194  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 195  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 196  * @pre @a view is created using maps_view_create().
 197  * @pre @a coordinates are created using maps_coordinates_create().
 198  * @see maps_view_get_center()
 199  * @see maps_view_set_zoom_level()
 200  * @see maps_view_set_orientation()
 201  * @see maps_coordinates_create()
 202  * @see maps_view_create()
 203  */
 204 int maps_view_set_center(maps_view_h view, maps_coordinates_h coordinates);
 205
 206
 207 /**
 208  * @brief Gets the central coordinates of a map.
 209  * @details This function gets the current central coordinates of a map.
 210  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 211  * @remarks The @a coordinates must be released using maps_coordinates_destroy().
 212  * @param[in] view The view handle
 213  * @param[out] coordinates The pointer to #maps_coordinates_h in which to
 214  *                         store the geographical coordinates of the central position of the map
 215  * @return @c 0 on success,
 216  *         otherwise a negative error value
 217  * @retval #MAPS_ERROR_NONE Successful
 218  * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 219  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 220  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 221  * @pre @a view is created using maps_view_create().
 222  * @see maps_view_set_center()
 223  * @see maps_view_get_zoom_level()
 224  * @see maps_view_get_orientation()
 225  * @see maps_coordinates_destroy()
 226  * @see maps_view_create()
 227  */
 228 int maps_view_get_center(const maps_view_h view, maps_coordinates_h *coordinates);
 229
 230
 231 /**
 232  * @brief Sets zoom level of the map.
 233  * @details This function sets the integer zoom level of the map.\n
 234  *          If the specified zoom level exceeds the maps Provider allowed zoom range,
 235  *          the function returns #MAPS_ERROR_INVALID_PARAMETER error.\n
 236  *          To check the range of allowed zoom level, use maps_view_get_min_zoom_level()
 237  *          and maps_view_get_max_zoom_level().
 238  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 239  * @privlevel public
 240  * @privilege %http://tizen.org/privilege/mapservice \n
 241  *            %http://tizen.org/privilege/internet \n
 242  *            %http://tizen.org/privilege/network.get
 243  * @param[in] view The view handle
 244  * @param[in] level The new zoom level
 245  * @return @c 0 on success,
 246  *         otherwise a negative error value
 247  * @retval #MAPS_ERROR_NONE Successful
 248  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 250  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 251  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 252  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 253  * @pre @a view is created using maps_view_create().
 254  * @see maps_view_get_zoom_level()
 255  * @see maps_view_set_orientation()
 256  * @see maps_view_get_min_zoom_level()
 257  * @see maps_view_get_max_zoom_level()
 258  * @see maps_view_create()
 259  */
 260 int maps_view_set_zoom_level(maps_view_h view, int level);
 261
 262
 263 /**
 264  * @brief Gets zoom level of the map.
 265  * @details This function gets the current integer zoom level of the map.
 266  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 267  * @param[in] view The view handle
 268  * @param[out] level The pointer to an integer in which to store the current zoom level
 269  * @return @c 0 on success,
 270  *         otherwise a negative error value
 271  * @retval #MAPS_ERROR_NONE Successful
 272  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 273  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 274  * @pre @a view is created using maps_view_create().
 275  * @see maps_view_set_zoom_level()
 276  * @see maps_view_get_min_zoom_level()
 277  * @see maps_view_get_max_zoom_level()
 278  * @see maps_view_create()
 279  */
 280 int maps_view_get_zoom_level(const maps_view_h view, int *level);
 281
 282
 283 /**
 284  * @brief Sets the minimal zoom level of the map.
 285  * @details This function sets the minimally allowed zoom level of the map.
 286  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 287  * @privlevel public
 288  * @privilege %http://tizen.org/privilege/mapservice
 289  * @param[in] view The view handle
 290  * @param[out] level The new minimal zoom level
 291  * @return @c 0 on success,
 292  *         otherwise a negative error value
 293  * @retval #MAPS_ERROR_NONE Successful
 294  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 296  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 297  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 298  * @pre @a view is created using maps_view_create().
 299  * @see maps_view_get_min_zoom_level()
 300  * @see maps_view_set_max_zoom_level()
 301  * @see maps_view_get_max_zoom_level()
 302  * @see maps_view_get_zoom_level()
 303  * @see maps_view_set_zoom_level()
 304  * @see maps_view_create()
 305  */
 306 int maps_view_set_min_zoom_level(maps_view_h view, int level);
 307
 308
 309 /**
 310  * @brief Gets the minimal zoom level of the map.
 311  * @details This function gets the minimally allowed zoom level of the map.
 312  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 313  * @param[in] view The view handle
 314  * @param[out] min_zoom_level The pointer to an integer in which to store the minimally allowed zoom level
 315  * @return @c 0 on success,
 316  *         otherwise a negative error value
 317  * @retval #MAPS_ERROR_NONE Successful
 318  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 320  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 321  * @pre @a view is created using maps_view_create().
 322  * @see maps_view_get_max_zoom_level()
 323  * @see maps_view_get_zoom_level()
 324  * @see maps_view_set_zoom_level()
 325  * @see maps_view_create()
 326  */
 327 int maps_view_get_min_zoom_level(const maps_view_h view, int *min_zoom_level);
 328
 329
 330 /**
 331  * @brief Sets the maximal zoom level of the map.
 332  * @details This function sets the maximally allowed zoom level of the map.
 333  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 334  * @privlevel public
 335  * @privilege %http://tizen.org/privilege/mapservice
 336  * @param[in] view The view handle
 337  * @param[out] level The new maximal zoom level
 338  * @return @c 0 on success,
 339  *         otherwise a negative error value
 340  * @retval #MAPS_ERROR_NONE Successful
 341  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @retval #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 343  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 344  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 345  * @pre @a view is created using maps_view_create().
 346  * @see maps_view_set_min_zoom_level()
 347  * @see maps_view_get_min_zoom_level()
 348  * @see maps_view_get_max_zoom_level()
 349  * @see maps_view_get_zoom_level()
 350  * @see maps_view_set_zoom_level()
 351  * @see maps_view_create()
 352  */
 353 int maps_view_set_max_zoom_level(maps_view_h view, int level);
 354
 355
 356 /**
 357  * @brief Gets the maximal zoom level of the map.
 358  * @details This function gets the maximally allowed zoom level of the map.
 359  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 360  * @param[in] view The view handle
 361  * @param[out] max_zoom_level The pointer to an integer in which to store the maximally allowed zoom level
 362  * @return @c 0 on success,
 363  *         otherwise a negative error value
 364  * @retval #MAPS_ERROR_NONE Successful
 365  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 366  * @retval #MAPS_ERROR_INVALID_OPERATION Operation is not valid
 367  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 368  * @pre @a view is created using maps_view_create().
 369  * @see maps_view_get_min_zoom_level()
 370  * @see maps_view_get_zoom_level()
 371  * @see maps_view_set_zoom_level()
 372  * @see maps_view_create()
 373  */
 374 int maps_view_get_max_zoom_level(const maps_view_h view, int *max_zoom_level);
 375
 376
 377 /**
 378  * @brief Sets the orientation on the View.
 379  * @details This function sets the rotation angle of the View.\n
 380  *          If the specified rotation angle exceeds the [0..360] range, the
 381  *          function returns #MAPS_ERROR_INVALID_PARAMETER error.
 382  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 383  * @privlevel public
 384  * @privilege %http://tizen.org/privilege/mapservice \n
 385  *            %http://tizen.org/privilege/internet \n
 386  *            %http://tizen.org/privilege/network.get
 387  * @param[in] view The view handle
 388  * @param[in] angle The new orientation angle
 389  * @return @c 0 on success,
 390  *         otherwise a negative error value
 391  * @retval #MAPS_ERROR_NONE Successful
 392  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 394  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 395  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 396  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 397  * @pre @a view is created using maps_view_create().
 398  * @see maps_view_get_orientation()
 399  * @see maps_view_set_zoom_level()
 400  * @see maps_view_create()
 401  */
 402 int maps_view_set_orientation(maps_view_h view, double angle);
 403
 404
 405 /**
 406  * @brief Gets the orientation.
 407  * @details This function gets the current map rotation angle on the View.
 408  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 409  * @param[in] view The view handle
 410  * @param[out] rotation_angle The pointer to a double in which to store the current rotation angle
 411  * @return @c 0 on success,
 412  *         otherwise a negative error value
 413  * @retval #MAPS_ERROR_NONE Successful
 414  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 415  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 416  * @pre @a view is created using maps_view_create().
 417  * @see maps_view_set_orientation()
 418  * @see maps_view_get_zoom_level()
 419  * @see maps_view_create()
 420  */
 421 int maps_view_get_orientation(const maps_view_h view, double *rotation_angle);
 422
 423
 424 /*----------------------SCREEN <--> GEOGRAPHY---------------------------------*/
 425
 426
 427 /**
 428  * @brief Converts screen coordinates to the geographical coordinates.
 429  * @details This function converts screen coordinates to the geographical
 430  *          coordinates accordingly to the current map zoom and orientation.
 431  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 432  * @privlevel public
 433  * @privilege %http://tizen.org/privilege/mapservice
 434  * @remarks The @a coordinates must be released using maps_coordinates_destroy().
 435  * @param[in] view The view handle
 436  * @param[in] x The x coordinate on the screen
 437  * @param[in] y The y coordinate on the screen
 438  * @param[out] coordinates The pointer to a #maps_coordinates_h in which to
 439  *                         store the handle of geographical coordinates,
 440  *                         corresponding to given screen coordinates
 441  * @return @c 0 on success,
 442  *         otherwise a negative error value
 443  * @retval #MAPS_ERROR_NONE Successful
 444  * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 445  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 446  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 447  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 448  * @pre @a view is created using maps_view_create().
 449  * @see maps_view_geolocation_to_screen()
 450  * @see #maps_coordinates_h
 451  * @see maps_coordinates_destroy()
 452  * @see maps_view_create()
 453  */
 454 int maps_view_screen_to_geolocation(maps_view_h view, int x, int y, maps_coordinates_h *coordinates);
 455
 456
 457 /**
 458  * @brief Converts geographical coordinates to the screen coordinates.
 459  * @details This function converts geographical coordinates to the screen
 460  *          coordinates accordingly to the current map zoom and orientation.
 461  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 462  * @privlevel public
 463  * @privilege %http://tizen.org/privilege/mapservice
 464  * @param[in] view The view handle
 465  * @param[in] coordinates The geographical coordinates
 466  * @param[out] x The pointer to an integer in which to store the x coordinate on the screen,
 467  *               corresponding to given geographical coordinates
 468  * @param[out] y The pointer to an integer in which to store the y coordinate on the screen,
 469  *               corresponding to given geographical coordinates
 470  * @return @c 0 on success,
 471  *         otherwise a negative error value
 472  * @retval #MAPS_ERROR_NONE Successful
 473  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 474  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 475  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 476  * @pre @a view is created using maps_view_create().
 477  * @pre @a coordinates is created using maps_coordinates_create().
 478  * @see maps_view_screen_to_geolocation()
 479  * @see #maps_coordinates_h
 480  * @see maps_coordinates_create()
 481  * @see maps_view_create()
 482  */
 483 int maps_view_geolocation_to_screen(maps_view_h view, const maps_coordinates_h coordinates, int *x, int *y);
 484
 485
 486 /* --------------------VIEW PREFERENCES----------------------------------*/
 487
 488
 489 /**
 490  * @brief Sets View type.
 491  * @details This function switches the View to a specified type, one of
 492  *          listed in #maps_view_type_e enumeration.
 493  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 494  * @privlevel public
 495  * @privilege %http://tizen.org/privilege/mapservice \n
 496  *            %http://tizen.org/privilege/internet \n
 497  *            %http://tizen.org/privilege/network.get
 498  * @param[in] view The view handle
 499  * @param[in] type The view type, one of listed in #maps_view_type_e
 500  * @return @c 0 on success,
 501  *         otherwise a negative error value
 502  * @retval #MAPS_ERROR_NONE Successful
 503  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 504  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 505  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 506  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 507  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 508  * @pre @a view is created using maps_view_create().
 509  * @see #maps_view_type_e
 510  * @see maps_view_get_type()
 511  * @see maps_view_set_language()
 512  * @see maps_view_create()
 513  */
 514 int maps_view_set_type(maps_view_h view, maps_view_type_e type);
 515
 516
 517 /**
 518  * @brief Gets View type.
 519  * @details This function gets the type of the given View.\n
 520  *          The type options are defined in the #maps_view_type_e enumeration.
 521  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 522  * @param[in] view The view handle
 523  * @param[out] type The pointer to a #maps_view_type_e in which to store current view type
 524  * @return @c 0 on success,
 525  *         otherwise a negative error value
 526  * @retval #MAPS_ERROR_NONE Successful
 527  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 528  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 529  * @pre @a view is created using maps_view_create().
 530  * @see #maps_view_type_e
 531  * @see maps_view_set_type()
 532  * @see maps_view_get_language()
 533  * @see maps_view_create()
 534  */
 535 int maps_view_get_type(const maps_view_h view, maps_view_type_e *type);
 536
 537
 538 /**
 539  * @brief Indicates whether the map should show the 3D buildings layer.
 540  * @details This function is called to indicate whether 3D buildings should be shown as a layer on the map.
 541  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 542  * @privlevel public
 543  * @privilege %http://tizen.org/privilege/mapservice \n
 544  *            %http://tizen.org/privilege/internet \n
 545  *            %http://tizen.org/privilege/network.get
 546  * @remarks To check if Maps Provider is capable of drawing 3D buildings,
 547  *          use maps_service_provider_is_data_supported() with
 548  *          #MAPS_VIEW_BUILDING passed as a service data parameter.
 549  * @param[in] view The view handle
 550  * @param[in] enable The enable status
 551  * @return @c 0 on success,
 552  *         otherwise a negative error value
 553  * @retval #MAPS_ERROR_NONE Successful
 554  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 555  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 556  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 557  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 558  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 559  * @pre @a view is created using maps_view_create().
 560  * @see maps_view_create()
 561  * @see maps_view_get_buildings_enabled()
 562  * @see maps_service_provider_is_data_supported()
 563  */
 564 int maps_view_set_buildings_enabled(maps_view_h view, bool enable);
 565
 566
 567 /**
 568  * @brief Queries whether the map has the 3D buildings layer enabled.
 569  * @details This function checks whether the map is set to show the 3D buildings layer.
 570  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 571  * @param[in] view The view handle
 572  * @param[out] enable The pointer to a boolean in which to store the enable status
 573  * @return @c 0 on success,
 574  *         otherwise a negative error value
 575  * @retval #MAPS_ERROR_NONE Successful
 576  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 577  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 578  * @pre @a view is created using maps_view_create().
 579  * @see maps_view_create()
 580  * @see maps_view_set_buildings_enabled()
 581  * @see maps_service_provider_is_data_supported()
 582  */
 583 int maps_view_get_buildings_enabled(const maps_view_h view, bool *enable);
 584
 585
 586 /**
 587  * @brief Indicates whether the map should show the traffic layer.
 588  * @details This function is called to indicate whether traffic conditions should be shown as a layer on the map.
 589  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 590  * @privlevel public
 591  * @privilege %http://tizen.org/privilege/mapservice \n
 592  *            %http://tizen.org/privilege/internet \n
 593  *            %http://tizen.org/privilege/network.get
 594  * @remarks To check if Maps Provider is capable of drawing traffic conditions,
 595  *          use maps_service_provider_is_data_supported() with
 596  *          #MAPS_VIEW_TRAFFIC passed as a service data parameter.
 597  * @param[in] view The view handle
 598  * @param[in] enable The enable status
 599  * @return @c 0 on success,
 600  *         otherwise a negative error value
 601  * @retval #MAPS_ERROR_NONE Successful
 602  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 603  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 604  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 605  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 606  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 607  * @pre @a view is created using maps_view_create().
 608  * @see maps_view_create()
 609  * @see maps_view_get_traffic_enabled()
 610  * @see maps_service_provider_is_data_supported()
 611  */
 612 int maps_view_set_traffic_enabled(maps_view_h view, bool enable);
 613
 614
 615 /**
 616  * @brief Queries whether the map has the traffic layer enabled.
 617  * @details This function checks whether the map is set to show the traffic layer.
 618  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 619  * @param[in] view The view handle
 620  * @param[out] enable The pointer to a boolean in which to store the enable status
 621  * @return @c 0 on success,
 622  *         otherwise a negative error value
 623  * @retval #MAPS_ERROR_NONE Successful
 624  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 625  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 626  * @pre @a view is created using maps_view_create().
 627  * @see maps_view_create()
 628  * @see maps_view_set_traffic_enabled()
 629  * @see maps_service_provider_is_data_supported()
 630  */
 631 int maps_view_get_traffic_enabled(const maps_view_h view, bool *enable);
 632
 633
 634 /**
 635  * @brief Indicates whether the map should show the public transit layer.
 636  * @details This function is called to indicate whether public transit routes should be shown as a layer on the map.
 637  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 638  * @privlevel public
 639  * @privilege %http://tizen.org/privilege/mapservice \n
 640  *            %http://tizen.org/privilege/internet \n
 641  *            %http://tizen.org/privilege/network.get
 642  * @remarks To check if Maps Provider is capable of drawing public transit routes,
 643  *          use maps_service_provider_is_data_supported() with
 644  *          #MAPS_VIEW_PUBLIC_TRANSIT passed as a service data parameter.
 645  * @param[in] view The view handle
 646  * @param[in] enable The enable status
 647  * @return @c 0 on success,
 648  *         otherwise a negative error value
 649  * @retval #MAPS_ERROR_NONE Successful
 650  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 651  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 652  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 653  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 654  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 655  * @pre @a view is created using maps_view_create().
 656  * @see maps_view_create()
 657  * @see maps_view_get_public_transit_enabled()
 658  * @see maps_service_provider_is_data_supported()
 659  */
 660 int maps_view_set_public_transit_enabled(maps_view_h view, bool enable);
 661
 662
 663 /**
 664  * @brief Queries whether the map has the public transit layer enabled.
 665  * @details This function checks whether the map is set to show the public transit routes layer.
 666  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 667  * @param[in] view The view handle
 668  * @param[out] enable The pointer to a boolean in which to store the enable status
 669  * @return @c 0 on success,
 670  *         otherwise a negative error value
 671  * @retval #MAPS_ERROR_NONE Successful
 672  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 673  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 674  * @pre @a view is created using maps_view_create().
 675  * @see maps_view_create()
 676  * @see maps_view_set_public_transit_enabled()
 677  * @see maps_service_provider_is_data_supported()
 678  */
 679 int maps_view_get_public_transit_enabled(const maps_view_h view, bool *enable);
 680
 681
 682 /**
 683  * @brief Sets View language.
 684  * @details This function sets the language to the given View.\n
 685  *          Note that map display language is different from places and route language.
 686  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 687  * @privlevel public
 688  * @privilege %http://tizen.org/privilege/mapservice \n
 689  *            %http://tizen.org/privilege/internet \n
 690  *            %http://tizen.org/privilege/network.get
 691  * @remarks If specific language wasn't set explicitly or map tile doesn't
 692  *          support the requested language, the default language of your Maps Provider is used.\n
 693  *          In general, Map Provider set the default language as the mother tongue of the country or English.
 694  * @param[in] view The view handle
 695  * @param[in] language The display language in the map.
 696  *                     A language is specified as an ISO 3166 alpha-2 two letter country-code
 697  *                     followed by ISO 639-1 for the two-letter language code.
 698  *                     Each language tag is composed of one or more "subtags" separated by hyphens (-).
 699  *                     Each subtag is composed of basic Latin letters or digits only.
 700  *                     For example, "ko-KR" for Korean, "en-US" for American English
 701  * @return @c 0 on success,
 702  *         otherwise a negative error value
 703  * @retval #MAPS_ERROR_NONE Successful
 704  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 705  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 706  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 707  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 708  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 709  * @pre @a view is created using maps_view_create().
 710  * @see maps_view_get_language()
 711  * @see maps_view_set_type()
 712  * @see maps_view_create()
 713  */
 714 int maps_view_set_language(maps_view_h view, const char *language);
 715
 716
 717 /**
 718  * @brief Gets View language.
 719  * @details This function gets the language set to the View.\n
 720  *          Note that map display language is different from places and route language.
 721  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 722  * @remarks The @a language should be freed using free().
 723  * @param[in] view The view handle
 724  * @param[out] language The pointer to a char* in which to store the language string value
 725  * @return @c 0 on success,
 726  *         otherwise a negative error value
 727  * @retval #MAPS_ERROR_NONE Successful
 728  * @retval #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 729  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 730  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 731  * @pre @a view is created using maps_view_create().
 732  * @see maps_view_set_language()
 733  * @see maps_view_get_type()
 734  * @see maps_view_create()
 735  */
 736 int maps_view_get_language(const maps_view_h view, char **language);
 737
 738
 739 /**
 740  * @brief Enables or disables scalebar.
 741  * @details This function enables or disables scalebar.
 742  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 743  * @privlevel public
 744  * @privilege %http://tizen.org/privilege/mapservice \n
 745  *            %http://tizen.org/privilege/internet \n
 746  *            %http://tizen.org/privilege/network.get
 747  * @param[in] view The view handle
 748  * @param[in] enable The enable status
 749  * @return @c 0 on success,
 750  *         otherwise a negative error value
 751  * @retval #MAPS_ERROR_NONE Successful
 752  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 753  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 754  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 755  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 756  * @retval  #MAPS_ERROR_NOT_SUPPORTED Not supported
 757  * @pre @a view is created using maps_view_create().
 758  * @see maps_view_create()
 759  * @see maps_view_get_scalebar_enabled()
 760  */
 761 int maps_view_set_scalebar_enabled(maps_view_h view, bool enable);
 762
 763
 764 /**
 765  * @brief Gets whether the scalebar is enabled or not.
 766  * @details This function gets whether the scalebar is enabled or not.
 767  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 768  * @param[in] view The view handle
 769  * @param[out] enabled The pointer to a boolean in which to store the enable status
 770  * @return @c 0 on success,
 771  *         otherwise a negative error value
 772  * @retval #MAPS_ERROR_NONE Successful
 773  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 774  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 775  * @pre @a view is created using maps_view_create().
 776  * @see maps_view_create()
 777  * @see maps_view_set_scalebar_enabled()
 778  */
 779 int maps_view_get_scalebar_enabled(const maps_view_h view, bool *enabled);
 780
 781
 782 /* --------------------MAPS PANEL MANIPULATIONS-------------------------------*/
 783
 784
 785 /**
 786  * @brief Gets the View port.
 787  * @details This function gets the View port as a pointer on Evas_Object.
 788  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 789  * @param[in] view The view handle
 790  * @param[out] viewport The pointer to Evas_Object in which to store the View port
 791  * @return @c 0 on success,
 792  *         otherwise a negative error value
 793  * @retval #MAPS_ERROR_NONE Successful
 794  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 795  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 796  * @pre @a view is created using maps_view_create().
 797  * @see maps_view_create()
 798  * @see Evas_Object
 799  */
 800 int maps_view_get_viewport(const maps_view_h view, Evas_Object **viewport);
 801
 802
 803 /**
 804  * @brief Sets geometry of View port.
 805  * @details This function set the position and (rectangular) size of the given View.\n
 806  *          The position, naturally, will be relative to the top left corner of the parent window.
 807  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 808  * @privlevel public
 809  * @privilege %http://tizen.org/privilege/mapservice \n
 810  *            %http://tizen.org/privilege/internet \n
 811  *            %http://tizen.org/privilege/network.get
 812  * @param[in] view The view handle
 813  * @param[in] x X screen coordinate for the top left corner of View
 814  * @param[in] y Y screen coordinate for the top left corner of View
 815  * @param[in] width The new width of View in screen units
 816  * @param[in] height The new height of View in screen units
 817  * @return @c 0 on success,
 818  *         otherwise a negative error value
 819  * @retval #MAPS_ERROR_NONE Successful
 820  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 821  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 822  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 823  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 824  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 825  * @pre @a view is created using maps_view_create().
 826  * @see maps_view_get_screen_location()
 827  * @see maps_view_resize()
 828  * @see maps_view_set_visibility()
 829  * @see maps_view_create()
 830  */
 831 int maps_view_set_screen_location(maps_view_h view, int x, int y, int width, int height);
 832
 833
 834 /**
 835  * @brief Gets geometry of View port.
 836  * @details This function retrieves the position and (rectangular) size of the given View.\n
 837  *          The position, naturally, will be relative to the top left corner of the parent window.
 838  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 839  * @remarks Use NULL pointers on the geometry components you're not interested in.
 840  * @param[in] view The view handle
 841  * @param[out] x X screen coordinate for the top left corner of View
 842  * @param[out] y Y screen coordinate for the left top corner of View
 843  * @param[out] width The pointer to an integer in which to store the width of the view
 844  * @param[out] height The pointer to an integer in which to store the height of the view
 845  * @return @c 0 on success,
 846  *         otherwise a negative error value
 847  * @retval #MAPS_ERROR_NONE Successful
 848  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 849  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 850  * @pre @a view is created using maps_view_create().
 851  * @see maps_view_set_screen_location()
 852  * @see maps_view_resize()
 853  * @see maps_view_get_visibility()
 854  * @see maps_view_create()
 855  */
 856 int maps_view_get_screen_location(const maps_view_h view, int *x, int *y, int *width, int *height);
 857
 858
 859 /**
 860  * @brief Moves the View.
 861  * @details This function moves View.
 862  * @remarks Newly created View port has the size of its parent.
 863  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 864  * @param[in] view The view handle
 865  * @param[in] x The new x position, in screen units
 866  * @param[in] y The new y position, in screen units
 867  * @return @c 0 on success,
 868  *         otherwise a negative error value
 869  * @retval #MAPS_ERROR_NONE Successful
 870  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 871  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 872  * @pre @a view is created using maps_view_create().
 873  * @see maps_view_set_screen_location()
 874  * @see maps_view_get_screen_location()
 875  * @see maps_view_set_visibility()
 876  * @see maps_view_create()
 877  */
 878 int maps_view_move(maps_view_h view, int x, int y);
 879
 880
 881 /**
 882  * @brief Resizes the View.
 883  * @details This function changes the size of the given View.
 884  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 885  * @remarks Newly created View port has the size of its parent.
 886  * @privlevel public
 887  * @privilege %http://tizen.org/privilege/mapservice \n
 888  *            %http://tizen.org/privilege/internet \n
 889  *            %http://tizen.org/privilege/network.get
 890  * @param[in] view The view handle
 891  * @param[in] width The new new width in screen units
 892  * @param[in] height The new new height in screen units
 893  * @return @c 0 on success,
 894  *         otherwise a negative error value
 895  * @retval #MAPS_ERROR_NONE Successful
 896  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 897  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 898  * @retval #MAPS_ERROR_CONNECTION_TIME_OUT Timeout error, no answer
 899  * @retval #MAPS_ERROR_NETWORK_UNREACHABLE Network unavailable
 900  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 901  * @pre @a view is created using maps_view_create().
 902  * @see maps_view_set_screen_location()
 903  * @see maps_view_get_screen_location()
 904  * @see maps_view_set_visibility()
 905  * @see maps_view_create()
 906  */
 907 int maps_view_resize(maps_view_h view, int width, int height);
 908
 909
 910 /**
 911  * @brief Shows or hides the View.
 912  * @details This function changes the visibility of View on the screen.
 913  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 914  * @param[in] view The view handle
 915  * @param[in] visible The new visibility of the View
 916  * @return @c 0 on success,
 917  *         otherwise a negative error value
 918  * @retval #MAPS_ERROR_NONE Successful
 919  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 920  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 921  * @pre @a view is created using maps_view_create().
 922  * @see maps_view_get_visibility()
 923  * @see maps_view_set_screen_location()
 924  * @see maps_view_create()
 925  */
 926 int maps_view_set_visibility(maps_view_h view, bool visible);
 927
 928
 929 /**
 930  * @brief Gets the View visibility.
 931  * @details This function retrieves whether or not the given View is visible.
 932  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 933  * @param[in] view The view handle
 934  * @param[out] visible The pointer to a boolean in which to store the visibility of the View
 935  * @return @c 0 on success,
 936  *         otherwise a negative error value
 937  * @retval #MAPS_ERROR_NONE Successful
 938  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 939  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 940  * @pre @a view is created using maps_view_create().
 941  * @see maps_view_set_visibility()
 942  * @see maps_view_set_screen_location()
 943  * @see maps_view_create()
 944  */
 945 int maps_view_get_visibility(const maps_view_h view, bool *visible);
 946
 947
 948 /* ---------------------UI CONTROL------------------------------------------*/
 949
 950
 951 /**
 952  * @brief Sets the event callback.
 953  * @details This function sets the callback which will be invoked every time the
 954  *          View processes the user's gesture, action, and objects over the map.
 955  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 956  * @remarks To unregister the callback, use maps_view_unset_event_cb().
 957  * @param[in] view The view handle
 958  * @param[in] type The event type
 959  * @param[in] callback The callback, matching the maps_view_on_event_cb() prototype
 960  * @param[in] user_data The user data pointer to be passed to the callback
 961  * @return @c 0 on success,
 962  *         otherwise a negative error value
 963  * @retval #MAPS_ERROR_NONE Successful
 964  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 965  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 966  * @pre @a view is created using maps_view_create().
 967  * @see maps_view_unset_event_cb()
 968  * @see maps_view_on_event_cb()
 969  * @see maps_view_set_gesture_enabled()
 970  * @see maps_view_create()
 971  */
 972 int maps_view_set_event_cb(maps_view_h view, maps_view_event_type_e type, maps_view_on_event_cb callback, void *user_data);
 973
 974
 975 /**
 976  * @brief Unsets the event callback.
 977  * @details This function unsets the event callback.
 978  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 979  * @param[in] view The view handle
 980  * @param[in] type The event type
 981  * @return @c 0 on success,
 982  *         otherwise a negative error value
 983  * @retval #MAPS_ERROR_NONE Successful
 984  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 985  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
 986  * @pre @a view is created using maps_view_create().
 987  * @pre the event callback is registered using maps_view_set_event_cb()
 988  * @see maps_view_set_event_cb()
 989  * @see maps_view_get_gesture_enabled()
 990  * @see maps_view_create()
 991  */
 992 int maps_view_unset_event_cb(maps_view_h view, maps_view_event_type_e type);
 993
 994
 995 /**
 996  * @brief Enables or disables the map gesture.
 997  * @details This function enables or disables the map gesture.
 998  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 999  * @param[in] view The view handle
1000  * @param[in] gesture The user gesture, one listed in #maps_view_gesture_e
1001  * @param[in] enabled The enable status
1002  * @return @c 0 on success,
1003  *         otherwise a negative error value
1004  * @retval #MAPS_ERROR_NONE Successful
1005  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1006  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1007  * @pre @a view is created using maps_view_create().
1008  * @see #maps_view_gesture_e
1009  * @see maps_view_get_gesture_enabled()
1010  * @see maps_view_create()
1011  */
1012 int maps_view_set_gesture_enabled(maps_view_h view, maps_view_gesture_e gesture, bool enabled);
1013
1014
1015 /**
1016  * @brief Checks whether the map gesture is enabled or not.
1017  * @details This function checks whether the map gesture is enabled or not.
1018  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1019  * @param[in] view The view handle
1020  * @param[in] gesture The user gesture, one of listed in #maps_view_gesture_e
1021  * @param[out] enabled The pointer to a boolean in which to store the enable status
1022  * @return @c 0 on success,
1023  *         otherwise a negative error value
1024  * @retval #MAPS_ERROR_NONE Successful
1025  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1026  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1027  * @pre @a view is created using maps_view_create().
1028  * @pre @a enabled status set ad default or modified using
1029  * maps_view_set_gesture_enabled().
1030  * @see #maps_view_gesture_e
1031  * @see maps_view_set_gesture_enabled()
1032  * @see maps_view_create()
1033  */
1034 int maps_view_get_gesture_enabled(const maps_view_h view, maps_view_gesture_e gesture, bool *enabled);
1035
1036
1037 /* ---------------------VISUAL OBJECTS ON THE MAP-----------------------------*/
1038
1039
1040 /**
1041  * @brief Adds a visual object on the map.
1042  * @details This function adds a visual object on the map.
1043  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1044  * @privlevel public
1045  * @privilege %http://tizen.org/privilege/mapservice
1046  * @remarks The @a object handle will be released automatically when the view is destroyed in the maps_view_destroy().
1047  * @param[in] view The view handle
1048  * @param[in] object The handle of the object to add
1049  * @return @c 0 on success,
1050  *         otherwise a negative error value
1051  * @retval #MAPS_ERROR_NONE Successful
1052  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1053  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1054  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1055  * @pre @a view is created using maps_view_create().
1056  * @pre @a object is created using #maps_view_object_create_marker(),
1057  *      maps_view_object_create_polygon(), maps_view_object_create_polyline() or
1058  *      maps_view_object_create_group().
1059  * @see #maps_view_object_h
1060  * @see maps_view_object_create_marker()
1061  * @see maps_view_object_create_polygon()
1062  * @see maps_view_object_create_polyline()
1063  * @see maps_view_remove_object()
1064  * @see maps_view_remove_all_objects()
1065  * @see maps_view_create()
1066  */
1067 int maps_view_add_object(maps_view_h view, maps_view_object_h object);
1068
1069
1070 /**
1071  * @brief Removes a visual object from the map.
1072  * @details This function removes a visual object from the map.
1073  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1074  * @privlevel public
1075  * @privilege %http://tizen.org/privilege/mapservice
1076  * @remarks The @a object handle will be released automatically by the View.
1077  * @param[in] view The view handle
1078  * @param[in] object The object to remove
1079  * @return @c 0 on success,
1080  *         otherwise a negative error value
1081  * @retval #MAPS_ERROR_NONE Successful
1082  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1083  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1084  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1085  * @pre @a view is created using maps_view_create().
1086  * @pre @a object is added using maps_view_add_object().
1087  * @see maps_view_add_object()
1088  * @see maps_view_remove_all_objects()
1089  * @see #maps_view_object_h
1090  * @see maps_view_create()
1091  */
1092 int maps_view_remove_object(maps_view_h view, maps_view_object_h object);
1093
1094
1095 /**
1096  * @brief Removes all visual objects from the map.
1097  * @details This function removes all visual object from the map.
1098  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1099  * @privlevel public
1100  * @privilege %http://tizen.org/privilege/mapservice
1101  * @remarks All object handles will be released automatically by the View.
1102  * @param[in] view The view handle
1103  * @return @c 0 on success,
1104  *         otherwise a negative error value
1105  * @retval #MAPS_ERROR_NONE Successful
1106  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1107  * @retval #MAPS_ERROR_PERMISSION_DENIED Permission Denied
1108  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1109  * @pre @a view is created using maps_view_create().
1110  * @pre objects are added using maps_view_add_object().
1111  * @see #maps_view_object_h
1112  * @see maps_view_add_object()
1113  * @see maps_view_remove_all_objects()
1114  * @see maps_view_create()
1115  */
1116 int maps_view_remove_all_objects(maps_view_h view);
1117
1118
1119 /**
1120  * @brief Retrieves all visual objects on the map.
1121  * @details This function retrieves all visual objects previously added to the map.
1122  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
1123  * @remarks The objects will be delivered via maps_view_object_cb().
1124  * @param[in] view The view handle
1125  * @param[in] callback The callback function to invoke
1126  * @param[in] user_data The user data pointer to be passed to the callback function
1127  * @return @c 0 on success,
1128  *         otherwise a negative error value
1129  * @retval #MAPS_ERROR_NONE Successful
1130  * @retval #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
1131  * @retval #MAPS_ERROR_NOT_FOUND Result not found
1132  * @retval #MAPS_ERROR_NOT_SUPPORTED Not supported
1133  * @pre @a view is created using maps_view_create().
1134  * @pre objects are added using maps_view_add_object().
1135  * @post This function invokes maps_view_object_cb() repeatedly to retrieve each visual object.
1136  * @see #maps_view_object_h
1137  * @see maps_view_object_cb()
1138  * @see maps_view_add_object()
1139  * @see maps_view_remove_object()
1140  * @see maps_view_remove_all_objects()
1141  * @see maps_view_create()
1142  */
1143 int maps_view_foreach_object(const maps_view_h view, maps_view_object_cb callback, void *user_data);
1144
1145
1146 /**
1147  * @}
1148  */
1149
1150 #ifdef __cplusplus
1151 }
1152 #endif
1153 /**
1154  * @}
1155  */
1156 #endif /* __MAPS_VIEW_H__*/