scarpe 0.4.0 → 0.5.0

data/docs/shoes_and_display_events.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: shoes and display events
+---
+
+# Shoes and Display Events
+
+This document covers how Scarpe handles events and display updates in relation to the original Shoes implementation.
+
+## Event Handling
+
+Scarpe implements event handling in a way that maintains compatibility with Shoes while providing modern features:
+
+1. **Event Types**
+   - Mouse events (click, hover, etc.)
+   - Keyboard events
+   - Window events
+   - Custom events
+
+2. **Event Flow**
+   - Events are captured in the display service
+   - Processed through the event loop
+   - Dispatched to appropriate handlers
+
+## Synchronous vs Asynchronous
+
+Scarpe supports both synchronous and asynchronous event handling:
+
+### Synchronous Events
+- Direct user interactions
+- Immediate UI updates
+- Traditional Shoes-style callbacks
+
+### Asynchronous Events
+- Background operations
+- Network requests
+- Long-running computations
+
+## Display Updates
+
+Display updates in Scarpe follow a specific pattern:
+
+1. State changes trigger update events
+2. Updates are batched when possible
+3. Changes are applied atomically
+4. The display service reflects changes efficiently
+
+## Compatibility Notes
+
+While maintaining compatibility with Shoes, Scarpe introduces some modern improvements:
+
+- Better event queueing
+- More efficient update batching
+- Enhanced error handling
+- Improved async support

data/docs/shoes_implementations.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: shoes implementations
+---
+
+# Shoes Implementations
+
+This document covers various Shoes implementations and how Scarpe relates to them.
+
+## Historical Implementations
+
+1. **Original Shoes**
+   - Written in C/Ruby
+   - Created by _why the lucky stiff
+   - Native GUI implementation
+
+2. **Green Shoes**
+   - Pure Ruby implementation
+   - GTK+ based
+   - Simplified architecture
+
+3. **Purple Shoes**
+   - Windows-specific version
+   - WinForms based
+   - Limited platform support
+
+## Modern Implementations
+
+1. **Scarpe**
+   - Web-based implementation
+   - Modern architecture
+   - Enhanced features
+
+2. **Other Current Projects**
+   - Various community efforts
+   - Different approach focuses
+   - Platform-specific versions
+
+## Implementation Comparisons
+
+Key differences between implementations:
+
+1. **Architecture**
+   - Display handling
+   - Event systems
+   - State management
+
+2. **Features**
+   - UI components
+   - Drawing capabilities
+   - Platform integration
+
+## Learning from History
+
+Lessons from previous implementations:
+
+1. **What Worked**
+   - Simple API design
+   - Flexible layouts
+   - Ruby-like syntax
+
+2. **What Needed Improvement**
+   - Event handling
+   - State management
+   - Cross-platform support
+
+## Future Directions
+
+Areas for continued development:
+
+1. **Modern Features**
+   - Better async support
+   - Enhanced components
+   - Improved tooling
+
+2. **Community Focus**
+   - Documentation
+   - Examples
+   - Learning resources

data/docs/static/manual.md

@@ -1,3 +1,8 @@
+---
+layout: default
+title: The Shoes Manual
+---
+
 # Hello!
 
 Shoes is a tiny graphics toolkit. It's simple and straightforward. Shoes was

data/docs/timeouts_and_handlers.md

@@ -0,0 +1,66 @@
+---
+layout: default
+title: timeouts and handlers
+---
+
+# Timeouts and Handlers
+
+This document explains how Scarpe manages timeouts and event handlers within its cooperative evented approach.
+
+## Timeout Management
+
+Scarpe implements timeouts with these key considerations:
+
+1. **Cooperative Nature**
+   - Timeouts don't interrupt execution
+   - They're processed when the event loop is ready
+   - Timing is approximate, not exact
+
+2. **Implementation**
+```ruby
+def after(milliseconds, &block)
+  register_timeout(Time.now + (milliseconds / 1000.0), block)
+end
+```
+
+## Event Handlers
+
+Event handlers in Scarpe follow these principles:
+
+1. **Registration**
+   - Handlers are registered with specific events
+   - Multiple handlers can exist per event
+   - Order of execution is preserved
+
+2. **Execution**
+   - Handlers run in the main event loop
+   - They should be non-blocking when possible
+   - Long operations should be broken up
+
+## Restrictions
+
+The cooperative approach has some important restrictions:
+
+1. **No Preemption**
+   - Long-running handlers block other events
+   - Timeouts may be delayed
+   - UI updates wait for handlers to complete
+
+2. **Best Practices**
+   - Keep handlers short
+   - Use async for long operations
+   - Break up complex tasks
+
+## Error Handling
+
+Handlers include error management:
+
+1. **Exception Catching**
+   - Errors don't crash the event loop
+   - Exceptions are logged appropriately
+   - Error handlers can be registered
+
+2. **Recovery**
+   - System can recover from handler errors
+   - State remains consistent
+   - Other handlers continue to work

data/docs/web_archaeology.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: web archaeology
+---
+
+# Web Archaeology
+
+This document catalogs various online sources of Shoes-related information, preserving important historical context.
+
+## Historical Sources
+
+1. **_why's Work**
+   - Original Shoes documentation
+   - Blog posts and tutorials
+   - Code examples and demos
+
+2. **Community Resources**
+   - Early forum discussions
+   - Mailing list archives
+   - Wiki pages
+
+## Code Archives
+
+Important code repositories:
+
+1. **Original Shoes**
+   - GitHub mirrors
+   - Historical versions
+   - Community forks
+
+2. **Related Projects**
+   - Green Shoes
+   - Purple Shoes
+   - Other implementations
+
+## Documentation Archives
+
+Preserved documentation:
+
+1. **Official Docs**
+   - Original manuals
+   - Tutorial content
+   - API references
+
+2. **Community Guides**
+   - Blog posts
+   - Tutorials
+   - Example collections
+
+## Learning Resources
+
+Educational materials:
+
+1. **Tutorials**
+   - Getting started guides
+   - Advanced topics
+   - Example applications
+
+2. **Reference Materials**
+   - API documentation
+   - Design principles
+   - Best practices
+
+## Historical Context
+
+Understanding Shoes' evolution:
+
+1. **Timeline**
+   - Key developments
+   - Major releases
+   - Community milestones
+
+2. **Impact**
+   - Influence on Ruby
+   - GUI development
+   - Community growth

data/examples/background_with_image.rb

@@ -1,16 +1,25 @@
 Shoes.app do
 
-  stack width:100, height:100 do
-    background "docs/static/avatar.png"
-    border blue ,strokewidth: 4
+  # Local file (path relative to this script)
+  stack width: 100, height: 100 do
+    background "../docs/static/avatar.png"
+    border blue, strokewidth: 4
   end
 
-  stack width:100, height:100 do
+  # Solid color
+  stack width: 100, height: 100 do
     background red
   end
 
-  stack width:100, height:100 do
+  # RGBA string
+  stack width: 100, height: 100 do
     background "rgba(255,200,0,255)"
   end
 
+  # Remote URL
+  stack width: 100, height: 100 do
+    background "http://shoesrb.com/manual/static/shoes-icon.png"
+    border green, strokewidth: 4
+  end
+
 end

data/examples/bloopsaphone/working/feepogram.rb

@@ -58,7 +58,7 @@ class Feepogram
     @tracks.each do |sound_name, notes|
       bloops.tune @sounds[sound_name], notes
 
-      #puts "#{sound_name}: #{notes.gsub(/\s+/, ' ')}"
+      puts "#{sound_name}: #{notes.gsub(/\s+/, ' ')}"
     end
 
     bloops.play

data/examples/bloopsaphone/working/le_dance_des_rubis.rb

@@ -0,0 +1,135 @@
+require_relative 'feepogram'
+
+bloops = Bloops.new
+bloops.tempo = 280
+
+song = Feepogram.new(bloops) do
+  # Define our instruments
+  sound :kick, Bloops::SINE do |s|
+    s.volume = 0.9
+    s.punch = 0.4
+    s.sustain = 0.1
+    s.decay = 0.2
+  end
+
+  sound :snare, Bloops::NOISE do |s|
+    s.volume = 0.8
+    s.punch = 0.2
+    s.sustain = 0.05
+    s.decay = 0.25
+  end
+
+  sound :hat, Bloops::NOISE do |s|
+    s.volume = 0.4
+    s.punch = 0.1
+    s.sustain = 0.02
+    s.decay = 0.1
+  end
+
+  sound :synth_bass, Bloops::SAWTOOTH do |s|
+    s.volume = 0.7
+    s.sustain = 0.3
+    s.decay = 0.1
+    s.slide = 0.2
+  end
+
+  sound :lead, Bloops::SQUARE do |s|
+    s.volume = 0.6
+    s.punch = 0.3
+    s.sustain = 0.4
+    s.decay = 0.2
+  end
+
+  sound :pad, Bloops::SINE do |s|
+    s.volume = 0.5
+    s.sustain = 1.0
+    s.decay = 0.5
+  end
+
+  # Helper methods for our patterns
+  def basic_beat
+    kick " c 4 4 c 4 4 c 4 " * 4
+    snare " 4 4 c 4 4 4 c 4 " * 4
+    hat " c5 " * 32
+  end
+
+  def bass_line_a
+    synth_bass %{
+      c2 4 e2 4 f2 4 g2 4
+      c2 4 e2 4 f2 4 g2 4
+      a1 4 c2 4 d2 4 e2 4
+      f2 4 e2 4 d2 4 c2 4
+    }
+  end
+
+  def lead_melody_a
+    lead %{
+      4 c4 e4 g4 4 c5 g4 e4
+      4 c4 f4 a4 4 c5 a4 f4
+      4 e4 g4 c5 4 e5 c5 g4
+      4 d4 f4 a4 4 d5 a4 f4
+    }
+  end
+
+  def ambient_pad
+    pad %{
+      1:c4 1:c4
+      1:f4 1:f4
+      1:g4 1:g4
+      1:e4 1:e4
+    }
+  end
+
+  # Structure our song
+  def intro
+    2.times do
+      phrase do
+        basic_beat
+        bass_line_a
+      end
+    end
+  end
+
+  def verse
+    2.times do
+      phrase do
+        basic_beat
+        bass_line_a
+        lead_melody_a
+      end
+    end
+  end
+
+  def bridge
+    phrase do
+      kick " c 4 4 4 " * 8
+      snare " 4 4 c 4 " * 8
+      hat " c5 " * 16
+      ambient_pad
+    end
+  end
+
+  def outro
+    phrase do
+      basic_beat
+      bass_line_a
+      lead_melody_a
+      ambient_pad
+    end
+
+    phrase do
+      kick "c"
+      synth_bass "c2"
+      pad "1:c4"
+    end
+  end
+
+  # Play the composition
+  intro
+  verse
+  bridge
+  verse
+  outro
+end
+
+song.play

data/examples/bloopsaphone/working/pixel_dreams_in_ruby.rb

@@ -0,0 +1,131 @@
+require_relative 'feepogram'
+
+bloops = Bloops.new
+bloops.tempo = 160  # Slower tempo for dreamy feel
+
+song = Feepogram.new(bloops) do
+  # Soft percussion
+  sound :soft_kick, Bloops::SINE do |s|
+    s.volume = 0.3
+    s.punch = 0.15
+    s.sustain = 0.1
+    s.decay = 0.3
+  end
+
+  sound :chimes, Bloops::SINE do |s|
+    s.volume = 0.35
+    s.punch = 0.1
+    s.sustain = 0.8
+    s.decay = 0.6
+    s.slide = 0.1
+  end
+
+  # Main melody instrument
+  sound :crystal, Bloops::SQUARE do |s|
+    s.volume = 0.45
+    s.punch = 0.1
+    s.sustain = 0.4
+    s.decay = 0.3
+    s.phase = 0.3
+  end
+
+  # Sparkly accent notes
+  sound :sparkle, Bloops::SQUARE do |s|
+    s.volume = 0.25
+    s.punch = 0.1
+    s.sustain = 0.1
+    s.decay = 0.4
+    s.phase = 0.2
+    s.lpf = 0.6
+  end
+
+  # Warm bass pad
+  sound :dream_pad, Bloops::SINE do |s|
+    s.volume = 0.25
+    s.sustain = 0.6
+    s.decay = 0.4
+    s.slide = 0.1
+    s.lpf = 0.4
+  end
+
+  def gentle_rhythm
+    soft_kick " c 4 4 4 " * 8
+    chimes " 4 c6 4 c6 " * 4
+  end
+
+  def dream_bass
+    dream_pad %{
+      2:c3 2:g3
+      2:a3 2:e3
+      2:f3 2:c3
+      2:g3 2:e3
+    }
+  end
+
+  def main_melody
+    crystal %{
+      c5 4 g5 4 e5 4 c6 g5
+      a5 4 e5 4 c5 4 g5 4
+      f5 4 c6 4 a5 4 f5 e5
+      g5 4 e5 4 c5 4 4 4
+    }
+  end
+
+  def sparkle_accent
+    sparkle %{
+      4 4 c7 4 4 4 e7 4
+      4 4 g6 4 4 4 c7 4
+      4 4 a6 4 4 4 f7 4
+      4 4 e7 4 4 4 g6 4
+    }
+  end
+
+  def title_theme
+    phrase do
+      dream_bass
+      gentle_rhythm
+    end
+
+    phrase do
+      dream_bass
+      gentle_rhythm
+      main_melody
+    end
+
+    phrase do
+      dream_bass
+      gentle_rhythm
+      main_melody
+      sparkle_accent
+    end
+  end
+
+  def peaceful_bridge
+    phrase do
+      dream_pad %{
+        4:c4 4:e4
+        4:f4 4:g4
+      }
+      sparkle " c6 e6 g6 c7 " * 4
+    end
+  end
+
+  def outro_fade
+    phrase do
+      dream_bass
+      crystal %{
+        c6 g5 e5 c5
+        4 4 4 4
+      }
+      sparkle " c7 g6 e6 c6 "
+    end
+  end
+
+  # The composition
+  2.times { title_theme }
+  peaceful_bridge
+  title_theme
+  outro_fade
+end
+
+song.play