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 accel_preference for details on this environment variable values.
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
Unknown window type (since 1.9)
A normal window.
Indicates a normal, top-level window. Almost every window will be created with this type.
Used for simple dialog windows
For special desktop windows, like a background window holding desktop icons.
The window is used as a dock or panel.
Usually would be kept on top of any other window by the Window Manager.
The window is used to hold a floating toolbar, or similar.
Similar to ELM_WIN_TOOLBAR.
A persistent utility window, like a toolbox or palette.
Splash window for a starting up application.
The window is a dropdown menu, as when an entry in a menubar is clicked.
Typically used with override. This hint exists for completion only, as the EFL way of implementing a menu would not normally use a separate window for its contents.
Like ELM_WIN_DROPDOWN_MENU, but for the menu triggered by right-clicking an object.
The window is a tooltip.
A short piece of explanatory text that typically appear after the mouse cursor hovers over an object for a while. Typically used with override and also not very commonly used in the EFL.
A notification window, like a warning about battery life or a new E-Mail received.
A window holding the contents of a combo box.
Not usually used in the EFL.
Used to indicate the window is a representation of an object being dragged across different windows, or even applications.
Typically used with override.
The window is rendered onto an image buffer.
No actual window is created for this type, instead the window and all of its contents will be rendered to an image buffer. This allows to have children window inside a parent one just like any other object would be, and do other things like applying Evas_Map effects to it. This is the only type of window that requires the parent parameter to be a valid efl.evas.Object.
The window is rendered onto an image buffer and can be shown other process’s plug image object.
No actual window is created for this type, instead the window and all of its contents will be rendered to an image buffer and can be shown other process’s plug image object
Unknown indicator state.
Hides the indicator.
Shows the indicator.
Unknown indicator opacity mode.
Opacifies the indicator.
Be translucent the indicator.
Transparentizes the indicator.
Unknown keyboard state.
Request to deactivate the keyboard.
Enable keyboard with default layout.
Alpha (a-z) keyboard layout.
Numeric keyboard layout.
PIN keyboard layout.
Phone keyboard layout.
Hexadecimal numeric keyboard layout.
Full (QWERTY) keyboard layout.
Password keyboard layout.
IP keyboard layout.
Host keyboard layout.
File keyboard layout.
URL keyboard layout.
Keypad layout.
J2ME keyboard layout.
Available commands that can be sent to the Illume manager.
When running under an Illume session, a window may send commands to the Illume manager to perform different actions.
Reverts focus to the previous window
Sends focus to the next window in the list
Hides all windows to show the Home screen
Closes the currently active window
Bases: efl.elementary.__init__.Object
This is the class that actually implements the widget.
Parameters: |
|
---|
Activate a window object.
This function sends a request to the Window Manager to activate the window. If honored by the WM, the window will receive the keyboard focus.
Note
This is just a request that a Window Manager may ignore, so calling this function does not ensure in any way that the window will be the active one after it.
The alpha channel state of a window.
If alpha is True, the alpha channel of the canvas will be enabled possibly making parts of the window completely or partially transparent. This is also subject to the underlying system supporting it, like for example, running under a compositing manager. If no compositing is available, enabling this option will instead fallback to using shaped windows, with shaped.
Type: | bool |
---|
Set the aspect ratio of a window.
If 0, the window has no aspect limits, otherwise it is width divided by height
Type: | float |
---|
The window’s autodel state.
When closing the window in any way outside of the program control, like pressing the X button in the titlebar or using a command from the Window Manager, a “delete,request” signal is emitted to indicate that this event occurred and the developer can take any action, which may include, or not, destroying the window object.
When this property is set, the window will be automatically destroyed when this event occurs, after the signal is emitted. If autodel is False, then the window will not be destroyed and is up to the program to do so when it’s required.
Type: | bool |
---|
The window’s autohide state.
This property works similarly to autodel(), automatically handling “delete,request” signals when set to True, with the difference that it will hide the window, instead of destroying it.
It is specially designed to work together with ELM_POLICY_QUIT_LAST_WINDOW_HIDDEN which allows exiting Elementary’s main loop when all the windows are hidden.
Note
autodel() and autohide() are not mutually exclusive. The window will be deleted if both are set to True.
Type: | bool |
---|
New in version 1.15.
The array of available profiles to a window.
Type: | list of strings |
---|
New in version 1.8.
The borderless state of a window.
Setting this to True requests the Window Manager to not draw any decoration around the window.
Type: | bool |
---|
The user requested to close the window. See autodel.
window got focus
window lost focus
When the window has received focus.
New in version 1.8.
window has become fullscreen
window is minimized (perhaps into an icon or taskbar)
an indicator’s property has been changed
there has been a low-level I/O error with the display system
window has been maximized
window that holds the canvas was moved
window is in a normal state (not withdrawn or iconified)
profile of the window has been changed
window rotation has been changed
window has become sticky (shows on all desktops)
When the theme was changed.
New in version 1.13.
When the window has lost focus.
New in version 1.8.
window has stopped being fullscreen
window has stopped being maximized
window has stopped being sticky
window is still managed normally but removed from view
Center a window on its screen
This function centers window horizontally and/or vertically based on the values of h and v.
Parameters: |
|
---|
Whether this window is an illume conformant window.
Type: | bool |
---|
The demand attention state of the window.
Type: | bool |
---|
Floating mode of a window.
Type: | bool |
---|
New in version 1.8.
Determine whether a window has focus
Type: | bool |
---|
The animate status for the focus highlight for this window.
This will enable or disable the animation of focus highlight only for the given window, regardless of the global setting for it
Type: | bool |
---|
New in version 1.8.
The enabled status of the focus highlight in a window
This will enable or disable the focus highlight only for the given window, regardless of the global setting for it
Type: | bool |
---|
The style for the focus highlight on this window
The style to use for theming the highlight of focused objects on the given window. If style is None, the default will be used.
Type: | string |
---|
Set the window to be skipped by keyboard focus
This sets the window to be skipped by normal keyboard input. This means a window manager will be asked to not focus this window as well as omit it from things like the taskbar, pager, “alt-tab” list etc. etc.
Set this and enable it on a window BEFORE you show it for the first time, otherwise it may have no effect.
Use this for windows that have only output information or might only be interacted with by the mouse or fingers, and never for typing input. Be careful that this may have side-effects like making the window non-accessible in some cases unless the window is specially handled. Use this with care.
Type: | bool |
---|
The fullscreen state of a window.
Type: | bool |
---|
The icon name of the window.
Type: | string |
---|
The object to represent the window icon
This sets an object that will be used as the icon for the window. The exact pixel dimensions of the object (not object size) will be used, and the image pixels will be used as-is when this function is called. If the image object has been updated, then call this function again to source the image pixels and put them on the window’s icon. This has limitations as only image objects allowed at this stage. This may be lifted in future.
Type: | efl.elementary.image.Image |
---|
The iconified state of the window.
Type: | bool |
---|
Send a command to the windowing environment
This is intended to work in touchscreen or small screen device environments where there is a more simplistic window management policy in place. This uses the window object indicated to select which part of the environment to control (the part that this window lives in), and provides a command and an optional parameter structure (use None for this if not needed).
Parameters: |
|
---|
The indicator mode of the window.
Type: | Indicator states |
---|
The indicator opacity mode of the window.
Type: | Indicator opacity |
---|
Get the inlined image object handle
When you create a window of type ELM_WIN_INLINED_IMAGE, then the window is in fact an evas image object inlined in the parent canvas. You can get this object (be careful to not manipulate it as it is under control of elementary), and use it to do things like get pixel data, save the image to a file, etc.
Type: | efl.evas.Image |
---|
The keyboard mode of the window.
Type: | Keyboard virtual keyboard modes |
---|
Whether the window is a keyboard.
Type: | bool |
---|
The layer of the window.
What this means exactly will depend on the underlying engine used.
In the case of X11 backed engines, the value in layer has the following meanings:
Type: | int |
---|
Lower a window object.
Places the window at the bottom of the stack, so that no other window is covered by it.
If override is not set, the Window Manager may ignore this request.
Get the Main Menu of a window.
Type: | efl.evas.Object |
---|
New in version 1.8.
The maximized state of a window.
Type: | bool |
---|
The Modal state of the window.
Type: | bool |
---|
How many times norender has been pushed on the window
Type: | int |
---|
See also
New in version 1.8.
This pops (decrements) the norender counter on the window
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
New in version 1.8.
This pushes (increments) the norender counter on the window
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
New in version 1.8.
The override state of a window.
A window with override set to True will not be managed by the Window Manager. This means that no decorations of any kind will be shown for it, moving and resizing must be handled by the application, as well as the window visibility.
This should not be used for normal windows, and even for not so normal ones, it should only be used when there’s a good reason and with a lot of care. Mishandling override windows may result situations that disrupt the normal workflow of the end user.
Type: | bool |
---|
The profile of a window.
Type: | unicode |
---|
New in version 1.8.
Whether this window is an illume quickpanel window.
Type: | bool |
---|
The major priority of a quickpanel window.
Type: | int |
---|
The minor priority of a quickpanel window.
Type: | int |
---|
Which zone this quickpanel should appear in.
Type: | int |
---|
This manually asks evas to render the window now
You should NEVER call this unless you really know what you are doing and why. Never call this unless you are asking for performance degradation and possibly weird behavior. Windows get automatically rendered when the application goes idle so there is never a need to call this UNLESS you have enabled “norender” mode.
See also
New in version 1.8.
Add subobj as a resize object of the window.
Setting an object as a resize object of the window means that the subobj child’s size and position will be controlled by the window directly. That is, the object will be resized to match the window size and should never be moved or resized manually by the developer.
In addition, resize objects of the window control what the minimum size of it will be, as well as whether it can or not be resized by the user.
For the end user to be able to resize a window by dragging the handles or borders provided by the Window Manager, or using any other similar mechanism, all of the resize objects in the window should have their size_hint_weight set to EVAS_HINT_EXPAND.
Also notice that the window can get resized to the current size of the object if the EVAS_HINT_EXPAND is set after the call to resize_object_add(). So if the object should get resized to the size of the window, set this hint before adding it as a resize object (this happens because the size of the window and the object are evaluated as soon as the object is added to the window).
Parameters: | subobj (Object) – The resize object to add |
---|
Delete subobj as a resize object of the window.
This function removes the object subobj from the resize objects of the window. It will not delete the object itself, which will be left unmanaged and should be deleted by the developer, manually handled or set as child of some other container.
Parameters: | subobj (efl.elementary.object.Object) – The resize object to add |
---|
The role of the window.
Type: | string |
---|
The rotation of the window.
Most engines only work with multiples of 90.
This function is used to set the orientation of the window to match that of the screen. The window itself will be resized to adjust to the new geometry of its contents. If you want to keep the window size, see rotation_with_resize.
Type: | int |
---|
Rotates the window and resizes it.
Like rotation, but it also resizes the window’s contents so that they fit inside the current window geometry.
Type: | int |
---|
Constrain the maximum width and height of a window to the width and height of its screen
When constrain is true, the window will never resize larger than the screen.
Type: | bool |
---|
Get screen DPI for the screen that a window is on
Type: | (int X_DPI, int Y_DPI) |
---|
New in version 1.8.
Get the screen position of a window.
Type: | (int X, int Y) |
---|
Get screen geometry details for the screen that a window is on
Type: | (int X, int Y, int W, int H) |
---|
The shaped state of a window.
Shaped windows, when supported, will render the parts of the window that has no content, transparent.
If shaped is False, then it is strongly advised to have some background object or cover the entire window in any other way, or the parts of the canvas that have no data will show framebuffer artifacts.
See also
Type: | bool |
---|
The base window size used with stepping calculation
Base size + stepping is what is calculated for window sizing restrictions.
Type: | (int w, int h) |
---|
See also
Set the window stepping used with sizing calculation
Base size + stepping is what is calculated for window sizing restrictions.
Type: | (int w, int h) |
---|
See also
Create a socket to provide the service for Plug widget
Parameters: |
|
---|---|
Raises RuntimeError: | |
if the socket could not be created. |
Changed in version 1.8: Raises RuntimeError if creating a socket fails
The Sticky state of the window.
Type: | bool |
---|
The title of the window.
Type: | string |
---|
Get the type of a window.
Returns: | The type of the window |
---|---|
Return type: | Window types |
The urgent state of the window.
Type: | bool |
---|
The withdrawn state of the window.
Type: | bool |
---|
List of available window rotations.
Type: | list of int |
---|
New in version 1.9.
The manual rotation done mode.
This is used to set the manual rotation done mode. The message of rotation done is sent to WM after rendering its canvas but, if this property is set to True, the user should call the wm_rotation_manual_rotation_done() explicitly to sends the message.
Type: | bool |
---|
New in version 1.9.
This function is used to notify the rotation done to WM manually.
New in version 1.9.
The preferred rotation value.
This is used to set the orientation of the window to a specific fixed angle in degrees, 0-360 counter-clockwise.
Type: | int |
---|
New in version 1.9.
Whether window manager supports window rotation or not.
The window manager rotation allows the WM to controls the rotation of application windows. It is designed to support synchronized rotation for the multiple application windows at same time.
Type: | bool |
---|
New in version 1.9.
Returns the X Window id.
X Window id is a value of type long int which can be used in combination with some functions/objects in the ecore_x module.
For example you can hide the mouse cursor with:
import ecore_x
xid = your_elm_win.xwindow_xid
xwin = ecore_x.Window_from_xid(xid)
xwin.cursor_hide()
Warning
This is not portable at all. Works only under the X window system. And you must build python-efl with ecore_x enabled.
Type: | long |
---|
Bases: efl.elementary.__init__.Window
A Window with standard setup.
This creates a window like Window but also puts in a standard Background, as well as setting the window title to title. The window type created is of type ELM_WIN_BASIC, with None as the parent widget.
Parameters: |
|
---|
Bases: efl.elementary.__init__.Window
A Window with standard dialog setup.
This creates a window like Window but also puts in a standard Background, 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.
New in version 1.13.
Parameters: |
|
---|