minigl 1.3.10 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3638cd0876552f96b482a2b5986581916a27a5f9
-  data.tar.gz: a6e059c49297f45b360e225394b687bb2650a0a9
+  metadata.gz: f8b03d2bc58b9642caa459346389f4d8a9368bdf
+  data.tar.gz: a16bbf130daa7014e576450145ab8acd8db57aea
 SHA512:
-  metadata.gz: 2ac542ef6d3fe0140636b591b26336c23ed4b8fe1c7188c751f89e439a7099c2e0baaaff1e7fdae65f9d1529a73757792c9c147282e2f83418ac8e00254dad13
-  data.tar.gz: 68dbca5b83d9600c2d2b75c11b4c69aabd536a9a41722e0f1e1235af27e7bf195cad88809571770a9e91d61e025e777df13ed479dc8eb6e0f814c8e48d588530
+  metadata.gz: 7c5ca7adb1c4b297affa552ed1a7e1f7fc723c47e09172363e1049b0fb625247c1efd95d3961433fda7675ce9a8add42bc75c41decf930d1e6fdd01d2a892e13
+  data.tar.gz: 0400e96968260c4a45791ed85b9e37659f6bfcf0d267919b1fabd61e0bc222d5a1622f58395a2f6ecbb9428fb56274a47223c5a61ae5bb6a93f5a36746c27d44

data/README.md

@@ -26,16 +26,22 @@ After installing the gosu dependencies, you can just `gem install minigl`.
 Please note:
 
   * The test package is not complete! Most of the functionality
-provided by the gem is difficult to test automatically, but you can check out
-this [working game example](https://github.com/victords/aventura-do-saber).
-  * The RDoc documentation is now available.
+provided by the gem is difficult to test automatically, but you can check the
+examples provided with the gem.
+  * The library is 100% RDoc-documented.
   * An auxiliary, tutorial-like documentation is under construction
-[here](https://github.com/victords/minigl/wiki).
+[here](https://github.com/victords/minigl/wiki/How-To).
 
-**Version 1.3.10**
+**Version 2.0.0**
 
-  * Split the `center` parameter in `Button` and `ToggleButton` constructors
-into `center_x` and `center_y` (see doc. for details).
+MiniGL 2.0.0 is finally released!
 
-**P.S.** This version can cause incompatibility because of the parameter order
-in the constructors of `Button` and `ToggleButton`.
+It brings new features, improvements to existing features and some bug fixes.
+For details on what has changed, visit
+[the changelog](https://github.com/victords/minigl/wiki/Changelog-(2.0.0)).
+
+As the semantic versioning implies, **this version is incompatible with the 1.x
+series**, so you'll need to adjust your code a little if you wish to upgrade.
+
+A new tutorial has to be built, because there have been some changes even in the
+basics of the usage. So please be patient while it doesn't come out!

data/lib/minigl/forms.rb

@@ -1,9 +1,21 @@
 require_relative 'global'
 
-module AGL
+module MiniGL
   # This class is an abstract ancestor for all form components (Button,
   # ToggleButton and TextField).
   class Component
+    # The horizontal coordinate of the component
+    attr_reader :x
+
+    # The vertical coordinate of the component
+    attr_reader :y
+
+    # The width of the component
+    attr_reader :w
+
+    # The height of the component
+    attr_reader :h
+
     # Determines whether the control is enabled, i.e., will process user input.
     attr_accessor :enabled
 
@@ -32,6 +44,12 @@ module AGL
 
   # This class represents a button.
   class Button < Component
+    # The current state of the button.
+    attr_reader :state
+
+    # The text of the button.
+    attr_accessor :text
+
     # Creates a button.
     #
     # Parameters:
@@ -49,6 +67,10 @@ module AGL
     # [text_color] Color of the button text, in hexadecimal RRGGBB format.
     # [disabled_text_color] Color of the button text, when it's disabled, in
     #                       hexadecimal RRGGBB format.
+    # [over_text_color] Color of the button text, when the cursor is over it
+    #                   (hexadecimal RRGGBB).
+    # [down_text_color] Color of the button text, when it is pressed
+    #                   (hexadecimal RRGGBB).
     # [center_x] Whether the button text should be horizontally centered in its
     #            area (the area is defined by the image size, if an image is
     #            given, or by the +width+ and +height+ parameters, otherwise).
@@ -71,9 +93,11 @@ module AGL
     #          parameters.
     # [action] The block of code executed when the button is clicked (or by
     #          calling the +click+ method).
-    def initialize(x, y, font, text, img, text_color = 0, disabled_text_color = 0, center_x = true, center_y = true,
-                   margin_x = 0, margin_y = 0, width = nil, height = nil, params = nil, &action)
+    def initialize(x, y, font, text, img, text_color = 0, disabled_text_color = 0, over_text_color = 0, down_text_color = 0,
+                   center_x = true, center_y = true, margin_x = 0, margin_y = 0, width = nil, height = nil, params = nil, &action)
       super x, y, font, text, text_color, disabled_text_color
+      @over_text_color = over_text_color
+      @down_text_color = down_text_color
       @img =
         if img; Res.imgs img, 1, 4, true
         else; nil; end
@@ -175,7 +199,17 @@ module AGL
       return unless @visible
 
       color = (alpha << 24) | 0xffffff
-      text_color = (alpha << 24) | (@enabled ? @text_color : @disabled_text_color)
+      text_color =
+        if @enabled
+          if @state == :down
+            @down_text_color
+          else
+            @state == :over ? @over_text_color : @text_color
+          end
+        else
+          @disabled_text_color
+        end
+      text_color = (alpha << 24) | text_color
       @img[@img_index].draw @x, @y, z_index, 1, 1, color if @img
       if @text
         if @center_x or @center_y
@@ -215,9 +249,10 @@ module AGL
     #     puts "button was checked" if checked
     #     # do something with params
     #   }
-    def initialize(x, y, font, text, img, checked = false, text_color = 0, disabled_text_color = 0, center_x = true, center_y = true,
-                   margin_x = 0, margin_y = 0, width = nil, height = nil, params = nil, &action)
-      super x, y, font, text, nil, text_color, disabled_text_color, center_x, center_y, margin_x, margin_y, width, height, params, &action
+    def initialize(x, y, font, text, img, checked = false, text_color = 0, disabled_text_color = 0, over_text_color = 0, down_text_color = 0,
+                   center_x = true, center_y = true, margin_x = 0, margin_y = 0, width = nil, height = nil, params = nil, &action)
+      super x, y, font, text, nil, text_color, disabled_text_color, over_text_color, down_text_color,
+            center_x, center_y, margin_x, margin_y, width, height, params, &action
       @img =
         if img; Res.imgs img, 2, 4, true
         else; nil; end
@@ -271,6 +306,10 @@ module AGL
     # The current text inside the text field.
     attr_reader :text
 
+    # The current 'locale' used for detecting the keys. THIS FEATURE IS
+    # INCOMPLETE!
+    attr_reader :locale
+
     # Creates a new text field.
     #
     # Parameters:
@@ -306,6 +345,10 @@ module AGL
     # [selection_color] The color of the rectangle highlighting selected text,
     #                   in hexadecimal RRGGBB format. The rectangle will
     #                   always be drawn with 50% of opacity.
+    # [locale] The locale to be used when detecting keys. By now, only 'en-US'
+    #          and 'pt-BR' are **partially** supported. Default is 'en-US'. If
+    #          any different value is supplied, all typed characters will be
+    #          mapped to '#'.
     # [params] An object containing any parameters you want passed to the
     #          +on_text_changed+ block. When the text of the text field is
     #          changed, the following is called:
@@ -317,7 +360,7 @@ module AGL
     #                   +text=+. The new text is passed as a first parameter
     #                   to this block, followed by +params+. Can be +nil+.
     def initialize(x, y, font, img, cursor_img = nil, disabled_img = nil, margin_x = 0, margin_y = 0, max_length = 100, active = false, text = '',
-                   allowed_chars = nil, text_color = 0, disabled_text_color = 0, selection_color = 0, params = nil, &on_text_changed)
+                   allowed_chars = nil, text_color = 0, disabled_text_color = 0, selection_color = 0, locale = 'en-us', params = nil, &on_text_changed)
       super x, y, font, text, text_color, disabled_text_color
       @img = Res.img img
       @w = @img.width
@@ -348,16 +391,13 @@ module AGL
         Gosu::KbDelete, Gosu::KbLeft, Gosu::KbRight, Gosu::KbHome,
         Gosu::KbEnd, Gosu::KbLeftShift, Gosu::KbRightShift,
         Gosu::KbBacktick, Gosu::KbMinus, Gosu::KbEqual, Gosu::KbBracketLeft,
-        Gosu::KbBracketRight, Gosu::KbBackslash, Gosu::KbApostrophe,
-        Gosu::KbComma, Gosu::KbPeriod, Gosu::KbSlash
+        Gosu::KbBracketRight, Gosu::KbBackslash, Gosu::KbSemicolon,
+        Gosu::KbApostrophe, Gosu::KbComma, Gosu::KbPeriod, Gosu::KbSlash,
+        Gosu::KbNumpadAdd, Gosu::KbNumpadSubtract,
+        Gosu::KbNumpadMultiply, Gosu::KbNumpadDivide
       ]
-      @chars = "abcdefghijklmnopqrstuvwxyz1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ'-=/[]\\,.;\"_+?{}|<>:!@#$%¨&*()"
-      @allowed_chars =
-        if allowed_chars
-          allowed_chars
-        else
-          @chars
-        end
+      @user_allowed_chars = allowed_chars
+      self.locale = locale
 
       @on_text_changed = on_text_changed
       @params = params
@@ -430,10 +470,10 @@ module AGL
               insert_char @chars[i]
             end
           elsif i < 36
-            if shift; insert_char @chars[i + 57]
+            if shift; insert_char @chars[i + 59]
             else; insert_char @chars[i]; end
           elsif shift
-            insert_char(@chars[i + 47])
+            insert_char(@chars[i + 49])
           else
             insert_char(@chars[i - 10])
           end
@@ -443,15 +483,26 @@ module AGL
       end
 
       return if inserted
-      for i in 55..64 # special
+      for i in 55..65 # special
         if KB.key_pressed?(@k[i]) or KB.key_held?(@k[i])
-          if shift; insert_char @chars[i + 18]
+          remove_interval true if @anchor1 and @anchor2
+          if shift; insert_char @chars[i + 19]
           else; insert_char @chars[i + 8]; end
           inserted = true
           break
         end
       end
 
+      return if inserted
+      for i in 66..69 # numpad operators
+        if KB.key_pressed?(@k[i]) or KB.key_held?(@k[i])
+          remove_interval true if @anchor1 and @anchor2
+          insert_char @chars[i + 19]
+          inserted = true
+          break
+        end
+      end
+
       return if inserted
       if KB.key_pressed?(@k[47]) or KB.key_held?(@k[47]) # back
         if @anchor1 and @anchor2
@@ -541,6 +592,25 @@ module AGL
       @on_text_changed.call @text, @params if @on_text_changed
     end
 
+    # Sets the locale used by the text field to detect keys. Only 'en-us' and
+    # 'pt-br' are **partially** supported. If any different value is supplied,
+    # all typed characters will be mapped to '#'.
+    def locale=(value)
+      @locale = value.downcase
+      @chars =
+          case @locale
+            when 'en-us' then "abcdefghijklmnopqrstuvwxyz1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ`-=[]\\;',./~_+{}|:\"<>?!@#$%^&*()+-*/"
+            when 'pt-br' then "abcdefghijklmnopqrstuvwxyz1234567890 ABCDEFGHIJKLMNOPQRSTUVWXYZ'-=/[]ç~,.;\"_+?{}Ç^<>:!@#$%¨&*()+-*/"
+            else              '###################################################################################################'
+          end
+      @allowed_chars =
+          if @user_allowed_chars
+            @user_allowed_chars
+          else
+            @chars
+          end
+    end
+
     # Returns the currently selected text.
     def selected_text
       return '' if @anchor2.nil?
@@ -597,10 +667,10 @@ module AGL
 
       if @anchor1 and @anchor2
         selection_color = ((alpha / 2) << 24) | @selection_color
-        Game.window.draw_quad @nodes[@anchor1], @text_y, selection_color,
-                              @nodes[@anchor2] + 1, @text_y, selection_color,
-                              @nodes[@anchor2] + 1, @text_y + @font.height, selection_color,
-                              @nodes[@anchor1], @text_y + @font.height, selection_color, z_index
+        G.window.draw_quad @nodes[@anchor1], @text_y, selection_color,
+                           @nodes[@anchor2] + 1, @text_y, selection_color,
+                           @nodes[@anchor2] + 1, @text_y + @font.height, selection_color,
+                           @nodes[@anchor1], @text_y + @font.height, selection_color, z_index
       end
 
       if @cursor_visible
@@ -608,10 +678,10 @@ module AGL
           @cursor_img.draw @nodes[@cur_node] - @cursor_img.width / 2, @text_y, z_index
         else
           cursor_color = alpha << 24
-          Game.window.draw_quad @nodes[@cur_node], @text_y, cursor_color,
-                                @nodes[@cur_node] + 1, @text_y, cursor_color,
-                                @nodes[@cur_node] + 1, @text_y + @font.height, cursor_color,
-                                @nodes[@cur_node], @text_y + @font.height, cursor_color, z_index
+          G.window.draw_quad @nodes[@cur_node], @text_y, cursor_color,
+                             @nodes[@cur_node] + 1, @text_y, cursor_color,
+                             @nodes[@cur_node] + 1, @text_y + @font.height, cursor_color,
+                             @nodes[@cur_node], @text_y + @font.height, cursor_color, z_index
         end
       end
     end
@@ -668,7 +738,7 @@ module AGL
         interval_width += @font.text_width(@text[i])
         @nodes.delete_at min + 1
       end
-      @text[min...max] = ""
+      @text[min...max] = ''
       for i in (min + 1)..(@nodes.size - 1)
         @nodes[i] -= interval_width
       end
@@ -691,4 +761,286 @@ module AGL
       @on_text_changed.call @text, @params if @on_text_changed
     end
   end
+
+  # Represents a progress bar.
+  class ProgressBar < Component
+    # The maximum value for this progress bar (when the current value equals
+    # the maximum, the bar is full).
+    attr_reader :max_value
+
+    # The current value of the progress bar (an integer greater than or equal
+    # to zero, and less than or equal to +max_value+).
+    attr_reader :value
+
+    # Creates a progress bar.
+    #
+    # Parameters:
+    # [x] The x-coordinate of the progress bar on the screen.
+    # [y] The y-coordinate of the progress bar on the screen.
+    # [w] Width of the progress bar, in pixels. This is the maximum space the
+    #     bar foreground can occupy. Note that the width of the foreground image
+    #     (+fg+) can be less than this.
+    # [h] Height of the progress bar. This will be the height of the bar
+    #     foreground when +fg+ is a color (when it is an image, the height of
+    #     the image will be kept).
+    # [bg] A background image (string or symbol that will be passed to
+    #      +Res.img+) or color (in RRGGBB hexadecimal format).
+    # [fg] A foreground image (string or symbol that will be passed to
+    #      +Res.img+) or color (in RRGGBB hexadecimal format). The image will
+    #      be horizontally repeated when needed, if its width is less than +w+.
+    # [max_value] The maximum value the progress bar can reach (an integer).
+    # [value] The starting value for the progress bar.
+    # [fg_margin_x] Horizontal margin between the background image and the
+    #               foreground image (when these are provided).
+    # [fg_margin_y] Vertical margin between the background image and the
+    #               foreground image (when these are provided).
+    # [font] Font that will be used to draw a text indicating the value of the
+    #        progress bar.
+    # [text_color] Color of the text.
+    # [format] Format to display the value. Specify '%' for a percentage and
+    #          anything else for absolute values (current/maximum).
+    def initialize(x, y, w, h, bg, fg, max_value = 100, value = 100, fg_margin_x = 0, fg_margin_y = 0, #fg_left = nil, fg_right = nil,
+                   font = nil, text_color = 0, format = nil)
+      super x, y, font, '', text_color, text_color
+      @w = w
+      @h = h
+      if bg.is_a? Integer
+        @bg_color = bg
+      else # String or Symbol
+        @bg = Res.img bg
+      end
+      if fg.is_a? Integer
+        @fg_color = fg
+      else # String or Symbol
+        @fg = Res.img fg
+        @fg_path = "#{Res.prefix}img/#{fg.to_s.gsub('_', '/')}.png"
+        puts @fg_path
+      end
+      @fg_margin_x = fg_margin_x
+      @fg_margin_y = fg_margin_y
+      # @fg_left = fg_left
+      # @fg_right = fg_right
+      @max_value = max_value
+      self.value = value
+      @format = format
+    end
+
+    # Increases the current value of the progress bar by the given amount.
+    #
+    # Parameters:
+    # [amount] (+Integer+) The amount to be added to the current value. If the
+    #          sum surpasses +max_value+, it is set to +max_value+.
+    def increase(amount)
+      @value += amount
+      @value = @max_value if @value > @max_value
+    end
+
+    # Descreases the current value of the progress bar by the given amount.
+    #
+    # Parameters:
+    # [amount] (+Integer+) The amount to be subtracted from the current value.
+    #          If the result is less than zero, it is set to zero.
+    def decrease(amount)
+      @value -= amount
+      @value = 0 if @value < 0
+    end
+
+    # Sets the value of the progress bar.
+    #
+    # Parameters:
+    # [val] (+Integer+) The value to be set. It will be changed as needed to be
+    #       between zero and +max_value+.
+    def value=(val)
+      @value = val
+      if @value > @max_value
+        @value = @max_value
+      elsif @value < 0
+        @value = 0
+      end
+    end
+
+    # Sets the value of the progress bar to a given percentage of +max_value+.
+    #
+    # Parameters:
+    # [pct] (+Numeric+) The percentage of +max_value+ to set the current value
+    #       to. The final result will be changed as needed to be between zero
+    #       and +max_value+.
+    def percentage=(pct)
+      self.value = (pct * @max_value).round
+    end
+
+    # Draws the progress bar.
+    #
+    # Parameters:
+    # [alpha] (+Fixnum+) The opacity with which the progress bar will be drawn.
+    #         Allowed values vary between 0 (fully transparent) and 255 (fully
+    #         opaque).
+    # [z_index] (+Fixnum+) The z-order to draw the object. Objects with larger
+    #           z-orders will be drawn on top of the ones with smaller z-orders.
+    def draw(alpha = 0xff, z_index = 0)
+      return unless @visible
+
+      if @bg
+        c = (alpha << 24) | 0xffffff
+        @bg.draw @x, @y, z_index, 1, 1, c
+      else
+        c = (alpha << 24) | @bg_color
+        G.window.draw_quad @x, @y, c,
+                           @x + @w, @y, c,
+                           @x + @w, @y + @h, c,
+                           @x, @y + @h, c, z_index
+      end
+      if @fg
+        c = (alpha << 24) | 0xffffff
+        w1 = @fg.width
+        w2 = (@value.to_f / @max_value * @w).round
+        x0 = @x + @fg_margin_x
+        x = 0
+        while x <= w2 - w1
+          @fg.draw x0 + x, @y + @fg_margin_y, z_index, 1, 1, c
+          x += w1
+        end
+        if w2 - x > 0
+          img = Gosu::Image.new(G.window, @fg_path, true, 0, 0, w2 - x, @fg.height)
+          img.draw x0 + x, @y + @fg_margin_y, z_index, 1, 1, c
+        end
+      else
+        c = (alpha << 24) | @fg_color
+        rect_r = @x + (@value.to_f / @max_value * @w).round
+        G.window.draw_quad @x, @y, c,
+                           rect_r, @y, c,
+                           rect_r, @y + @h, c,
+                           @x, @y + @h, c, z_index
+      end
+      if @font
+        c = (alpha << 24) | @text_color
+        @text = @format == '%' ? "#{(@value.to_f / @max_value * 100).round}%" : "#{@value}/#{@max_value}"
+        @font.draw_rel @text, @x + @fg_margin_x + @w / 2, @y + @fg_margin_y + @h / 2, 0, 0.5, 0.5, 1, 1, c
+      end
+    end
+  end
+
+  # This class represents a "drop-down list" form component, here composed of a
+  # group of +Button+ objects.
+  class DropDownList < Component
+    # The selected value in the drop-down list. This is one of the +options+.
+    attr_reader :value
+
+    # An array containing all the options (each of them +String+s) that can be
+    # selected in the drop-down list.
+    attr_accessor :options
+
+    # Creates a new drop-down list.
+    #
+    # Parameters:
+    # [x] The x-coordinate of the object.
+    # [y] The y-coordinate of the object.
+    # [font] Font to be used by the buttons that compose the drop-donwn list.
+    # [img] Image of the main button, i.e., the one at the top, that toggles
+    #       visibility of the other buttons (the "option" buttons).
+    # [opt_img] Image for the "option" buttons, as described above.
+    # [options] Array of available options for this control (+String+s).
+    # [option] Index of the firstly selected option.
+    # [text_margin] Left margin of the text inside the buttons (vertically, the
+    #               text will always be centered).
+    # [width] Width of the control, used when no image is provided.
+    # [height] Height of the control, used when no image is provided.
+    # [text_color] Used as the +text_color+ parameter in the constructor of the
+    #              buttons.
+    # [disabled_text_color] Analogous to +text_color+.
+    # [over_text_color] Same as above.
+    # [down_text_color] Same as above.
+    def initialize(x, y, font, img, opt_img, options, option = 0, text_margin = 0, width = nil, height = nil,
+                   text_color = 0, disabled_text_color = 0, over_text_color = 0, down_text_color = 0)
+      super x, y, font, options[option], text_color, disabled_text_color
+      @img = img
+      @opt_img = opt_img
+      @options = options
+      @value = @options[option]
+      @open = false
+      @buttons = []
+      @buttons.push(
+        Button.new(x, y, font, @value, img, text_color, disabled_text_color, over_text_color, down_text_color,
+                   false, true, text_margin, 0, width, height) {
+                     toggle
+                   }
+      )
+      @w = @buttons[0].w
+      @h = @buttons[0].h
+      @options.each_with_index do |o, i|
+        b = Button.new(x, y + (i+1) * @h, font, o, opt_img, text_color, disabled_text_color, over_text_color, down_text_color,
+                       false, true, text_margin, 0, @w, @h) {
+                         @value = @buttons[0].text = o
+                         toggle
+                       }
+        b.visible = false
+        @buttons.push b
+      end
+      @max_h = (@options.size + 1) * @h
+    end
+
+    # Updates the control.
+    def update
+      return unless @enabled and @visible
+      if @open and Mouse.button_pressed? :left and not Mouse.over?(@x, @y, @w, @max_h)
+        toggle
+        return
+      end
+      @buttons.each { |b| b.update }
+    end
+
+    # Sets the currently selected value of the drop-down list. It is ignored if
+    # it is not among the available options.
+    def value=(val)
+      if @options.include? val
+        @value = @buttons[0].text = val
+      end
+    end
+
+    def enabled=(value) # :nodoc:
+      toggle if @open
+      @buttons[0].enabled = value
+      @enabled = value
+    end
+
+    # Draws the drop-down list.
+    #
+    # Parameters:
+    # [alpha] (+Fixnum+) The opacity with which the drop-down list will be
+    #         drawn. Allowed values vary between 0 (fully transparent) and 255
+    #         (fully opaque).
+    # [z_index] (+Fixnum+) The z-order to draw the object. Objects with larger
+    #           z-orders will be drawn on top of the ones with smaller z-orders.
+    def draw(alpha = 0xff, z_index = 0)
+      return unless @visible
+      unless @img
+        bottom = @open ? @y + @max_h + 1 : @y + @h + 1
+        b_color = (alpha << 24)
+        G.window.draw_quad @x - 1, @y - 1, b_color,
+                           @x + @w + 1, @y - 1, b_color,
+                           @x + @w + 1, bottom, b_color,
+                           @x - 1, bottom, b_color, z_index
+        @buttons.each do |b|
+          color = (alpha << 24) | (b.state == :over ? 0xcccccc : 0xffffff)
+          G.window.draw_quad b.x, b.y, color,
+                             b.x + b.w, b.y, color,
+                             b.x + b.w, b.y + b.h, color,
+                             b.x, b.y + b.h, color, z_index if b.visible
+        end
+      end
+      @buttons.each { |b| b.draw alpha, z_index }
+    end
+
+    private
+
+    def toggle
+      if @open
+        @buttons[1..-1].each { |b| b.visible = false }
+        @open = false
+      else
+        @buttons[1..-1].each { |b| b.visible = true }
+        @open = true
+      end
+    end
+  end
 end