Merge pull request #714 from ticky/friendlier-controllerdeviceadded

Friendlier ControllerDeviceAdded and JoyDeviceAdded `which` values

changelog.md

@@ -28,6 +28,12 @@ static lifetime from a buffer that also has a static lifetime.
 * Makes the fields of the `sdl2::mixer::Channel(i32)` and `sdl::mixer::Group(i32)` structs
 public so they can be instantiated directly, and deprecates `sdl2::mixer::channel(i32)`.
 
+[PR #714](https://github.com/Rust-SDL2/rust-sdl2/pull/714)
+
+* **Breaking change** Updates the `which` fields of `sdl2::Event::ControllerDeviceAdded` and `sdl2::Event::JoyDeviceAdded` to be `u32`s so they can be used with `sdl2::GameControllerSubsystem` and `sdl::JoystickSubsystem` methods directly.
+* **Breaking change** Updates `sdl2::HapticSubsystem::open_from_joystick_id` to correctly advertise `joystick_index` as being a `u32`.
+* This should only mean removing type conversions which were previously needed to use these values, or changing incorrect assumptions in existing code.
+
 ### v0.30
 
 Re-exported sdl2\_sys as sdl2::sys

examples/haptic.rs

@@ -13,28 +13,26 @@ fn main() {
 
     println!("{} joysticks available", available);
 
-    let mut joystick = None;
+    let mut joystick_index = None;
 
     // Iterate over all available joysticks and stop once we manage to
     // open one.
     for id in 0..available {
         match joystick_subsystem.open(id) {
             Ok(c) => {
                 println!("Success: opened \"{}\"", c.name());
-                joystick = Some(c);
+                joystick_index = Some(id);
                 break;
             },
             Err(e) => println!("failed: {:?}", e),
         }
     }
 
-    if joystick.is_none() {
+    if joystick_index.is_none() {
         panic!("Couldn't open any joystick");
     };
 
-    let joystick = joystick.unwrap();
-
-    let mut haptic = haptic_subsystem.open_from_joystick_id(joystick.instance_id()).unwrap();
+    let mut haptic = haptic_subsystem.open_from_joystick_id(joystick_index.unwrap()).unwrap();
 
     for event in sdl_context.event_pump().unwrap().wait_iter() {
         use sdl2::event::Event;

src/sdl2/controller.rs

@@ -56,23 +56,22 @@ impl GameControllerSubsystem {
         }
     }
 
-    /// Return true if the joystick at index `id` is a game controller.
+    /// Return true if the joystick at index `joystick_index` is a game controller.
     #[inline]
-    pub fn is_game_controller(&self, id: u32) -> bool {
-        match validate_int(id, "id") {
-            Ok(id) => unsafe { ll::SDL_IsGameController(id) != 0 },
+    pub fn is_game_controller(&self, joystick_index: u32) -> bool {
+        match validate_int(joystick_index, "joystick_index") {
+            Ok(joystick_index) => unsafe { ll::SDL_IsGameController(joystick_index) != 0 },
             Err(_) => false
         }
     }
 
-    /// Attempt to open the controller number `id` and return
-    /// it. Controller IDs are the same as joystick IDs and the
-    /// maximum number can be retreived using the `SDL_NumJoysticks`
-    /// function.
-    pub fn open(&self, id: u32) -> Result<GameController, IntegerOrSdlError> {
+    /// Attempt to open the controller ad index `joystick_index` and return it.
+    /// Controller IDs are the same as joystick IDs and the maximum number can
+    /// be retreived using the `SDL_NumJoysticks` function.
+    pub fn open(&self, joystick_index: u32) -> Result<GameController, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
-        let id = try!(validate_int(id, "id"));
-        let controller = unsafe { ll::SDL_GameControllerOpen(id) };
+        let joystick_index = try!(validate_int(joystick_index, "joystick_index"));
+        let controller = unsafe { ll::SDL_GameControllerOpen(joystick_index) };
 
         if controller.is_null() {
             Err(SdlError(get_error()))
@@ -84,11 +83,11 @@ impl GameControllerSubsystem {
         }
     }
 
-    /// Return the name of the controller at the given index.
-    pub fn name_for_index(&self, index: u32) -> Result<String, IntegerOrSdlError> {
+    /// Return the name of the controller at index `joystick_index`.
+    pub fn name_for_index(&self, joystick_index: u32) -> Result<String, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
-        let index = try!(validate_int(index, "index"));
-        let c_str = unsafe { ll::SDL_GameControllerNameForIndex(index) };
+        let joystick_index = try!(validate_int(joystick_index, "joystick_index"));
+        let c_str = unsafe { ll::SDL_GameControllerNameForIndex(joystick_index) };
 
         if c_str.is_null() {
             Err(SdlError(get_error()))
@@ -345,7 +344,7 @@ impl GameController {
         unsafe { ll::SDL_GameControllerGetAttached(self.raw) != 0 }
     }
 
-    /// Return the joystick id of this controller
+    /// Return the joystick instance id of this controller
     pub fn instance_id(&self) -> i32 {
         let result = unsafe {
           let joystick = ll::SDL_GameControllerGetJoystick(self.raw);

src/sdl2/event.rs

@@ -537,13 +537,15 @@ pub enum Event {
 
     JoyAxisMotion {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32,
         axis_idx: u8,
         value: i16
     },
 
     JoyBallMotion {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32,
         ball_idx: u8,
         xrel: i16,
@@ -552,59 +554,70 @@ pub enum Event {
 
     JoyHatMotion {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32,
         hat_idx: u8,
         state: HatState
     },
 
     JoyButtonDown {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32,
         button_idx: u8
     },
     JoyButtonUp {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32,
         button_idx: u8
     },
 
     JoyDeviceAdded {
         timestamp: u32,
-        which: i32
+        /// The newly added joystick's `joystick_index`
+        which: u32
     },
     JoyDeviceRemoved {
         timestamp: u32,
+        /// The joystick's `id`
         which: i32
     },
 
     ControllerAxisMotion {
         timestamp: u32,
+        /// The controller's joystick `id`
         which: i32,
         axis: Axis,
         value: i16
     },
 
     ControllerButtonDown {
         timestamp: u32,
+        /// The controller's joystick `id`
         which: i32,
         button: Button
     },
     ControllerButtonUp {
         timestamp: u32,
+        /// The controller's joystick `id`
         which: i32,
         button: Button
     },
 
     ControllerDeviceAdded {
         timestamp: u32,
-        which: i32
+        /// The newly added controller's `joystick_index`
+        which: u32
     },
     ControllerDeviceRemoved {
         timestamp: u32,
+        /// The controller's joystick `id`
         which: i32
     },
     ControllerDeviceRemapped {
         timestamp: u32,
+        /// The controller's joystick `id`
         which: i32
     },
 
@@ -1084,7 +1097,7 @@ impl Event {
                 let event = ll::SDL_JoyDeviceEvent {
                     type_: ll::SDL_JOYDEVICEADDED,
                     timestamp: timestamp,
-                    which: which,
+                    which: which as i32,
                 };
                 unsafe {
                     ptr::copy(&event, &mut ret as *mut ll::SDL_Event as *mut ll::SDL_JoyDeviceEvent, 1);
@@ -1181,7 +1194,7 @@ impl Event {
                 let event = ll::SDL_ControllerDeviceEvent {
                     type_: ll::SDL_CONTROLLERDEVICEADDED,
                     timestamp: timestamp,
-                    which: which,
+                    which: which as i32,
                 };
                 unsafe {
                     ptr::copy(&event, &mut ret as *mut ll::SDL_Event as *mut ll::SDL_ControllerDeviceEvent, 1);
@@ -1447,7 +1460,7 @@ impl Event {
                 let ref event = *raw.jdevice();
                 Event::JoyDeviceAdded {
                     timestamp: event.timestamp,
-                    which: event.which
+                    which: event.which as u32
                 }
             }
             EventType::JoyDeviceRemoved => {
@@ -1493,7 +1506,7 @@ impl Event {
                 let ref event = *raw.cdevice();
                 Event::ControllerDeviceAdded {
                     timestamp: event.timestamp,
-                    which: event.which
+                    which: event.which as u32
                 }
             }
             EventType::ControllerDeviceRemoved => {

src/sdl2/haptic.rs

@@ -3,13 +3,14 @@ use sys::haptic as ll;
 use sys::joystick as sys_joystick;
 
 use HapticSubsystem;
-use common::IntegerOrSdlError;
+use common::{validate_int, IntegerOrSdlError};
 use get_error;
 
 impl HapticSubsystem {
-    /// Attempt to open the joystick at number `id` and return it.
-    pub fn open_from_joystick_id(&self, joystick_index: i32) -> Result<Haptic, IntegerOrSdlError> {
+    /// Attempt to open the joystick at index `joystick_index` and return its haptic device.
+    pub fn open_from_joystick_id(&self, joystick_index: u32) -> Result<Haptic, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
+        let joystick_index = try!(validate_int(joystick_index, "joystick_index"));
 
         let haptic = unsafe {
             let joystick = sys_joystick::SDL_JoystickOpen(joystick_index);

src/sdl2/joystick.rs

@@ -21,7 +21,7 @@ impl JoystickSubsystem {
         }
     }
 
-    /// Attempt to open the joystick at number `id` and return it.
+    /// Attempt to open the joystick at index `joystick_index` and return it.
     pub fn open(&self, joystick_index: u32) 
             -> Result<Joystick, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
@@ -39,7 +39,7 @@ impl JoystickSubsystem {
         }
     }
 
-    /// Return the name of the joystick at index `id`
+    /// Return the name of the joystick at index `joystick_index`.
     pub fn name_for_index(&self, joystick_index: u32) -> Result<String, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
         let joystick_index = try!(validate_int(joystick_index, "joystick_index"));
@@ -55,7 +55,7 @@ impl JoystickSubsystem {
         }
     }
 
-    /// Get the GUID for the joystick number `id`
+    /// Get the GUID for the joystick at index `joystick_index`
     pub fn device_guid(&self, joystick_index: u32) -> Result<Guid, IntegerOrSdlError> {
         use common::IntegerOrSdlError::*;
         let joystick_index = try!(validate_int(joystick_index, "joystick_index"));