-
Notifications
You must be signed in to change notification settings - Fork 0
InputCandy:Advanced global.IC Methods Reference
h3rb edited this page Apr 2, 2021
·
1 revision
This page describes the methods of __INPUTCANDY created in the New_InputCandy() function. You do not need to call New_InputCandy() directly, as it is called for you by __Private_Init_InputCandy() which is in turn called by Init_InputCandy_Advanced(). You can use this reference if you want to delve deeper into understanding InputCandy's underlying functionality.
This is considered the "API" or "Interface" class, and implements the InputCandy Advanced API.
A brief overview of concepts is found in InputCandy:Advanced Under The Hood.
You can call these methods using __IC.<method-name> or __INPUTCANDY.interface.<method-name> or global.INPUTCANDY.interface.<method-name>
| Method | Purpose / Description |
|---|---|
| Step() | Call this in a controller object's Step event, once per frame/room, whenever Input needs to be polled |
| ClearActions() | Empties the action list. You probably won't need this. |
| Action( .. ) | Installs a new action. You can call it with 3, but it can take up to 7 parameters: verb_string - the name of your action you will look it up by, **default_gamepad **- this expects an IC_ button code, like IC_dpad_U, for gamepad default suggestion, IC_none otherwise/default, default_keyboard- this expects an IC_ button code, like IC_key_A, for gamepad default suggestion, IC_none otherwise/default, default_mouse - IC_mouse_left, IC_mouse_right, IC_mouse_middle, IC_mouse_scrollup, IC_mouse_scrolldown or IC_none (default), group - another string that groups actions together (optional), is_directional - a true/false value indicating this is for a dpad, hat or axis (false by default), requires_angle - a true/false value that further specifies we are expecting a vert/horiz axis to be used (false by default), enabled - optional, a true/false (true is default) that starts this action as deactivated or activated ... returns the newly added index in the master actions list |
| ActionPush( in ) | The value for in is a modified version of an [[InputCandy:Advanced Class Reference |
| Action_ext( name, group, gamepad, gamepad_combo, keyboard, keyboard_combo, mouse, mouse_combo, mouse_keyboard_combo, is_directional, requires_angle, held_for_seconds, fire_limit, released, enabled, forbid_rebinding ) | Another way to define an action, returns the newly added index in the master actions list |
| Actions( action_list ) | Alternatively, you can install an action list from an array of struct source, using the template for actions defined in New_ICAction() |
| ActivateAction( action_index ) | Sets enabled to true on the action. Actions that are enabled are triggered. |
| DeactivateAction( action_index ) | Sets enabled to false on the action. Actions that aren't enabled are ignored. |
| IsActionEnabled( action_index ) | Queries the value of the action's enabled flag. This is a formal function, it may be just as fast to look it up directly, but it protects the value from being modified unintentionally |
| DeactivateGroup( group_name ) | Deactivates (enabled=false) all actions belonging to the same group_name, note that this string may be case sensitive |
| ActivateGroup( group_name ) | Activates (enabled=true) all actions belonging to the same group_name, note that this string may be case sensitive |
| GetAction( name, (group_name) ) | Gets the action_index of the action by name, or by name and group_name. If there is no match, returns none |
| GetActionGroup( group_name ) | Returns a list of action indexes referring to actions in the same named group. Pass string "None" for ungrouped actions. |
| ActionCheck( player_number, action_name, (group_name) ) | Checks a specific player&device&binding pairing for presence of a provided action currently for a specific player_number. This is not the recommended way of checking an action but it can be used. It is faster to use IC_Match. Returns true if the action is being matched, false if is not. |
| ActionCheckReleased( player_number, action_name, (group_name) ) | Same as above but returns true only on release of the action. |
| ActionCheckAny( action_name, (group_name) ) | Checks if any player is currently performing the action, similar to ActionCheck |
| ActionCheckReleasedAny( action_name, (group_name) ) ) | Checks if any player is releasing the action, similar to ActionCheckReleased |
| Match( player_number, action_index ) | This is the fastest way to check and is exposed as IC_Match() global function. Uses no strings, so the test is extremely fast. Use this to interpret your actions. |
| KeyHeld( ic_code ) | Expects a valid IC_code for keyboard devices. Cannot check a Directional like IC_wasd. Returns the number of frames a key has been held for, or 0 if it is not being held. |
| KeyDown( ic_code ) | Expects a valid IC_code for keyboard devices. Cannot check a Directional like IC_wasd. Returns true if the key is down, false if it is not. |
| KeyUp( ic_code ) | Similar to the above, returns true if the key is up, false if it is not. |
| KeyReleased( ic_code ) | Returns true if the key has recently been released, false otherwise. |
| KeyPressed( ic_code ) | Returns true if the key has recently been pressed, false otherwise. |
| GetMouseState( ic_code ) | Expects a valid IC_code for mouse buttons and scroll wheel. This function maps to the values of other Mouse* functions explained in the next few rows of this table. |
| MouseLeftHeld() | Returns the number of frames that the mouse left button has been held. 0 if not |
| MouseRightHeld() | Returns the number of frames that the mouse right button has been held. 0 if not |
| MouseMiddleHeld() | Returns the number of frames that the mouse middle button is being held. 0 if not |
| MouseScrolledUp() or MouseWheelUp() | Returns the GML function value for mouse_wheel_up() |
| MouseScrolledDown() or MouseWheelDown() | Returns the GML function value for mouse_wheel_down() |
| Signal( player_number, IC_code) | Directly checks a signal for a player_number, bypassing the Actions system, -1 means "none", otherwise # of frames its been held for. Note that a signal IC_code cannot be a directional IC_code, and must appear in the signals table. Also note that signals only come from gamepads, not mice or keyboards. |
| SignalAny( IC_code ) | Directly checks a signal for any player, bypassing the Actions system, -1 means "none", otherwise # of frames its been held for. Note that a signal IC_code cannot be a directional IC_code, and must appear in the signals table. Also note that signals only come from gamepads, not mice or keyboards. |
| SignalReleased( player_number, IC_code ) | Returns true only when a signal has recently been released. Similar to the above Signal* functions |
| SignalAnyReleased( IC_code ) | Directly checks a signal for any player, bypassing the Actions system, returning true when a signal has been released or false otherwise |
| GetHatSignal( player_number, hat_number ) | Returns the signal struct for a hat matching the index (0...hat_count-1) as a state like { up: false, down: false, left: false, right: false, not_available: false } ... if the hat is not on the device, then not_available will be set to true |
| GetAxisSignal( player_number, axis_number ) | Returns a struct of the axis signal matching the axis number provided, as well as the values of GML's gamepad_axis_value() function for gp_axis* (left and right sticks), an AxisToAngle conversion and an AxisToHat conversion, as well as directional states and horizontal/vertical values in an object that looks like { up: false, down: false, left: false, right: false, value: AXIS_NO_VALUE, angle: AXIS_NO_VALUE, H: AXIS_NO_VALUE, V: AXIS_NO_VALUE, rH: AXIS_NO_VALUE, rV: AXIS_NO_VALUE, not_available: false } where AXIS_NO_VALUE appears for signals if they are not available, and a true/false setting for not_available indicates that the axis is not supported or there was no attached gamepad |
| GetStickSignal( player_number, axis_number_X, axis_number_Y ) | Returns a struct of the stick signals (similar to the axis signal above) where the H and V values contain the two axis queried. This function is mapped to IC_stick_XY codes in other functions. If not_available is set to true, this indicates that one or more axis were not supported or the player's associated device was none |
| AxisToAngle( H, V ) | This function returns point_direction(0,0,H,V) therefore an indicator of the direction angle |
| AxisToHat( H, V ) | This function returns values that map to ICGamepad_Hat_R/U/D/L or combinations, similar to the gamepad_hat_value values supported in GML. |
| SetMaxPlayers(max_players) | A number, usually less than 14 and must be greater than 0, indicating the number of players that can choose devices in the ICUI and the number of players supported by the system. This number should be set once per game project, and your game should be designed around this number. This value should be set right after InputCandy's Init, before the first Step is called. |
| GetPlayers() | returns __ICI.GetActivePlayers(), a list of players that are marked as active |
| GetPlayerIndex(player_number) | Returns player_number-1 |
| ActivatePlayer(player_number) | Asks the question "Is this player active?" meaning that they have "pressed start" and are playing the game; Returns 1 if the player has been activated, 2 if the player doesn't exist or 3 was already active |
| DeactivePlayer(player_number) | Deactivates the player, returning 1 if deactivated, 2 if the player doesn't exist and 3 if the player was not active when called |
| ParseDeviceGUIDs() | This function supports SDLDB by performing a lookup to an entry in the SDLDB and is called when a device is created. |
| DiagnosticsString( (verbose) ) | Returns a combined string based on __ICI.ICDeviceStatePrintDiagnostics() for each active device and its states, for gamepads only, and if you provide a single parameter true it will use the Verbose version of the functions. |
| DiagnosticsVibrate() | Sends a signal to all connected controllers to perform a quick single shot vibration. |
| KeyboardMouseDiagnosticString() | Returns the keyboard and mouse states in a readable string |
| PlayerDiagnosticString(player_number) | Returns a string version of the player state along with related gamepad device states |
Note the difference between "player_number" and "player_index" -- an index is 0...X, whereas number is 1...X+1 (where X is the value for max global players). Essentially, __INPUTCANDY.players[player_index] == __INPUTCANDY.players[player_number-1]