Implements the following functionality
in order to share data across application windows.
Contains functions to select text or a portion of data, send it to a buffer, and paste the data into a target.
elm_cnp provides a generic copy and paste facility based on its windowing system. It is not necessary to know the details of each windowing system, but some terms and behavior are common. Currently the X11 window system is widely used, and only X11 functionality is implemented.
In X11R6 window system, CopyPaste works like a peer-to-peer communication. Copying is an operation on an object in an X server. X11 calls those objects ‘selections’ which have names. Generally, two selection types are needed for copy and paste: The Primary selection and the Clipboard selection. Primary selection is for selecting text (that means highlighted text). Clipboard selection is for explicit copying behavior (such as ctrl+c, or ‘copy’ in a menu). Thus, in applications most cases only use the clipboard selection. As stated before, taking ownership of a selection doesn’t move any actual data. Copying and Pasting is described as follows:
efl.elementary.
ELM_FOCUS_PREVIOUS
¶Focus previous
efl.elementary.
ELM_FOCUS_NEXT
¶Focus next
efl.elementary.
ELM_FOCUS_UP
¶Focus up
New in version 1.8.1.
efl.elementary.
ELM_FOCUS_DOWN
¶Focus down
New in version 1.8.1.
efl.elementary.
ELM_FOCUS_RIGHT
¶Focus right
New in version 1.8.1.
efl.elementary.
ELM_FOCUS_LEFT
¶Focus left
New in version 1.8.1.
efl.elementary.
ELM_FOCUS_MOVE_POLICY_CLICK
¶Give focus to object when they are clicked
New in version 1.10.
efl.elementary.
ELM_FOCUS_MOVE_POLICY_IN
¶Give focus to object on mouse-in
New in version 1.10.
efl.elementary.
ELM_FOCUS_MOVE_POLICY_KEY_ONLY
¶Focus is set on key input like Left, Right, Up, Down, Tab, or Shift+Tab
New in version 1.15.
efl.elementary.
ELM_FOCUS_AUTOSCROLL_MODE_SHOW
¶Directly show the focused region or item automatically.
New in version 1.10.
efl.elementary.
ELM_FOCUS_AUTOSCROLL_MODE_NONE
¶Do not show the focused region or item automatically.
New in version 1.10.
efl.elementary.
ELM_FOCUS_AUTOSCROLL_MODE_BRING_IN
¶Bring_in the focused region or item automatically which might invole the scrolling
New in version 1.10.
efl.elementary.
EVAS_CALLBACK_KEY_DOWN
¶efl.elementary.
EVAS_CALLBACK_KEY_UP
¶efl.elementary.
EVAS_CALLBACK_MOUSE_WHEEL
¶Defines the types of selection property names.
see: | http://www.x.org/docs/X11/xlib.pdf for more details. |
---|
efl.elementary.
ELM_SEL_TYPE_PRIMARY
¶Primary text selection (highlighted or selected text)
efl.elementary.
ELM_SEL_TYPE_SECONDARY
¶Used when primary selection is in use
efl.elementary.
ELM_SEL_TYPE_XDND
¶Drag ‘n’ Drop
efl.elementary.
ELM_SEL_TYPE_CLIPBOARD
¶Clipboard selection (ctrl+C)
Defines the types of content.
efl.elementary.
ELM_SEL_FORMAT_TARGETS
¶For matching every possible atom
efl.elementary.
ELM_SEL_FORMAT_NONE
¶Content is from outside of Elementary
efl.elementary.
ELM_SEL_FORMAT_TEXT
¶Plain unformatted text: Used for things that don’t want rich markup
efl.elementary.
ELM_SEL_FORMAT_MARKUP
¶Edje textblock markup, including inline images
efl.elementary.
ELM_SEL_FORMAT_IMAGE
¶Images
efl.elementary.
ELM_SEL_FORMAT_VCARD
¶Vcards
efl.elementary.
ELM_SEL_FORMAT_HTML
¶Raw HTML-like data (eg. webkit)
Defines the kind of action associated with the drop data if for XDND
New in version 1.8.
efl.elementary.
ELM_XDND_ACTION_UNKNOWN
¶Action type is unknown
efl.elementary.
ELM_XDND_ACTION_COPY
¶Copy the data
efl.elementary.
ELM_XDND_ACTION_MOVE
¶Move the data
efl.elementary.
ELM_XDND_ACTION_PRIVATE
¶Private action type
efl.elementary.
ELM_XDND_ACTION_ASK
¶Ask the user what to do
efl.elementary.
ELM_XDND_ACTION_LIST
¶List the data
efl.elementary.
ELM_XDND_ACTION_LINK
¶Link the data
efl.elementary.
ELM_XDND_ACTION_DESCRIPTION
¶Describe the data
efl.elementary.
ELM_OBJECT_SELECT_MODE_DEFAULT
¶Items will only call their selection func and callback when first becoming selected. Any further clicks will do nothing, unless you set always select mode.
efl.elementary.
ELM_OBJECT_SELECT_MODE_ALWAYS
¶This means that, even if selected, every click will make the selected callbacks be called.
efl.elementary.
ELM_OBJECT_SELECT_MODE_NONE
¶This will turn off the ability to select items entirely and they will neither appear selected nor call selected callback functions.
efl.elementary.
ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY
¶No select mode with no finger size rule
efl.elementary.
Object
(*args, **kwargs)¶Bases: efl.evas.SmartObject
All widgets are based on this class.
cnp_selection_clear
(selection)¶Clear the selection data of a widget.
Clear all data from the selection which is owned by a widget.
Parameters: | selection (Selection type) – Selection type for copying and pasting |
---|---|
Return bool: | Whether clearing cnp data was successful or not. |
cnp_selection_get
(selection, format, datacb, udata=None)¶Retrieve data from a widget that has a selection.
Gets the current selection data from a widget. The widget input here
will usually be elm_entry, in which case datacb
and udata
can be
None. If a different widget is passed, datacb
and udata
are used
for retrieving data.
Parameters: |
|
---|---|
Return bool: | Whether getting cnp data was successful or not. |
cnp_selection_loss_callback_set
(selection, func, data=None)¶Set a function to be called when a selection is lost
The function func
is set of be called when selection selection
is lost to another process or when cnp_selection_set()
is
called. If func
is None then it is not called. data
is passed as
the data parameter to the callback functions and selection is passed in
as the selection that has been lost.
cnp_selection_set()
and cnp_selection_clear()
automatically set this loss callback to NULL when called. If you wish to
take the selection and then be notified of loss please do this
(for example):
obj.cnp_selection_set(ELM_SEL_TYPE_PRIMARY, ELM_SEL_FORMAT_TEXT, "hello")
obj.cnp_selection_loss_callback_set(ELM_SEL_TYPE_PRIMARY, loss_cb)
Parameters: |
|
---|
cnp_selection_set
(selection, format, buf)¶Set copy data for a widget.
Set copy data and take ownership of selection. Format is used for specifying the selection type, and this is used during pasting.
Parameters: |
|
---|---|
Return bool: | Whether setting cnp data was successful or not. |
content
¶Main content part for this object.
Type: | efl.evas.Object |
---|
content_get
()¶content_set
(obj)¶content_unset
()¶cursor
¶The cursor to be shown when mouse is over the object
Type: | string |
---|
cursor_get
()¶cursor_set
(cursor)¶cursor_style
¶The style for this object cursor.
Type: | string |
---|
cursor_style_get
()¶cursor_style_set
(style=None)¶cursor_theme_search_enabled
¶Whether cursor engine only usage is enabled for this object.
Type: | bool |
---|
Note
before you set engine only usage you should define a
cursor with cursor
cursor_theme_search_enabled_get
()¶cursor_theme_search_enabled_set
(engine_only)¶cursor_unset
()¶disabled
¶The disabled state of an Elementary object.
Elementary objects can be disabled, in which state they won’t receive input and, in general, will be themed differently from their normal state, usually greyed out. Useful for contexts where you don’t want your users to interact with some of the parts of you interface.
Type: | bool |
---|
disabled_get
()¶disabled_set
(disabled)¶domain_part_text_translatable_set
(part, domain, translatable)¶Mark the part text to be translatable or not.
Once you mark the part text to be translatable, the text will be translated
internally regardless of part_text_set()
and
domain_translatable_part_text_set()
. In other case, if you set the
Elementary policy that all text will be translatable in default, you can set
the part text to not be translated by calling this API.
Parameters: |
|
---|---|
Seealso: |
|
New in version 1.8.
domain_text_translatable_set
(domain, translatable)¶A convenience function.
domain_translatable_part_text_set
(part=None, domain=None, text=None)¶Set the text for an object’s part, marking it as translatable.
The string to set as text
must be the original one. Do not pass the
return of gettext()
here. Elementary will translate the string
internally and set it on the object using part_text_set()
,
also storing the original string so that it can be automatically
translated when the language is changed with
efl.elementary.general.language_set()
.
The domain
will be stored along to find the translation in the
correct catalog. It can be None, in which case it will use whatever
domain was set by the application with textdomain()
. This is useful
in case you are building a library on top of Elementary that will have
its own translatable strings, that should not be mixed with those of
programs using the library.
Parameters: |
|
---|
New in version 1.8.
domain_translatable_text_part_set
(part, domain, text)¶domain_translatable_text_part_set(part, domain, text)
Deprecated since version 1.8: Use domain_translatable_part_text_set()
instead.
domain_translatable_text_set
(domain, text)¶A convenience function.
elm_event_callback_add
(func, *args, **kargs)¶Add a callback for input events (key up, key down, mouse wheel) on a given Elementary widget
Every widget in an Elementary interface set to receive focus, with
focus_allow
, will propagate all of its key up,
key down and mouse wheel input events up to its parent object, and
so on. All of the focusable ones in this chain which had an event
callback set, with this call, will be able to treat those events.
There are two ways of making the propagation of these event upwards
in the tree of widgets to cease:
True
on func. False
will mean the eventwas not processed, so the propagation will go on.
event_info
passed to func
will contain theevent’s structure and, if you OR its event_flags
inner
value to EVAS_EVENT_FLAG_ON_HOLD, you’re telling
Elementary one has already handled it, thus killing the
event’s propagation, too.
Note
Your event callback will be issued on those events taking place only if no other child widget has consumed the event already.
Note
Not to be confused with
efl.evas.Object.event_callback_add()
,
which will add event callbacks per type on general Evas objects
(no event propagation infrastructure taken in account).
Note
Not to be confused with signal_callback_add()
,
which will add callbacks to signals coming from a widget’s
theme, not input events.
Note
Not to be confused with
efl.edje.Edje.signal_callback_add()
,
which does the same as signal_callback_add()
, but
directly on an Edje object.
Note
Not to be confused with
efl.evas.Object.smart_callback_add()
,
which adds callbacks to smart objects’ smart events, and not
input events.
See also
Parameters: |
|
---|
elm_event_callback_del
(func, *args, **kargs)¶Remove an event callback from a widget.
This function removes a callback, previously attached to event emission.
The parameters func and args, kwargs must match exactly those passed to
a previous call to elm_event_callback_add()
.
Parameters: |
|
---|
focus
¶Set/unset focus to a given Elementary object.
Note
When you set focus to this object, if it can handle focus, will take the focus away from the one who had it previously and will, for now on, be the one receiving input events. Unsetting focus will remove the focus from the object, passing it back to the previous element in the focus chain list.
Type: | bool |
---|
focus_allow
¶The ability for the Elementary object to be focused.
Whether the object is able to take focus or not. Unfocusable objects do nothing when programmatically focused, being the nearest focusable parent object the one really getting focus. Also, when they receive mouse input, they will get the event, but not take away the focus from where it was previously.
Type: | bool |
---|
focus_allow_get
()¶focus_allow_set
(allow)¶focus_custom_chain
¶The custom focus chain.
Type: | list of Object |
---|
focus_custom_chain_append
(child, relative_child=None)¶Append object to custom focus chain.
Note
If relative_child equal to None or not in custom chain, the object will be added in end.
Note
On focus cycle, only will be evaluated children of this container.
Parameters: |
|
---|
focus_custom_chain_get
()¶focus_custom_chain_prepend
(child, relative_child=None)¶Prepend object to custom focus chain.
Note
If relative_child equal to None or not in custom chain, the object will be added in begin.
Note
On focus cycle, only will be evaluated children of this container.
Parameters: |
|
---|
focus_custom_chain_set
(objs)¶focus_custom_chain_unset
()¶focus_get
()¶focus_highlight_style
¶The focus highlight style name to be used.
Type: | string |
---|
Note
This overrides the style which is set by
Win.focus_highlight_style_set()
.
New in version 1.9.
focus_highlight_style_get
()¶focus_highlight_style_set
(style)¶focus_move_policy
¶The focus movement policy for the object.
Type: | Focus move policy |
---|
New in version 1.15.
focus_move_policy_get
()¶focus_move_policy_set
(policy)¶focus_next
(direction)¶Give focus to next object in object tree.
Give focus to next object in focus chain of one object sub-tree. If the last object of chain already have focus, the focus will go to the first object of chain.
Parameters: | dir (Focus direction) – Direction to move the focus |
---|
focus_next_object_get
(direction)¶Get next object which was set with specific focus direction.
Get next object which was set by elm_object_focus_next_object_set with specific focus direction.
Parameters: | dir (Focus direction) – Focus direction |
---|---|
Returns: | Focus next object or None, if there is no focus next object. |
See: | focus_next() |
New in version 1.8.
focus_next_object_set
(next, direction)¶Set next object with specific focus direction.
When focus next object is set with specific focus direction, this object will be the first candidate when finding next focusable object. Focus next object can be registered with six directions that are previous, next, up, down, right, and left.
Parameters: |
|
---|---|
See: |
New in version 1.8.
focus_set
(focus)¶focused_item
¶The focused object item in an object tree.
Returns: | Current focused item or None, if there is no focused item. |
---|
New in version 1.10.
focused_item_get
()¶focused_object
¶The focused object in an object tree.
Returns: | Current focused or None, if there is no focused object. |
---|
New in version 1.8.
focused_object_get
()¶mirrored
¶The widget’s mirrored mode.
Type: | bool |
---|
mirrored_automatic
¶The widget’s mirrored mode setting. When widget in automatic
mode, it follows the system mirrored mode set by
efl.elementary.configuration.Configuration.mirrored
.
Type: | bool |
---|
mirrored_automatic_get
()¶mirrored_automatic_set
(automatic)¶mirrored_get
()¶mirrored_set
(mirrored)¶name_find
(name, recurse=0)¶Get a named object from the children
This function searches the children (or recursively children of children
and so on) of the given object looking for a child with the name of
name. If the child is found the object is returned, or None is
returned. You can set the name of an object with
name
. If the name is not unique within
the child objects (or the tree is recurse
is greater than 0) then it
is undefined as to which child of that name is returned, so ensure the
name is unique amongst children. If recurse is set to -1 it will recurse
without limit.
Parameters: |
|
---|---|
Returns: | The found object of that name, or None if none is found |
Return type: |
|
orientation_mode_disabled
¶For disabling the orientation mode.
Orientation mode is used by widgets to change their styles or to send signals whenever their window orientation is changed. If the orientation mode is enabled and the widget has different looks and styles for a window orientation (0, 90, 180, 270), it will apply a style that has been prepared for the new orientation, otherwise, it will send signals to its own edje to change its states.
Type: | bool |
---|
New in version 1.8.
orientation_mode_disabled_get
()¶orientation_mode_disabled_set
(disabled)¶parent_widget
¶The first parent of the given object that is an Elementary widget. This is a readonly property.
Note
Most of Elementary users wouldn’t be mixing non-Elementary smart objects in the objects tree of an application, as this is an advanced usage of Elementary with Evas. So, except for the application’s window, which is the root of that tree, all other objects would have valid Elementary widget parents.
Type: | Object |
---|
parent_widget_get
()¶part_content_get
(part)¶Get a content of an object
Note
Elementary objects may have many contents
Parameters: | part (string) – The content part name to get (None for the default content) |
---|---|
Returns: | content of the object or None for any error |
Return type: | efl.evas.Object |
part_content_set
(part, content)¶Set a content of an object
This sets a new object to a widget as a content object. If any object was already set as a content object in the same part, previous object will be deleted automatically.
Note
Elementary objects may have many contents
Parameters: |
|
---|
part_content_unset
(part)¶Unset a content of an object
Note
Elementary objects may have many contents
Parameters: | part (string) – The content part name to unset (None for the default content) |
---|
part_text_get
(part)¶Gets the text of a given part of this object.
See also
text
and part_text_set()
Parameters: | part (string) – part name to get the text. |
---|---|
Returns: | the text of a part or None if nothing was set. |
Return type: | string |
part_text_set
(part, text)¶Sets the text of a given part of this object.
See also
text
and part_text_get()
Parameters: |
|
---|
part_text_translatable_set
(part, translatable)¶A convenience function.
scale
¶The scaling factor for the Elementary object.
Type: | float |
---|
scale_get
()¶scale_set
(scale)¶scroll_freeze
¶The scroll freeze count.
Type: | int |
---|
New in version 1.8.
scroll_freeze_get
()¶scroll_freeze_pop
()¶Pop the scroll freeze by 1
This decrements the scroll freeze count by one. If it is more than 0 it will take effect on the parents of the indicated object.
scroll_freeze_push
()¶Push the scroll freeze by 1
This increments the scroll freeze count by one. If it is more than 0 it will take effect on the parents of the indicated object.
scroll_hold
¶The scroll hold count.
Type: | int |
---|
New in version 1.8.
scroll_hold_get
()¶scroll_hold_pop
()¶Pop the scroll hold by 1
This decrements the scroll hold count by one. If it is more than 0 it will take effect on the parents of the indicated object.
scroll_hold_push
()¶Push the scroll hold by 1
This increments the scroll hold count by one. If it is more than 0 it will take effect on the parents of the indicated object.
scroll_item_loop_enabled
¶Enable item loop feature of the given widget
If this is True, item selection/focus will loop internally. This means if arrow keys are pressed at end of scroller’s item, screen is moved to opposite side.
Type: | bool |
---|
New in version 1.10.
scroll_item_loop_enabled_get
()¶scroll_item_loop_enabled_set
(enable)¶scroll_lock_x_get
()¶scroll_lock_x_set
(lock)¶scroll_lock_y_get
()¶scroll_lock_y_set
(lock)¶signal_callback_add
(emission, source, func, *args, **kwargs)¶Add a callback for a signal emitted by widget edje object.
This function connects a callback function to a signal emitted by the edje object of the obj. Globs can occur in either the emission or source name.
Parameters: |
|
---|
signal_callback_del
(emission, source, func)¶Remove a signal-triggered callback from a widget edje object.
Parameters: |
|
---|
This function removes the last callback, previously attached to
a signal emitted by an underlying Edje object, whose
parameters emission, source and func match exactly with
those passed to a previous call to
signal_callback_add()
.
signal_emit
(emission, source)¶Send a signal to the widget edje object.
This function sends a signal to the edje object of the obj. An edje program can respond to a signal by specifying matching ‘signal’ and ‘source’ fields.
Parameters: |
|
---|
style
¶The style to be used by the widget
Type: | string |
---|
style_get
()¶style_set
(style)¶text
¶The main text for this object.
Type: | string |
---|
text_get
()¶text_set
(text)¶theme
¶A theme to be used for this object and its children.
This sets a specific theme that will be used for the given object
and any child objects it has. If th
is None then the theme to be
used is cleared and the object will inherit its theme from its
parent (which ultimately will use the default theme if no specific
themes are set).
Use special themes with great care as this will annoy users and make configuration difficult. Avoid any custom themes at all if it can be helped.
Type: | Theme |
---|
tooltip_content_cb_set
(func, *args, **kargs)¶Set the content to be shown in the tooltip object
Setup the tooltip to object. The object can have only one tooltip,
so any previews tooltip data is removed. func(owner, tooltip,
args, kargs)
will be called every time that need show the tooltip
and it should return a valid Evas_Object. This object is then
managed fully by tooltip system and is deleted when the tooltip is
gone.
Parameters: | func – Function to be create tooltip content, called when need show tooltip. |
---|
tooltip_domain_translatable_text_set
(domain, text)¶tooltip_hide
()¶Force hide tooltip of the object and (re)enable future mouse interactions.
tooltip_move_freeze_get
()¶Get the movement freeze count of the object
New in version 1.9.
tooltip_move_freeze_pop
()¶This decrements the tooltip freeze count by one. If the count is more than 0, the tooltip position will be fixed.
New in version 1.9.
tooltip_move_freeze_push
()¶This increments the tooltip movement freeze count by one. If the count is more than 0, the tooltip position will be fixed.
New in version 1.9.
tooltip_show
()¶Force show the tooltip and disable hide on mouse_out If another content is set as tooltip, the visible tooltip will hidden and showed again with new content.
This can force show more than one tooltip at a time.
tooltip_style
¶The style for this object tooltip.
Type: | string |
---|
tooltip_style_get
()¶tooltip_style_set
(style=None)¶tooltip_text_set
(text)¶Set the text to be shown in the tooltip object
Setup the text as tooltip object. The object can have only one
tooltip, so any previous tooltip data is removed. Internally, this
method calls tooltip_content_cb_set()
tooltip_translatable_text_set
(text)¶tooltip_unset
()¶Unset tooltip from object
Remove tooltip from object. If used the tooltip_text_set()
the
internal copy of label will be removed correctly. If used
tooltip_content_cb_set()
, the data will be unreferred but no
freed.
tooltip_window_mode_get
()¶tooltip_window_mode_set
(disable)¶top_widget
¶The top level parent of an Elementary widget. This is a readonly property.
Type: | Object |
---|
top_widget_get
()¶translatable_part_text_get
(part=None)¶Gets the original string set as translatable for an object
When setting translated strings, the function part_text_get()
will return the translation returned by gettext()
. To get the
original string use this function.
Parameters: | part (unicode) – The name of the part that was set |
---|---|
Returns: | The original, untranslated string |
Return type: | unicode |
See: | translatable_part_text_set() |
New in version 1.8.
translatable_part_text_set
(part, text)¶A convenience function.
translatable_text
¶Translatable text for the main text part of the widget.
translatable_text_get
()¶translatable_text_part_get
(part)¶Deprecated since version 1.8: Use translatable_part_text_get()
instead.
translatable_text_set
(text)¶tree_focus_allow
¶Whether the Elementary object and its children are focusable or not.
This reflects whether the object and its children objects are able to take focus or not. If the tree is set as unfocusable, newest focused object which is not in this tree will get focus. This API can be helpful for an object to be deleted. When an object will be deleted soon, it and its children may not want to get focus (by focus reverting or by other focus controls). Then, just use this API before deleting.
Type: | bool |
---|
tree_focus_allow_get
()¶tree_focus_allow_set
(focusable)¶widget_check
()¶Check if the given Evas Object is an Elementary widget.
return: True
if it is an elementary widget variant,False
otherwisertype: bool
Deprecated since version 1.8: Use type(obj) instead.
widget_type
¶The string that represents this Elementary widget.
This is a readonly property.
Note
Elementary is weird and exposes itself as a single Evas_Object_Smart_Class of type “elm_widget”, so evas_object_type_get() always return that, making debug and language bindings hard. This function tries to mitigate this problem, but the solution is to change Elementary to use proper inheritance.
Type: | string |
---|
widget_type_get
()¶Deprecated since version 1.8: Use type(obj) instead.