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