Make EFL easier to use by improving its interface
Open, TODOPublic

Description

Currently intended for EFl 1.21 release.

While moving to use Eo and Eolian, we are getting a chance to cleanup EFL API that has grown organically over more than a decade. The goal of this task is to link and track all sub task that are addressing a specific point that needs to be changed.

The new timeline is by end of the 2017 (already late), which give us some time to get things done correctly.

There are a few different kind of task :

  • Improve the infrastructure (generate more helper/documentation automatically for examples)
  • Remove widgets from the new API (legacy is still going to carry all existing widgets for some times)
  • Rename/Refactor widgets and interfaces to fit better together and reduce the overall multiplication of API
  • Improve widgets by providing missing features or information

Related Objects

StatusAssignedTask
Opencedric
Resolvedsingh.amitesh
Resolvedthiepha
Openraster
Resolvedcedric
Opensingh.amitesh
OpenNone
Openherdsman
Resolvedherdsman
Openherdsman
Openherdsman
Resolvedherdsman
Openjpeg
Opensingh.amitesh
Resolvedsingh.amitesh
Resolvedsingh.amitesh
Resolvedsingh.amitesh
Resolvedsingh.amitesh
Resolvedsingh.amitesh
Opensingh.amitesh
Openjpeg
Resolvedwoohyun
Resolvedsingh.amitesh
OpenJaehyun_Cho
Resolvedzmike
OpenNone
Openeunue
Openeunue
OpenNone
Openherdsman
Openthiepha
Opencedric
Opensmohanty
Openkimcinoo
Openfelipealmeida
Openfelipealmeida
OpenNone
Openfelipealmeida
Openfelipealmeida
Opencedric
OpenJaehyun_Cho
Opencedric
Openajwillia.ms
Openajwillia.ms
Openherdsman
Openeagleeye
Resolvedjpeg
Resolvedeagleeye
OpenNone
Openfelipealmeida
Resolvedjpeg
Resolvedfelipealmeida
OpenNone
OpenNone
Openq66
Resolvedq66
Opensingh.amitesh
Opentaxi2se
Openthiepha
Openbu5hm4n
Openraster
Opensingh.amitesh
Opentaxi2se
Resolvedsingh.amitesh
OpenCHAN
Resolvedsingh.amitesh
Opencedric
Openthiepha
Opencedric
OpenNone
OpenCHAN
Openbu5hm4n
Openbu5hm4n
Resolvedbu5hm4n
Openbu5hm4n
Resolvedbu5hm4n
Resolvedbu5hm4n
Openbu5hm4n
Resolvedsingh.amitesh
Openbu5hm4n
Resolvedbu5hm4n
Openbu5hm4n
Openherdsman
Openherdsman
Openherdsman
Openthiepha
Openherdsman
Opensingh.amitesh
Openq66
Openajwillia.ms
OpenNone
Resolvedcedric
Opencedric
Resolvedcedric
Openwoohyun
OpenNone
OpenNone
There are a very large number of changes, so older changes are hidden. Show Older Changes

I also think that EXPAND should be the default - it's more intuitive and it forces the user to adjust sizing to better balance what's visible (I.e. Button bar not expand vertical, buttons not expand horizontal).
Currently folk have to struggle with why things are all small and for things like text entries, scrollers or images they may not even be visible by default...

jpeg added a comment.Jun 12 2017, 10:25 PM

I also think that EXPAND should be the default - it's more intuitive and it forces the user to adjust sizing to better balance what's visible (I.e. Button bar not expand vertical, buttons not expand horizontal).
Currently folk have to struggle with why things are all small and for things like text entries, scrollers or images they may not even be visible by default...

This is a good question. We can easily change the default value for visibility, align and weight when we are using efl_add vs. a legacy _add API. It's just a bit of work marking all legacy objects as such and changing the default value inside the finalizer. It can be done.
The problem is only which values really are the best?

In T5301#88816, @jpeg wrote:

I also think that EXPAND should be the default - it's more intuitive and it forces the user to adjust sizing to better balance what's visible (I.e. Button bar not expand vertical, buttons not expand horizontal).
Currently folk have to struggle with why things are all small and for things like text entries, scrollers or images they may not even be visible by default...

This is a good question. We can easily change the default value for visibility, align and weight when we are using efl_add vs. a legacy _add API. It's just a bit of work marking all legacy objects as such and changing the default value inside the finalizer. It can be done.
The problem is only which values really are the best?

since this is not a problem exclusive of EFL and basically everyone else had it, solved slightly different in many places... which lead to even more confusion, particularly to transitioning developers.

it seems that many technologies are moving to the web standard called FLEXBOX and it can be implemented easily on top of our box... actually our box layout looks similar to that, but not exactly. Then why not make a flexbox layout matching the more well known FLEXBOX and stick with that? they have specs, tests... that makes our lives easier.

While at that we go and deprecate all legacy properties (keeping them and the box layout callbacks as legacy-only), claiming we did a cleanup and we're following with the flexbox standard.

Nothing is broken and no extra care needs to be done with legacy other than keeping old code around.

While at that we convert from a layout callback to a layout method, then people can create new layouts by overrides. Of course legacy keep the callbacks, with its layout method is simply a proxy to the set callbacks.

References:

In T5301#88816, @jpeg wrote:

I also think that EXPAND should be the default - it's more intuitive and it forces the user to adjust sizing to better balance what's visible (I.e. Button bar not expand vertical, buttons not expand horizontal).
Currently folk have to struggle with why things are all small and for things like text entries, scrollers or images they may not even be visible by default...

This is a good question. We can easily change the default value for visibility, align and weight when we are using efl_add vs. a legacy _add API. It's just a bit of work marking all legacy objects as such and changing the default value inside the finalizer. It can be done.
The problem is only which values really are the best?

since this is not a problem exclusive of EFL and basically everyone else had it, solved slightly different in many places... which lead to even more confusion, particularly to transitioning developers.

it seems that many technologies are moving to the web standard called FLEXBOX and it can be implemented easily on top of our box... actually our box layout looks similar to that, but not exactly. Then why not make a flexbox layout matching the more well known FLEXBOX and stick with that? they have specs, tests... that makes our lives easier.

While at that we go and deprecate all legacy properties (keeping them and the box layout callbacks as legacy-only), claiming we did a cleanup and we're following with the flexbox standard.

Nothing is broken and no extra care needs to be done with legacy other than keeping old code around.

While at that we convert from a layout callback to a layout method, then people can create new layouts by overrides. Of course legacy keep the callbacks, with its layout method is simply a proxy to the set callbacks.

References:

Before investigating other layout technologies I think we need to make the mindset shift to expand by default - most layout engines, especially like you illustrate, rely on expand by default so we're an outlier in that regard already. Additional layouts can be added later and are not required for a stable Eo API...

jpeg added a comment.Jul 16 2017, 6:08 PM

Before investigating other layout technologies I think we need to make the mindset shift to expand by default - most layout engines, especially like you illustrate, rely on expand by default so we're an outlier in that regard already. Additional layouts can be added later and are not required for a stable Eo API...

I will make an experiment, and after conversion of some examples or elm_test I'll know if it's worth it.
I already have a pending patch for visibility by default (there's only one small catch but that might be acceptable).
*note: only talking about EO API here, obviously :)

jpeg added a comment.Aug 1 2017, 1:33 AM

I made an experiment to set EXPAND by default. It's in my devs/jpeg/work branch.
I think it saves a little bit of typing. I don't have a large EO application at hand so it's only elm_test and some examples.

YOhoho added a subscriber: YOhoho.Sep 19 2017, 3:53 PM
raster updated the task description. (Show Details)Jan 3 2018, 11:09 PM
raster mentioned this in Main.Jan 3 2018, 11:19 PM
jpeg closed subtask T5322: One window ! as Resolved.Jan 17 2018, 9:30 PM
jpeg added a comment.Jan 18 2018, 9:42 PM

As mentioned in T6441, I think this is the current state of Efl.Ui wrt. this task.

Most API's are now completed, but:

Potentially useful things missing in the unified API may include:

  • combobox
  • colorselector, see T5324
  • fileselector, see T5356
  • glview, see T5364
  • index, see T5317 (pager & tab)
  • inwin, probably no need as we also have inlined windows
  • map & route (geographic map)
  • mapbuf, see T5316
  • naviframe, see T5350 and T5351
  • toolbar, see T5317 (as toolbar is often used as a tab widget header)
  • web, see T5362

And maybe new things like:

  • Pager/Tab, see T5317
  • "Realize" widget, see T6265
  • Simple item API for short lists, see T6360

Among the above things, only simple list+item API are required and completely missing. Tizen also expresses strong interest in client-local Naviframe (T5351) and Pager (T5317) widgets.
Some other features are still half done, like efl.ui.list for instance.

I disagree with the combining of toolbar and tab bar. Whilst they may be similar from a ui (and also external api) point of view the function differently.

Tab bar should indicate current tab and allow through api the addition of views attached to a tab button. Whereas toolbar is simply a list of tool buttons probably with separators...

jpeg added a comment.Sun, Jan 21, 6:59 PM

I disagree with the combining of toolbar and tab bar. Whilst they may be similar from a ui (and also external api) point of view the function differently.

Tab bar should indicate current tab and allow through api the addition of views attached to a tab button. Whereas toolbar is simply a list of tool buttons probably with separators...

Ah yes, toolbar == tab bar would be dubious. I should have also pointed to T5327, where @cedric's last comment is more explicit:

We are looking into using pager instead of toolbar in Tizen, there is no rush in implementing this one anymore.

The key point being "no rush" and not "no need".

jpeg added a comment.Wed, Feb 7, 10:15 PM

Quick recap before I leave.

Uncompleted items / Work in progress

ELEMENTARY

Box needs a homogenous mode (my initial plan of using weights works but only in some cases -- homogenous could be defined as "weight == size share" which by default means 1 size per item since default weight is 1.0, or it could be just like legacy homogenous, i.e. ignore weights)

  • Naviframe (jaehyun) - T5351
  • Pager, Tab, Index (eunue) - T5317
  • Multibuttonentry (CHAN) - T5358

Needs a SIMPLE api. Forget about model for now, only make sure it can be implemented later (with model_set). items can probably be derived from elm_widget_item for now as long as the API hides this entirely.

  • List (felipe, sanghyeon) - T5355

Apparently a lot of work remains to be done (Selection interface, focus, etc...)

Efl.Ui.Text uses too much "Elm" stuff
Text styles not yet standardized from theme (rather hardcoded in C at the moment)
Still a lot of work remains... :(

  • Toolbar, Fileselector, Menu, Tooltip, etc...

Some useful widgets haven't been worked on (a good fs requires a LOT of love), because no immediate need from Tizen

  • CnP, DnD, Selectable

CnP selection API must be different from List Selection.
Cnp has bugs right now, but no one is in charge anymore.

ECORE - T5522

  • Thread support

Maybe not required to be a stable API in the very first release. Note below the disagreements around EO ID / domain API.

  • Efl.Loop

It was mentioned that the signals don't belong to the Loop class, rather another "Main Loop" class (which doesn't exist yet). There seems to be some issue with the ecore events.

  • App

In some cases we have global APIs in legacy that don't exist in EO because we don't have a global app context. Examples: elm_config, elm_policy (T5494), edje classes, ...

  • Promise/Future API

Efl.Future is still present in EFL. This must be removed ASAP.

  • Model API

Related to Ui.List.

EVAS

  • Canvas object

Too many APIs exposed all the way up to the individual widgets... Some confusing things exist, like freeze_events (efl_canvas_object) and event_freeze (efl_object). Low-level APIs like render_op, no_render, is_frame_object, etc... are exposed to app developers even if they only care about elm-level usage.

  • Efl.Canvas.Group (smart objects)

Now those are always "clipped" i.e. children move and there's a master clip.
BUT!!! Widgets are NOT clipped!
2nd issue is Widget children are not smart children. See T5967.

There is barely a prototype API, support is incomplete.

Things we may roll back if necessary

This was a tough choice... Add a new theme for efl_add'ed objects. This allows us to clean the theme API, simplify the part names, potentially add color/text/size classes where needed, make signals consistents. BUT... this requires an insane amount of work of which almost none has been done. We may want to rollback this change (just disable the eo theme load), and use the legacy theme. Some part names will need to then be manually translated inside widgets code, eg. "first" -> "front" in Panes. I really hope we don't have to roll this back, but this can be considered. For upstream the double theme might be harmful in the short term.

  • Pack interfaces - T5328

Table does not need to inherit from "linear" (1d) layout: this brings unnecessary complexity, for a dubious use case.

  • Styles

One style = one class. See T5307. style_set API is now @protected, and can't be called after creation. This is an artificial limitation, and could be rolled back since the legacy code still works. But this complexity can never be removed (EFL 2.x in mind).

Existing points of disagreement

The below points are things where some developers disagree on the API and design choices, but solving them requires a lot of work. Ignoring them means accepting their problems as "new legacy".

  • EO domain API

It's a very divisive solution. Counter-intuitive and makes it hard or impossible to use objects in multiple threads (right now).
Shared objects rely on a single lock. It's a problem already for ector buffers (filters & vg async render need it), as async render thus may block the main loop, and vice-versa.

  • vpath vs. async file i/o - T5314

Vpath at the moment is a *sync* path resolution mechanism, even if it says it's async. Also it assumes by design all files can be downloaded (not streamed).
Some have proposed ideas of a stream api (a la gstreamer/upipe/libvlc internals...).
Another idea proposed was efl_url_set (async, returns a future) vs. efl_file_set (sync, backs legacy, useful until proper async support can be implemented).
Only vpath is implemented right now.

  • Naviframe vs. Window Stack API - T5351

Window stack API does not follow some Wayland specifications (I don't know the details here - is it xdg-external?).
Also, Tizen Window Manager will not implement support for sharing a back buffer, optimizing and customizing transitions between frames. That's not a technical limitation, rather a human & available workforce issue.

  • efl_add / efl_add_ref / efl_invalidate

@noparent tag + parenting all objects would help, but some issues remain open:
need a root object in all thread, even non-eo threads (i.e. created by app or external lib in some uncontrolled fashion)
@owned return values (eg. "dup" or "create" methods): how to make efl_unref request deletion, safely, without ERR?
efl_part needs special handling (auto-unref + safe unref with a parent)
invalidate could simply replace the main destructor for most objects, and invalidate is called with a parent, destructor is called without a parent (provider_find fails). Prototype at devs/jpeg/efl_invalidate, which I can not complete.

  • autodel

Extremely useful API in C that has issues in bindings (dangling references). See efl_invalidate above.

  • Namespaces / Class names

See https://www.enlightenment.org/develop/api/start
The current structure is a mess, too many top-level namespaces that could be better organized:
Vg, Vpath, Animation, Config, Gesture, Image, Input, Interpolator, Selection -> should be grouped more clearly in sub namespaces (eg. group selection, cnp, dnd together)
Efl.Ui is too crowded but at the same time using sub namespaces looks awful in some bindings like Python
The naming scheme is not always obvious

Some more name conflicts to be solved by creative naming (efl.net, efl.vg and elm stuff i think)
eolian should FAIL on duplicate API, we probably need to allow legacy APIs to conflict (eg. with a special, undocumented, tag)

Future ideas to ignore for now

  • Elementary widgets modularity

Tizen platform devs want to fully customize the widgets, so a solution needs to be found to customize the C code and not only the EDC theme, without forking.