scarpe 0.3.0 → 0.5.0

data/docs/lacci.md

@@ -0,0 +1,121 @@
+---
+layout: default
+title: Lacci
+---
+
+# Lacci: The Shoes4 Compatibility Layer
+
+## Overview
+
+Lacci (Italian for "laces") serves as the compatibility layer between Shoes4 applications and Scarpe's display services. Think of it as the translator that allows your classic Shoes4 code to work seamlessly with modern display backends.
+
+## Core Concepts
+
+### 1. Event Handling and Drawing Model
+
+Lacci implements the Shoes4 drawing model, which includes:
+- Slot-based layout system (stacks, flows)
+- Event propagation
+- Drawing context inheritance
+- Margin and positioning calculations
+
+### 2. Display Service Abstraction
+
+Lacci abstracts away the details of different display services (like Webview or Qt) by:
+- Translating Shoes4 drawing commands into display-agnostic operations
+- Managing widget lifecycles
+- Handling parent-child relationships between elements
+- Coordinating style inheritance
+
+### 3. Test Infrastructure
+
+The test infrastructure in Lacci uses Niente (Italian for "nothing"), a null display service that:
+- Allows testing without a real display backend
+- Verifies drawing operations and event handling
+- Supports multiple simultaneous Shoes apps in test environments
+- Provides fast, reliable test execution
+
+## Key Components
+
+### MarginHelper
+Handles margin calculations with support for:
+- Numeric values
+- Array-based margins
+- Hash-based margins
+- String-based margin definitions
+
+### FontHelper
+Manages font parsing and styling with support for:
+- Font families
+- Font sizes
+- Font weights
+- Font variants
+- Font styles
+
+### DrawContext
+Manages the drawing context inheritance system:
+- Style propagation (fill, stroke, etc.)
+- Context stacking
+- Property overrides
+
+## Usage Examples
+
+```ruby
+# Basic Shoes4 App
+Shoes.app do
+  stack do
+    para "Hello from Lacci!"
+    button "Click me" do
+      alert "Button clicked!"
+    end
+  end
+end
+```
+
+## Error Handling
+
+Lacci provides rich error handling through the `Shoes::Errors` module:
+- `InvalidAttributeValueError`
+- `BadArgumentListError`
+- `UnsupportedFeatureError`
+- `MultipleDrawablesFoundError`
+- `NoDrawablesFoundError`
+
+## Display Service Requirements
+
+For a display service to be compatible with Lacci, it must:
+1. Implement the basic drawing primitives
+2. Support parent-child relationships
+3. Handle event propagation
+4. Manage drawing contexts
+5. Support style inheritance
+
+## Testing
+
+Lacci uses a comprehensive test suite with:
+- Unit tests for helpers and utilities
+- Integration tests for drawing operations
+- Feature tests for end-to-end functionality
+- Niente-based tests for display service compatibility
+
+## Future Development
+
+Areas for future enhancement include:
+- Additional drawing primitives
+- Enhanced animation support
+- Improved error reporting
+- Extended display service capabilities
+
+## Contributing
+
+When contributing to Lacci:
+1. Ensure tests pass with Niente
+2. Maintain backward compatibility
+3. Follow the existing error handling patterns
+4. Document new features and changes
+
+## Related Components
+
+- Scarpe: The main project
+- Niente: The null display service for testing
+- Display Services: Various backend implementations

data/docs/scarpe_shoes_incompatibilities.md

@@ -0,0 +1,71 @@
+---
+layout: default
+title: scarpe shoes incompatibilities
+---
+
+# Scarpe/Shoes Incompatibilities
+
+This document outlines the known incompatibilities between Scarpe and the original Shoes implementation.
+
+## API Differences
+
+1. **Method Names**
+   - Some methods have been renamed for clarity
+   - Deprecated Shoes methods are not supported
+   - New methods added for modern features
+
+2. **Parameters**
+   - Some parameter orders have changed
+   - Additional options are available
+   - Some legacy options are not supported
+
+## Behavioral Changes
+
+Key behavioral differences include:
+
+1. **Event Handling**
+   - More consistent event model
+   - Better async support
+   - Different timing guarantees
+
+2. **Layout System**
+   - More predictable layout behavior
+   - Enhanced flexibility
+   - Some legacy layouts may render differently
+
+## Unsupported Features
+
+Some Shoes features are not supported in Scarpe:
+
+1. **Legacy Components**
+   - Certain deprecated widgets
+   - Old animation system
+   - Legacy drawing methods
+
+2. **Platform-Specific Features**
+   - Some OS-specific capabilities
+   - Direct hardware access
+   - Legacy system integration
+
+## Modernization Changes
+
+Intentional changes for modern development:
+
+1. **Architecture**
+   - Separate display service
+   - Modern component model
+   - Enhanced state management
+
+2. **Development Experience**
+   - Better debugging tools
+   - Modern testing support
+   - Improved error messages
+
+## Migration Guide
+
+When moving from Shoes to Scarpe:
+
+1. Review API changes
+2. Update event handlers
+3. Test layouts thoroughly
+4. Use modern alternatives for legacy features

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/Edit_box_Styles.rb

@@ -0,0 +1,8 @@
+Shoes.app do
+    para "Anything:",size:"30px"
+    lorem = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim."
+    @manuscript = edit_box(lorem, width: "100%", font:"italic normal bold 25px 'Times New Roman', serif;", tooltip:"This is a tooltip") do |box|
+      @char_count.replace("#{box.text.length} characters")
+    end
+    @char_count = para "#{@manuscript.text.length} characters" ,size:"20px"
+  end

data/examples/Kerning.rb

@@ -0,0 +1,7 @@
+Shoes.app do
+
+    para "This text have kerning applied to it", kerning:10, size:18
+
+    para "This is normal text for reference", size:18
+    
+end

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