Doubts about status bar progress implementation + how to operate with cookies 100% correctly

[lsoft]

Do we really need to send cookie = 0 in each invocation of statusBar.Progress? If I understand status bar API correcty, I think we need to reuse same value of the cookie between our progress change invocation.

So we need to grab an our new cookie:

uint _cookie = 0; //zero matters!
_statusBar.Progress(ref _cookie, 1, "", 0, 0);

and then reuse it until our progress has finished. I really don't know what way is 100% correct, can anyone shed light on it?

if I right about reusing cookie value, I would suggest the following API:

//in VS.Notification we put:
        public async Task<StatusBarProgress> StartStatusBarAnimationAsync()
        {
            await ThreadHelper.JoinableTaskFactory.SwitchToMainThreadAsync();
            IVsStatusbar? statusBar = await GetStatusBarAsync();

            return new StatusBarProgress(statusBar);
        }

        public class StatusBarProgress : IDisposable
        {
            private readonly IVsStatusbar _statusBar;
            private uint _cookie;

            public StatusBarProgress(IVsStatusbar statusBar)
            {
                ThreadHelper.ThrowIfNotOnUIThread();

                _statusBar = statusBar ?? throw new ArgumentNullException(nameof(statusBar));

                _statusBar.FreezeOutput(0);
                _statusBar.Progress(ref _cookie, 1, "", 0, 0); //grab our cookie
            }

            public void SetProgress(string text, int currentStep, int numberOfSteps)
            {
                ThreadHelper.ThrowIfNotOnUIThread();
                _statusBar.Progress(ref _cookie, 1, text, (uint)currentStep, (uint)numberOfSteps);
            }

            public void Dispose()
            {
                ThreadHelper.ThrowIfNotOnUIThread();
                _statusBar.Progress(ref _cookie, 0, "", 0, 0); //please make note that fInProgress = 0; it works because _cookie is not zero
            }
        }

//using it:
            using (var statusBarAnimation = await VS.Notifications.StartStatusBarAnimationAsync())
            {
                statusBarAnimation.SetProgress("1", 1, 3); //show first progress step
                await Task.Delay(1000);
                statusBarAnimation.SetProgress("0", 0, 3); //hide our progress for a second
                await Task.Delay(1000);
                statusBarAnimation.SetProgress("2", 2, 3); //reshow it
                await Task.Delay(1000);
            }

In this design we allowed to use currentStep = 0 to temporarily hide progress, because animation stops in the Dispose method. Also, both examples in the last episode demonstrates same behaviour with cookie.

any thoughs?
Thanks guys!

[yannduran]

@lsoft this isn't directed at you or what you wrote, I'm just talking generally.

Details like this should be totally hidden from the user of the API. All these cookies and weird names come from 20-odd years ago, if not more, using arcane COM naming standards and practices.

We should be aiming to hide all of that behind a more modern and simpler facade.

• the API should expose both async and non-async methods
  • so as not for force the user to do complicated code gymnastics to get the type of code they need
  • such as figuring out which is the best way to run async code in a method that can't be made async
• the methods should describe what you want to do
  • all (or at least most of) the method names should be figured out first
  • then after you've figured them all out, then work out how to implement them
• the names should be as simple as possible
  • to describe what they do
  • no repetition, no weird abbreviations etc
    • so nothing like VS.StatusBar.StartStatusBarAnimationAsync
  • it should read exactly like what you want to do

Whatever the implementation ends up being, it shouldn't drive what the API looks like.

• aim for readability over technical correctness
• ideally verb/noun (StartProgress/EndProgress, StartAnimation/EndAnimation)

All start bar operations would need something like:

• var statusBar = VS.StatusBar.Initialise() / await VS.StatusBar.InitialiseAsync()
  • gets the service and stores it behind the scenes
  • does any setup required
  • returns a disposable class instance so the whole things can be wrapped in a using statement
    • allowing for automatic disposing
    • the internal Dispose() method could also be publicly exposed
      • in case the user has their own reason to not want/be able to use a using statement

**Async Example**

public async Task MyStatusBarExample()
{
  // initialise a StartusBar instance to add parts to
  // we shouldn't have to get a status bar service and store it ourselves
  // we shouldn't have to keep track of any implementation details at all

  using (var statusBar = await VS.StatusBar.InitialiseAsync())
  {
    // for showing progress, it really should be as **_easy_** as:

    var progressIndicator = await statusBar.CreateProgressIndicatorAsync();

    await progressIndicator.BeginAsync(5) // or NumberOfStepsAsync(5)
    // indicating there's going to be 5 steps
    // displays progress indicator at 0%

    // do step 1
    await progressIndicator.UpdateAsync(); 
    // displays 20% (1 / 5 * 100 = 20%)

    // do step 2
    await progressIndicator.UpdateAsync();
    // displays 40% (2 / 5 * 100 = 40%)

    // do step 3
    await progressIndicator.UpdateAsync();
    // displays 60% (3 / 5 * 100 = 60%)

    // do step 4
    await progressIndicator.UpdateAsync();
    // displays 80% (4 / 5 * 100 = 80%)

    // do step 5
    await progressIndicator.UpdateAsync();
    // displays 100% (5 / 5 * 100 = 100%)

    await progressBar.EndAsync();
    // removes the progress bar

    // more status bar operations could follow here, as the `startusBar` variable has not yet been disposed

    // for creating/using an animation, it should be as easy as:

    var animation = await statusBar.CreateAnimationAsync();
    // with overloads for the different types of objects that can be added for separate animations
    // one overload could take in an array/list of objects to be added to the animation

    await animation.BeginAsync();

    //when you're ready for the animation to finish
    await animation.EndAsync();
  }
}

Of course it _could_ also be `await VS.Notifications.StatusBar.Initialise()`, but personally I really don't think that `Notifications`. People are not going to think "I want to add something to the start bar" and immediately try `VS.Notifications.StatusBar`. It flows so much better as `VS.Notifications.StatusBar.Innitialise()....`.

The API should just describe **_what_** you want to do, and not **_how_** to do it. Behind the scenes it would get and store the service object (in `Initialise`), then dispose of it later (in `Dispose`). 

[lsoft]

@yannduran I completely agree. But, regardless of statusbar API design, I would like to know how to operate with cookies 100% correctly. It was my primary point to open this issue.
There are a lot of cookies in vsix development, you know that better than me :) StatusBar, IVsOperationProgressStatusService, AdviseSolutionEvents... I think we need to know how to work with cookies correctly. After that, advanced statusbar API and its implementation can be discussed in details.

Thanks for your thoughs!

[yannduran]

@lsoft fair enough :-)

Perhaps it'd be better to add your question to discussions. Might I suggest 'How to properly handle cookies?' as a title?

Your title for this issue was a bit misleading if what you want to know is 'how to operate with cookies 100% correctly'.