#136 PAUSE should have self-documenting GUI

[DanielAjoy]

While reading the HELP entry for the PAUSE primitive, I didn't see what the difference between the OK and the Cancel buttons is.

I also couldn't see what the title of the modal window said, the window was too narrow (image attached).

The HELP says:

The user is prompted for instructions with a dialog box that includes the name of the procedure in which PAUSE was invoked.

That little window did not show any instructions that I could see.

I had the PAUSE command inside a very long loop in my code, and I couldn't press the STOP button because the dialog box is modal.

I couldn't type STOP in the dialog box because "STOP can only be used in a procedure"

Thankfully I had a STOPALL procedure that helped me escape that situation.

[David Costanzo]

The title bar that you can't see on Mint gives a better hint. I have attached a picture of what you'd see on Windows. If you had seen the full title bar, you might have been able to deduce that clicking Cancelar acts the same as entering CONTINUE and pressing OK.

I don't think the "pause" dialog box is documented in the manual. The manual mostly documents the language, not the UI.

It looks like you found the documentation for PAUSE. The part that you didn't quote explains how to get out of it

If the pause is ended by a CONTINUE instruction, then PAUSE outputs whatever the input to CONTINUE was.

The documentation for CONTINUE also explains this

Ends the current interactive pause, returning to the context of the PAUSE invocation that began it

I suppose your STOPALL throws an error, perhaps even THROW "Toplevel. That would also work to end the PAUSE, but it wouldn't return control to the location where PAUSE was run.

[DanielAjoy]

deduce that clicking Cancelar acts the same as entering CONTINUE and pressing OK

I gather that both buttons do the same thing.

It looks like you found the documentation for PAUSE. The part that you didn't quote explains how to get out of it

the issue was that PAUSE was in a loop

repeat 10000 [fd 10 rt 47 PAUSE]

I suppose your STOPALL throws an error, perhaps even THROW "Toplevel

Yes.

.macro stopall
output [THROW "TOPLEVEL]
end

It seems to me that PAUSE is one of the few debugging tools Logo has, other than (TRACE, PRINT and SLOWDRAW).

I wonder if it shouldn't be more user friendly. It has two buttons that do the same thing, but not a way to stop the whole thing.

Maybe:

CANCEL should do THROW "TOPLEVEL
OK should the CONTINUE

Preferably the buttons would say:

[CONTINUE] [STOP]

[David Costanzo]

The OK and Cancel don't do the same thing. "OK" would be better labelled as "Execute", since it functions like the commander. I agree that "Continue" is a good name for cancel. There could also be a better explanation of what to do. I think a Halt button would make more sense than a THROW "Toplevel since Halt is already a familiar concept and is what Cancel on READWORD does. Similar, the dialog text could explain what Pause mode is. Of course, any change to the text means that languages other than English lose their translation.

In my view, the only useful debugging command that exists in FMSLogo is SHOW. I've never been able to use TRACE, STEP, :erract, or PAUSE effectively. What might be useful is a symbolic debugger that integrates breakpoints, single stepping, and expression evaluation, all without having to change the source code. I say might because my younger professional colleagues, who all have degrees in computer science, are reluctant to use symbolic debuggers and prefer debugging by printouts. If professional programmers nowadays use SHOW, what can we expect from the children and tech enthusiasts who use FMSLogo?

Have you ever used PAUSE effectively?

[David Costanzo]

David Costanzo wrote

I think a Halt button would make more sense than a THROW "Toplevel since Halt is already a familiar concept and is what Cancel on READWORD does.

I started working on this and discovered why HALT doesn't work. PAUSE will print and ignore all errors that any instruction has. From lpause() in error.cpp:

    else if (Error.Equals(throw_node))
    {
        // There was an error in the instruction that the
        // user provided.  Print the error, but remain in
        // pause mode.
        err_print();
        stopping_flag = RUN;
    }

Since HALT works by throwing a "Stopping error, it can't exit pause mode. Throwing a non-error like "TopLevel can exit pause mode. I don't know why this behavior isn't documented.

I can see why Brian would want to ignore errors in pause mode, since running command interactive often has error, particularly due to typos. While I could add a special case to allow "Stopping errors to exit pause mode but not other errors, it's better if FMSLogo and UCBLogo behave the same.

To handle the case that Daniel Ajoy had, which is to breakout out of a PAUSE within a REPEAT, I think Daniel's suggestion of adding a THROW "TopLevel button is the way to go.

[DanielAjoy]

Yeah, I've never used STEP but I have used PAUSE from time to time. It helped me see what each iteration of a loop is doing. specially in cases when the loop is deeply nested in procedure calls. That way I can see how variables and arguments are instantiated.

PAUSE is also useful to see how turtle pictures get created with each iteration of a loop.

I run it for a few iterations of the loop but then I need to abort execution altogether to start making changes to the code. The HALT button would be useful in that instance.

I've also used TRACE to see what goes into functions as inputs. But it is cumbersome to specify the name of the procedure each time to trace it and untrace it.

This reminds me, I noticed that the "File" menu has a way to select the procedure you want to edit. A similar feature could be used to specify which procedure to trace.

I know realize that that feature would then also need a complementary dropdown option to select the procedures you want to UNTRACE, populated but the first list provided by TRACED.

[David Costanzo]

Ticket moved from /p/fmslogo/support-requests/54/

[David Costanzo]

I've moved this to be a feature request, which it may have been all along. I expect that I'll enhance the PAUSE dialog some day, mostly as a personal favor to you. I doubt I'd add dialog boxes that let you pick procedures for STEP and TRACE, but feel free to open another feature request for that. Maybe someone else will want to do it.

[David Costanzo]

I have documented how to exit pause mode in [r6099].

[David Costanzo]

Here's a prototype (and screenshot) of what you requested. "Resume Execution" executes continue and "Halt Program" executes throw "toplevel. I also made it so that the executed instructions get printed to the commander history.

I'm considering making this more transparent by removing the "Resume Execution" and "Halt Program" buttons and adding links to the part of the text that explains what you can do. Clicking on the link would then replace the input control with continue or throw "toplevel, but not execute it. This is a less obvious and less efficient UI, but it makes it clearer what the buttons do.

What do you think?

[DanielAjoy]

Here's a prototype (and screenshot) of what you requested. "Resume Execution" executes continue and "Halt Program" executes throw "toplevel. I also made it so that the executed instructions get printed to the commander history.

Thanks David, I like this feature.

However, there is a typo, it says insrtuctions

Attached is how it looks in my computer.

There is an X in the upper-right corner, presumably to Close the dialog window. It seems it does the same as Resume Execution. Can it be removed? (thinking that, why have two UI elements that do the same thing)

What happened to me just now is that I was running:

repeat 10000 [fd 10 rt 47 PAUSE]

And then took a screenshot, and the tried to close the Dialog window using the [X] but off course it didn't close the Dialog because of the loop.

I was also wondering if "Execute" is common terminology in FMSLogo, cause it seems that what it does is "RUN"

Here's a prototype (and screenshot) of what you requested. "Resume Execution" executes continue and "Halt Program" executes throw "toplevel. I also made it so that the executed instructions get printed to the commander history.

I don't like that this adds an extra step.

[David Costanzo]

Daniel Ajoy writes:

However, there is a typo, it says insrtuctions

Thanks. I'll fix that. I'm still working on the overall wording. I also want to include that errors are ignored. I may even try to get the name of the function that ran PAUSE into the dialog box, but this is surprisingly difficult.

There is an X in the upper-right corner, presumably to Close the dialog window. It seems it does the same as Resume Execution. Can it be removed? (thinking that, why have two UI elements that do the same thing)

It's common for an "X" to appear on modal boxes and to have it be synonymous with "Cancel". The dialog box for READWORD does this, too. I expect it's part of the Windows UX Guidelines, but I haven't checked. You can see this in many places within Windows. I've attached a screenshot of a dialog box that has a "Cancel" and an "X". The "X" is also tied to what pressing the Esc does. It generally means "dismiss the dialog box without making a change". While this dialog has no explicit "Cancel" button, the previous version used made CONTINUE synonymous with Cancel.

Knowing this, do you still want me to remove the "X" and the Esc keyboard shortcut?

I was also wondering if "Execute" is common terminology in FMSLogo, cause it seems that what it does is "RUN"

Within the English manual, using the term "run" is part of the style guide. (The Spanish manual uses ejectuar, because that's how RUN was translated.) However, the commander has had an "Execute" button since MSWLogo, so I kept the new dialog box consistent with that. In fact, I wanted to also have a "Halt" button like the commander, but HALT can't exit pause mode, so I chose different text to emphasize that it's not running HALT. I stopped short of putting throw "toplevel on the button because I thought that would be more confusing.

Here's a prototype (and screenshot) of what you requested. "Resume Execution" executes continue and "Halt Program" executes throw "toplevel. I also made it so that the executed instructions get printed to the commander history.

I don't like that this adds an extra step.

I think you may have quoted the wrong thing, because printing to the commander history doesn't add an extra step. Did you mean to say you don't want the buttons (or links) to replace the input control? Keep in mind that some UX intentionally have extra steps. This would give the user a chance to see what the instruction is before executing it. More commonly, an extra step may be for showing an "are you sure you want to do that?" dialog for dangerous or irreversible actions. Maybe throw "toplevel counts as a dangerous or irreversible action. To me the instruction preview would be better for first-time users, but could get annoying once the user knows what the buttons/links do. I also don't really like that the buttons are also special cases of Execute and they might also complicate the layout if I ever make the instruction box have multiple lines.

[DanielAjoy]

I'm still working on the overall wording.
It generally means "dismiss the dialog box without making a change". While this dialog has no explicit "Cancel" button, the previous version used made CONTINUE synonymous with Cancel.

Knowing this, do you still want me to remove the "X" and the Esc keyboard shortcut?

I guess it is almost harmless to keep the X.

However, the commander has had an "Execute" button since MSWLogo, so I kept the new dialog box consistent with that. In fact, I wanted to also have a "Halt" button like the commander

The fact that the "Execute" button has been there all along in the commander, and the fact that it is probably described in dozens (if not hundreds) of intro documents and videos, convinces me that "Execute" for this dialog is the way to go.

I think I prefer the label CONTINUE instead of "Resume Execution"

Execution has a martial meaning too, And Resume is a synonym of Continue.

I think you may have quoted the wrong thing,

You are right, sorry.

Clicking on the link would then replace the input control with continue or throw "toplevel, but not execute it. This is a less obvious and less efficient UI, but it makes it clearer what the buttons do.

Above is the description of the extra step I don't particularly like. And you are right that it might be because I'm not a novice anymore.

[David Costanzo]

Daniel Ajoy writes:

I guess it is almost harmless to keep the X.

I can remove it if you like. I was just explaining why I had kept it. But I agree, the only harm that I can see of keeping the "X" is if it confuses users into thinking that it does something different.

I think I prefer the label CONTINUE instead of "Resume Execution"

That's what I started with. Then I changed it to "Continue" because all-caps looked ugly in the UI. I also wondered if the procedure name wouldn't be clear, which is part of why I changed it to a more descriptive "Resume Execution" and added tracing to the commander history.

I might be able to make "Continue" work, if I link the word "continue" with the concept of resuming execution in the explain text. Technical writing in the manual is hard, but it's even harder when trying to write text that is concise and clear enough to appear in a dialog box which novices may read but experienced users will always ignore and only read the button text.

[DanielAjoy]

I can remove it if you like.

I don't have a strong opinion either way.

I might be able to make "Continue" work, if I link the word "continue" with the concept of resuming execution in the explain text.

Maybe something like "Continue right after the Pause command"

[David Costanzo]

Another possibility is to have the button text be the Logo instruction and have additional explain text next to the button that ties the button to the text in the overall explain text. What do you think of this screenshot? Better or worse than before?

I expect that that a user will read the overall explain text at most once in their life. The text next to the button might be read more than once. This has a slight advantage of educating the user about Throw "TopLevel, even if they never click it.

For the scenario you described (PAUSE in a loop), I expect a novice would skim the text, click Continue a few times, then read the text more carefully and click Throw "TopLevel.

[DanielAjoy]

I think it's better. When I saw it, what I thought of was that navigating it using TABs is equivalent in this version as before. I think it is illustrative that the button says

throw "TopLevel

[David Costanzo]

Daniel Ajoy wrote:

When I saw it, what I thought of was that navigating it using TABs is equivalent in this version as before.

If you look carefully at the screenshot, you'll see that I added some underlined letters to the button text. These are keyboard shortcuts. In English, Alt+c (or Esc) will continue. Alt+t will halt the program. So a power user is only two keystrokes away from the button they want.

[David Costanzo]

I have finished implementing the dialog box, as describe. This is committed in [r6106]. This will be first available in FMSLogo 8.5.0, which has no planned release date.

I translated it to Spanish but not any other languages. Daniel, you might take a look at the attached screenshot of the Spanish translation, since I'm not a native speaker and don't know the natural way to say that execution is paused.

[DanielAjoy]

Thanks David, Sure:

El programa que se ejecuta actualmente está pausado. Cuando FMSLogo está pausado puedes ejecutar cualquier instrucción que quieras, incluidas las instrucciones para inspeccionar los valores de las variables locales, reanudar la ejecución, o detener el programa por completo.

Ejecutar

Reanudar la ejecución justo después de la instrucción PAUSA
Sigue

[David Costanzo]

Thanks for the corrections, Daniel. I committed them as [r6107].