Hi @StendProg,

Improving discoverability and documentation of the render queue is one of my upcoming goals in the triage list (#1028)! I really want to make this feature more discoverable and easier to understand for new users.

My concern with this PR is that new users may get confused about how these are different:

formsPlot1.Render(lowQuality: true);
formsPlot1.RenderLowQuality();

Name Async() to improve queue discoverability?

What do you think about something like this? It doesn't return a Task and it isn't even a real async method (so maybe this is bad)... but having Async() in the function name makes it more obvious to the user that the render may occur later and that the call is non-blocking. XML documentation for the method and the enum could eplain the details.

public void RenderAsync(AsyncRenderQuality quality = AsyncRenderQuality.High) {
    quality switch {
        AsyncRenderQuality.Low => Backend.Backend.RenderLowQuality(),
        AsyncRenderQuality.High=> Backend.Backend.RenderHighQuality(),
        AsyncRenderQuality.LowHigh => Backend.Backend.RenderLowThenImmediateHighQuality(),
        AsyncRenderQuality.LowDelayHigh => Backend.Backend.RenderDelayedHighQuality(),
    };
}

Method to toggle render queue?

While we're here, we may want to make it easier to discover how to enable the render queue. The advantage here is that users looking for this type of behavior will immediately know what "async" means (even though they may not think to look for the word queue).

/// <summary>
/// Control whether asynchronous rendering is used for future renders.
/// Asynchronous render calls are non-blocking, but slightly less responsive to mouse events.
/// </summary>
public void RenderAsync(bool enable = true, bool renderNow = true) {
    Configuration.UseRenderQueue = true;
    if (renderNow)
        Render();
}

Again, I haven't thought about this in detail, and I'm not an async/await expert... but I'm very interested to hear what you think of these potential designs. Thanks for your input!

Scott

Hi @swharden,

I just borrowed the existing style used RenderLowThenImmediateHighQuality(), but I'm ready to discuss a better option.

As you rightly noted, Async has a well-established background and can be misleading.
Technically, this is not really an asynchronous call, but rather a request. Since the current call will be processed there is no guarantee. It will be skipped if the queue is heavily loaded, but the Render is guaranteed to be called for a later state of the Plots, i.e. the current state will be taken into account.
So in order to more accurately describe what this method does, I would choose something like RequestRender or QueueRender, but as it will be more clear for users, I personally find it difficult to say, maybe RenderAsync still a good option.

Adding a enum parameter instead of 4 different methods is a great idea, no options here.

I shared my thoughts, and the choice is yours.

@StendProg thanks for your input! I took your advice and arrived at a solution I feel good about:

All user controls now have a RenderRequest() method that accepts a RenderType enum.

formsPlot1.RenderRequest(RenderType.LowQualityThenHighQualityDelayed)

XML docs indicate this method is non-blocking, and the enum items all have XML docs that describe what they do and how they are commonly used. If you have any suggestions let me know, otherwise I'll merge this shortly 👍

I add default renderType value = RenderType.LowQualityThenHighQualityDelayed
I think it is suitable for 95% of cases and will allow to make a simple call formsplot.RenderRequest();

Thank you for all your work on this @StendProg! The render queue is a very nice system, and I'm happy it is now easier to find and use 👍