diff --git a/docs/examples/app.rb b/docs/examples/app.rb new file mode 100644 index 000000000..caa70c523 --- /dev/null +++ b/docs/examples/app.rb @@ -0,0 +1,2 @@ +Shoes.app(title: "Shoes", width: 600, height: 600,resizable: false) do +end diff --git a/docs/examples/background.rb b/docs/examples/background.rb new file mode 100644 index 000000000..0d9bed94d --- /dev/null +++ b/docs/examples/background.rb @@ -0,0 +1,3 @@ +Shoes.app(title: "Shoes", width: 600, height: 600,resizable: false) do + background "purple" +end diff --git a/docs/examples/border.rb b/docs/examples/border.rb new file mode 100644 index 000000000..0401122c5 --- /dev/null +++ b/docs/examples/border.rb @@ -0,0 +1,3 @@ +Shoes.app(title: "Shoes", width: 600, height: 600,resizable: false) do + border red, strokewidth: 6000 +end diff --git a/docs/examples/editline.rb b/docs/examples/editline.rb new file mode 100644 index 000000000..7d8ee492d --- /dev/null +++ b/docs/examples/editline.rb @@ -0,0 +1,3 @@ +Shoes.app do + edit_line "Hello" +end diff --git a/lacci/lib/shoes/app.rb b/lacci/lib/shoes/app.rb index 232347110..acc1c7dbf 100644 --- a/lacci/lib/shoes/app.rb +++ b/lacci/lib/shoes/app.rb @@ -1,6 +1,7 @@ # frozen_string_literal: true module Shoes + # The main class for creating Shoes applications. class App < Shoes::Drawable include Shoes::Log @@ -8,12 +9,18 @@ class << self attr_accessor :instance end + # @return [Object] The root of the document for this application. attr_reader :document_root shoes_styles :title, :width, :height, :resizable CUSTOM_EVENT_LOOP_TYPES = ["displaylib", "return", "wait"] + # @param title [String] The title of the application window. + # @param width [Integer] The width of the application window. + # @param height [Integer] The height of the application window. + # @param resizable [Boolean] Set to `true` to allow window resizing. + # @see https://github.com/scarpe-team/scarpe/tree/main/docs/examples/app.rb def initialize( title: "Shoes!", width: 480, @@ -23,6 +30,9 @@ def initialize( ) log_init("Shoes::App") + # Initializes the Shoes application. + + # Checks if another Shoes::App instance already exists in the same process. if Shoes::App.instance @log.error("Trying to create a second Shoes::App in the same process! Fail!") raise Scarpe::TooManyInstancesError, "Cannot create multiple Shoes::App objects!" @@ -41,6 +51,7 @@ def initialize( @draw_context = { "fill" => "", "stroke" => "", + "rotate" => 0, } # This creates the DocumentRoot, including its corresponding display drawable @@ -95,7 +106,9 @@ def initialize( end end + # Initializes the application. def init + # Sends the "init" event. send_shoes_event(event_name: "init") return if @do_shutdown @@ -105,20 +118,26 @@ def init # "Container" drawables like flows, stacks, masks and the document root # are considered "slots" in Shoes parlance. When a new slot is created, # we push it here in order to track what drawables are found in that slot. + # Pushes a new slot onto the stack. def push_slot(slot) + # Pushes a new slot onto the stack. @slots.push(slot) end + # Pops the last slot from the slots stack. def pop_slot return if @slots.size <= 1 @slots.pop end + # Returns the current slot. + # @return [Drawable] The current slot. def current_slot @slots[-1] end + # Executes a block within a specific slot. def with_slot(slot_item, &block) return unless block_given? @@ -128,6 +147,8 @@ def with_slot(slot_item, &block) pop_slot end + # Returns a copy of the current drawing context. + # @return [Hash] The current drawing context. def current_draw_context @draw_context.dup end @@ -161,11 +182,15 @@ def run end end + # Signals the application to destroy itself. + # @param send_event [Boolean] Set to `true` to send a "destroy" event. def destroy(send_event: true) @do_shutdown = true send_shoes_event(event_name: "destroy") if send_event end + # Retrieves all drawables within the application. + # @return [Array] An array of all drawables in the application. def all_drawables out = [] @@ -180,6 +205,8 @@ def all_drawables # We can add various ways to find drawables here. # These are sort of like Shoes selectors, used for testing. + # @param specs [Array] An array of criteria for finding drawables. + # @return [Array] An array of drawables that match the criteria. def find_drawables_by(*specs) drawables = all_drawables specs.each do |spec| @@ -215,43 +242,45 @@ def find_drawables_by(*specs) # DSL methods class Shoes::App + # Sets the background of the current slot. def background(...) current_slot.background(...) end + # Sets the border of the current slot. def border(...) current_slot.border(...) end - # Event handler objects - + # Defines event handler methods for various events. events = [:motion, :hover, :leave, :click, :release, :keypress, :animate, :every, :timer] events.each do |event| define_method(event) do |*args, &block| subscription_item(args:, shoes_api_name: event.to_s, &block) end end - # Draw context methods - + # Sets the fill color in the drawing context. def fill(color) @draw_context["fill"] = color end + # Clears the fill color in the drawing context. def nofill @draw_context["fill"] = "" end + # Sets the stroke color in the drawing context. def stroke(color) @draw_context["stroke"] = color end + # Clears the stroke color in the drawing context. def nostroke @draw_context["stroke"] = "" end - # Shape DSL methods - + # Moves the current slot to the specified coordinates. def move_to(x, y) raise(InvalidAttributeValueError, "Pass only Numeric arguments to move_to!") unless x.is_a?(Numeric) && y.is_a?(Numeric) @@ -260,6 +289,7 @@ def move_to(x, y) end end + # Draws a line from the current position to the specified coordinates. def line_to(x, y) raise(InvalidAttributeValueError, "Pass only Numeric arguments to line_to!") unless x.is_a?(Numeric) && y.is_a?(Numeric) @@ -268,7 +298,13 @@ def line_to(x, y) end end + # Rotates the current slot by the specified angle. + def rotate(angle) + @draw_context["rotate"] = angle + end + # Not implemented yet: curve_to, arc_to + # Outputs information to the console. alias_method :info, :puts end diff --git a/lacci/lib/shoes/background.rb b/lacci/lib/shoes/background.rb index 6e05097d8..453011c4f 100644 --- a/lacci/lib/shoes/background.rb +++ b/lacci/lib/shoes/background.rb @@ -1,12 +1,23 @@ # frozen_string_literal: true module Shoes + # The `Background` module provides functionality for setting the background color module Background + # @param includer [Class] The class including this module. def self.included(includer) includer.shoes_style(:background_color) end - # NOTE: this needs to be passed through in order for the styling to work + # Set the background color of the object to the specified color. + # + # @param color [String] The background color to set. This should be a valid color representation, such as a color name (e.g., "red") or a hex code (e.g., "#FF0000"). + # @param options [Hash] (optional) Additional options for setting the background. + # @option options [Any] :option_name A description of an optional parameter. + # + # @return [void] + # + # @see https://github.com/scarpe-team/scarpe/tree/main/docs/examples/background.rb + # NOTE: This method needs to be called in order for the styling to work properly. def background(color, options = {}) self.background_color = color end diff --git a/lacci/lib/shoes/border.rb b/lacci/lib/shoes/border.rb index c7305c918..769dff661 100644 --- a/lacci/lib/shoes/border.rb +++ b/lacci/lib/shoes/border.rb @@ -1,13 +1,22 @@ # frozen_string_literal: true module Shoes + # The `Border` module provides methods for defining border styles in a Shoes-based application. module Border + # This class method is automatically invoked when the `Border` module is included in another class or module. + # It sets up the styles for border color and options. + # + # @param includer [Class] The class or module that includes the `Border` module. def self.included(includer) includer.shoes_styles :border_color, :options end - # Considering a signature like this: - # border "#00D0FF", :strokewidth => 3, :curve => 12 + # Set the border style for an element. + # + # @param color [String] The color of the border. + # @param options [Hash] (optional) A hash of options for customizing the border style. + # + # @see https://github.com/scarpe-team/scarpe/tree/main/docs/examples/border.rb def border(color, options = {}) self.border_color = color self.options = options diff --git a/lacci/lib/shoes/drawables/edit_line.rb b/lacci/lib/shoes/drawables/edit_line.rb index e7efe5b76..a761637a5 100644 --- a/lacci/lib/shoes/drawables/edit_line.rb +++ b/lacci/lib/shoes/drawables/edit_line.rb @@ -1,22 +1,38 @@ # frozen_string_literal: true module Shoes + # The `EditLine` class represents an editable text input field in a Shoes application. + # @see https://github.com/scarpe-team/scarpe/tree/main/docs/examples/editline.rb + class EditLine < Shoes::Drawable + # Sets the styles for text content and width. shoes_styles :text, :width + # Initializes a new `EditLine` instance. + # + # @param text [String] The initial text content of the EditLine. + # @param width [Integer] (optional) The width of the EditLine in pixels. + # @yield [new_text] Optional block to be executed when the text content changes. + # @yieldparam new_text [String] The new text content of the EditLine. def initialize(text = "", width: nil, &block) super @block = block @text = text + # Binds a "change" event to the EditLine, which triggers when the text content changes. bind_self_event("change") do |new_text| self.text = new_text @block&.call(new_text) end + # Creates the display drawable for the EditLine. create_display_drawable end + # Sets a block to be executed when the text content changes. + # + # @yield [new_text] Block to be executed when the text content changes. + # @yieldparam new_text [String] The new text content of the EditLine. def change(&block) @block = block end