Add Context::request_repaint_after

[coderedart]

Closes #1691.

kinda my first PR.

I am wondering whether i should store this idle timeout interval in platform output our full output. I did not implement this for wgpu yet, but should be pretty similar.

by storing it in platform output, it affects the take function and the Default derive to be manually implemented.

[emilk]

Thanks for starting to work on this!

I think it is worth thinking through what the most common use cases for this feature would be.

If this is a setting ("minimal refresh interval") I think it would make most sense to have it as a member of eframe::App (similar to auto_save_interval, for instance).

However, there could be cases were an egui widget want to schedule a deferred repaint. For instance, a clock widget may want an update every second to show move the second hand. In this case it makes more sense to have it as a member of egui::Context (like is currently the case of this PR). In that case, we also want to make sure that if several widgets calls the function then we do a repaint after the shortest requested time. So if one widget needs updating every two seconds, and one every 500ms, the latter time is used no matter what order the widgets are called. Let's call this something like request_repaint_in with a Duration member. In this case we probably also want request_repaint and request_repaint_in(Duration::ZERO) to mean the exact same thing.

Thoughts?

[coderedart]

I thought it would be best to implement this in eframe too, but then i realized other non-eframe implementations might want this feature too and decided to use Context instead.

The primary purpose of this issue was to just have some sort of timeout interval for the next repaint callback.

I had two use cases in mind:

1. a simple stopwatch or timer app. if it is only showing seconds, then they only need to refresh every second. but request_repaint doesn't allow them to delay the repaint signal. and every time the app repaints, they can set the interval for the next frame by checking the current time and calculating how long before the seconds text displayed in gui needs to change. then, set that as the delay for the next frame. here, you want to make sure that the gui refreshes at this particular instant in future, regardless of whether it had input or not. if there's input, causing an earlier refresh, app will recalculate the timeout and set it again this frame.
2. a normal application like weather app or something, where you only want the gui to not be completely stale / dead due to idling in the background. here, you don't care about how long till a particular moment in time, but rather just a simple, maximum timeout like 5 seconds or something from the frame where it received the last input event. you can just provide the same duration every frame with no calculation.

I did not think about widgets explicitly wanting to set a timeout. but, I don't think that changes anything here.

my plan was to only just store the shortest duration too. as long as the repaint happens at or before the Instant desired by widget / user, they can recalculate their next duration according to their repaint needs just like in stop watch usecase.

I guess, that settles most questions.
request_repaint_in will take a duration, and will keep track of the smallest duration inside context. will provide that duration to backend in FullOutput along with the needs_repaint bool. winit/glfw/sdl will need to make sure to not idle longer than that duration waiting for events.

the name request_repaint_in is slightly misleading, but it should be fine. duration starts at the next frame. lets say for example that its a very inefficient app and takes 500 milliseconds per frame at 2 fps. the widget / user might want a repaint in next 500 milliseconds. now, app takes 1000 ms per frame (1 fps) because the backend event timeout takes 500 milli seconds AFTER the vsync swap buffer.

so, its not that we are requesting repaint within X duration. we are rather timing out during app idle time without any input events.
just need to mention this in the docs, so that they understand what is happening in the background.

[emilk]

Good points! Perhaps request_repaint_after is a better name to communicate that the time starts ticking after the current frame finishes?

You can also use Duration::MAX to avoid using an Option (will make .min(…) easier to call)

[coderedart]

should i just replace needs_repaint bool with the repaint_after duration? then, checking for needs_repaint is simply repaint_after == Duration::ZERO

it will be a breaking change

[emilk]

should i just replace needs_repaint bool with the repaint_after duration? then, checking for needs_repaint is simply repaint_after == Duration::ZERO

it will be a breaking change

Yeah, I think that sounds good!

[coderedart]

I have no idea how to deal with web, so i left it alone except changing the type signature in the logic function.
todo:

• add to changelog about breaking change

[coderedart]

Unfortunately libspeechd is failing to link on my arch. So, I could not check for failures offline with --all-features. Had to commit and wait for ci workflow to run and show me errors to fix.

I hope this works now.

[emilk]

Excellent job - sorry for the slow review, but almost there now!

[emilk]

You should be able to combine these with winit::event::Event::UserEvent(RequestRepaintEvent | winit::event::Event::NewEvents…

[coderedart]

I have a feeling that we might see some sort of issue with repaint_after feature once people start using it.

so, i thought it would be better for debugging or adding special case handling for ResumeTimeReached event if both are treated as separate events.

[coderedart]

apologies for the delay. I had sudden irl stuff to take care of until yesterday and only now got to finally open my PC to work on this.

[coderedart]

think all CI should pass now. its been so long since i cared about grammar, that i forgot you capitalize first letter in a sentence :)

[emilk]

Great job!