4 * @image html img/widget/win/preview-00.png
5 * @image latex img/widget/win/preview-00.eps
7 * The window class of Elementary. Contains functions to manipulate
8 * windows. The Evas engine used to render the window contents is specified
9 * in the system or user elementary config files (whichever is found last),
10 * and can be overridden with the ELM_ENGINE environment variable for
11 * testing. Engines that may be supported (depending on Evas and Ecore-Evas
12 * compilation setup and modules actually installed at runtime) are (listed
13 * in order of best supported and most likely to be complete and work to
16 * @li "x11", "x", "software-x11", "software_x11" (Software rendering in X11)
17 * @li "gl", "opengl", "opengl-x11", "opengl_x11" (OpenGL or OpenGL-ES2
19 * @li "shot:..." (Virtual screenshot renderer - renders to output file and
21 * @li "fb", "software-fb", "software_fb" (Linux framebuffer direct software
23 * @li "sdl", "software-sdl", "software_sdl" (SDL software rendering to SDL
25 * @li "gl-sdl", "gl_sdl", "opengl-sdl", "opengl_sdl" (OpenGL or OpenGL-ES2
26 * rendering using SDL as the buffer)
27 * @li "gdi", "software-gdi", "software_gdi" (Windows WIN32 rendering via
29 * @li "dfb", "directfb" (Rendering to a DirectFB window)
30 * @li "x11-8", "x8", "software-8-x11", "software_8_x11" (Rendering in
31 * grayscale using dedicated 8bit software engine in X11)
32 * @li "x11-16", "x16", "software-16-x11", "software_16_x11" (Rendering in
33 * X11 using 16bit software engine)
34 * @li "wince-gdi", "software-16-wince-gdi", "software_16_wince_gdi"
35 * (Windows CE rendering via GDI with 16bit software renderer)
36 * @li "sdl-16", "software-16-sdl", "software_16_sdl" (Rendering to SDL
37 * buffer with 16bit software renderer)
38 * @li "ews" (rendering to EWS - Ecore + Evas Single Process Windowing System)
39 * @li "gl-cocoa", "gl_cocoa", "opengl-cocoa", "opengl_cocoa" (OpenGL rendering in Cocoa)
40 * @li "psl1ght" (PS3 rendering using PSL1GHT)
42 * All engines use a simple string to select the engine to render, EXCEPT
43 * the "shot" engine. This actually encodes the output of the virtual
44 * screenshot and how long to delay in the engine string. The engine string
45 * is encoded in the following way:
47 * "shot:[delay=XX][:][repeat=DDD][:][file=XX]"
49 * Where options are separated by a ":" char if more than one option is
50 * given, with delay, if provided being the first option and file the last
51 * (order is important). The delay specifies how long to wait after the
52 * window is shown before doing the virtual "in memory" rendering and then
53 * save the output to the file specified by the file option (and then exit).
54 * If no delay is given, the default is 0.5 seconds. If no file is given the
55 * default output file is "out.png". Repeat option is for continous
56 * capturing screenshots. Repeat range is from 1 to 999 and filename is
57 * fixed to "out001.png" Some examples of using the shot engine:
59 * ELM_ENGINE="shot:delay=1.0:repeat=5:file=elm_test.png" elementary_test
60 * ELM_ENGINE="shot:delay=1.0:file=elm_test.png" elementary_test
61 * ELM_ENGINE="shot:file=elm_test2.png" elementary_test
62 * ELM_ENGINE="shot:delay=2.0" elementary_test
63 * ELM_ENGINE="shot:" elementary_test
65 * Signals that you can add callbacks for are:
67 * @li "delete,request": the user requested to close the window. See
68 * elm_win_autodel_set().
69 * @li "focus,in": window got focus
70 * @li "focus,out": window lost focus
71 * @li "moved": window that holds the canvas was moved
74 * @li @ref win_example_01
79 * Defines the types of window that can be created
81 * These are hints set on the window so that a running Window Manager knows
82 * how the window should be handled and/or what kind of decorations it
85 * Currently, only the X11 backed engines use them.
89 ELM_WIN_BASIC, /**< A normal window. Indicates a normal, top-level
90 window. Almost every window will be created with this
92 ELM_WIN_DIALOG_BASIC, /**< Used for simple dialog windows/ */
93 ELM_WIN_DESKTOP, /**< For special desktop windows, like a background
94 window holding desktop icons. */
95 ELM_WIN_DOCK, /**< The window is used as a dock or panel. Usually would
96 be kept on top of any other window by the Window
98 ELM_WIN_TOOLBAR, /**< The window is used to hold a floating toolbar, or
100 ELM_WIN_MENU, /**< Similar to #ELM_WIN_TOOLBAR. */
101 ELM_WIN_UTILITY, /**< A persistent utility window, like a toolbox or
103 ELM_WIN_SPLASH, /**< Splash window for a starting up application. */
104 ELM_WIN_DROPDOWN_MENU, /**< The window is a dropdown menu, as when an
105 entry in a menubar is clicked. Typically used
106 with elm_win_override_set(). This hint exists
107 for completion only, as the EFL way of
108 implementing a menu would not normally use a
109 separate window for its contents. */
110 ELM_WIN_POPUP_MENU, /**< Like #ELM_WIN_DROPDOWN_MENU, but for the menu
111 triggered by right-clicking an object. */
112 ELM_WIN_TOOLTIP, /**< The window is a tooltip. A short piece of
113 explanatory text that typically appear after the
114 mouse cursor hovers over an object for a while.
115 Typically used with elm_win_override_set() and also
116 not very commonly used in the EFL. */
117 ELM_WIN_NOTIFICATION, /**< A notification window, like a warning about
118 battery life or a new E-Mail received. */
119 ELM_WIN_COMBO, /**< A window holding the contents of a combo box. Not
120 usually used in the EFL. */
121 ELM_WIN_DND, /**< Used to indicate the window is a representation of an
122 object being dragged across different windows, or even
123 applications. Typically used with
124 elm_win_override_set(). */
125 ELM_WIN_INLINED_IMAGE, /**< The window is rendered onto an image
126 buffer. No actual window is created for this
127 type, instead the window and all of its
128 contents will be rendered to an image buffer.
129 This allows to have children window inside a
130 parent one just like any other object would
131 be, and do other things like applying @c
132 Evas_Map effects to it. This is the only type
133 of window that requires the @c parent
134 parameter of elm_win_add() to be a valid @c
139 * The differents layouts that can be requested for the virtual keyboard.
141 * When the application window is being managed by Illume, it may request
142 * any of the following layouts for the virtual keyboard.
144 // XXX: remove this as it conflicts with input panel
147 ELM_WIN_KEYBOARD_UNKNOWN, /**< Unknown keyboard state */
148 ELM_WIN_KEYBOARD_OFF, /**< Request to deactivate the keyboard */
149 ELM_WIN_KEYBOARD_ON, /**< Enable keyboard with default layout */
150 ELM_WIN_KEYBOARD_ALPHA, /**< Alpha (a-z) keyboard layout */
151 ELM_WIN_KEYBOARD_NUMERIC, /**< Numeric keyboard layout */
152 ELM_WIN_KEYBOARD_PIN, /**< PIN keyboard layout */
153 ELM_WIN_KEYBOARD_PHONE_NUMBER, /**< Phone keyboard layout */
154 ELM_WIN_KEYBOARD_HEX, /**< Hexadecimal numeric keyboard layout */
155 ELM_WIN_KEYBOARD_TERMINAL, /**< Full (QUERTY) keyboard layout */
156 ELM_WIN_KEYBOARD_PASSWORD, /**< Password keyboard layout */
157 ELM_WIN_KEYBOARD_IP, /**< IP keyboard layout */
158 ELM_WIN_KEYBOARD_HOST, /**< Host keyboard layout */
159 ELM_WIN_KEYBOARD_FILE, /**< File keyboard layout */
160 ELM_WIN_KEYBOARD_URL, /**< URL keyboard layout */
161 ELM_WIN_KEYBOARD_KEYPAD, /**< Keypad layout */
162 ELM_WIN_KEYBOARD_J2ME /**< J2ME keyboard layout */
163 } Elm_Win_Keyboard_Mode;
166 * Available commands that can be sent to the Illume manager.
168 * When running under an Illume session, a window may send commands to the
169 * Illume manager to perform different actions.
173 ELM_ILLUME_COMMAND_FOCUS_BACK, /**< Reverts focus to the previous window */
174 ELM_ILLUME_COMMAND_FOCUS_FORWARD, /**< Sends focus to the next window in the list */
175 ELM_ILLUME_COMMAND_FOCUS_HOME, /**< Hides all windows to show the Home screen */
176 ELM_ILLUME_COMMAND_CLOSE /**< Closes the currently active window */
177 } Elm_Illume_Command;
180 * Adds a window object. If this is the first window created, pass NULL as
183 * @param parent Parent object to add the window to, or NULL
184 * @param name The name of the window
185 * @param type The window type, one of #Elm_Win_Type.
187 * The @p parent paramter can be @c NULL for every window @p type except
188 * #ELM_WIN_INLINED_IMAGE, which needs a parent to retrieve the canvas on
189 * which the image object will be created.
191 * @return The created object, or NULL on failure
193 EAPI Evas_Object *elm_win_add(Evas_Object *parent, const char *name, Elm_Win_Type type);
196 * Adds a window object with standard setup
198 * @param name The name of the window
199 * @param title The title for the window
201 * This creates a window like elm_win_add() but also puts in a standard
202 * background with elm_bg_add(), as well as setting the window title to
203 * @p title. The window type created is of type ELM_WIN_BASIC, with NULL
204 * as the parent widget.
206 * @return The created object, or NULL on failure
210 EAPI Evas_Object *elm_win_util_standard_add(const char *name, const char *title);
213 * Add @p subobj as a resize object of window @p obj.
216 * Setting an object as a resize object of the window means that the
217 * @p subobj child's size and position will be controlled by the window
218 * directly. That is, the object will be resized to match the window size
219 * and should never be moved or resized manually by the developer.
221 * In addition, resize objects of the window control what the minimum size
222 * of it will be, as well as whether it can or not be resized by the user.
224 * For the end user to be able to resize a window by dragging the handles
225 * or borders provided by the Window Manager, or using any other similar
226 * mechanism, all of the resize objects in the window should have their
227 * evas_object_size_hint_weight_set() set to EVAS_HINT_EXPAND.
229 * Also notice that the window can get resized to the current size of the
230 * object if the EVAS_HINT_EXPAND is set @b after the call to
231 * elm_win_resize_object_add(). So if the object should get resized to the
232 * size of the window, set this hint @b before adding it as a resize object
233 * (this happens because the size of the window and the object are evaluated
234 * as soon as the object is added to the window).
236 * @param obj The window object
237 * @param subobj The resize object to add
239 EAPI void elm_win_resize_object_add(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
242 * Delete @p subobj as a resize object of window @p obj.
244 * This function removes the object @p subobj from the resize objects of
245 * the window @p obj. It will not delete the object itself, which will be
246 * left unmanaged and should be deleted by the developer, manually handled
247 * or set as child of some other container.
249 * @param obj The window object
250 * @param subobj The resize object to add
252 EAPI void elm_win_resize_object_del(Evas_Object *obj, Evas_Object *subobj) EINA_ARG_NONNULL(1);
255 * Set the title of the window
257 * @param obj The window object
258 * @param title The title to set
260 EAPI void elm_win_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
263 * Get the title of the window
265 * The returned string is an internal one and should not be freed or
266 * modified. It will also be rendered invalid if a new title is set or if
267 * the window is destroyed.
269 * @param obj The window object
272 EAPI const char *elm_win_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
275 * Set the window's autodel state.
277 * When closing the window in any way outside of the program control, like
278 * pressing the X button in the titlebar or using a command from the
279 * Window Manager, a "delete,request" signal is emitted to indicate that
280 * this event occurred and the developer can take any action, which may
281 * include, or not, destroying the window object.
283 * When the @p autodel parameter is set, the window will be automatically
284 * destroyed when this event occurs, after the signal is emitted.
285 * If @p autodel is @c EINA_FALSE, then the window will not be destroyed
286 * and is up to the program to do so when it's required.
288 * @param obj The window object
289 * @param autodel If true, the window will automatically delete itself when
292 EAPI void elm_win_autodel_set(Evas_Object *obj, Eina_Bool autodel) EINA_ARG_NONNULL(1);
295 * Get the window's autodel state.
297 * @param obj The window object
298 * @return If the window will automatically delete itself when closed
300 * @see elm_win_autodel_set()
302 EAPI Eina_Bool elm_win_autodel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
305 * Activate a window object.
307 * This function sends a request to the Window Manager to activate the
308 * window pointed by @p obj. If honored by the WM, the window will receive
309 * the keyboard focus.
311 * @note This is just a request that a Window Manager may ignore, so calling
312 * this function does not ensure in any way that the window will be the
313 * active one after it.
315 * @param obj The window object
317 EAPI void elm_win_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
320 * Lower a window object.
322 * Places the window pointed by @p obj at the bottom of the stack, so that
323 * no other window is covered by it.
325 * If elm_win_override_set() is not set, the Window Manager may ignore this
328 * @param obj The window object
330 EAPI void elm_win_lower(Evas_Object *obj) EINA_ARG_NONNULL(1);
333 * Raise a window object.
335 * Places the window pointed by @p obj at the top of the stack, so that it's
336 * not covered by any other window.
338 * If elm_win_override_set() is not set, the Window Manager may ignore this
341 * @param obj The window object
343 EAPI void elm_win_raise(Evas_Object *obj) EINA_ARG_NONNULL(1);
346 * Center a window on its screen
348 * This function centers window @p obj horizontally and/or vertically based on the values
350 * @param obj The window object
351 * @param h If true, center horizontally. If false, do not change horizontal location.
352 * @param v If true, center vertically. If false, do not change vertical location.
354 EAPI void elm_win_center(Evas_Object *obj, Eina_Bool h, Eina_Bool v) EINA_ARG_NONNULL(1);
357 * Set the borderless state of a window.
359 * This function requests the Window Manager to not draw any decoration
362 * @param obj The window object
363 * @param borderless If true, the window is borderless
365 EAPI void elm_win_borderless_set(Evas_Object *obj, Eina_Bool borderless) EINA_ARG_NONNULL(1);
368 * Get the borderless state of a window.
370 * @param obj The window object
371 * @return If true, the window is borderless
373 EAPI Eina_Bool elm_win_borderless_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
376 * Set the shaped state of a window.
378 * Shaped windows, when supported, will render the parts of the window that
379 * has no content, transparent.
381 * If @p shaped is EINA_FALSE, then it is strongly adviced to have some
382 * background object or cover the entire window in any other way, or the
383 * parts of the canvas that have no data will show framebuffer artifacts.
385 * @param obj The window object
386 * @param shaped If true, the window is shaped
388 * @see elm_win_alpha_set()
390 EAPI void elm_win_shaped_set(Evas_Object *obj, Eina_Bool shaped) EINA_ARG_NONNULL(1);
393 * Get the shaped state of a window.
395 * @param obj The window object
396 * @return If true, the window is shaped
398 * @see elm_win_shaped_set()
400 EAPI Eina_Bool elm_win_shaped_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
403 * Set the alpha channel state of a window.
405 * If @p alpha is EINA_TRUE, the alpha channel of the canvas will be enabled
406 * possibly making parts of the window completely or partially transparent.
407 * This is also subject to the underlying system supporting it, like for
408 * example, running under a compositing manager. If no compositing is
409 * available, enabling this option will instead fallback to using shaped
410 * windows, with elm_win_shaped_set().
412 * @param obj The window object
413 * @param alpha If true, the window has an alpha channel
415 * @see elm_win_alpha_set()
417 EAPI void elm_win_alpha_set(Evas_Object *obj, Eina_Bool alpha) EINA_ARG_NONNULL(1);
420 * Get the transparency state of a window.
422 * @param obj The window object
423 * @return If true, the window is transparent
425 * @see elm_win_transparent_set()
427 // XXX: deprecate this
428 EAPI Eina_Bool elm_win_transparent_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
431 * Set the transparency state of a window.
433 * Use elm_win_alpha_set() instead.
435 * @param obj The window object
436 * @param transparent If true, the window is transparent
438 * @see elm_win_alpha_set()
440 // XXX: deprecate this
441 EAPI void elm_win_transparent_set(Evas_Object *obj, Eina_Bool transparent) EINA_ARG_NONNULL(1);
444 * Get the alpha channel state of a window.
446 * @param obj The window object
447 * @return If true, the window has an alpha channel
449 EAPI Eina_Bool elm_win_alpha_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
452 * Set the override state of a window.
454 * A window with @p override set to EINA_TRUE will not be managed by the
455 * Window Manager. This means that no decorations of any kind will be shown
456 * for it, moving and resizing must be handled by the application, as well
457 * as the window visibility.
459 * This should not be used for normal windows, and even for not so normal
460 * ones, it should only be used when there's a good reason and with a lot
461 * of care. Mishandling override windows may result situations that
462 * disrupt the normal workflow of the end user.
464 * @param obj The window object
465 * @param override If true, the window is overridden
467 EAPI void elm_win_override_set(Evas_Object *obj, Eina_Bool override) EINA_ARG_NONNULL(1);
470 * Get the override state of a window.
472 * @param obj The window object
473 * @return If true, the window is overridden
475 * @see elm_win_override_set()
477 EAPI Eina_Bool elm_win_override_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
480 * Set the fullscreen state of a window.
482 * @param obj The window object
483 * @param fullscreen If true, the window is fullscreen
485 EAPI void elm_win_fullscreen_set(Evas_Object *obj, Eina_Bool fullscreen) EINA_ARG_NONNULL(1);
488 * Get the fullscreen state of a window.
490 * @param obj The window object
491 * @return If true, the window is fullscreen
493 EAPI Eina_Bool elm_win_fullscreen_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
496 * Set the maximized state of a window.
498 * @param obj The window object
499 * @param maximized If true, the window is maximized
501 EAPI void elm_win_maximized_set(Evas_Object *obj, Eina_Bool maximized) EINA_ARG_NONNULL(1);
504 * Get the maximized state of a window.
506 * @param obj The window object
507 * @return If true, the window is maximized
509 EAPI Eina_Bool elm_win_maximized_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
512 * Set the iconified state of a window.
514 * @param obj The window object
515 * @param iconified If true, the window is iconified
517 EAPI void elm_win_iconified_set(Evas_Object *obj, Eina_Bool iconified) EINA_ARG_NONNULL(1);
520 * Get the iconified state of a window.
522 * @param obj The window object
523 * @return If true, the window is iconified
525 EAPI Eina_Bool elm_win_iconified_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
528 * Set the layer of the window.
530 * What this means exactly will depend on the underlying engine used.
532 * In the case of X11 backed engines, the value in @p layer has the
533 * following meanings:
534 * @li < 3: The window will be placed below all others.
535 * @li > 5: The window will be placed above all others.
536 * @li other: The window will be placed in the default layer.
538 * @param obj The window object
539 * @param layer The layer of the window
541 EAPI void elm_win_layer_set(Evas_Object *obj, int layer) EINA_ARG_NONNULL(1);
544 * Get the layer of the window.
546 * @param obj The window object
547 * @return The layer of the window
549 * @see elm_win_layer_set()
551 EAPI int elm_win_layer_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
554 * Set the rotation of the window.
556 * Most engines only work with multiples of 90.
558 * This function is used to set the orientation of the window @p obj to
559 * match that of the screen. The window itself will be resized to adjust
560 * to the new geometry of its contents. If you want to keep the window size,
561 * see elm_win_rotation_with_resize_set().
563 * @param obj The window object
564 * @param rotation The rotation of the window, in degrees (0-360),
567 EAPI void elm_win_rotation_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
570 * Rotates the window and resizes it.
572 * Like elm_win_rotation_set(), but it also resizes the window's contents so
573 * that they fit inside the current window geometry.
575 * @param obj The window object
576 * @param rotation The rotation of the window in degrees (0-360),
579 EAPI void elm_win_rotation_with_resize_set(Evas_Object *obj, int rotation) EINA_ARG_NONNULL(1);
582 * Get the rotation of the window.
584 * @param obj The window object
585 * @return The rotation of the window in degrees (0-360)
587 * @see elm_win_rotation_set()
588 * @see elm_win_rotation_with_resize_set()
590 EAPI int elm_win_rotation_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
593 * Set the sticky state of the window.
595 * Hints the Window Manager that the window in @p obj should be left fixed
596 * at its position even when the virtual desktop it's on moves or changes.
598 * @param obj The window object
599 * @param sticky If true, the window's sticky state is enabled
601 EAPI void elm_win_sticky_set(Evas_Object *obj, Eina_Bool sticky) EINA_ARG_NONNULL(1);
604 * Get the sticky state of the window.
606 * @param obj The window object
607 * @return If true, the window's sticky state is enabled
609 * @see elm_win_sticky_set()
611 EAPI Eina_Bool elm_win_sticky_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
614 * Set if this window is an illume conformant window
616 * @param obj The window object
617 * @param conformant The conformant flag (1 = conformant, 0 = non-conformant)
619 EAPI void elm_win_conformant_set(Evas_Object *obj, Eina_Bool conformant) EINA_ARG_NONNULL(1);
622 * Get if this window is an illume conformant window
624 * @param obj The window object
625 * @return A boolean if this window is illume conformant or not
627 EAPI Eina_Bool elm_win_conformant_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
630 * Set a window to be an illume quickpanel window
632 * By default window objects are not quickpanel windows.
634 * @param obj The window object
635 * @param quickpanel The quickpanel flag (1 = quickpanel, 0 = normal window)
637 EAPI void elm_win_quickpanel_set(Evas_Object *obj, Eina_Bool quickpanel) EINA_ARG_NONNULL(1);
640 * Get if this window is a quickpanel or not
642 * @param obj The window object
643 * @return A boolean if this window is a quickpanel or not
645 EAPI Eina_Bool elm_win_quickpanel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
648 * Set the major priority of a quickpanel window
650 * @param obj The window object
651 * @param priority The major priority for this quickpanel
653 EAPI void elm_win_quickpanel_priority_major_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
656 * Get the major priority of a quickpanel window
658 * @param obj The window object
659 * @return The major priority of this quickpanel
661 EAPI int elm_win_quickpanel_priority_major_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
664 * Set the minor priority of a quickpanel window
666 * @param obj The window object
667 * @param priority The minor priority for this quickpanel
669 EAPI void elm_win_quickpanel_priority_minor_set(Evas_Object *obj, int priority) EINA_ARG_NONNULL(1);
672 * Get the minor priority of a quickpanel window
674 * @param obj The window object
675 * @return The minor priority of this quickpanel
677 EAPI int elm_win_quickpanel_priority_minor_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
680 * Set which zone this quickpanel should appear in
682 * @param obj The window object
683 * @param zone The requested zone for this quickpanel
685 EAPI void elm_win_quickpanel_zone_set(Evas_Object *obj, int zone) EINA_ARG_NONNULL(1);
688 * Get which zone this quickpanel should appear in
690 * @param obj The window object
691 * @return The requested zone for this quickpanel
693 EAPI int elm_win_quickpanel_zone_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
696 * Set the window to be skipped by keyboard focus
698 * This sets the window to be skipped by normal keyboard input. This means
699 * a window manager will be asked to not focus this window as well as omit
700 * it from things like the taskbar, pager, "alt-tab" list etc. etc.
702 * Call this and enable it on a window BEFORE you show it for the first time,
703 * otherwise it may have no effect.
705 * Use this for windows that have only output information or might only be
706 * interacted with by the mouse or fingers, and never for typing input.
707 * Be careful that this may have side-effects like making the window
708 * non-accessible in some cases unless the window is specially handled. Use
711 * @param obj The window object
712 * @param skip The skip flag state (EINA_TRUE if it is to be skipped)
714 EAPI void elm_win_prop_focus_skip_set(Evas_Object *obj, Eina_Bool skip) EINA_ARG_NONNULL(1);
717 * Send a command to the windowing environment
719 * This is intended to work in touchscreen or small screen device
720 * environments where there is a more simplistic window management policy in
721 * place. This uses the window object indicated to select which part of the
722 * environment to control (the part that this window lives in), and provides
723 * a command and an optional parameter structure (use NULL for this if not
726 * @param obj The window object that lives in the environment to control
727 * @param command The command to send
728 * @param params Optional parameters for the command
730 EAPI void elm_win_illume_command_send(Evas_Object *obj, Elm_Illume_Command command, void *params) EINA_ARG_NONNULL(1);
733 * Get the inlined image object handle
735 * When you create a window with elm_win_add() of type ELM_WIN_INLINED_IMAGE,
736 * then the window is in fact an evas image object inlined in the parent
737 * canvas. You can get this object (be careful to not manipulate it as it
738 * is under control of elementary), and use it to do things like get pixel
739 * data, save the image to a file, etc.
741 * @param obj The window object to get the inlined image from
742 * @return The inlined image object, or NULL if none exists
744 EAPI Evas_Object *elm_win_inlined_image_object_get(Evas_Object *obj);
747 * Determine whether a window has focus
748 * @param obj The window to query
749 * @return EINA_TRUE if the window exists and has focus, else EINA_FALSE
751 EAPI Eina_Bool elm_win_focus_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
754 * Constrain the maximum width and height of a window to the width and height of its screen
756 * When @p constrain is true, @p obj will never resize larger than the screen.
757 * @param obj The window object
758 * @param constrain EINA_TRUE to restrict the window's maximum size, EINA_FALSE to disable restriction
760 EAPI void elm_win_screen_constrain_set(Evas_Object *obj, Eina_Bool constrain) EINA_ARG_NONNULL(1);
763 * Retrieve the constraints on the maximum width and height of a window relative to the width and height of its screen
765 * When this function returns true, @p obj will never resize larger than the screen.
766 * @param obj The window object
767 * @return EINA_TRUE to restrict the window's maximum size, EINA_FALSE to disable restriction
769 EAPI Eina_Bool elm_win_screen_constrain_get(Evas_Object *obj) EINA_ARG_NONNULL(1);
772 * Get screen geometry details for the screen that a window is on
773 * @param obj The window to query
774 * @param x where to return the horizontal offset value. May be NULL.
775 * @param y where to return the vertical offset value. May be NULL.
776 * @param w where to return the width value. May be NULL.
777 * @param h where to return the height value. May be NULL.
779 EAPI void elm_win_screen_size_get(const Evas_Object *obj, int *x, int *y, int *w, int *h) EINA_ARG_NONNULL(1);
782 * Set the enabled status for the focus highlight in a window
784 * This function will enable or disable the focus highlight only for the
785 * given window, regardless of the global setting for it
787 * @param obj The window where to enable the highlight
788 * @param enabled The enabled value for the highlight
790 EAPI void elm_win_focus_highlight_enabled_set(Evas_Object *obj, Eina_Bool enabled) EINA_ARG_NONNULL(1);
793 * Get the enabled value of the focus highlight for this window
795 * @param obj The window in which to check if the focus highlight is enabled
797 * @return EINA_TRUE if enabled, EINA_FALSE otherwise
799 EAPI Eina_Bool elm_win_focus_highlight_enabled_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
802 * Set the style for the focus highlight on this window
804 * Sets the style to use for theming the highlight of focused objects on
805 * the given window. If @p style is NULL, the default will be used.
807 * @param obj The window where to set the style
808 * @param style The style to set
810 EAPI void elm_win_focus_highlight_style_set(Evas_Object *obj, const char *style) EINA_ARG_NONNULL(1);
813 * Get the style set for the focus highlight object
815 * Gets the style set for this windows highilght object, or NULL if none
818 * @param obj The window to retrieve the highlights style from
820 * @return The style set or NULL if none was. Default is used in that case.
822 EAPI const char *elm_win_focus_highlight_style_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
825 * ecore_x_icccm_hints_set -> accepts_focus (add to ecore_evas)
826 * ecore_x_icccm_hints_set -> window_group (add to ecore_evas)
827 * ecore_x_icccm_size_pos_hints_set -> request_pos (add to ecore_evas)
828 * ecore_x_icccm_client_leader_set -> l (add to ecore_evas)
829 * ecore_x_icccm_window_role_set -> role (add to ecore_evas)
830 * ecore_x_icccm_transient_for_set -> forwin (add to ecore_evas)
831 * ecore_x_netwm_window_type_set -> type (add to ecore_evas)
833 * (add to ecore_x) set netwm argb icon! (add to ecore_evas)
834 * (blank mouse, private mouse obj, defaultmouse)
839 * Sets the keyboard mode of the window.
841 * @param obj The window object
842 * @param mode The mode to set, one of #Elm_Win_Keyboard_Mode
844 EAPI void elm_win_keyboard_mode_set(Evas_Object *obj, Elm_Win_Keyboard_Mode mode) EINA_ARG_NONNULL(1);
847 * Gets the keyboard mode of the window.
849 * @param obj The window object
850 * @return The mode, one of #Elm_Win_Keyboard_Mode
852 EAPI Elm_Win_Keyboard_Mode elm_win_keyboard_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
855 * Sets whether the window is a keyboard.
857 * @param obj The window object
858 * @param is_keyboard If true, the window is a virtual keyboard
860 EAPI void elm_win_keyboard_win_set(Evas_Object *obj, Eina_Bool is_keyboard) EINA_ARG_NONNULL(1);
863 * Gets whether the window is a keyboard.
865 * @param obj The window object
866 * @return If the window is a virtual keyboard
868 EAPI Eina_Bool elm_win_keyboard_win_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
871 * Get the screen position of a window.
873 * @param obj The window object
874 * @param x The int to store the x coordinate to
875 * @param y The int to store the y coordinate to
877 EAPI void elm_win_screen_position_get(const Evas_Object *obj, int *x, int *y) EINA_ARG_NONNULL(1);
884 * @defgroup Inwin Inwin
886 * @image html img/widget/inwin/preview-00.png
887 * @image latex img/widget/inwin/preview-00.eps
888 * @image html img/widget/inwin/preview-01.png
889 * @image latex img/widget/inwin/preview-01.eps
890 * @image html img/widget/inwin/preview-02.png
891 * @image latex img/widget/inwin/preview-02.eps
893 * An inwin is a window inside a window that is useful for a quick popup.
896 * It works by creating an object that will occupy the entire window, so it
897 * must be created using an @ref Win "elm_win" as parent only. The inwin
898 * object can be hidden or restacked below every other object if it's
899 * needed to show what's behind it without destroying it. If this is done,
900 * the elm_win_inwin_activate() function can be used to bring it back to
901 * full visibility again.
903 * There are three styles available in the default theme. These are:
904 * @li default: The inwin is sized to take over most of the window it's
906 * @li minimal: The size of the inwin will be the minimum necessary to show
908 * @li minimal_vertical: Horizontally, the inwin takes as much space as
909 * possible, but it's sized vertically the most it needs to fit its\
912 * Some examples of Inwin can be found in the following:
913 * @li @ref inwin_example_01
919 * Adds an inwin to the current window
921 * The @p obj used as parent @b MUST be an @ref Win "Elementary Window".
922 * Never call this function with anything other than the top-most window
923 * as its parameter, unless you are fond of undefined behavior.
925 * After creating the object, the widget will set itself as resize object
926 * for the window with elm_win_resize_object_add(), so when shown it will
927 * appear to cover almost the entire window (how much of it depends on its
928 * content and the style used). It must not be added into other container
929 * objects and it needs not be moved or resized manually.
931 * @param parent The parent object
932 * @return The new object or NULL if it cannot be created
934 // XXX: deprecate this
935 EAPI Evas_Object *elm_win_inwin_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
938 * Activates an inwin object, ensuring its visibility
940 * This function will make sure that the inwin @p obj is completely visible
941 * by calling evas_object_show() and evas_object_raise() on it, to bring it
942 * to the front. It also sets the keyboard focus to it, which will be passed
945 * The object's theme will also receive the signal "elm,action,show" with
948 * @param obj The inwin to activate
950 // XXX: deprecate this
951 EAPI void elm_win_inwin_activate(Evas_Object *obj) EINA_ARG_NONNULL(1);
954 * Set the content of an inwin object.
956 * Once the content object is set, a previously set one will be deleted.
957 * If you want to keep that old content object, use the
958 * elm_win_inwin_content_unset() function.
960 * @param obj The inwin object
961 * @param content The object to set as content
963 // XXX: deprecate this
964 EAPI void elm_win_inwin_content_set(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
967 * Get the content of an inwin object.
969 * Return the content object which is set for this widget.
971 * The returned object is valid as long as the inwin is still alive and no
972 * other content is set on it. Deleting the object will notify the inwin
973 * about it and this one will be left empty.
975 * If you need to remove an inwin's content to be reused somewhere else,
976 * see elm_win_inwin_content_unset().
978 * @param obj The inwin object
979 * @return The content that is being used
981 // XXX: deprecate this
982 EAPI Evas_Object *elm_win_inwin_content_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
985 * Unset the content of an inwin object.
987 * Unparent and return the content object which was set for this widget.
989 * @param obj The inwin object
990 * @return The content that was being used
992 // XXX: deprecate this
993 EAPI Evas_Object *elm_win_inwin_content_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
998 /* X specific calls - won't work on non-x engines (return 0) */
1001 * Get the Ecore_X_Window of an Evas_Object
1003 * @param obj The object
1005 * @return The Ecore_X_Window of @p obj
1009 EAPI Ecore_X_Window elm_win_xwindow_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
1011 /* smart callbacks called:
1012 * "delete,request" - the user requested to delete the window
1013 * "focus,in" - window got focus
1014 * "focus,out" - window lost focus
1015 * "moved" - window that holds the canvas was moved