Add documentation for program blocks including heap and boxes

[JaySoni1]

Fix: #3844 Add documentation for program blocks including heap and box blocks

• Added documentation for program blocks (heap and box blocks) in guide/README.md.
  -Explained key blocks: Set Heap, Load Heap, Store in Box, Add One, etc.
  -Provided a clear example to demonstrate usage in musical programs.

Fixes:- #3844

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[walterbender]

This is a nice addition. It would be even better if there was an example of its use with a MB program. Perhaps something like recording and playing back notes?

[JaySoni1]

@walterbender Thank you for the feedback!
You're right that a more concrete MB program example would be valuable. I have one example that demonstrates recording and playing back musical notes.
The new example demonstrates:

-Recording notes with timing information using the heap.
-Playing back recorded melodies with proper timing.
-Saving and loading melodies with names.
-Button interactions to control recording and playback.

// Initialize our note recorder
function initRecorder() {
set heap "isRecording" to false
set heap "recordedNotes" to []
set heap "startTime" to 0
}

// Start recording notes
function startRecording() {
set heap "isRecording" to true
set heap "recordedNotes" to []
set heap "startTime" to currentTimeMillis()

// Visual indicator that recording has started
setLED(RED)
displayText("Recording...")
}

// Record a note when it's played
function recordNote(note, duration) {
if (load heap "isRecording") {
var currentTime = currentTimeMillis()
var timestamp = currentTime - (load heap "startTime")

// Save the note data (timestamp, note value, and duration)
var noteData = {
"time": timestamp,
"note": note,
"duration": duration
}

// Add to our recorded notes array
var notes = load heap "recordedNotes"
notes.push(noteData)
set heap "recordedNotes" to notes

// Visual feedback
flashLED(GREEN)
}
}

// rest of the recording/playback example
How is this example?

[walterbender]

The example should be coded in Music Blocks

[github-actions]

✅ All Jest tests passed! This PR is ready to merge.

[JaySoni1]

@walterbender I have added the heap and note recording examples as suggested and I have revised the PR. Please review when you have a moment.
Thank you @walterbender for your guidance !

[walterbender]

The example would be fine if MB was a text-based language. But it is block-based. Please create a visual similar to all of the other examples in the guide.

[JaySoni1]

Should I create a simple Music Blocks program that demonstrates:

-Basic heap operations (set/load)
-A practical example like note recording

• And then document it with screenshots of the actual blocks?

[walterbender]

Yes. Note that there is a save block art work option in advanced mode -- an SVG of your project.

[JaySoni1]

Hi @walterbender ,
I have captured the block artwork showing basic heap functionality:

• Set heap -> Box1 -> 4
• Load heap -> Box2

Here's the SVG image showing the implementation:

I have covered this following points :-

1. Demonstration of basic heap operations.
2. Value storage and retrieval .
3. Clear block arrangement for documentation.

Could you please review this and let me know if any additional details or changes are needed?

Thanks!

[walterbender]

Are you sure you attached the correct image?

[JaySoni1]

@walterbender In the image I shared, please focus on the left side which demonstrates the heap operations:

set heap
└─> box1 [4]
load heap
└─> box2

The other blocks on the right (music notes, drums, etc.) are unrelated to the heap example and can be ignored for this discussion. I included them because they were part of my workspace, but only the left-side blocks are relevant to showing heap functionality.

Would you prefer if I:

1. Share a new image with only the heap blocks.
2. Continue discussing the current heap implementation as shown on the left.

Please let me know which would be more helpful for the documentation.

[walterbender]

Do you know how to edit SVG? I recommend Inkscape.
In any case, I think an example that shows a practical use of the heap would be better.
Maybe you can make a simpler version of the coinflip example code?

[walterbender]

[rakesh0x]

hey @walterbender should i proceed further , is this issue is still relevant??

[walterbender]

It would be nice to finish this up.