Design Decisions

Navigation

Arrow-Keys

• Left/Right: will move to the closest editable character/code-construct. moves into text-editable code-constructs.
• Up/Down: will work similar to clicking on the position above or below the current position.
• Selectables: will only select holes and nothing else will be selected. Selection will be done through another mechanism discussed later.

Clicks

• Editable code-constructs: will move the cursor to the clicked position.
• Non-editable code-constructs: if clicked on the first half of the code-construct, will go to the beginning, o.w. to the end of it.

Editing

Adding Using Toolbox

• Main code-constructs: for, if, else, elif, and while will be added simply by clicking
• Expressions: --- + ---, --- and ---, --- >= ---
• Working with variables:
• Working with lists:
• Function/Method calls:
• The toolbox can also be aware of the user's focus (in the AST) and disable completely invalid buttons (e.g. disabling the for loop button when the user is inside the condition of an if statement)

Draft Mode

When filling in expressions, sometimes the user might start with an incorrect type (e.g. a number in a condition). In these cases, the system will automatically move into draft mode, becoming yellow but allowing the user to finalize their edit so that the final expression would evaluate into the required type.

Unconstrained Typing Mode

Users can enter an unconstrained typing box at the place that they're coding in which they could freely type and only has syntax highlighting and vs-code-level linting and error highlighting. When the user focuses off of this unconstrained typing box, the code will be transformed into our own AST.

Adding Using Keyboard

With the help of the suggestion system the user is able to add code-constructs, call functions, create variables, fill-in expressions and more. This will also ensure that no incorrect characters are inputted.

The Suggestion Menu/Drop-down:

• opens up when the user clicks on an empty line, or an empty hole, or presses Ctrl + Space
• contains addable code constructs and modifications that could be done to
• the UI design: will use a tree UI as it its easier to use compared to wizard menus (how would they go back if went through the wrong wizard)

Based on where the user is, we will be able to suggest different statements, expressions and etc.:

Beginning of Lines (New Statements):

• code constructs: if, for, while, def, and class (if validated, else and elif could be possible options)
• variable definition (e.g. player_name = ---)
• calling functions that do not return anything and do not update the state of anything (note that we can call other functions that return things, but we have to give a warning to the user and let them know that the returned value is not being used)
• a return statement (e.g. return ---)
• accessing a variable to: -- reassign its value (such as points = 0 or points[player] = 0) -- update its value (using the +=, -=, *=, /= operators) -- calling a method on it (such as players.append(---))

Within Expressions:

• Literals -- Numbers (integers and floating points, validated by: '^(([0-9]*)|(([0-9]*)\\.([0-9]*)))$') -- String (almost anything except new line characters and the double quote character itself, validated by: '^([^\\r\\n\\"]*)$') -- Boolean (True and False which need to be typed exactly like that.)
• Accessing identifiers: -- variables (e.g. print(---) => print(player_name)) -- member of a list (e.g. print(---) => print(players[player_id]))
• lists
• function calls that return something (e.g. range() and len())
• unary operators (+ and -)
• binary operators after an existing left operand/expression (e.g. ... + b)

Toolbox and Typing Consistency:

• we need to have parenthesis:
• every op could have parenthesis similar to blocks-based languages. However, in BBPLs, the user is able to move these around and do interesting things with them.
• binary ops:
  • print(123|) => pressing + => print((123 + ⏹)) => how does the user get back to just having print(123)? =>
  • ((5 in x) and ☐)| => pressing + => (((5 in x) and ☐) + ⏹)
  • ((|(5 in x) and ☐) + ☐) => pressing delete => ((⏹ and ☐) + ☐)
  • ((☐ and ⏹) + ☐) => pressing + => ((☐ and (⏹ + ☐)) + ☐)
  • if ⏹ : => inserting a variable named count => if count| : => pressing the > sign => if (count > ⏹) :
  • at if (count > ⏹) : => lets say the user wants to change the operator => they have to move the cursor to the end of the parenthesis and press backspace, so: if (count > ☐)| : => backspace => if ⏹ :
  • we could also add a right-click event for operators that would open up the suggestion menu with valid changes of the operator.
• unary ops:
  • at (|(count - 5) >= 10)) => inserting not => (not((count - 5)) >= 10))

User-Defined Items (Variables, Functions and Classes) and Hierarchical Menus in the toolbox:

• Scope-aware box for User-defined items: it will simply display all user-defined variables in the current scope (based on the user's current focused navigation) in a box within the toolbox.
• Each variable should have a type (or a list of types if it is ambiguous at a particular navigation point)
• Clicking on each variable opens up a hierarchical menu that contains all of the actions associated with that particular button based on its type at that point:
  • accessing variables or indexing list variables
  • reassignments (foo = ---)
  • other list method calls (such as .append())
  • string method calls on a string variable
• Note that we will also allow users to perform interesting draft-mode keyboard based actions with variables:
  • start with variable at the beginning of a line => immediately show the suggestion menu on what the user wants to do with it

imports

• in the case that we add new functions from different modules that require to be imported, lets not use cascaded menus and have everything in the toolbox (similar to Scratch - and in the case of a cluttering the UI, we can simply just add expand/drop-down buttons)

Selecting

Removing

Unsolved challenges

• Visual indicators in empty lists, or empty function definitions to let the user know that they can add more items to the list, or more arguments
• When and how should the drop-down menu for suggestions be shown? on every click? on every click on an empty hole and empty line? what about arrow key navigations?