indexing

	description: "[

		Class for direct access to a snapshot of the keyboard state
		and possibilities to customize the publishing of keyboard events.
		
		For getting information about pressed keys better use EM_KEYBOARD_EVENT
		(see `key_down_event' and `key_up_event' in EM_EVENT_LOOP),
		this class should only be used for customizing keyboard event publishing
		or if absolutly necessary to have direct access to all keys.

	]"
	date: "$Date$"
	revision: "$Revision$"

class EM_KEYBOARD

inherit

	SDLKEY_ENUM_EXTERNAL
		rename
			is_valid_enum as is_valid_key
		end

	SDL_KEYBOARD_FUNCTIONS
		export {NONE} all end

	EM_SHARED_ERROR_HANDLER
		export {NONE} all end

create

	make_snapshot

feature -- Creation

	make_snapshot is
			-- Create snapshot of current keyboard state.
		local
			p: POINTER
		do
			p := sdl_get_key_state (Default_pointer)
			create keyboard_state.make_shared (p, sdlk_last)
		end

feature -- Status report

	is_unicode_characters_enabled: BOOLEAN is
			-- Is receiving of `unicode_character' for keys in keyboard events enabled?
		do
			Result := sdl_enable_unicode (-1) = 1
		end

feature -- Status setting

	enable_unicode_characters is
			-- Enable receiving of `unicode_character' for keys in keyboard events.
			-- Fetching unicode characters incurs a slight overhead for each keyboard event
			-- and should therefore only be enabled if absolutly necessary (i.e. for textual input).
		local
			tmp: INTEGER
		do
			-- sdl_enable_unicode returns current mode. So to test success, a query has to be done
			tmp := sdl_enable_unicode (1)
			tmp := sdl_enable_unicode (-1)
			if tmp /= 1 then
				Error_handler.raise_warning (Error_handler.Em_error_enable_unicode, [])
			end
		end

	disable_unicode_characters is
			-- Disable receiving of `unicode_character' in EM_KEYBOARD_EVENTs.
		local
			tmp: INTEGER
		do
			-- sdl_enable_unicode returns current mode. So to test success, a query has to be done
			tmp := sdl_enable_unicode (0)
			tmp := sdl_enable_unicode (-1)
			if tmp /= 0 then
				Error_handler.raise_warning (Error_handler.Em_error_disable_unicode, [])
			end
		end

feature -- Basic operations

	enable_repeating_key_down_events (delay: INTEGER; interval: INTEGER) is
			-- Enable repeating key down events,
			-- when the user keeps pressing a key
			-- for more than `delay' milliseconds.
			-- Key down events will then occur every `interval' milliseconds
			-- as long as the user keeps a key pressed.
		require
			positive_delay: delay > 0
			positive_interval: interval > 0
		do
			if sdl_enable_key_repeat (delay, interval) /= 0 then
				Error_handler.raise_warning (Error_handler.Em_error_enable_repeating_keyboard_events, [delay, interval])
			end
		end

	disable_repeating_key_down_events is
			-- Disable repeating key down events
			-- when the user keeps pressing a key for a long time.
		do
			if sdl_enable_key_repeat (0, 0) /= 0 then
				Error_handler.raise_warning (Error_handler.Em_error_disable_repeating_keyboard_events, [])
			end
		end

feature -- Queries

	is_pressed (a_key: INTEGER): BOOLEAN is
			-- Is `a_key' pressed?
			-- (See sdlk_... features in SDLKEY_ENUM_EXTERNAL for possible `a_key' values)
		do
			Result := keyboard_state.read_integer_8 (a_key) /= 0
		end

	key_name (key: INTEGER): STRING is
			-- SDL name for `key'
			-- (See sdlk_... features in SDLKEY_ENUM_EXTERNAL for possible `key' values)
		require
			key_is_valid: is_valid_key (key)
		local
			str: EWG_ZERO_TERMINATED_STRING
			p: POINTER
		do
			p := sdl_get_key_name (key)
			create str.make_shared (p)
			Result := str.string
		ensure
			key_name_returned: Result /= Void and then not Result.is_empty
		end

feature {NONE} -- Implementation

	keyboard_state: EWG_MANAGED_POINTER
		-- Shared structure containing the states of all keys

invariant

	keyboard_state_not_void: keyboard_state /= Void

end