indexing

	description: "[

		Class for wrapping C SDL_JOYSTICK struct. This class represents a joystick.
		
		Use this class for access directly a joystick and to get all information
		about the given device (number of buttons, axies, hats and balls)
		
		For getting information about position changes, pressed buttons, ...
		bette use those handlers form the event loop:
			- handle_joystick_axis_event
			- handle_joystick_ball_event
			- handle_joystick_button_event
			- handle_joystick_hat_event
		
		or simple subscribe to:
			- joystick_axis_event
			- joystick_ball_event
			- joystick_button_down_event
			- joystick_button_up_event
			- joystick_hat_event
		
		Note: This class should only be uses for customizing joystick event publishing
		or for reading the joystick properties.

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

class EM_JOYSTICK

inherit

	EM_CONSTANTS
		export {NONE} all end

	EM_SHARED_SUBSYSTEMS
		export {NONE} all end

	EM_SHARED_ERROR_HANDLER
		export {NONE} all end

	SDL_JOYSTICK_STRUCT_EXTERNAL
		export {NONE} all end

	SDL_JOYSTICK_FUNCTIONS_EXTERNAL
		export {NONE} all end

	EWG_STRUCT

create

	make_default, make_for_device

feature {NONE} -- Implementation

	sizeof: INTEGER is
		do
			-- bugfix, EWG does not like 0 size structs
			Result := 1 -- sizeof_external
		end

feature {NONE} -- Initialization

	make_default is
			-- Initialization class for CD-Rom device `0' (default)
		do
			make_for_device (0)
		end

	make_for_device (a_device: INTEGER) is
			-- Initialization class for CD-Rom device `a_device'
		require
			joystick_subsystem_enbaled: joystick_subsystem.is_enabled
			valid_device: a_device >= 0 and a_device < joystick_subsystem.count
		do
			-- open the new device handler
			make_shared (sdl_joystick_open_external (a_device))

			-- set device indetifier and regiter it
			device := a_device
			joystick_subsystem.register_device (current)

			-- Mark `current' as valid
			valid_handler := true
		ensure
			device_set: device = a_device
			device_registered: joystick_subsystem.devices.has (current)
		end

feature -- Device handler handling

	close is
			-- Here free the device handler
			-- Automatically called by the cdrom_subsystem if called `disable'
		require
			valid_joystick_handler: exists implies valid_handler
		do
			joystick_subsystem.unregister_device (current)

			-- first determines whether a joystick has been
			-- opened within the application
			if sdl_joystick_opened_external (device) = 0 then
				sdl_joystick_close_external (item)
			end

			-- Mark `current' as invalid
			valid_handler := false
		ensure
			device_unregistered: not joystick_subsystem.devices.has (current)
		end

feature -- Joystick Access

	axes: DS_LINKED_LIST [INTEGER] is
			-- `axies' returns the current state of the given axis on `item'.
			--
			-- On most modern joysticks the X axis is usually represented by axis 0
			-- and the Y axis by axis 1. The value returned by `axies' is a signed
			-- integer (-32768 to 32767) representing the current position of the
			-- axis, it may be necessary to impose certain tolerances on these values
			-- to account for jitter. It is worth noting that some joysticks use
			-- axes 2 and 3 for extra buttons.
		require
			valid_joystick_handler: exists implies valid_handler
		local
			i: INTEGER
		do
			create result.make

			from
				i := 0
			until
				i = count_axes
			loop
				result.put_last (sdl_joystick_get_axis_external (item, i))
			end
		end

	balls: DS_LINKED_LIST [INTEGER] is
			-- Get the ball axis change since the last call of `balls'
			-- Trackballs can only return relative motion since the last call to
			-- `balls', these motion deltas are placed into dx and dy.
		require
			valid_joystick_handler: exists implies valid_handler
		local
			i: INTEGER
	--		x, y: EWG_
		do
			create result.make

			from
				i := 0
			until
				i = count_balls
			loop
	--			result.put_last (sdl_joystick_get_ball_external (item, i, x, y))
			end
		end

	buttons: DS_LINKED_LIST [INTEGER] is
			-- `button' returns the current state of all buttons on the given joystick
			-- in a `DS_LINKED_LIST' sturcture.
			-- Subrcribe to the appropriate joystick event to speed things up.
		require
			valid_joystick_handler: exists implies valid_handler
		local
			i: INTEGER
		do
			create result.make

			from
				i := 0
			until
				i = count_buttons
			loop
				result.put_last (sdl_joystick_get_button_external (item, i))

				i := i + 1
			end
		end

	hats: DS_LINKED_LIST [EM_JOYSTICK_HAT] is
			-- The current state is returned as a Uint8 which is an OR'd combination
			-- of one or more of the following:
			--	- SDL_HAT_CENTERED
			--	- SDL_HAT_UP
			--	- SDL_HAT_RIGHT
			--	- SDL_HAT_DOWN
			--	- SDL_HAT_LEFT
			--	- SDL_HAT_RIGHTUP
			--	- SDL_HAT_RIGHTDOWN
			--	- SDL_HAT_LEFTUP
			--	- SDL_HAT_LEFTDOWN
		require
			valid_joystick_handler: exists implies valid_handler
		local
			i: INTEGER
			hat: EM_JOYSTICK_HAT
		do
			create result.make

			from
				i := 0
			until
				i = count_hats
			loop
				create hat
				hat.set_value (sdl_joystick_get_hat_external (item, i))

				result.put_last (hat)
			end
		end

feature -- Properties

	device: INTEGER
		-- Device indentifier
		-- `0' is the default device

	count_axes: INTEGER is
			-- return the number of axes available from the opened Joystick (`item')
		require
			valid_joystick_handler: exists implies valid_handler
		do
			result := sdl_joystick_num_axes_external (item)
		ensure
			count_set: result = sdl_joystick_num_axes_external (item)
		end

	count_balls: INTEGER is
			-- return the number of trackballs available from the opened Joystick (`item')
		require
			valid_joystick_handler: exists implies valid_handler
		do
			result := sdl_joystick_num_balls_external (item)
		ensure
			count_set: result = sdl_joystick_num_balls_external (item)
		end

	count_buttons: INTEGER is
			-- return the number of buttons available from the opened Joystick (`item')
		require
			valid_joystick_handler: exists implies valid_handler
		do
			result := sdl_joystick_num_buttons_external (item)
		ensure
			count_set: result = sdl_joystick_num_buttons_external (item)
		end

	count_hats: INTEGER is
			-- return the number of hats available from the opened Joystick (`item')
		require
			valid_joystick_handler: exists implies valid_handler
		do
			result := sdl_joystick_num_hats_external (item)
		ensure
			count_set: result = sdl_joystick_num_hats_external (item)
		end

feature -- Joystick subsystem flags

	valid_handler: BOOLEAN
			-- Indicates if this Joystick handler (`current') is valid
			-- An invalid handler can be the result of following code
			--		create instance of EM_JOYSTICK
			--		joystick_subsystem.disable		<-- from here the handler is invalid and can cause an segmentation fault
			--		<do something>
			--		joystick_subsystem.enable

feature {NONE} -- Implementation

	update_status is
			-- updates the state (position, buttons, etc.) of all
			-- joysticks manually
		do
			-- returns the current status of the given drive
			sdl_joystick_update_external
		end

invariant

	joystick_subsystem_enabled: joystick_subsystem.is_enabled
end