include/maps_view_object.h

   1 /* Copyright (c) 2010-2014 Samsung Electronics Co., Ltd. All rights reserved.
   2  *
   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
  18 #ifndef __MAPS_VIEW_OBJECT_H__
  19 #define __MAPS_VIEW_OBJECT_H__
  20
  21 #include <Evas.h>
  22 #include <maps_coordinates.h>
  23
  24 /**
  25  * @ingroup     CAPI_MAPS_VIEW_MODULE
  26  * @defgroup    CAPI_MAPS_VIEW_OBJECT_MODULE View Object
  27  *
  28  * @file maps_view_object.h
  29  * @brief This file contains the functions of Map Object API
  30  *
  31  * @addtogroup CAPI_MAPS_VIEW_OBJECT_MODULE
  32  * @{
  33  * @brief This provides APIs related to operations, used in View Object.
  34  * @details Supported Object types are following:
  35  *  - Markers
  36  *  - Polygons
  37  *  - Polylines
  38  *  - Group Objects
  39  *  .
  40  */
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /**
  47  * @brief       The View Object handle
  48  * @details The handle of an arbitrary visual object instance.
  49  * @remarks The handle may be issued with one of following functions:
  50  *  * maps_view_object_create_marker()
  51  *  * maps_view_object_create_polygon()
  52  *  * maps_view_object_create_polyline()
  53  * \n To release the handle use maps_view_object_destroy().
  54  * \n Note that when the object is added to View it will be released
  55  * automatically when the View is destroyed
  56  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  57  *
  58  * @see maps_view_object_destroy()
  59  * @see maps_view_add_object()
  60  */
  61 typedef void *maps_view_object_h;
  62
  63 /**
  64  * @brief       Enumerations of visual object types
  65  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  66  */
  67 typedef enum _maps_view_object_type_e {
  68         MAPS_VIEW_OBJECT_POLYLINE,      /**< Indicates the polyline */
  69         MAPS_VIEW_OBJECT_POLYGON,       /**< Indicates the polygon */
  70         MAPS_VIEW_OBJECT_MARKER,        /**< Indicates the marker */
  71         MAPS_VIEW_OBJECT_OVERLAY,       /**< Indicates the overlay */
  72 } maps_view_object_type_e;
  73
  74 /**
  75  * @brief       Enumerations of map marker types
  76  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  77  */
  78 typedef enum _maps_view_marker_type_e {
  79         MAPS_VIEW_MARKER_PIN,           /**< Indicates the pin marker type */
  80         MAPS_VIEW_MARKER_STICKER,       /**< Indicates the sticker marker type */
  81 } maps_view_marker_type_e;
  82
  83 /**
  84  * @brief       Enumerations of overlay types
  85  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  86  */
  87 typedef enum _maps_view_overlay_type_e {
  88         MAPS_VIEW_OVERLAY_NORMAL,       /**< Indicates the normal type */
  89         MAPS_VIEW_OVERLAY_BUBBLE,       /**< Indicates the bubble type */
  90         MAPS_VIEW_OVERLAY_BOX,          /**< Indicates the box type */
  91 } maps_view_overlay_type_e;
  92
  93 /**
  94  * @brief       Called when requesting the list of points of the polyline.
  95  * @details This callback is invoked while iterating through the list of
  96  * points, added to the polyline.
  97  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
  98  * @remarks @a point must be released using maps_coordinates_destroy().
  99  * \n To use @a point outside this function, clone it with
 100  * maps_coordinates_clone().
 101  *
 102  * @param[in]   index           The current index of path point
 103  * @param[in]   total           The total amount of path points
 104  * @param[in]   point           The point
 105  * @param[in]   user_data       The user data pointer passed from
 106  * maps_view_object_polyline_foreach_point()
 107  * @return      @c true to continue with the next iteration of the loop, \n @c
 108  * false to break out of the loop
 109  *
 110  * @pre maps_view_object_polyline_foreach_point() will invoke this callback.
 111  *
 112  * @see maps_view_object_polyline_foreach_point()
 113  * @see #maps_coordinates_h
 114  */
 115 typedef bool(*maps_view_object_polyline_point_cb) (int index, int total,
 116         maps_coordinates_h point, void *user_data);
 117
 118
 119 /**
 120  * @brief       Called when requesting the list of points of the polygon.
 121  * @details This callback is invoked while iterating through the list of
 122  * points, added to the polygon.
 123  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 124  * @remarks @a point must be released using maps_coordinates_destroy().
 125  * \n To use @a point outside this function, clone it with
 126  * maps_coordinates_clone().
 127  *
 128  * @param[in]   index           The current index of path point
 129  * @param[in]   total           The total amount of path points
 130  * @param[in]   point           The point
 131  * @param[in]   user_data       The user data pointer passed from
 132  * maps_view_object_polygon_foreach_point()
 133  * @return      @c true to continue with the next iteration of the loop, \n @c
 134  * false to break out of the loop
 135  *
 136  * @pre maps_view_object_polygon_foreach_point() will invoke this callback.
 137  *
 138  * @see maps_view_object_polygon_foreach_point()
 139  * @see #maps_coordinates_h
 140  */
 141 typedef bool(*maps_view_object_polygon_point_cb) (int index, int total,
 142         maps_coordinates_h point, void *user_data);
 143
 144
 145 /*----------------------------------------------------------------------------*/
 146 /*
 147  * Common Visual Object Features
 148  */
 149
 150
 151 /**
 152  * @brief       Creates a marker visual object.
 153  * @details This function creates a marker on a given geographical coordinates.
 154  * The marker is specified with a given image file and a type.
 155  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 156  * @remarks @a marker can be released by using maps_view_object_destroy().
 157  * \n If added to the View using maps_view_add_object(), @a marker will be
 158  * released automatically when the View is destroyed.
 159  * \n http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
 160  * \n http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 161  *
 162  * @param[in]   coordinates     The geographical coordinates to add marker on
 163  * @param[in]   image_file_path The file name with the image for the marker
 164  * @param[in]   type            The type of the marker, one of listed in maps_view_marker_type_e
 165  * @param[out]  marker          The handle of newly created marker
 166  * @return      0 on success, otherwise a negative error value
 167  * @retval      #MAPS_ERROR_NONE Successful
 168  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 169  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 171  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 172  *
 173  * @pre @a coordinates are created using map_coordinates_create().
 174  *
 175  * @see #maps_view_object_h
 176  * @see #maps_view_marker_type_e
 177  * @see maps_view_object_create_polygon()
 178  * @see maps_view_object_create_polyline()
 179  * @see maps_view_add_object()
 180  * @see maps_view_object_destroy()
 181  * @see #maps_coordinates_h
 182  */
 183 int maps_view_object_create_marker(maps_coordinates_h coordinates,
 184         const char *image_file_path, maps_view_marker_type_e type, maps_view_object_h *marker);
 185
 186 /**
 187  * @brief       Creates a polyline visual object.
 188  * @details This function creates a polyline visual object, specified
 189  * with a list of geographical coordinates, line width and color.
 190  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 191  * @remarks @a polyline can be released by using maps_view_object_destroy().
 192  * \n If added to the View using maps_view_add_object(), @a polyline will be
 193  * released automatically when the View is destroyed.
 194  *
 195  * @param[in]   coordinates     The list of geographical coordinates
 196  * @param[in]   r               The red component of polyline color [0 ~ 255]
 197  * @param[in]   g               The green component of polyline color [0 ~ 255]
 198  * @param[in]   b               The blue component of polyline color [0 ~ 255]
 199  * @param[in]   a               The alpha component of polyline color [0 ~ 255]
 200  * @param[in]   width           The width of line [1 ~ 100] (pixels)
 201  * @param[out]  polyline        The handle of newly added polyline
 202  * @return      0 on success, otherwise a negative error value
 203  * @retval      #MAPS_ERROR_NONE Successful
 204  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 205  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 207  *
 208  * @pre @a coordinates is created using maps_coordinates_list_create().
 209  *
 210  * @see #maps_view_object_h
 211  * @see maps_view_object_create_marker()
 212  * @see maps_view_object_create_polygon()
 213  * @see maps_view_add_object()
 214  * @see maps_view_object_destroy()
 215  * @see #maps_coordinates_list_h
 216  * @see maps_coordinates_list_create()
 217  */
 218 int maps_view_object_create_polyline(maps_coordinates_list_h coordinates,
 219         unsigned char r, unsigned char g, unsigned char b, unsigned char a,
 220         int width, maps_view_object_h *polyline);
 221
 222 /**
 223  * @brief       Creates a polygon visual object.
 224  * @details This function creates a polygon visual object, specified
 225  * with a list of geographical coordinates and fill color.
 226  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 227  * @remarks @a polygon can be released by using maps_view_object_destroy().
 228  * \n If added to the View using maps_view_add_object(), @a polygon will be
 229  * released automatically when the View is destroyed.
 230  *
 231  * @param[in]   coordinates     The list of geographical coordinates
 232  * @param[in]   r               The red component of polygon background color [0 ~ 255]
 233  * @param[in]   g               The green component of polygon background color [0 ~ 255]
 234  * @param[in]   b               The blue component of polygon background color [0 ~ 255]
 235  * @param[in]   a               The alpha component of polygon background color [0 ~ 255]
 236  * @param[out]  polygon         The handle of newly created polygon
 237  * @return      0 on success, otherwise a negative error value
 238  * @retval      #MAPS_ERROR_NONE Successful
 239  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 240  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 241  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 242  *
 243  * @pre @a coordinates is created using maps_coordinates_list_create().
 244  *
 245  * @see #maps_view_object_h
 246  * @see maps_view_object_create_marker()
 247  * @see maps_view_object_create_polyline()
 248  * @see maps_view_add_object()
 249  * @see maps_view_object_destroy()
 250  * @see #maps_coordinates_list_h
 251  * @see maps_coordinates_list_create()
 252  */
 253 int maps_view_object_create_polygon(maps_coordinates_list_h coordinates,
 254         unsigned char r, unsigned char g, unsigned char b, unsigned char a,
 255         maps_view_object_h *polygon);
 256
 257 /**
 258  * @brief       Creates a overlay object.
 259  * @details This function creates a overlay object to contain Evas objects.
 260  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 261  * @remarks @a overlay can be released by using maps_view_object_destroy().
 262  * \n If added to the View using maps_view_add_object(), @a overlay will be
 263  * released automatically when the View is destroyed.
 264  *
 265  * @param[in]   coordinates     The list of geographical coordinates
 266  * @param[in]   object          The Evas object to be contained
 267  * @param[in]   type            The type of boxing the @a object
 268  * @param[out]  overlay         The handle of newly created polygon
 269  * @return      0 on success, otherwise a negative error value
 270  * @retval      #MAPS_ERROR_NONE Successful
 271  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 272  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 273  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 274  *
 275  * @pre @a coordinates is created using maps_coordinates_list_create().
 276  *
 277  * @see #maps_view_object_h
 278  * @see maps_view_object_create_marker()
 279  * @see maps_view_object_create_polyline()
 280  * @see maps_view_object_create_polygon()
 281  * @see maps_view_add_object()
 282  * @see maps_view_object_destroy()
 283  * @see #maps_coordinates_h
 284  * @see maps_coordinates_create()
 285  */
 286 int maps_view_object_create_overlay(maps_coordinates_h coordinates,
 287         Evas_Object *object, maps_view_overlay_type_e type, maps_view_object_h *overlay);
 288
 289 /**
 290  * @brief       Destroys the object.
 291  * @details This function destroys the object handle and releases all its resources.
 292  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 293  *
 294  * @param[in]   object          The object handle to destroy
 295  * @return      0 on success, otherwise a negative error value
 296  * @retval      #MAPS_ERROR_NONE Successful
 297  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 299  *
 300  * @see #maps_view_object_h
 301  * @see maps_view_object_create_marker()
 302  * @see maps_view_object_create_polygon()
 303  * @see maps_view_object_create_polyline()
 304  */
 305 int maps_view_object_destroy(maps_view_object_h object);
 306
 307 /**
 308  * @brief       Gets the object type.
 309  * @details This function gets the object type.
 310  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 311  *
 312  * @param[in]   object          The object handle
 313  * @param[out]  type            The pointer to #maps_view_object_type_e in which to
 314  * store the object type
 315  * @return      0 on success, otherwise a negative error value
 316  * @retval      #MAPS_ERROR_NONE Successful
 317  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 318  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 319  *
 320  * @pre @a object is created using maps_view_object_create_marker(),
 321  * maps_view_object_create_polyline() or maps_view_object_create_polygon().
 322  *
 323  * @see #maps_view_object_h
 324  * @see maps_view_object_create_marker()
 325  * @see maps_view_object_create_polyline()
 326  * @see maps_view_object_create_polygon()
 327  */
 328 int maps_view_object_get_type(maps_view_object_h object, maps_view_object_type_e *type);
 329
 330 /**
 331  * @brief       Shows the object.
 332  * @details This function changes the visibility of the given object on the View.
 333  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 334  *
 335  * @param[in]   object          The object handle
 336  * @param[in]   visible         The new visibility of the object
 337  * @return      0, otherwise a negative error value
 338  * @retval      #MAPS_ERROR_NONE Successful
 339  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 340  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 341  *
 342  * @pre @a object is created using maps_view_object_create_marker(),
 343  * maps_view_object_create_polyline(), maps_view_object_create_polygon().
 344  *
 345  * @see #maps_view_object_h
 346  * @see maps_view_object_get_visible()
 347  */
 348 int maps_view_object_set_visible(maps_view_object_h object, bool visible);
 349
 350 /**
 351  * @brief       Gets the object visibility.
 352  * @details This function retrieves whether or not the given object is visible.
 353  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 354  *
 355  * @param[in]   object          The object handle
 356  * @param[out]  visible         The pointer to a boolean in which to store the
 357  * object visibility
 358  * @return      0, otherwise a negative error value
 359  * @retval      #MAPS_ERROR_NONE Successful
 360  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 361  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 362  *
 363  * @pre @a object is created using maps_view_object_create_marker(),
 364  * maps_view_object_create_polyline(), maps_view_object_create_polygon().
 365  *
 366  * @see #maps_view_object_h
 367  * @see maps_view_object_set_visible()
 368  */
 369 int maps_view_object_get_visible(const maps_view_object_h object, bool *visible);
 370
 371
 372 /*----------------------------------------------------------------------------*/
 373 /*
 374  * Polyline
 375  */
 376
 377 /**
 378  * @brief       Sets points to the polyline.
 379  * @details This function sets point list to the polyline.
 380  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 381  *
 382  * @param[in]   polyline        The polyline object handle
 383  * @param[in]   points          The points to set
 384  * @return      0 on success, otherwise a negative error value
 385  * @retval      #MAPS_ERROR_NONE Successful
 386  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 387  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 388  *
 389  * @pre @a polyline is created using maps_view_object_create_polyline().
 390  * @pre @a points are created using maps_coordinates_list_create().
 391  * @post Previous points will be destroyed automatically.
 392  *
 393  * @see #maps_view_object_h
 394  * @see #maps_coordinates_list_h
 395  * @see maps_coordinates_list_create()
 396  * @see maps_view_object_create_polyline()
 397  * @see maps_view_object_polyline_foreach_point()
 398  */
 399 int maps_view_object_polyline_set_polyline(maps_view_object_h polyline, maps_coordinates_list_h points);
 400
 401 /**
 402  * @brief       Retrieves all points, added to the polyline.
 403  * @details This function retrieves all points, added to the polyline.
 404  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 405  * @remarks The points will be delivered via maps_view_object_polyline_point_cb().
 406  *
 407  * @param[in]   polyline        The polyline object handle
 408  * @param[in]   callback        The callback function to invoke
 409  * @param[in]   user_data       The user data pointer to be passed to the
 410  * callback function
 411  * @return      0 on success, otherwise a negative error value
 412  * @retval      #MAPS_ERROR_NONE Successful
 413  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 414  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 415  *
 416  * @pre @a polyline is created using maps_view_object_create_polyline().
 417  * @post This function invokes maps_view_object_polyline_point_cb() repeatedly to
 418  * retrieve each point.
 419  *
 420  * @see #maps_view_object_h
 421  * @see maps_view_object_create_polyline()
 422  * @see maps_view_object_polyline_set_polyline()
 423  * @see maps_view_object_polyline_point_cb()
 424  */
 425 int maps_view_object_polyline_foreach_point(maps_view_object_h polyline,
 426         maps_coordinates_cb callback, void *user_data);
 427
 428 /**
 429  * @brief       Sets the polyline color.
 430  * @details This function sets the polyline color on canvas.
 431  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 432  *
 433  * @param[in]   polyline        The polyline object handle
 434  * @param[in]   r               The red component of the color
 435  * @param[in]   g               The green component of the color
 436  * @param[in]   b               The blue component of the color
 437  * @param[in]   a               The alpha component of the color
 438  * @return      0, otherwise a negative error value
 439  * @retval      #MAPS_ERROR_NONE Successful
 440  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 441  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 442  *
 443  * @pre @a polyline is created using maps_view_object_create_polyline().
 444  *
 445  * @see maps_view_object_polyline_get_color()
 446  * @see maps_view_object_polyline_set_width()
 447  * @see maps_view_object_create_polyline()
 448  */
 449 int maps_view_object_polyline_set_color(maps_view_object_h polyline,
 450         unsigned char r, unsigned char g, unsigned char b, unsigned char a);
 451
 452 /**
 453  * @brief       Gets the polyline color.
 454  * @details This function gets the polyline color on canvas.
 455  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 456  *
 457  * @param[in]   polyline        The polyline object handle
 458  * @param[out]  r               The unsigned char pointer in which to store the
 459  * red component of the color, or NULL if not interested
 460  * @param[out]  g               The unsigned char pointer in which to store the
 461  * green component of the color, or NULL if not interested
 462  * @param[out]  b               The unsigned char pointer in which to store the
 463  * blue component of the color, or NULL if not interested
 464  * @param[out]  a               The unsigned char pointer in which to store the
 465  * alpha component of the color, or NULL if not interested
 466  * @return      0, otherwise a negative error value
 467  * @retval      #MAPS_ERROR_NONE Successful
 468  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 469  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 470  *
 471  * @pre @a polyline is created using maps_view_object_create_polyline().
 472  * @pre color components may be previously set using
 473  * maps_view_object_polyline_set_color().
 474  *
 475  * @see maps_view_object_polyline_set_color()
 476  * @see maps_view_object_polyline_get_width()
 477  * @see maps_view_object_create_polyline()
 478  */
 479 int maps_view_object_polyline_get_color(const maps_view_object_h polyline,
 480         unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a);
 481
 482 /**
 483  * @brief       Sets the polyline width.
 484  * @details This function sets the polyline width on canvas.
 485  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 486  *
 487  * @param[in]   polyline        The polyline object handle
 488  * @param[in]   width           The new width of line [1 ~ 100] (pixels)
 489  * @return      0, otherwise a negative error value
 490  * @retval      #MAPS_ERROR_NONE Successful
 491  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 492  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 493  *
 494  * @pre @a polyline is created using maps_view_object_create_polyline().
 495  *
 496  * @see maps_view_object_polyline_get_width()
 497  * @see maps_view_object_polyline_set_color()
 498  * @see maps_view_object_create_polyline()
 499  */
 500 int maps_view_object_polyline_set_width(maps_view_object_h polyline, int width);
 501
 502 /**
 503  * @brief       Gets the polyline width.
 504  * @details This function gets the polyline width on canvas.
 505  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 506  *
 507  * @param[in]   polyline        The polyline object handle
 508  * @param[out]  width           The width of line [1 ~ 100] (pixels)
 509  * @return      0, otherwise a negative error value
 510  * @retval      #MAPS_ERROR_NONE Successful
 511  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 512  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 513  *
 514  * @pre @a polyline is created using maps_view_object_create_polyline().
 515  * @pre @a width may be previously set using maps_view_object_polyline_set_width().
 516  *
 517  * @see maps_view_object_polyline_set_width()
 518  * @see maps_view_object_polyline_get_color()
 519  * @see maps_view_object_create_polyline()
 520  */
 521 int maps_view_object_polyline_get_width(const maps_view_object_h polyline, int *width);
 522
 523
 524 /*----------------------------------------------------------------------------*/
 525 /*
 526  * Polygon
 527  */
 528
 529 /**
 530  * @brief       Sets points to the polygon.
 531  * @details This function sets point list to the polygon.
 532  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 533  *
 534  * @param[in]   polygon         The polygon object handle
 535  * @param[in]   points          The points to set
 536  * @return      0 on success, otherwise a negative error value
 537  * @retval      #MAPS_ERROR_NONE Successful
 538  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 539  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 540  *
 541  * @pre @a polygon is created using maps_view_object_create_polygon().
 542  * @pre @a points are created using maps_coordinates_list_create().
 543  *
 544  * @see maps_view_object_create_polygon()
 545  * @see #maps_view_object_h
 546  * @see #maps_coordinates_list_h
 547  * @see maps_coordinates_list_create()
 548  * @see maps_view_object_polygon_foreach_point()
 549  */
 550 int maps_view_object_polygon_set_polygon(maps_view_object_h polygon, maps_coordinates_list_h points);
 551
 552 /**
 553  * @brief       Retrieves all points, added to the polygon.
 554  * @details This function retrieves all points, added to the polygon.
 555  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 556  * @remarks The objects will be delivered via maps_view_object_polygon_point_cb().
 557  *
 558  * @param[in]   polygon         The polygon object handle
 559  * @param[in]   callback        The callback function to invoke
 560  * @param[in]   user_data       The user data to be passed to the callback function
 561  * @return      0 on success, otherwise a negative error value
 562  * @retval      #MAPS_ERROR_NONE Successful
 563  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 564  * @retval      #MAPS_ERROR_NOT_FOUND Result not found
 565  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 566  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 567  *
 568  * @pre @a polygon is created using maps_view_object_create_polygon().
 569  * @post This function invokes maps_view_object_polygon_point_cb() repeatedly to
 570  * retrieve each point.
 571  *
 572  * @see maps_view_object_polygon_point_cb()
 573  * @see maps_view_object_create_polygon()
 574  * @see #maps_view_object_h
 575  * @see maps_view_object_polygon_set_polygon()
 576  */
 577 int maps_view_object_polygon_foreach_point(maps_view_object_h polygon,
 578         maps_coordinates_cb callback, void *user_data);
 579
 580 /**
 581  * @brief       Sets polygon fill color.
 582  * @details This function sets the polygon fill color on canvas.
 583  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 584  *
 585  * @param[in]   polygon         The polygon object handle
 586  * @param[in]   r               The red component of the fill color
 587  * @param[in]   g               The green component of the fill color
 588  * @param[in]   b               The blue component of the fill color
 589  * @param[in]   a               The alpha component of the fill color
 590  * @return      0, otherwise a negative error value
 591  * @retval      #MAPS_ERROR_NONE Successful
 592  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 593  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 594  *
 595  * @pre @a polygon is created using maps_view_object_create_polygon().
 596  *
 597  * @see maps_view_object_polygon_get_fill_color()
 598  * @see maps_view_object_create_polygon()
 599  */
 600 int maps_view_object_polygon_set_fill_color(maps_view_object_h polygon,
 601         unsigned char r, unsigned char g, unsigned char b, unsigned char a);
 602
 603 /**
 604  * @brief       Gets polygon fill color.
 605  * @details This function gets the polygon fill color on canvas.
 606  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 607  *
 608  * @param[in]   polygon         The polygon data handle
 609  * @param[in]   r               The unsigned char pointer in which to store the
 610  * red component of the background color
 611  * @param[in]   g               The unsigned char pointer in which to store the
 612  * green component of the background color
 613  * @param[in]   b               The unsigned char pointer in which to store the
 614  * blue component of the background color
 615  * @param[in]   a               The unsigned char pointer in which to store the
 616  * alpha component of the background color
 617  * @return      0, otherwise a negative error value
 618  * @retval      #MAPS_ERROR_NONE Successful
 619  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 620  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 621  *
 622  * @pre @a polygon is created using maps_view_object_create_polygon().
 623  * @pre fill color components may be previously set using
 624  * maps_view_object_polygon_set_fill_color().
 625  *
 626  * @see maps_view_object_polygon_set_fill_color()
 627  * @see maps_view_object_create_polygon()
 628  */
 629 int maps_view_object_polygon_get_fill_color(const maps_view_object_h polygon,
 630         unsigned char *r, unsigned char *g, unsigned char *b, unsigned char *a);
 631
 632
 633 /*----------------------------------------------------------------------------*/
 634 /*
 635  * Marker
 636  */
 637
 638 /**
 639  * @brief       Sets the marker coordinates.
 640  * @details This function sets the marker geographical coordinates.
 641  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 642  *
 643  * @param[in]   marker          The marker object handle
 644  * @param[in]   coordinates     The marker geographical coordinates handle
 645  * @return      0, otherwise a negative error value
 646  * @retval      #MAPS_ERROR_NONE Successful
 647  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 648  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 649  *
 650  * @pre @a marker is created using maps_view_object_create_marker().
 651  * @pre @a coordinates are created using maps_coordinates_create().
 652  *
 653  * @see maps_view_object_create_marker()
 654  * @see maps_view_object_marker_get_coordinates()
 655  * @see #maps_coordinates_h
 656  * @see maps_coordinates_create()
 657  */
 658 int maps_view_object_marker_set_coordinates(maps_view_object_h marker, maps_coordinates_h coordinates);
 659
 660 /**
 661  * @brief       Sets the marker screen size.
 662  * @details This function sets the marker screen size.
 663  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 664  * @remark      To make the marker size proportionally, use 0 as the value for the @a width or @a height paramter.
 665  * For instance, to make the width of an marker 150 pixels, and change the height using the same proportion,
 666  * use maps_view_object_marker_resize(marker, 150, 0).
 667  *
 668  * @param[in]   marker  The marker object handle
 669  * @param[in]   width   The resized marker pixels in width on the screen
 670  * @param[in]   height  The resized marker pixels in height on the screen
 671  * @return      0, otherwise a negative error value
 672  * @retval      #MAPS_ERROR_NONE Successful
 673  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 674  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 675  *
 676  * @pre @a marker is created using maps_view_object_create_marker().
 677  *
 678  * @see maps_view_object_create_marker()
 679  * @see maps_view_object_marker_get_size()
 680  */
 681 int maps_view_object_marker_resize(maps_view_object_h marker, int width, int height);
 682
 683 /**
 684  * @brief       Sets the marker image file path.
 685  * @details This function sets the marker image file path.
 686  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 687  * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
 688  * \n http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 689  *
 690  * @param[in]   marker          The marker object handle
 691  * @param[in]   file_path       The marker image file path
 692  * @return      0, otherwise a negative error value
 693  * @retval      #MAPS_ERROR_NONE Successful
 694  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 695  * @retval      #MAPS_ERROR_PERMISSION_DENIED Permission Denied
 696  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 697  *
 698  * @pre @a marker is created using maps_view_object_create_marker().
 699  *
 700  * @see maps_view_object_marker_get_image_file()
 701  * @see maps_view_object_create_marker()
 702  */
 703 int maps_view_object_marker_set_image_file(maps_view_object_h marker, const char *file_path);
 704
 705 /**
 706  * @brief       Gets the marker image file path.
 707  * @details This function gets the marker image file path.
 708  * @remarks The @a file_path should be freed using free().
 709  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 710  *
 711  * @param[in]   marker          The marker object handle
 712  * @param[out]  file_path       The marker image file path
 713  * @return      0, otherwise a negative error value
 714  * @retval      #MAPS_ERROR_NONE Successful
 715  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 716  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 717  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 718  *
 719  * @pre @a marker is created using maps_view_object_create_marker().
 720  * @pre @a file_path may be set previously using maps_view_object_marker_set_image_file().
 721  *
 722  * @see maps_view_object_marker_set_image_file()
 723  * @see maps_view_object_create_marker()
 724  */
 725 int maps_view_object_marker_get_image_file(const maps_view_object_h marker, char **file_path);
 726
 727 /**
 728  * @brief       Gets the marker coordinates.
 729  * @details This function gets the marker geographical coordinates.
 730  * @remarks The @a coordinates should be freed using maps_coordinates_destroy().
 731  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 732  *
 733  * @param[in]   marker          The marker object handle
 734  * @param[out]  coordinates     The pointer to #maps_coordinates_h in which to
 735  * store the marker geographical coordinates
 736  * @return      0, otherwise a negative error value
 737  * @retval      #MAPS_ERROR_NONE Successful
 738  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 739  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 740  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 741  *
 742  * @pre @a marker is created using maps_view_object_create_marker().
 743  * @pre @a coordinates may be set previously using maps_view_object_marker_set_coordinates().
 744  *
 745  * @see maps_view_object_marker_set_coordinates()
 746  * @see #maps_coordinates_h
 747  * @see maps_view_object_create_marker()
 748  */
 749 int maps_view_object_marker_get_coordinates(const maps_view_object_h marker, maps_coordinates_h *coordinates);
 750
 751 /**
 752  * @brief       Gets the marker screen size.
 753  * @details This function gets the marker size on the screen.
 754  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 755  *
 756  * @param[in]   marker          The marker object handle
 757  * @param[out]  width           The pointer to an integer in which to store the
 758  * marker width on the screen in pixels
 759  * @param[out]  height          The pointer to an integer in which to store the
 760  * marker height on the screen in pixels
 761  * @return      0, otherwise a negative error value
 762  * @retval      #MAPS_ERROR_NONE Successful
 763  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 764  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 765  *
 766  * @pre @a marker is created using maps_view_object_create_marker().
 767  * @pre @a width and @a height may be set previously using maps_view_object_marker_resize().
 768  *
 769  * @see maps_view_object_marker_resize()
 770  * @see maps_view_object_create_marker()
 771  */
 772 int maps_view_object_marker_get_size(const maps_view_object_h marker, int *width, int *height);
 773
 774 /**
 775  * @brief       Gets the marker type.
 776  * @details This function gets the marker type.
 777  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 778  *
 779  * @param[in]   marker          The marker object handle
 780  * @param[out]  type            The pointer to a maps_view_marker_type_e in which to
 781  * store the marker type
 782  * @return      0, otherwise a negative error value
 783  * @retval      #MAPS_ERROR_NONE Successful
 784  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 785  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 786  *
 787  * @pre @a marker is created using maps_view_object_create_marker().
 788  *
 789  * @see #maps_view_marker_type_e
 790  * @see maps_view_object_create_marker()
 791  */
 792 int maps_view_object_marker_get_type(const maps_view_object_h marker, maps_view_marker_type_e *type);
 793
 794 /**
 795  * @brief       Sets the marker z-order.
 796  * @details This function sets the z-order.
 797  * @remarks The @a z_order must be in range of [-100, 100].
 798  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 799  *
 800  * @param[in]   marker          The marker object handle
 801  * @param[in]   z_order         The z-order
 802  * @return      0, otherwise a negative error value
 803  * @retval      #MAPS_ERROR_NONE Successful
 804  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 805  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 806  *
 807  * @pre @a marker is created using maps_view_object_create_marker().
 808  *
 809  * @see maps_view_object_create_marker()
 810  * @see maps_view_object_marker_get_z_order()
 811  */
 812 int maps_view_object_marker_set_z_order(maps_view_object_h marker, int z_order);
 813
 814 /**
 815  * @brief       Gets the marker z-order.
 816  * @details This function gets the z-order.
 817  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 818  *
 819  * @param[in]   marker          The marker object handle
 820  * @param[out]  z_order         The z-order
 821  * @return      0, otherwise a negative error value
 822  * @retval      #MAPS_ERROR_NONE Successful
 823  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 824  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 825  *
 826  * @pre @a marker is created using maps_view_object_create_marker().
 827  *
 828  * @see maps_view_object_create_marker()
 829  * @see maps_view_object_marker_set_z_order()
 830  */
 831 int maps_view_object_marker_get_z_order(const maps_view_object_h marker, int *z_order);
 832
 833
 834
 835 /*----------------------------------------------------------------------------*/
 836 /*
 837  * Overlay
 838  */
 839
 840 /**
 841  * @brief       Gets the Evas object.
 842  * @details This function gets the Evas object.
 843  * @remarks The @a object must not be released.
 844  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 845  *
 846  * @param[in]   overlay         The overlay object handle
 847  * @param[out]  object          The Evas object handle
 848  * @return      0, otherwise a negative error value
 849  * @retval      #MAPS_ERROR_NONE Successful
 850  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 851  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 852  *
 853  * @pre @a marker is created using maps_view_object_create_overlay().
 854  *
 855  * @see maps_view_object_create_overlay()
 856  */
 857 int maps_view_object_overlay_get_object(maps_view_object_h overlay, Evas_Object **object);
 858
 859 /**
 860  * @brief       Sets the overlay coordinates.
 861  * @details This function sets the overlay geographical coordinates.
 862  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 863  *
 864  * @param[in]   overlay         The overlay object handle
 865  * @param[in]   coordinates     The overlay geographical coordinates handle
 866  * @return      0, otherwise a negative error value
 867  * @retval      #MAPS_ERROR_NONE Successful
 868  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 869  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 870  *
 871  * @pre @a overlay is created using maps_view_object_create_overlay().
 872  * @pre @a coordinates are created using maps_coordinates_create().
 873  *
 874  * @see maps_view_object_create_overlay()
 875  * @see maps_view_object_overlay_get_coordinates()
 876  * @see #maps_coordinates_h
 877  * @see maps_coordinates_create()
 878  */
 879 int maps_view_object_overlay_set_coordinates(maps_view_object_h overlay, maps_coordinates_h coordinates);
 880
 881 /**
 882  * @brief       Gets the overlay coordinates.
 883  * @details This function gets the overlay geographical coordinates.
 884  * @remarks The @a coordinates should be freed using maps_coordinates_destroy().
 885  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 886  *
 887  * @param[in]   overlay         The overlay object handle
 888  * @param[out]  coordinates     The pointer to #maps_coordinates_h in which to
 889  * store the overlay geographical coordinates
 890  * @return      0, otherwise a negative error value
 891  * @retval      #MAPS_ERROR_NONE Successful
 892  * @retval      #MAPS_ERROR_OUT_OF_MEMORY Out of memory
 893  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 894  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 895  *
 896  * @pre @a overlay is created using maps_view_object_create_overlay().
 897  * @pre @a coordinates may be set previously using maps_view_object_overlay_set_coordinates().
 898  *
 899  * @see maps_view_object_create_overlay()
 900  * @see maps_view_object_overlay_set_coordinates()
 901  * @see #maps_coordinates_h
 902  * @see maps_coordinates_destroy()
 903  */
 904 int maps_view_object_overlay_get_coordinates(const maps_view_object_h overlay, maps_coordinates_h *coordinates);
 905
 906 /**
 907  * @brief       Sets the minimal zoom level for overlay.
 908  * @details This function sets the minimally allowed zoom level of the map to show the overlay.
 909  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 910  *
 911  * @param[in]   overlay         The overlay object handle
 912  * @param[in]   zoom            The new minimal zoom level
 913  * @return      0, otherwise a negative error value
 914  * @retval      #MAPS_ERROR_NONE Successful
 915  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 916  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 917  *
 918  * @pre @a overlay is created using maps_view_object_create_overlay().
 919  *
 920  * @see maps_view_object_create_overlay()
 921  * @see maps_view_object_overlay_get_min_zoom_level()
 922  * @see maps_view_object_overlay_set_max_zoom_level()
 923  * @see maps_view_object_overlay_get_max_zoom_level()
 924  */
 925 int maps_view_object_overlay_set_min_zoom_level(maps_view_object_h overlay, int zoom);
 926
 927 /**
 928  * @brief       Gets the minimal zoom level for overlay.
 929  * @details This function gets the minimally allowed zoom level of the map to show the overlay.
 930  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 931  *
 932  * @param[in]   overlay         The overlay object handle
 933  * @param[out]  zoom            The pointer to an integer in which to store
 934  * the minimally allowed zoom level.
 935  * @return      0, otherwise a negative error value
 936  * @retval      #MAPS_ERROR_NONE Successful
 937  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 938  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 939  *
 940  * @pre @a overlay is created using maps_view_object_create_overlay().
 941  *
 942  * @see maps_view_object_create_overlay()
 943  * @see maps_view_object_overlay_set_min_zoom_level()
 944  * @see maps_view_object_overlay_set_max_zoom_level()
 945  * @see maps_view_object_overlay_get_max_zoom_level()
 946  */
 947 int maps_view_object_overlay_get_min_zoom_level(const maps_view_object_h overlay, int *zoom);
 948
 949 /**
 950  * @brief       Sets the minimal zoom level for overlay.
 951  * @details This function sets the minimally allowed zoom level of the map to show the overlay.
 952  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 953  *
 954  * @param[in]   overlay         The overlay object handle
 955  * @param[in]   zoom            The new minimal zoom level
 956  * @return      0, otherwise a negative error value
 957  * @retval      #MAPS_ERROR_NONE Successful
 958  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 959  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 960  *
 961  * @pre @a overlay is created using maps_view_object_create_overlay().
 962  *
 963  * @see maps_view_object_create_overlay()
 964  * @see maps_view_object_overlay_get_min_zoom_level()
 965  * @see maps_view_object_overlay_set_min_zoom_level()
 966  * @see maps_view_object_overlay_get_max_zoom_level()
 967  */
 968 int maps_view_object_overlay_set_max_zoom_level(maps_view_object_h overlay, int zoom);
 969
 970 /**
 971  * @brief       Gets the minimal zoom level for overlay.
 972  * @details This function gets the minimally allowed zoom level of the map to show the overlay.
 973  * @since_tizen @if MOBILE 3.0 @elseif WEARABLE 2.3.2 @endif
 974  *
 975  * @param[in]   overlay         The overlay object handle
 976  * @param[out]  zoom            The pointer to an integer in which to store
 977  * the minimally allowed zoom level.
 978  * @return      0, otherwise a negative error value
 979  * @retval      #MAPS_ERROR_NONE Successful
 980  * @retval      #MAPS_ERROR_INVALID_PARAMETER Invalid parameter
 981  * @retval      #MAPS_ERROR_NOT_SUPPORTED Not supported
 982  *
 983  * @pre @a overlay is created using maps_view_object_create_overlay().
 984  *
 985  * @see maps_view_object_create_overlay()
 986  * @see maps_view_object_overlay_get_min_zoom_level()
 987  * @see maps_view_object_overlay_set_min_zoom_level()
 988  * @see maps_view_object_overlay_set_max_zoom_level()
 989  */
 990 int maps_view_object_overlay_get_max_zoom_level(const maps_view_object_h overlay, int *zoom);
 991
 992 #ifdef __cplusplus
 993 }
 994 #endif
 995 /**
 996  * @}
 997  */
 998 #endif                          /* __MAPS_VIEW_OBJECT_H__ */