Win

- Main Page
- Related Pages
- Data Structures
- Files
- Examples

Modules | Typedefs | Functions
Win

## Modules
| Inwin

## Typedefs
typedef struct _Elm_Win_Trap | Elm_Win_Trap
| Trap can be set with elm_win_trap_set() and will intercept the calls to internal ecore_evas with the same name and parameters. More...

## Functions
Eina_Bool | elm_win_trap_set (const Elm_Win_Trap *trap)
| Sets the trap to be used for internal `Ecore_Evas` management. More...
Evas_Object * | elm_win_add (Evas_Object *parent, const char *name, Elm_Win_Type type)
| Adds a window object. More...
Evas_Object * | elm_win_fake_add (Ecore_Evas *ee)
| Creates a fake window object using a pre-existing canvas. More...
Evas_Object * | elm_win_util_standard_add (const char *name, const char *title)
| Adds a window object with standard setup. More...
Evas_Object * | elm_win_util_dialog_add (Evas_Object *parent, const char *name, const char *title)
| Adds a window object with dialog setup. More...
void | elm_win_floating_mode_set (Evas_Object *obj, Eina_Bool floating)
| Set the floating mode of a window. More...
Eina_Bool | elm_win_floating_mode_get (const Evas_Object *obj)
| Get the floating mode of a window. More...
void | elm_win_norender_push (Evas_Object *obj)
| This pushes (increments) the norender counter on the window. More...
void | elm_win_norender_pop (Evas_Object *obj)
| This pops (decrements) the norender counter on the window. More...
int | elm_win_norender_get (const Evas_Object *obj)
| The retruns how many times norender has been pushed on the window. More...
void | elm_win_render (Evas_Object *obj)
| This manually asks evas to render the window now. More...
Ecore_Wl_Window * | elm_win_wl_window_get (const Evas_Object *obj)
| Get the Ecore_Wl_Window of an Evas_Object. More...
Ecore_Window | elm_win_window_id_get (const Evas_Object *obj)
| Get the Ecore_Window of an Evas_Object. More...

## Detailed Description

The window class of Elementary. Contains functions to manipulate windows. The Evas engine used to render the window contents is specified in the system or user elementary config files (whichever is found last), and can be overridden with the ELM_ENGINE environment variable for testing. Engines that may be supported (depending on Evas and Ecore-Evas compilation setup and modules actually installed at runtime) are (listed in order of best supported and most likely to be complete and work to lowest quality). Note that ELM_ENGINE is really only needed for special cases and debugging. you should normally use ELM_DISPLAY and ELM_ACCEL environment variables, or core elementary config. ELM_DISPLAY can be set to "x11" or "wl" to indicate the target display system (as on Linux systems you may have both display systems available, so this selects which to use). ELM_ACCEL may also be set to indicate if you want accelerations and which kind to use. see elm_config_accel_preference_set(0 for details on this environment variable values.

- "x11", "x", "software-x11", "software_x11" (Software rendering in X11)
- "gl", "opengl", "opengl-x11", "opengl_x11" (OpenGL or OpenGL-ES2 rendering in X11)
- "shot:..." (Virtual screenshot renderer - renders to output file and exits)
- "fb", "software-fb", "software_fb" (Linux framebuffer direct software rendering)
- "sdl", "software-sdl", "software_sdl" (SDL software rendering to SDL buffer)
- "gl-sdl", "gl_sdl", "opengl-sdl", "opengl_sdl" (OpenGL or OpenGL-ES2 rendering using SDL as the buffer)
- "gdi", "software-gdi", "software_gdi" (Windows WIN32 rendering via GDI with software)
- "ddraw", "software-ddraw", "software_ddraw" (Windows WIN32 rendering via DirectDraw with software)
- "ews" (rendering to EWS - Ecore + Evas Single Process Windowing System)
- "gl-cocoa", "gl_cocoa", "opengl-cocoa", "opengl_cocoa" (OpenGL rendering in Cocoa)
- "wayland_shm" (Wayland client SHM rendering)
- "wayland_egl" (Wayland client OpenGL/EGL rendering)
- "drm" (Linux drm/kms etc. direct display)

All engines use a simple string to select the engine to render, EXCEPT the "shot" engine. This actually encodes the output of the virtual screenshot and how long to delay in the engine string. The engine string is encoded in the following way:

"shot:[delay=XX][:][repeat=DDD][:][file=XX]"

Where options are separated by a ":" char if more than one option is given, with delay, if provided being the first option and file the last (order is important). The delay specifies how long to wait after the window is shown before doing the virtual "in memory" rendering and then save the output to the file specified by the file option (and then exit). If no delay is given, the default is 0.5 seconds. If no file is given the default output file is "out.png". Repeat option is for continuous capturing screenshots. Repeat range is from 1 to 999 and filename is fixed to "out001.png" Some examples of using the shot engine:

ELM_ENGINE="shot:delay=1.0:repeat=5:file=elm_test.png" elementary_test ELM_ENGINE="shot:delay=1.0:file=elm_test.png" elementary_test ELM_ENGINE="shot:file=elm_test2.png" elementary_test ELM_ENGINE="shot:delay=2.0" elementary_test ELM_ENGINE="shot:" elementary_test

Signals that you can add callbacks for are:

- "delete,request": the user requested to close the window. See elm_win_autodel_set() and elm_win_autohide_set().
- "focus,in": window got focus (deprecated. use "focused" instead.)
- "focus,out": window lost focus (deprecated. use "unfocused" instead.)
- "moved": window that holds the canvas was moved
- "withdrawn": window is still managed normally but removed from view
- "iconified": window is minimized (perhaps into an icon or taskbar)
- "normal": window is in a normal state (not withdrawn or iconified)
- "stick": window has become sticky (shows on all desktops)
- "unstick": window has stopped being sticky
- "fullscreen": window has become fullscreen
- "unfullscreen": window has stopped being fullscreen
- "maximized": window has been maximized
- "unmaximized": window has stopped being maximized
- "ioerr": there has been a low-level I/O error with the display system
- "indicator,prop,changed": an indicator's property has been changed
- "rotation,changed": window rotation has been changed
- "profile,changed": profile of the window has been changed
- "focused" : When the win has received focus. (since 1.8)
- "unfocused" : When the win has lost focus. (since 1.8)
- "theme,changed" - The theme was changed. (since 1.13)

Note that calling evas_object_show() after window contents creation is recommended. It will trigger evas_smart_objects_calculate() and some backend calls directly. For example, XMapWindow is called directly during evas_object_show() in X11 engine.

Examples:

- Win - General API overview

## Typedef Documentation

Elm_Win_Trap

Trap can be set with elm_win_trap_set() and will intercept the calls to internal ecore_evas with the same name and parameters.

If there is a trap and it returns `EINA_TRUE` then the call will be allowed, otherwise it will be ignored.

Since
  1.7

## Function Documentation

Evas_Object* elm_win_add | ( | Evas_Object * | parent,
|  | const char * | name,
|  | Elm_Win_Type | type
| ) |  |

Adds a window object.

If this is the first window created, pass NULL as `parent`.

Parameters

  parent | Parent object to add the window to, or NULL
  name | The name of the window
  type | The window type, one of #Elm_Win_Type.

The `parent` parameter can be `NULL` for every window `type` except #ELM_WIN_INLINED_IMAGE, which needs a parent to retrieve the canvas on which the image object will be created.

Returns
  The created object, or `NULL` on failure

Referenced by elm_quicklaunch_seed(), elm_win_util_dialog_add(), and elm_win_util_standard_add().

Evas_Object* elm_win_fake_add | ( | Ecore_Evas * | ee | ) |

Creates a fake window object using a pre-existing canvas.

Parameters

  ee | The Ecore_Evas to use

The returned window widget will not manage or modify the canvas; this canvas must continue to be managed externally.

Do not use this function if you are not writing a window manager.

Warning
  Exact behaviors of this function are not guaranteed.

Returns
  The created object, or `NULL` on failure

Since
  1.13

Eina_Bool elm_win_floating_mode_get | ( | const Evas_Object * | obj | ) |

Get the floating mode of a window.

Parameters

  obj | The window object

Returns
  If true, the window is floating mode

See also
  elm_win_floating_mode_set()

Since
  1.8

void elm_win_floating_mode_set | ( | Evas_Object * | obj,
|  | Eina_Bool | floating
| ) |  |

Set the floating mode of a window.

Parameters

  obj | The window object
  floating | If true, the window is floating mode

The floating mode can be used on mobile environment. For example, if the video-player window sets the floating mode, then e (enlightenment window manager) changes its geometry and handles it like a popup. This is similar to a multi window concept in a mobile phone. The way of handling floating mode window is decided by enlightenment window manager.

See also
  elm_win_floating_mode_get()

Since
  1.8

int elm_win_norender_get | ( | const Evas_Object * | obj | ) |

The retruns how many times norender has been pushed on the window.

Parameters

  obj | The window object

Returns
  The number of times norender has been pushed

See also
  elm_win_norender_push()
  elm_win_norender_pop()
  elm_win_render()

Since
  1.7

void elm_win_norender_pop | ( | Evas_Object * | obj | ) |

This pops (decrements) the norender counter on the window.

Parameters

  obj | The window object

Once norender has gone back to 0, then automatic rendering will continue in the given window. If it is already at 0, this will have no effect.

See also
  elm_win_norender_push()
  elm_win_norender_get()
  elm_win_render()

Since
  1.7

void elm_win_norender_push | ( | Evas_Object * | obj | ) |

This pushes (increments) the norender counter on the window.

Parameters

  obj | The window object

There are some occasions where you wish to suspend rendering on a window. You may be "sleeping" and have nothing to update and do not want animations or other theme side-effects causing rendering to the window while "asleep". You can push (and pop) the norender mode to have this work.

If combined with evas_render_dump(), evas_image_cache_flush() and evas_font_cache_flush() (and maybe edje_file_cache_flush() and edje_collection_cache_flush()), you can minimize memory footprint significantly while "asleep", and the pausing of rendering ensures evas does not re-load data into memory until needed. When rendering is resumed, data will be re-loaded as needed, which may result in some lag, but does save memory.

See also
  elm_win_norender_pop()
  elm_win_norender_get()
  elm_win_render()

Since
  1.7

void elm_win_render | ( | Evas_Object * | obj | ) |

This manually asks evas to render the window now.

Parameters

  obj | The window object

You should NEVER call this unless you really know what you are doing and why. Never call this unless you are asking for performance degredation and possibly weird behavior. Windows get automatically rendered when the application goes into the idle enter state so there is never a need to call this UNLESS you have enabled "norender" mode.

See also
  elm_win_norender_push()
  elm_win_norender_pop()
  elm_win_norender_get()

Since
  1.7

Eina_Bool elm_win_trap_set | ( | const Elm_Win_Trap * | trap | ) |

Sets the trap to be used for internal `Ecore_Evas` management.

Parameters

  trap | the trap to be used or `NULL` to remove traps. Pointer is not modified or copied, keep it alive.

Returns
  `EINA_TRUE` on success, `EINA_FALSE` if there was a problem, such as invalid version number.

Warning
  this is an advanced feature that you should avoid using.

Since
  1.7

Evas_Object* elm_win_util_dialog_add | ( | Evas_Object * | parent,
|  | const char * | name,
|  | const char * | title
| ) |  |

Adds a window object with dialog setup.

Parameters

  parent | The parent window
  name | The name of the window
  title | The title for the window

This creates a window like elm_win_add() but also puts in a standard background with elm_bg_add(), as well as setting the window title to `title`. The window type created is of type ELM_WIN_DIALOG_BASIC. This tipe of window will be handled in special mode by window managers with regards of it's `parent` window.

Returns
  The created object, or `NULL` on failure

See also
  elm_win_add()

Since
  1.13

References elm_bg_add(), and elm_win_add().

Evas_Object* elm_win_util_standard_add | ( | const char * | name,
|  | const char * | title
| ) |  |

Adds a window object with standard setup.

Parameters

  name | The name of the window
  title | The title for the window

This creates a window like elm_win_add() but also puts in a standard background with elm_bg_add(), as well as setting the window title to `title`. The window type created is of type ELM_WIN_BASIC, with `NULL` as the parent widget.

Returns
  The created object, or `NULL` on failure

See also
  elm_win_add()

References elm_bg_add(), and elm_win_add().

Ecore_Window elm_win_window_id_get | ( | const Evas_Object * | obj | ) |

Get the Ecore_Window of an Evas_Object.

When Elementary is using a Wayland engine, this function will return the surface id of the elm window's surface.

Parameters

  obj | The window object

Returns
  The Ecore_Window of an Evas_Object

Since
  1.8

Note
  Unless you are getting the window id for the purpose of communicating between client<->compositor over dbus, this is definitely not the function you are looking for.

Ecore_Wl_Window* elm_win_wl_window_get | ( | const Evas_Object * | obj | ) |

Get the Ecore_Wl_Window of an Evas_Object.

Do not use this function if you'd like your application/library be portable. You have been warned.

Parameters

  obj | the object

Returns
  The Ecore_Wl_Window of `obj`