Skip to content

Breaking changes that would improve the overall API #24722

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
2 of 49 tasks
Hixie opened this issue Nov 26, 2018 · 37 comments
Open
2 of 49 tasks

Breaking changes that would improve the overall API #24722

Hixie opened this issue Nov 26, 2018 · 37 comments
Labels
c: API break Backwards-incompatible API changes framework flutter/packages/flutter repository. See also f: labels. P3 Issues that are less important to the Flutter project team-framework Owned by Framework team triaged-framework Triaged by Framework team

Comments

@Hixie
Copy link
Contributor

Hixie commented Nov 26, 2018

This bug lists changes we'll probably never make, but should consider if we ever for some reason decided to start over in a new universe.

Foundation

  • ChangeNotifier and Listenable and company are a bit mixed up. We could refactor the code here so that we more clearly have a Listenable and a ListenableController, and a ValueListenable and a ValueListenableController, and so on.

Services

  • StandardMessageCodec should be a static class or should be stateful.
  • dev.flutter/channel-buffers control messages should use a more efficient binary format rather than an inefficient bespoke \r-delimited text-based format.
  • flutter/system, flutter/navigation, etc, control messages should use a more efficient binary format rather than JSON.

Painting

  • addListener/removeListener on ImageStream have a broken API that should be redesigned.
  • NotchedShape should be a shape, or should have another name.
  • TextStyle has many decoration properties, it would be nice if they were all in one object, maybe separate objects for underline and overline and strike-through.

Gestures

  • Rename PointerMoveEvent to PointerUpdateEvent, because it's also triggered at button changes without moves.

Animation

Rendering

  • Adaptor -> Adapter
  • SliverChildListDelegate should have a children argument instead of a positional one
  • CustomPainter.hitTest should take a Size argument (CustomPainter.hitTest missing size argument #28206)
  • Layer.pushLayer should be renamed to withLayer, since it is not matched by a popLayer. The same applies to its relatives.
  • BlendMode.srcATop -> BlendMode.srcAtop
  • BlendMode.dstATop -> BlendMode.dstAtop

Widgets

  • TabController should be a ValueListenable
  • Rename WidgetBuilder to make it clear it's a typedef.
  • Rename TransitionBuilder to make it clear it's a typedef with a child.
  • Rename AnimatedBuilder to make it clear it takes any Listenable (even AnimationBuilder would be more consistent...), see also: Breaking changes that would improve the overall API #24722 (comment).
  • Rename Listener to be PointerListener
  • (Subclasses of) AnimatedWidget and ImplicitlyAnimatedWidget should be named consistently (see Breaking changes that would improve the overall API #24722 (comment)).
  • Name the Foo vs FooTransition vs AnimatedFoo widgets more consistently (e.g. FadeTransition vs AnimatedOpacity, also AnimatedSize).
  • Consider merging all the one-argument FooBuilder typedefs into one generic typedef, or otherwise cleaning up the inconsistencies there.
  • inheritFromWidgetOfExactType should be generic rather than taking a Type (so it can guarantee its return type is of the same type as the argument).
  • Container's width and height properties should size the child, and imply an alignment.
  • It's weird that we have both showDialog and showGeneralDialog.
  • AnimatedList should be AnimatedListView.
  • SliverMultiBoxAdaptorWidget is not an adaptor; consider naming like SliverMultiChildRenderObjectWidget.
  • Rename RichText to RawText.
  • Change the type of maxLines from int to double (TextField maxLines should be a double, not an int. #35064).
  • ColorFiltered -> ColorFilter
  • Be consistent about callback parameter names for tapping/pressing something (onTap vs onPressed, Be consistent about callback parameter names for tapping/pressing something #17407)
  • FocusNode and FocusScopeNode should use 'focusable' instead of 'canRequestFocus' as the attribute for controlling focusability.
  • MediaQueryData.disableAnimations should be called MediaQueryData.enableAnimations with the opposite semantics (see style guide under "double negatives").
  • MediaQuery.viewPadding should be used instead of MediaQuery.padding throughout the framework. viewPadding was added ATF to address edge cases, but the API surface has become confusing as a result, see SafeArea.maintainBottomViewPadding should be true by default #59204
  • Element.activate should rename to Element.reactivate, because only the reactivate will callback.
  • OnInvokeCallback should be called just InvokeCallback per the style guide.
  • Navigator: reportsRouteUpdateToEngine should be reportRouteUpdateToEngine (imperative not descriptive).
  • Better property's naming for Form widget (autoValidateMode, instead of autovalidateMode) #115820

Material

  • ColorScheme.on* shouldn't look like event handlers
  • Handle the tap target padding for e.g. mini fabs more intuitively (dunno what that would entail exactly)
  • InputDecoration.filled should be isFilled
  • InputDecoration should only have one prefix field and one suffix field, rather than three each (widget, icon, text). And it probably should have an error, a label, and a hint instead of just errorText, labelText, and hintText.
  • Change Divider and VerticalDivider's indent and endIndent properties to simply be margin
  • Colors.grey -> Colors.gray
@Hixie Hixie added framework flutter/packages/flutter repository. See also f: labels. c: API break Backwards-incompatible API changes labels Nov 26, 2018
@Hixie Hixie added this to the Future milestone Nov 26, 2018
@SteveAlexander
Copy link

May I propose this for the Framework too? #19143

I currently have some pretty ugly code to allow me to sequence an animation of changing tab and then scrolling to a certain position. This is because while ScrollController.animateTo returns a Future so I can sequence something to happen after scrolling is done, TabController.animateTo is void.

Workaround (in the referenced issue above) is complicated and slightly absurd :-)

@Hixie
Copy link
Contributor Author

Hixie commented Nov 27, 2018

We should just be able to fix #19143, turning something from returning void to returning a Future when it's something that we don't expect people to implement shouldn't be a breaking change.

This bug is specifically about changes we can never really make because they're breaking changes.

@jonahwilliams
Copy link
Member

jonahwilliams commented Jan 11, 2019

Adding a type parameter to invokeMethod would be nice too: #17333

Done, and non-breaking

@jamesderlin
Copy link
Contributor

May I complain here that I dislike how Stack expects its children ordered back-to-front in z-order? For example:

Stack(children: [
  child1,
  child2,
  child3,
])

I find it rather unintuitive that child1 appears on top in the code but is actually at the bottom of the stack.

@rrousselGit
Copy link
Contributor

rrousselGit commented May 20, 2019

Just passing there after listening to your awesome podcast on itsallwidgets.com

ChangeNotifier and Listenable and company are a bit mixed up. We could refactor the code here so that we more clearly have a Listenable and a ListenableController, and a ValueListenable and a ValueListenableController, and so on.

What does it mean? Moving toward an API closer to Stream vs StreamController for Listenable?

Container's width and height properties should size the child, and imply an alignment.

I'm not sure I agree with that one.
While the current behavior is definitely surprising for newcomers, that's a good thing IMO.

From my experience mentoring in Flutter, that specific API is usually the first step that led peoples understanding that Flutter does layout differently.
This helped my mentees a lot in understanding that, in Flutter, UI elements means nothing without the rest of the tree – and that everything is declarative to the core.

tvolkert added a commit to tvolkert/flutter that referenced this issue May 20, 2019
The current API was broken in that you registered multiple
callbacks at once, but when you removed listeners, only the
primary listener was used to determine what was removed.
This led to unintuitive cases where the caller could get
unexpected behavior.

This updates the API to add and remove listeners using
a newly introduced [ImageStreamListener] object, a value
object that has references to the individual callbacks
that may fire.

flutter#24722
flutter#32374
flutter#32935
tvolkert added a commit that referenced this issue May 21, 2019
The current API was broken in that you registered multiple
callbacks at once, but when you removed listeners, only the
primary listener was used to determine what was removed.
This led to unintuitive cases where the caller could get
unexpected behavior.

This updates the API to add and remove listeners using
a newly introduced [ImageStreamListener] object, a value
object that has references to the individual callbacks
that may fire.

#24722
#32374
#32935
kiku-jw pushed a commit to kiku-jw/flutter that referenced this issue Jun 14, 2019
The current API was broken in that you registered multiple
callbacks at once, but when you removed listeners, only the
primary listener was used to determine what was removed.
This led to unintuitive cases where the caller could get
unexpected behavior.

This updates the API to add and remove listeners using
a newly introduced [ImageStreamListener] object, a value
object that has references to the individual callbacks
that may fire.

flutter#24722
flutter#32374
flutter#32935
@goderbauer
Copy link
Member

goderbauer commented Aug 1, 2019

AnimatedWidget, ImplicitlyAnimatedWidget and their subclasses should be named consistently. For the most part, subclasses of AnimatedWidget are named FooTransition and subclasses of of ImplicitlyAnimatedWidget are named AnimatedFoo. There are annoying/unnecessary exceptions, though, which should be renamed for consistency:

  • AnimatedModalBarrier (subclass of AnimatedWidget) should be renamed to ModalBarrierTransition
  • AnimatedBuilder (subclass of AnimatedWidget) should be renamed to something like TransitionBuilder *)
  • AnimatedWidget itself should probably more accurately be named TransitionWidget
  • Maybe: ImplicitlyAnimatedWidget should just be AnimatedWidget
  • Name the Foo vs FooTransition vs AnimatedFoo widgets more consistently (e.g. Opacity vs FadeTransition vs AnimatedOpacity).

*) This would also fix another item on the list above: "Rename AnimatedBuilder to make it clear it takes any Listenable (even AnimationBuilder would be more consistent...)."

@Hixie
Copy link
Contributor Author

Hixie commented Aug 1, 2019

Please feel free to edit the list above so that we just have one comment with all the proposed changes.

@goderbauer
Copy link
Member

@Hixie I added a bullet to the list in the top post and linked to the detailed description in the comments.

@goderbauer goderbauer mentioned this issue Sep 4, 2019
1 task
@bartekpacia
Copy link
Member

It seems to me that some naming-related items on this list could be done by renaming the offending identifiers, and introducing a temporary (for ~1 year/4 major releases) type-alias with the old name.

For example:

  • Adapter -> Adaptor
  • BlendMode.srcATop -> BlendMode.srcAtop
  • BlendMode.dstATop -> BlendMode.dstAtop

@Piinks
Copy link
Contributor

Piinks commented Jul 18, 2024

Adding this one as well: #61690

@nate-thegrate
Copy link
Contributor

nate-thegrate commented Aug 14, 2024

One more thing a few more things for the list…


  • Convert Builder classes into constructors.

StatefulBuilder can be useful, but there's really no benefit to extending the class. Instead, we could follow the example of ListView.builder and turn it into StatefulWidget.builder, and the same could apply to every "builder" class.
Freeing up the namespace would be beneficial, e.g. a developer could use Builder as a class or typedef without a name overlap.


  • Separate packages for framework layers

I don't like when "intellisense" gives me multiple copies of the same suggestion. It'd be nice if, for instance, material and foundation were separate packages, so projects would have an indirect dependency on foundation rather than a direct one.


  • Combine Animatable<T> and ParametricCurve<T>

Animatable has a transform method which creates a value based on a double t parameter (a fraction in the range 0.0 to 1.0); ParametricCurve.transform() does pretty much exactly the same thing.
But a few differences in the implementation make it so we can't just have one of those classes as a subtype of the other without breakages.

@justinmc
Copy link
Contributor

A small one: SelectionChangedCause.scribble should be renamed to SelectionChangedCause.stylusHandwriting to indicate that it is not iOS-specific.

Tracked in: #159223

@colbymaloy
Copy link

could you please add some gesture information to the hitTest method for custompainter??? for example when using interactiveViewer and painting a list of items, say like a map with points of interest, i need to detect taps on those items.

hitTest gets triggered when panning on the map, causing accidental clicks. if hitTest has some info about which gesture happened i could make it work. Current workaround is to wrap CustomPaint in a GestureDetector and use onTapDown.

@feinstein
Copy link
Contributor

I think you might be using hitTest wrongly. It's purpose is not to tell you that your widget was tapped, so you can call a callback, or trigger some logic. It's purpose is for you to inform the framework that there's something in those coordinates, so the gesture detection algorithm can decide which widget is being tapped (as you might be tapping on a transparent area in your widget, so the widget that's behind can get that gesture instead), and will get the gesture callback activated.

@caseycrogers
Copy link
Contributor

Developers often use ValueChanged<T> in contexts where the function isn't being called on changes and has nothing to do with changing values-they just wanted a type def for void Function(T) and ValueChanged was handy.

As such, ValueChanged<T> should've just been called ValueCallback<T> to make it more obviously usable outside of strictly on change callbacks.

@mateusfccp
Copy link
Contributor

Developers often use ValueChanged<T> in contexts where the function isn't being called on changes and has nothing to do with changing values-they just wanted a type def for void Function(T) and ValueChanged was handy.

As such, ValueChanged<T> should've just been called ValueCallback<T> to make it more obviously usable outside of strictly on change callbacks.

This can be no breaking. If found valuable, we can introduce one without removing the other. They would be virtually equal, but have different semantics.

@feinstein
Copy link
Contributor

feinstein commented Mar 19, 2025

I agree this would be a nice addition, in the mean time remember that the framework also provides ValueSetter<T>.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c: API break Backwards-incompatible API changes framework flutter/packages/flutter repository. See also f: labels. P3 Issues that are less important to the Flutter project team-framework Owned by Framework team triaged-framework Triaged by Framework team
Projects
None yet
Development

No branches or pull requests

pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy