#--
#  This file is one part of:
#  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
#
#  Copyright (C) 2008  John Croisant
#
#  This library is free software; you can redistribute it and/or
#  modify it under the terms of the GNU Lesser General Public
#  License as published by the Free Software Foundation; either
#  version 2.1 of the License, or (at your option) any later version.
#
#  This library is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#  Lesser General Public License for more details.
#
#  You should have received a copy of the GNU Lesser General Public
#  License along with this library; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
# ++


module Rubygame

  module Events

    # 
    # KeyboardEvent is a mixin module included in the KeyPressed
    # and KeyReleased classes. It defines the #key and #modifiers
    # accessors.
    # 
    module KeyboardEvent
      attr_reader :key, :modifiers

      # 
      # Initialize the KeyboardEvent.
      # 
      # key::       a key symbol for the key that was pressed or
      #             released. (Symbol, required)
      # 
      # modifiers:: an Array of key symbols for the modifier keys
      #             that were active when the event occured.
      #             (Array, optional)
      # 
      def initialize( key, modifiers=[] )

        unless key.kind_of? Symbol
          raise ArgumentError, "key must be a :symbol"
        end

        @key = key

        @modifiers = modifiers.to_ary.dup
        @modifiers.freeze

      end
    end


    # 
    # KeyPressed is an event class which occurs when a key
    # on the keyboard is pressed down. 
    # 
    # This class gains #key and #modifiers readers from
    # the KeyboardEvent mixin module.
    # 
    # It also has #string, which is a UTF8 string containing
    # the text character that was generated by the keystroke;
    # if nothing was generated, #string will be the empty string,
    # "". 
    # 
    # The #string attribute is useful for for taking text input
    # (e.g. in a GUI). It supports UTF8 Unicode characters, and
    # works correctly on many different types of keyboards.
    # 
    class KeyPressed
      include KeyboardEvent

      attr_reader :string

      # 
      # Create a new KeyPressed instance.
      # 
      # key::       a key symbol for the key that was pressed or
      #             released. (Symbol, required)
      # 
      # modifiers:: an Array of key symbols for the modifier keys
      #             that were active when the event occured.
      #             (Array, optional)
      # 
      # string::    a String containing the text character that
      #             was generated by the keystroke, or "" if
      #             nothing was generated. (String, optional)
      # 
      def initialize( key, modifiers=[], string="" )
        super( key, modifiers )

        @string = string.to_str.dup
        @string.freeze

      end
    end


    # 
    # KeyReleased is an event class which occurs when a key
    # on the keyboard is released (no longer being pressed).
    # 
    # This class gains #key and #modifiers readers from
    # the KeyboardEvent mixin module.
    # 
    class KeyReleased
      include KeyboardEvent

      # 
      # Create a new KeyReleased instance.
      # 
      # key::       a key symbol for the key that was pressed or
      #             released. (Symbol, required)
      # 
      # modifiers:: an Array of key symbols for the modifier keys
      #             that were active when the event occured.
      #             (Array, optional)
      # 
      def initialize( key, modifiers=[] )
        super
      end

    end

  end
end
