1 /** 2 * @file Ecore_Cocoa.h 3 * 4 * @brief Ecore_Cocoa Wrapper Library to interact with the Cocoa 5 * environment (Mac OS X) from the E environment 6 * 7 */ 8 #ifndef __ECORE_COCOA_H__ 9 #define __ECORE_COCOA_H__ 10 11 #include <Eina.h> 12 13 #ifdef EAPI 14 # undef EAPI 15 #endif 16 17 #ifdef __GNUC__ 18 # if __GNUC__ >= 4 19 # define EAPI __attribute__ ((visibility("default"))) 20 # else 21 # define EAPI 22 # endif 23 #else 24 # define EAPI 25 #endif 26 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #ifndef _ECORE_COCOA_WINDOW_PREDEF 33 /** 34 * @typedef Ecore_Cocoa_Window 35 * Opaque handler to manipulate a Cocoa Window through Ecore 36 * @since 1.18 37 */ 38 typedef struct _Ecore_Cocoa_Window Ecore_Cocoa_Window; 39 #endif /* ! _ECORE_COCOA_WINDOW_PREDEF */ 40 41 /** 42 * @typedef Ecore_Cocoa_Screen 43 * Opaque handler to manipulate a Cocoa Screen through Ecore 44 * @since 1.18 45 */ 46 typedef struct _Ecore_Cocoa_Screen Ecore_Cocoa_Screen; 47 48 /** 49 * @typedef Ecore_Cocoa_Object 50 * Opaque handler to refer to an objective-c object (a.k.a. id) 51 * @since 1.18 52 */ 53 typedef void Ecore_Cocoa_Object; 54 55 /** 56 * @typedef Ecore_Cocoa_Event_Window_Resize_Request 57 * Type of event thrown when a Cocoa window is resized 58 * @since 1.18 59 */ 60 typedef struct _Ecore_Cocoa_Event_Window_Resize_Request Ecore_Cocoa_Event_Window_Resize_Request; 61 62 /** 63 * @typedef Ecore_Cocoa_Event_Window_Focused 64 * Type of event thrown when a Cocoa window receives focus 65 * @since 1.18 66 */ 67 typedef struct _Ecore_Cocoa_Event_Window_Focused Ecore_Cocoa_Event_Window_Focused; 68 69 /** 70 * @typedef Ecore_Cocoa_Event_Window_Unfocused 71 * Type of event thrown when a Cocoa window loses the focus 72 * @since 1.18 73 */ 74 typedef struct _Ecore_Cocoa_Event_Window_Unfocused Ecore_Cocoa_Event_Window_Unfocused; 75 76 /** 77 * @typedef Ecore_Cocoa_Event_Window_Destroy 78 * Type of event thrown when a Cocoa window gets destoyed 79 * @since 1.18 80 */ 81 typedef struct _Ecore_Cocoa_Event_Window_Destroy Ecore_Cocoa_Event_Window_Destroy; 82 83 /** 84 * @typedef Ecore_Cocoa_Terminate_Cb 85 * Callback called when a delete request is sent to the application. 86 * Such function must return EINA_TRUE for the application to terminate, 87 * and EINA_FALSE to ignore application termination. 88 * It is typically called by a CMD+Q signal. 89 * @param sender The NSApplication instance to be terminated 90 * @since 1.19 91 */ 92 typedef Eina_Bool (*Ecore_Cocoa_Terminate_Cb)(Ecore_Cocoa_Object *sender); 93 94 /** 95 * @typedef Ecore_Cocoa_Cursor 96 * Values of the Cocoa cursors handled by Ecore_Cocoa 97 * See https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSCursor_Class/index.html for images of each cursors. 98 * @since 1.18 99 */ 100 typedef enum 101 { 102 ECORE_COCOA_CURSOR_ARROW = 0, /**< Arrow cursor */ 103 ECORE_COCOA_CURSOR_CONTEXTUAL_MENU, /**< Contextual menu cursor */ 104 ECORE_COCOA_CURSOR_CLOSED_HAND, /**< Closed hand cursor */ 105 ECORE_COCOA_CURSOR_CROSSHAIR, /**< Crosshair cursor */ 106 ECORE_COCOA_CURSOR_DISAPPEARING_ITEM, /**< Disappearing item cursor */ 107 ECORE_COCOA_CURSOR_DRAG_COPY, /** Drag copy cursor */ 108 ECORE_COCOA_CURSOR_DRAG_LINK, /**< Drag link cursor */ 109 ECORE_COCOA_CURSOR_IBEAM, /**< IBeam cursor */ 110 ECORE_COCOA_CURSOR_OPEN_HAND, /**< Open hand cursor */ 111 ECORE_COCOA_CURSOR_OPERATION_NOT_ALLOWED, /**< Operation not allowed cursor */ 112 ECORE_COCOA_CURSOR_POINTING_HAND, /**< Pointing hand cursor */ 113 ECORE_COCOA_CURSOR_RESIZE_DOWN, /**< Resize down cursor */ 114 ECORE_COCOA_CURSOR_RESIZE_LEFT, /**< Resize left cursor */ 115 ECORE_COCOA_CURSOR_RESIZE_LEFT_RIGHT, /**< Resize left right cursor */ 116 ECORE_COCOA_CURSOR_RESIZE_RIGHT, /**< Resize right cursor */ 117 ECORE_COCOA_CURSOR_RESIZE_UP, /**< Resize up cursor */ 118 ECORE_COCOA_CURSOR_RESIZE_UP_DOWN, /**< Resize up down cursor */ 119 ECORE_COCOA_CURSOR_IBEAM_VERTICAL, /**< IBeam vertical cursor */ 120 121 __ECORE_COCOA_CURSOR_LAST /**< Sentinel. DO NOT USE */ 122 } Ecore_Cocoa_Cursor; 123 124 125 /** 126 * @def ECORE_COCOA_CURSOR_DEFAULT 127 * Defines the default Cocoa cursor, to be used when nothing 128 * is specified or as a fallback. 129 * @since 1.18 130 */ 131 #define ECORE_COCOA_CURSOR_DEFAULT ECORE_COCOA_CURSOR_ARROW 132 133 134 /** 135 * Event triggered when a Cocoa window receives focus 136 * @since 1.18 137 */ 138 EAPI extern int ECORE_COCOA_EVENT_WINDOW_FOCUSED; 139 140 /** 141 * Event triggered when a Cocoa window loses focus 142 * @since 1.18 143 */ 144 EAPI extern int ECORE_COCOA_EVENT_WINDOW_UNFOCUSED; 145 146 /** 147 * Event triggered when a Cocoa window is resized 148 * @since 1.18 149 */ 150 EAPI extern int ECORE_COCOA_EVENT_WINDOW_RESIZE_REQUEST; 151 152 /** Event triggered when a Cocoa window get destroyed 153 * @since 1.18 154 */ 155 EAPI extern int ECORE_COCOA_EVENT_WINDOW_DESTROY; 156 157 /** 158 * @struct _Ecore_Cocoa_Event_Window_Resize_Request 159 * Data available when a window is resized 160 * @since 1.18 161 */ 162 struct _Ecore_Cocoa_Event_Window_Resize_Request 163 { 164 int w; /**< Current width of the window */ 165 int h; /**< Current height of the window */ 166 Ecore_Cocoa_Object *cocoa_window; /**< Handler of the Cocoa window */ 167 }; 168 169 /** 170 * @struct _Ecore_Cocoa_Event_Window_Focused 171 * Data available when a Cocoa window receives focus 172 * @since 1.18 173 */ 174 struct _Ecore_Cocoa_Event_Window_Focused 175 { 176 Ecore_Cocoa_Object *cocoa_window; /**< Handler of the Cocoa window */ 177 }; 178 179 /** 180 * @struct _Ecore_Cocoa_Event_Window_Unfocused 181 * Data available when a Cocoa window losrs focus 182 * @since 1.18 183 */ 184 struct _Ecore_Cocoa_Event_Window_Unfocused 185 { 186 Ecore_Cocoa_Object *cocoa_window; /**< Handler of the Cocoa window */ 187 }; 188 189 /** 190 * @struct _Ecore_Cocoa_Event_Window_Destroy 191 * Data available when a Cocoa window is destroyed 192 * @since 1.18 193 */ 194 struct _Ecore_Cocoa_Event_Window_Destroy 195 { 196 Ecore_Cocoa_Object *cocoa_window; /**< Handler of the Cocoa window */ 197 }; 198 199 /*============================================================================* 200 * Core * 201 *============================================================================*/ 202 203 /** 204 * Inits the Ecore_Cocoa library 205 * @return How many times Ecore_Cocoa has been initted 206 * @since 1.18 207 */ 208 EAPI int ecore_cocoa_init(void); 209 210 /** 211 * Shuts the Ecore_Cocoa library down 212 * @return How many times Ecore_Cocoa has been shut down 213 * @since 1.18 214 */ 215 EAPI int ecore_cocoa_shutdown(void); 216 217 218 /*============================================================================* 219 * Screen * 220 *============================================================================*/ 221 222 /** 223 * Retrieves the size of a Cocoa screen 224 * @param screen The screen which size must be retrieved 225 * @param [out] w The width of the screen 226 * @param [out] h The height of the screen 227 * @since 1.18 228 */ 229 EAPI void ecore_cocoa_screen_size_get(Ecore_Cocoa_Screen *screen, int *w, int *h); 230 231 232 /*============================================================================* 233 * Window * 234 *============================================================================*/ 235 236 /** 237 * Creates a Cocoa window 238 * @param x The origin (X) where the window must be created 239 * @param y The origin (Y) where the window must be created 240 * @param w The width of the window 241 * @param h The height of the window 242 * @return A handler on the window. NULL on failure 243 * @since 1.18 244 */ 245 EAPI Ecore_Cocoa_Window *ecore_cocoa_window_new(int x, 246 int y, 247 int w, 248 int h) 249 EINA_MALLOC 250 EINA_WARN_UNUSED_RESULT; 251 252 /** 253 * Releases a Cocoa window 254 * @param window The window to be released 255 * @since 1.18 256 */ 257 EAPI void ecore_cocoa_window_free(Ecore_Cocoa_Window *window) 258 EINA_ARG_NONNULL(1); 259 260 /** 261 * Moves a Cocoa window at a given point 262 * @param window The window to be moved 263 * @param x The new origin of the window (X) 264 * @param y The new origin of the window (Y) 265 * @since 1.18 266 */ 267 EAPI void ecore_cocoa_window_move(Ecore_Cocoa_Window *window, 268 int x, 269 int y) 270 EINA_ARG_NONNULL(1); 271 272 /** 273 * Resizes a Cocoa window to a given size 274 * @param window The window to be moved 275 * @param w The new width of the window 276 * @param h The new height of the window 277 * @since 1.18 278 */ 279 EAPI void ecore_cocoa_window_resize(Ecore_Cocoa_Window *window, 280 int w, 281 int h) 282 EINA_ARG_NONNULL(1); 283 284 /** 285 * Moves and resizes a Cocoa window to a given point and size 286 * @param window The window to be moved 287 * @param x The new origin of the window (X) 288 * @param y The new origin of the window (Y) 289 * @param w The new width of the window 290 * @param h The new height of the window 291 * 292 * @see ecore_cocoa_window_resize() 293 * @see ecore_cocoa_window_move() 294 * @since 1.18 295 */ 296 EAPI void ecore_cocoa_window_move_resize(Ecore_Cocoa_Window *window, 297 int x, 298 int y, 299 int w, 300 int h) 301 EINA_ARG_NONNULL(1); 302 303 /** 304 * Gets the geometry of a Cocoa window 305 * @param window The window which geometry is queried 306 * @param x Pointer used to retrieve its origin in X 307 * @param y Pointer used to retrieve its origin in Y 308 * @param w Pointer used to retrieve its width 309 * @param h Pointer used to retrieve its height 310 * @since 1.18 311 */ 312 EAPI void ecore_cocoa_window_geometry_get(const Ecore_Cocoa_Window *window, 313 int *x, 314 int *y, 315 int *w, 316 int *h) 317 EINA_ARG_NONNULL(1); 318 319 /** 320 * Gets the size of a Cocoa window 321 * @param window The window which size is queried 322 * @param w Pointer used to retrieve its width 323 * @param h Pointer used to retrieve its height 324 * @since 1.18 325 */ 326 EAPI void ecore_cocoa_window_size_get(const Ecore_Cocoa_Window *window, 327 int *w, 328 int *h) 329 EINA_ARG_NONNULL(1); 330 331 /** 332 * Sets the minimum size of a Cocoa window 333 * @param window The window which minimum size is to be altered 334 * @param w The new minimum width of the window 335 * @param h The new minimum height of the window 336 * @since 1.18 337 */ 338 EAPI void ecore_cocoa_window_size_min_set(Ecore_Cocoa_Window *window, 339 int w, 340 int h) 341 EINA_ARG_NONNULL(1); 342 343 /** 344 * Gets the minimum size size of a Cocoa window 345 * @param window The window which minimum size is queried 346 * @param w Pointer used to retrieve its minimum width 347 * @param h Pointer used to retrieve its minimum height 348 * @since 1.18 349 */ 350 EAPI void ecore_cocoa_window_size_min_get(const Ecore_Cocoa_Window *window, 351 int *w, 352 int *h) 353 EINA_ARG_NONNULL(1); 354 355 /** 356 * Sets the maximum size of a Cocoa window 357 * @param window The window which maximum size is to be altered 358 * @param w The new maximum width of the window 359 * @param h The new maximum height of the window 360 * @since 1.18 361 */ 362 EAPI void ecore_cocoa_window_size_max_set(Ecore_Cocoa_Window *window, 363 int w, 364 int h) 365 EINA_ARG_NONNULL(1); 366 367 /** 368 * Gets the maximum size size of a Cocoa window 369 * @param window The window which maximum size is queried 370 * @param w Pointer used to retrieve its maximum width 371 * @param h Pointer used to retrieve its maximum height 372 * @since 1.18 373 */ 374 EAPI void ecore_cocoa_window_size_max_get(const Ecore_Cocoa_Window *window, 375 int *w, 376 int *h) 377 EINA_ARG_NONNULL(1); 378 379 /** 380 * Sets a Cocoa window's resize increment 381 * @param window The Cocoa window which resize increment is to be set 382 * @param w The width size increment 383 * @param h The height size increment 384 * @since 1.18 385 */ 386 EAPI void ecore_cocoa_window_size_step_set(Ecore_Cocoa_Window *window, 387 int w, 388 int h) 389 EINA_ARG_NONNULL(1); 390 391 /** 392 * Gets a Cocoa window's resize increment 393 * @param window The Cocoa window which resize increment queried 394 * @param w The width size increment 395 * @param h The height size increment 396 * @since 1.18 397 */ 398 EAPI void ecore_cocoa_window_size_step_get(const Ecore_Cocoa_Window *window, 399 int *w, 400 int *h) 401 EINA_ARG_NONNULL(1); 402 403 /** 404 * Displays a Cocoa window 405 * @param window The Cocoa window to be displayed 406 * @since 1.18 407 */ 408 EAPI void ecore_cocoa_window_show(Ecore_Cocoa_Window *window) 409 EINA_ARG_NONNULL(1); 410 411 /** 412 * Hides a Cocoa window 413 * @param window The Cocoa window to be hid 414 * @since 1.18 415 */ 416 EAPI void ecore_cocoa_window_hide(Ecore_Cocoa_Window *window) 417 EINA_ARG_NONNULL(1); 418 419 /** 420 * Brings a Cocoa window to front 421 * @param window The Cocoa window to be raised 422 * @since 1.18 423 */ 424 EAPI void ecore_cocoa_window_raise(Ecore_Cocoa_Window *window) 425 EINA_ARG_NONNULL(1); 426 427 /** 428 * Brings a Cocoa window back 429 * @param window The Cocoa window to be lowered 430 * @since 1.18 431 */ 432 EAPI void ecore_cocoa_window_lower(Ecore_Cocoa_Window *window) 433 EINA_ARG_NONNULL(1); 434 435 /** 436 * Makes a Cocoa window the current key window by raising it 437 * @param window The Cocoa window to be activated 438 * @since 1.18 439 */ 440 EAPI void ecore_cocoa_window_activate(Ecore_Cocoa_Window *window) 441 EINA_ARG_NONNULL(1); 442 443 /** 444 * Changes the title of a Cocoa window 445 * @param window The Cocoa window which title is to be changed 446 * @param title The new title of the Cocoa window 447 * @since 1.18 448 */ 449 EAPI void ecore_cocoa_window_title_set(Ecore_Cocoa_Window *window, 450 const char *title) 451 EINA_ARG_NONNULL(1); 452 453 /** 454 * Miniaturizes or deminiaturizes a Cocoa window 455 * @param window The Cocoa window which iconify status is to be changed 456 * @param on If #EINA_TRUE, will miniaturize the window. Will deminiaturize it if #EINA_FALSE 457 * @since 1.18 458 */ 459 EAPI void ecore_cocoa_window_iconified_set(Ecore_Cocoa_Window *window, 460 Eina_Bool on) 461 EINA_ARG_NONNULL(1); 462 463 /** 464 * Manages the borders of a Cocoa window 465 * @param window The Cocoa window which borders are to be changed 466 * @param on If #EINA_TRUE, will remove borders. Will restore them if #EINA_FALSE 467 * @since 1.18 468 */ 469 EAPI void ecore_cocoa_window_borderless_set(Ecore_Cocoa_Window *window, 470 Eina_Bool on) 471 EINA_ARG_NONNULL(1); 472 473 /** 474 * Sets the content view of a Cocoa window 475 * 476 * Refer to Apple's documentation of the property 'contentView' of 477 * the NSWindow class for more details about the content view. 478 * 479 * @param window The Cocoa window which internal view is to be set 480 * @param view The NSView to be set as @c window content view 481 * @since 1.18 482 */ 483 EAPI void ecore_cocoa_window_view_set(Ecore_Cocoa_Window *window, 484 Ecore_Cocoa_Object *view) 485 EINA_ARG_NONNULL(1) 486 EINA_ARG_NONNULL(2); 487 488 /** 489 * Gets the height of the title bar of Cocoa windows 490 * @return The height of the title bar of Cocoa windows 491 * @since 1.18 492 */ 493 EAPI int ecore_cocoa_titlebar_height_get(void); 494 495 /** 496 * Retrieves the actual NSWindow behind the Ecore_Cocoa wrapper 497 * @param window The Ecore_Cocoa wrapper which window is to be retrieved 498 * @return The Cocoa NSWindow manipulated by @c window 499 * @since 1.18 500 */ 501 EAPI Ecore_Cocoa_Object *ecore_cocoa_window_get(const Ecore_Cocoa_Window *window) 502 EINA_ARG_NONNULL(1) 503 EINA_WARN_UNUSED_RESULT; 504 505 506 /** 507 * Sets the Cocoa cursor for a given Cocoa window 508 * @param win The Cocoa window on which the cursor is to be changed. 509 * @param c The cursor to be set 510 * @since 1.18 511 */ 512 EAPI void ecore_cocoa_window_cursor_set(Ecore_Cocoa_Window *win, 513 Ecore_Cocoa_Cursor c) 514 EINA_ARG_NONNULL(1); 515 516 /** 517 * Hides or shows the Cocoa cursor for a given Cocoa window 518 * @param win The Cocoa window on which the cursor is to be hid 519 * @param show Shows the cursor if EINA_TRUE. Hides it if EINA_FALSE 520 * @since 1.18 521 */ 522 EAPI void ecore_cocoa_window_cursor_show(Ecore_Cocoa_Window *win, Eina_Bool show); 523 EINA_ARG_NONNULL(1); 524 525 /** 526 * Overrides the default behaviour in response to an application delete 527 * request. When an application receives a delete request (i.e. CMD+Q) 528 * the termination callback will be called and its result will determine 529 * whether the application should terminate or not 530 * @param cb The custom termination callback to set 531 * @see Ecore_Cocoa_Terminate_Cb 532 * @since 1.19 533 */ 534 EAPI void ecore_cocoa_terminate_cb_set(Ecore_Cocoa_Terminate_Cb cb) 535 EINA_ARG_NONNULL(1); 536 537 538 /* 539 * The clipboard API is still BETA 540 */ 541 542 #ifdef EFL_BETA_API_SUPPORT 543 544 /* 545 * Sets the clipboard of Cocoa (NSPasteboard) 546 * @param data The contents to be set in the clipboard 547 * @param size The size in bytes of @c data 548 * @param mime_type The type of object to set the data 549 * @return EINA_TRUE on success, EINA_FALSE on failure 550 */ 551 EAPI Eina_Bool ecore_cocoa_clipboard_set(const void *data, 552 int size, 553 const char *mime_type); 554 555 /* 556 * Gets the contents of the Cocoa clipboard 557 * @param size Pointer used to retrieve the size of the received contents 558 * @param mime_type The type of object to retrieve from the clipboard 559 * @return The data retrieved from the clipboard. NULL on failure 560 * 561 */ 562 EAPI void *ecore_cocoa_clipboard_get(int *size, 563 const char *mime_type) 564 EINA_WARN_UNUSED_RESULT; 565 566 /* 567 * Deletes the contents of the Cocoa clipboard 568 */ 569 EAPI void ecore_cocoa_clipboard_clear(void); 570 571 /* 572 * Returns true when the clipboard contains data that can be received. 573 */ 574 EAPI Eina_Bool ecore_cocoa_clipboard_exists(void); 575 576 #endif /* EFL_BETA_API_SUPPORT */ 577 578 #ifdef __cplusplus 579 } 580 #endif 581 582 #undef EAPI 583 #define EAPI 584 585 #endif 586