edu_draw 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fd768abe04a69ab7b6157dfff3bcad5bb051464b
-  data.tar.gz: cfa2a99ee7eb1320b237ce207dd8d4c595cf3247
+  metadata.gz: dfc3b98dd75cc8bba96e5c4232b6fd63af037220
+  data.tar.gz: 7ad1c99a69f9146c9ec8b9c2fdc8d3d58c1591ea
 SHA512:
-  metadata.gz: ffca39137a42964697fb9bf6fe8de51caae460af6022f8cb3f3d90775ffa1c58949225743e1a6162929bc2c590fd240a0aef1a5bcff34ba14da2c80489def5ef
-  data.tar.gz: 1847a9ed2b554d930c2eab0da09aab7abcdeb7e4fb76106492558a6e24e6bbc0f87ee572fbe7e5f6da4bfafdbc053e9f79c1a1eabe0705f0ea1aa29542845506
+  metadata.gz: 94cdaeefbc9b682466f99041b32632e0fcb167f92140cd4d363d6cb67c6926e52b8a25f14d7191a7bf636207213aa7c4e23839bbf1a0f8bc1da7b0bea93d3851
+  data.tar.gz: 1516ae2a65123eebbe63a900f9500d744635c320cf71c79e08b34ce00d17c59f085cce7a65d6afd42ce9c25613e7818e790e1ac89254e79cadff63cc1d6ac10e

data/README.md

@@ -41,10 +41,10 @@ When you are done drawing, you have to make one final call to the sheet, to actu
 
 The whole program looks like this:
 
-```
+```ruby
 require "edu_draw"
 
-sheet = EduDraw::Sheet.new x: 500, y: 600, title: "It works"
+sheet = EduDraw::Sheet.new x: 500, y: 600, title: "A beautiful rectangle"
 green_pen = sheet.new_pen(x: 100, y: 20)
 
 green_pen.move 100
@@ -58,6 +58,71 @@ green_pen.move 80
 sheet.show
 ```
 
+### Areas / Filled shapes
+You can also draw filled or party-filled shapes. Here is an short example, that can be also found in the examples folder:
+```ruby
+require "edu_draw"
+
+sheet = EduDraw::Sheet.new(x: 150, y: 150)
+pen = sheet.new_pen(x: 52, y: 10)
+
+# Every move in the fill-block will create a filled a shape
+pen.fill do
+	5.times do
+		pen.move 40
+		pen.turn_right 36
+	end
+end
+
+#Every move out of the fill block just draws a line
+# Those 10 moves result in a half-filled decagon
+5.times do
+	pen.move 40
+	pen.turn_right 36
+end
+
+
+sheet.show
+```
+
+### Animations
+You can even draw animated shapes. Here is an short example, that can be also found in the examples folder:
+```ruby
+require "edu_draw"
+
+sheet = EduDraw::Sheet.new(x: 150, y: 150)
+
+# Instead of using sheet.new_pen, now you create a new_animation_pen
+pen = sheet.new_animation_pen(x: 75, y: 75)
+
+# Here you define what happens in the beginning of each frame
+pen.each_frame do
+	pen.turn_right 1
+end
+
+# Now you define what the pen should draw each frame
+# It is important to leave the pen in a state, where
+# it can start drawing on the next frame, that's why
+# the pens moves back, even though it does not draw
+# any actual lines.
+pen.draw_frame do
+	pen.move 50
+	pen.move -50
+end
+
+
+# You're set. No just show the sheet as usual and enjoy
+# the wonderfully spinning line you just drew.
+sheet.show
+```
+
+## Changelog
+* 2.0.0
+  * Adds ability to fill shapes. See `examples/areas.rb`
+  * Adds ability to draw animated shapes. See `examples/animations.rb`
+  * Makes state of pen writable
+  * Greatly improves documentation
+
 ## Contributing
 Feel free to contribute anything, may it be better tests, better documentation or more features. As you can see, I tried to keep the code tidy so it is appreciated if you'd do the same. Just add a pull request and we will make it work. Oh, and don't forget to have fun ;)
 

data/examples/animations.rb

@@ -0,0 +1,26 @@
+require "edu_draw"
+
+sheet = EduDraw::Sheet.new(x: 150, y: 150)
+
+# Instead of using sheet.new_pen, now you create a new_animation_pen
+pen = sheet.new_animation_pen(x: 75, y: 75)
+
+# Here you define what happens in the beginning of each frame
+pen.each_frame do
+	pen.turn_right 1
+end
+
+# Now you define what the pen should draw each frame
+# It is important to leave the pen in a state, where
+# it can start drawing on the next frame, that's why
+# the pens moves back, even though it does not draw
+# any actual lines.
+pen.draw_frame do
+	pen.move 50
+	pen.move -50
+end
+
+
+# You're set. No just show the sheet as usual and enjoy
+# the wonderfully spinning line you just drew.
+sheet.show

data/examples/areas.rb

@@ -0,0 +1,22 @@
+require "edu_draw"
+
+sheet = EduDraw::Sheet.new(x: 150, y: 150)
+pen = sheet.new_pen(x: 52, y: 10)
+
+# Every move in the fill-block will create a filled a shape
+pen.fill do
+	5.times do
+		pen.move 40
+		pen.turn_right 36
+	end
+end
+
+#Every move out of the fill block just draws a line
+# Those 10 moves result in a half-filled decagon
+5.times do
+	pen.move 40
+	pen.turn_right 36
+end
+
+
+sheet.show

data/lib/edu_draw.rb

@@ -1,3 +1,4 @@
 require "gosu"
 require_relative "edu_draw/sheet"
 require_relative "edu_draw/pen"
+require_relative "edu_draw/animation_pen"

data/lib/edu_draw/animation_pen.rb

@@ -0,0 +1,65 @@
+module EduDraw
+	# An AnimatedPen is a special {Pen} that is used for drawing animated shapes
+	class AnimationPen < Pen
+
+		# @private
+		# Creates a new AnimationPen
+		# @overload initialize(x, y, angle, color)
+		# @param (see Pen#initialize)
+		def initialize(*args)
+			super
+			@update_block = -> {}
+			@draw_block = -> {}
+		end
+
+		# Defines what needs to be done every frame before drawing
+		#
+		# @example
+		# 	# This makes the pen turn around slowly
+		# 	pen.each_frame do
+		# 		pen.turn_right 1
+		# 	end
+		def each_frame &block
+			@update_block = block
+		end
+
+		# Defines what the pen needs to draw every frame
+		#
+		# @note Every {#move} outside this block will draw only in the first frame
+		#
+		# @note Remember to set the state of the pen so that it can start drawing the next frame.
+		# 		In the given example the last `pen.turn_right 90` is not neccessary for the shape,
+		# 		but without it, the pen would draw the rectangle in a different direction on the next frame.
+		# 		Maybe, this is what you need, but it is still recommended to do these changes in the
+		# 		{#each_frame}-block.
+		#
+		# @example
+		# 	# Draw a rectangle
+		# 	pen.draw_frame do
+		# 		pen.move 20
+		# 		pen.turn_right 90
+		# 		pen.move 10
+		# 		pen.turn_right 90
+		# 		pen.move 20
+		# 		pen.turn_right 90
+		# 		pen.move 10
+		# 		pen.turn_right 90
+		# 	end
+		def draw_frame &block
+			@draw_block = block
+		end
+
+		# @private
+		def update
+			empty_shapes
+			@update_block.call
+			@draw_block.call
+		end
+
+		private
+
+			def empty_shapes
+				shapes.clear
+			end
+	end
+end

data/lib/edu_draw/pen.rb

@@ -2,30 +2,39 @@ module EduDraw
 	# A Pen is a drawing tool that provides basic drawing functionalities on a 2d {Sheet}.
 	class Pen
 
+		# Tolerance with which to consider two points the same
+		PIXEL_TOLERANCE = 0.2
+		private_constant :PIXEL_TOLERANCE
+
+		# Shapes to be drawn by sheet
+		# @private
+		attr_reader :shapes
+
 		# @return [Fixnum] x-coordinate of position in pixel where left is 0
-		attr_reader :x
+		attr_accessor :x
 
 		# @return [Fixnum] y-coordinate of position in pixel where top is 0
-		attr_reader :y
+		attr_accessor :y
 
 		# @return [Fixnum] Direction of the pen in degree where 0 points to the right
-		attr_reader :angle
+		attr_accessor :angle
 
 		# @return [Gosu::Color] Color of the pen
-		attr_reader :color
+		attr_accessor :color
 
-		# Creates a new Sheet
+		# Creates a new Pen
 		#
-		# @param x [Fixnum] initial value of {#x}
-		# @param y [Fixnum] initial value of {#y}
-		# @param angle [Fixnum] initial value of {#angle}
-		# @param color [Gosu::Color] initial value of {#color}
-		def initialize(sheet, x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
+		# @param x [Fixnum] Initial value of {#x}
+		# @param y [Fixnum] Initial value of {#y}
+		# @param angle [Fixnum] Initial value of {#angle}
+		# @param color [Gosu::Color] Initial value of {#color}
+		def initialize(x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
 			@x = x
 			@y = y
 			@angle = angle
 			@color = color
-			@sheet = sheet
+			@shapes = []
+			@to_be_filled = []
 
 			down!
 		end
@@ -42,7 +51,7 @@ module EduDraw
 		# Changes the direction of self to be turned to the right
 		# The {#angle} stays within 0..364
 		#
-		# @param degree [Fixnum] Amount of degree to be turned
+		# @param (see #turn_left)
 		def turn_right(degree)
 			turn_left -degree
 		end
@@ -52,23 +61,23 @@ module EduDraw
 			@up
 		end
 
-		# If the pen is up, it touches the {Sheet} and is drawing when moved.
+		# If the pen is down, it touches the {Sheet} and is drawing when moved.
 		def down?
 			!up?
 		end
 
 		# Lifts the pen from the {Sheet}
 		#
-		# @see {#up?}
-		# @see {#down?}
+		# @see #up?
+		# @see #down?
 		def up!
 			@up = true
 		end
 
 		# Sticks the pen to the {Sheet}
 		#
-		# @see {#up?}
-		# @see {#down?}
+		# @see #up?
+		# @see #down?
 		def down!
 			@up = false
 		end
@@ -80,9 +89,7 @@ module EduDraw
 		def move(length)
 			target_x = x + Math.cos(angle_in_rad) * length
 			target_y = y + Math.sin(angle_in_rad) * length
-			if down?
-				@sheet.shapes << [:draw_line, x, y, color, target_x, target_y, color]
-			end
+			handle_movement x, y, target_x, target_y
 			@x = target_x
 			@y = target_y
 		end
@@ -91,5 +98,73 @@ module EduDraw
 		def angle_in_rad
 			angle * Math::PI / 180.0
 		end
+
+		# Draws filled shapes.
+		#
+		# @note If the pen does not end where it started, the
+		# 		pen will assume a connection between start and end point.
+		# 		This does not affect the actual position and direction
+		# 		of the pen.
+		#
+		# @example
+		# 	# This draws a triangle
+		# 	pen.fill do
+		# 		pen.move 10
+		# 		pen.turn_right 90
+		# 		pen.move 10
+		#   end
+		def fill(&block)
+			@to_be_filled << [x,y]
+			yield
+			if starting_point_is_end_point?
+				@to_be_filled.delete_at(0)
+			end
+			origin_x, origin_y = @to_be_filled.first
+			@to_be_filled[1..@to_be_filled.length-1].each_cons(2) do |point_a, point_b|
+				@shapes << [:draw_triangle,
+					origin_x, origin_y, color,
+					point_a[0], point_a[1], color,
+					point_b[0], point_b[1], color]
+			end
+			@to_be_filled.clear
+		end
+
+		# Hook method
+		# @private
+		def update
+			# nothing to do since nothing ever changes
+		end
+
+		private
+
+
+			# True, if pen is currently in a {#fill}-block
+			def fill_mode?
+				@to_be_filled.length > 0
+			end
+
+			# Does whatever needs to be done upon movement.
+			# This depends on the state of the pen.
+			# up or down? fill mode or regular mode?
+			def handle_movement(x, y, target_x, target_y)
+				if down?
+					if fill_mode?
+						@to_be_filled << [target_x, target_y]
+					else
+						@shapes << [:draw_line, x, y, color, target_x, target_y, color]
+					end
+				end
+			end
+
+			# Checks whether the pen came back to its starting point during
+			# the {#fill}-block.
+			def starting_point_is_end_point?
+				start_x = @to_be_filled.first[0]
+				start_y = @to_be_filled.first[1]
+				end_x = @to_be_filled.last[0]
+				end_y = @to_be_filled.last[1]
+				(start_x - end_x).abs <= PIXEL_TOLERANCE and
+					(start_y - end_y).abs <= PIXEL_TOLERANCE
+			end
 	end
 end

data/lib/edu_draw/sheet.rb

@@ -3,7 +3,9 @@ module EduDraw
 	class Sheet < Gosu::Window
 
 		# @private
-		attr_reader :shapes
+		# All pens created by and for this sheet
+		attr_reader :pens
+		private :pens
 
 		# Creates a new Sheet
 		#
@@ -13,39 +15,58 @@ module EduDraw
 		def initialize(x: 100, y: 100, title: "A blank sheet")
 			super x, y, false
 			self.caption = title
-			@shapes = []
+			@pens = []
 		end
 
-		# @private
-		def needs_cursor?
-			true
-		end
 
 		# Creates a new {Pen} that draws on self
 		#
-		# @see {Pen}
+		# @see Pen
 		#
 		# @param x [Fixnum] x-coordinate of starting position. Left is 0.
 		# @param y [Fixnum] y-coordinate of starting position. Top is 0.
 		# @param angle [Fixnum] Direction of pen in degree. 0 points to the right.
 		# @param color [Gosu::Color] Color of the pen
 		def new_pen(x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
-			Pen.new(self, x: x, y: y, angle: angle, color: color)
+			pen = Pen.new(x: x, y: y, angle: angle, color: color)
+			pens << pen
+			pen
 		end
 
-		# @private
-		def draw
-			shapes.each do |shape|
-				method,*args = shape
-				send method, *args
-			end
+		# Create a new {AnimationPen} that draws something different each frame
+		#
+		# @see AnimationPen
+		#
+		# @param (see #new_pen)
+		def new_animation_pen(x: 0, y: 0, angle: 0, color: Gosu::Color::GREEN)
+			pen = AnimationPen.new(x: x, y: y, angle: angle, color: color)
+			pens << pen
+			pen
 		end
 
-		# @private
-		def update
-			if button_down? Gosu::KbEscape
-				close
+		private
+			# Makes gosu display the system mouse cursor
+			def needs_cursor?
+				true
+			end
+
+			# Gosu hook method for drawing window content
+			def draw
+				pens.map(&:shapes).each do |shapes|
+					shapes.each do |shape|
+						method,*args = shape
+						send method, *args
+					end
+				end
+			end
+
+			# Gosu hook method for updating game state before drawing
+			# This is called once per frame
+			def update
+				pens.each &:update
+				if button_down? Gosu::KbEscape
+					close
+				end
 			end
-		end
 	end
 end

data/test/edu_draw/animation_pen_test.rb

@@ -0,0 +1,16 @@
+require_relative "../test_helper"
+module EduDraw
+	class AnimationPenTest < Minitest::Unit::TestCase
+		include BasicPenTests
+
+		def setup
+			@pen = AnimationPen.new(x: 10, y: 20, angle: 25, color: Gosu::Color::BLACK)
+		end
+
+		def test_update_removes_shapes
+			pen_shapes << Object.new
+			@pen.send :update
+			assert_empty pen_shapes
+		end
+	end
+end

data/test/edu_draw/basic_pen_tests.rb

@@ -0,0 +1,71 @@
+module EduDraw
+	module BasicPenTests
+		def pen_shapes
+			@pen.instance_variable_get :@shapes
+		end
+
+		def test_initialize
+			assert_equal 10, @pen.x
+			assert_equal 20, @pen.y
+			assert_equal 25, @pen.angle
+			assert_equal Gosu::Color::BLACK, @pen.color
+		end
+
+		def test_move
+			@pen.move 100
+			expected_x = 10 + Math.cos(25 * Math::PI / 180.0) * 100
+			expected_y = 20 + Math.sin(25 * Math::PI / 180.0) * 100
+			assert_equal expected_x, @pen.x 						# x changed
+			assert_equal expected_y, @pen.y 						# y changed
+			assert_equal 25, @pen.angle 							  # angle unchanged
+			assert_equal Gosu::Color::BLACK, @pen.color # color unchanged
+		end
+
+		def test_doesnt_draws_when_up
+			@pen.up!
+			@pen.move 100
+			assert_empty pen_shapes
+		end
+
+		def test_up_and_down
+			assert @pen.down?
+			refute @pen.up?
+
+			@pen.up!
+			assert @pen.up?
+			refute @pen.down?
+
+			@pen.down!
+			assert @pen.down?
+			refute @pen.up?
+		end
+
+		def test_turning
+			assert_equal 25, @pen.angle
+
+			@pen.turn_left 25
+			assert_equal 0, @pen.angle
+
+			@pen.turn_left 10
+			assert_equal 350, @pen.angle
+
+			@pen.turn_right 20
+			assert_equal 10, @pen.angle
+		end
+
+		def test_angle_in_rad
+			assert_equal 25 * Math::PI / 180.0, @pen.angle_in_rad
+		end
+
+		def test_area
+			assert_respond_to @pen, :fill
+			@pen.fill do
+				4.times do
+					@pen.move 10
+					@pen.turn_right 90
+				end
+			end
+			assert_equal 2, pen_shapes.length # 2 rectangles
+		end
+	end
+end

data/test/edu_draw/pen_test.rb

@@ -1,62 +1,16 @@
 require_relative "../test_helper"
 module EduDraw
 	class PenTest < Minitest::Unit::TestCase
-		def setup
-			@sheet_stub = stub shapes: []
-			@pen = Pen.new(@sheet_stub, x: 10, y: 20, angle: 25, color: Gosu::Color::BLACK)
-		end
-
-		def test_initialize
-			assert_equal 10, @pen.x
-			assert_equal 20, @pen.y
-			assert_equal 25, @pen.angle
-			assert_equal Gosu::Color::BLACK, @pen.color
-		end
-
-		def test_move
-			@pen.move 100
-			expected_x = 10 + Math.cos(25 * Math::PI / 180.0) * 100
-			expected_y = 20 + Math.sin(25 * Math::PI / 180.0) * 100
-			assert_equal expected_x, @pen.x 						# x changed
-			assert_equal expected_y, @pen.y 						# y changed
-			assert_equal 25, @pen.angle 							  # angle unchanged
-			assert_equal Gosu::Color::BLACK, @pen.color # color unchanged
-		end
-
-		def test_doesnt_draws_when_up
-			@sheet_stub.expects(:shapes).times(0)
-			@pen.up!
-			@pen.move 100
-		end
+		include BasicPenTests
 
-		def test_up_and_down
-			assert @pen.down?
-			refute @pen.up?
-
-			@pen.up!
-			assert @pen.up?
-			refute @pen.down?
-
-			@pen.down!
-			assert @pen.down?
-			refute @pen.up?
-		end
-
-		def test_turning
-			assert_equal 25, @pen.angle
-
-			@pen.turn_left 25
-			assert_equal 0, @pen.angle
-
-			@pen.turn_left 10
-			assert_equal 350, @pen.angle
-
-			@pen.turn_right 20
-			assert_equal 10, @pen.angle
+		def setup
+			@pen = Pen.new(x: 10, y: 20, angle: 25, color: Gosu::Color::BLACK)
 		end
 
-		def test_angle_in_rad
-			assert_equal 25 * Math::PI / 180.0, @pen.angle_in_rad
+		def test_update_does_not_remove_shapes
+			pen_shapes << Object.new
+			@pen.send :update
+			refute_empty pen_shapes
 		end
 	end
 end

data/test/edu_draw/sheet_test.rb

@@ -12,7 +12,7 @@ module EduDraw
 		end
 
 		def test_cursor_visible
-			assert @sheet.needs_cursor?
+			assert @sheet.send :needs_cursor?
 		end
 
 		def test_window
@@ -26,8 +26,14 @@ module EduDraw
 
 		def test_new_pen_creates_new_instance
 			Pen.expects(:new).once
+			AnimationPen.expects(:new).never
 			@sheet.new_pen
 		end
 
+		def test_new_animation_pen
+			AnimationPen.expects(:new).never
+			Pen.expects(:new).once
+			@sheet.new_animation_pen
+		end
 	end
 end

data/test/test_helper.rb

@@ -1,5 +1,10 @@
 require "minitest/autorun"
 require "minitest/mock"
+require "minitest/focus"
+
 require "mocha"
 require "mocha/mini_test"
+
+require_relative "edu_draw/basic_pen_tests.rb"
+
 require_relative "../lib/edu_draw"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: edu_draw
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Marvin Ede
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
 description: Simple object oriented API for opening a window and drawing in it. Based
   on gosu. It's meant to teach beginners programming as a visualization of code can
   help.
@@ -49,10 +63,15 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples/animations.rb
+- examples/areas.rb
 - examples/lines.rb
 - lib/edu_draw.rb
+- lib/edu_draw/animation_pen.rb
 - lib/edu_draw/pen.rb
 - lib/edu_draw/sheet.rb
+- test/edu_draw/animation_pen_test.rb
+- test/edu_draw/basic_pen_tests.rb
 - test/edu_draw/pen_test.rb
 - test/edu_draw/sheet_test.rb
 - test/test_helper.rb