ICUI
ICUI is a generally responsive, fully featured, stylable UI that permits players to access advanced settings, rebind their controls, test their controls, and use SDL DB.
You can make changes to the style (colors of rectangles, buttons, text, visual effects, corner radius, etc) and you can set a font by modifying the style:: clause found in the __INPUTCANDY.ui object either "on the fly" or by making changes to ICUI.gml __Init_ICUI().
| Style Option | Description |
|---|
__Init_ICUI() is called when InputCandy is initialized. If you do not plan to import ICUI, you will need to remove the reference to this function from InputCandy.gml, but using ICUI saves you a ton of time so why not use it. When this function is called, the style: clause is populated.
Basically, all the o_ICUI object does is call ICUI_Draw() in its Draw event.
To use ICUI without modifications as a submenu of your existing game menus, or in the "escape options menu" of your game, you can simply follow the guidance of the sample project's rm_InputCandy_UI and related o_ICUI object that renders and updates the UI.
The UI is broken into a series of menus that adjust their appearance depending on the state of the InputCandy settings and the style and the player's interaction and plugged in hardware.
These main "modes" are:
- device_select: UI mode where we're selecting a device for each player, this is the first subpanel, and it leads into input_binding and back to the room value for __INPUTCANDY.ui.exit_to
- SDLDB_select: An optional UI mode where the user is selecting a remapping from the SDL database. This panel is reached through the default menu. If you have deactivated this feature in the InputCandy.gml default settings, you will not see this option on the device_select panel.
- gamepad_test: UI mode where we're testing a gamepad (leads to SDLDB_select and input_binding panels)
- input_binding: UI mode where we're mapping controls for a gamepad or loading settings
- capture: UI mode where we're capturing input to show the player what gamepad control means what to InputCandy/SDL
ICUI has both a state and then a frame rendering function. Those functions are called each Draw event of the o_ICUI object. The function that draw the actual panels and UI are really a mix of Step and Draw. It's assumed ICUI is being called at the end of the room's instance list, so that it appears above everything else. It's up to you to maintain this if you make modifications to the room.
The file starts with a bunch of helper functions for rendering. The parameter is_focused gets passed a boolean value calculated through various means. x,y,w,h maps to a rectangle top-left, width-height.
You could use these functions to create other menus that "lead to" ICUI.
| Function | Purpose | | ICUI_slider( is_focused, value, increment, x,y,w,h ) | Draws a slider, used for setting Axis and Button Deadzone | | ICUI_text( is_focused, text, x,y ) | Draws text at a location | | ICUI_text_color( c1,c2,c3,c4, text, x,y ) | Draws text centered/middle text at a location | | ICUI_box( x,y,w,h ) | Wraps draw_roundrect_color_ext and applies styling | | ICUI_tinted_box( tint1,tint2, x,y,w,h ) | Draws a tinted box | | ICUI_fit_image( sprite, index, x,y,w,h, tint, scale, rotation, alpha ) | Fits an image within a box based on the image aspect ratio | | ICUI_image( sprite, index, x,y,w,h, tint, rotation, alpha ) | Stretches an image to fit a box on the screen and can rotate it | | ICUI_margin_image( sprite, index, x,y,w,h, tint, margin, alpha ) | Performs the same stretch but also allows a margin input | | ICUI_text_in_box( is_focused, text, x,y,w,h ) | Draws text in a box based on the styling settings | | ICUI_surround_button( is_focused, x,y,w,h ) | Used for menu items, draws a button that has a highlight surrounding it when focused | | ICUI_labeled_text_in_box( is_focused, text1,text2, x1,x2, y,w,h ) | Draws labeled text in a box. x1 is for text1, and x2 is for the boxed text2 | | ICUI_labeled_button( is_focused, labeltext, x,y,w,h ) | Draws labeled button based on the style settings | | ICUI_get_key_size( sx, sy, fontsize, swh ) | Used by ICUI_draw_ICaction to estimate the size of a rendered key | | ICUI_draw_ICaction( codes, deviceType, is_directional, is_combo, key_mouse_combo, r ) | Draws a "button description" like A,B,X,Y,hat0_L,a key |
The following functions are used to build the o_ICUI object.
| Function | Purpose |
|---|---|
| ICUI_Draw() | Call in the Draw Step of an ICUI controller object, like o_ICUI |
These functions render the individual panels and are called from ICUI_Draw(); you can think of them as "web pages" in a way.
| Function | Purpose |
|---|---|
| Select Player / Swap Device | - |
| ICUI_Draw_device_select() | Draws the device select mode, and its modal inspection menu |
| ICUI_Draw_device_select_swapping() | Draws the swapping menu to pick your device of the panel device_select |
| Input Configuration | - |
| ICUI_Draw_input_binding() | Draws the menu for input binding |
| ICUI_Draw_input_binding_choice() | Draws the modal menu of the panel input_binding letting you choose an option to change |
| ICUI_Draw_input_binding_choice_pick() | Draws the "Choose Binding" from list subpanel of input_binding_choice |
| ICUI_assure_settings_exist() | A utility function that creates a new setting profile for a player who doesn't have one when customizing |
| ICUI_Draw_input_binding_choice_capture() | Draws the "Capture Mode" part of input_binding_choice |
| ICUI_Draw_input_binding_set_profile() | Lets you pick a settings profile from saved profiles |
| SDLDB Menus | - |
| ICUI_MinSearchMode() | returns -1 |
| ICUI_SDLDB_Search_Character() | Checks the state of SDLDB_search_mode so you can fast travel the DB by letter/number |
| ICUI_MaxSearchMode() | returns 36 |
| ICUI_SDLDB_Mode() | Return the name of the search mode |
| ICUI_trim(s) | Trims a string, utility function |
| ICUI_string_into_words(str) | Breaks a string into an array of words, utility function |
| ICUI_StringMatchPercentage( haystack, needle, limited ) | Does some testing to determine how much needle matches haystack, utility function |
| ICUI_DoSearch(device,next) | Search functionality of the SDLDB browser panel |
| ICUI_Draw_SDLDB_select() | The searchable selection modal subpanel for the optional SDLDB_select section of input_binding |
| ICUI_Draw_gamepad_test() | Draws the "Gamepad Test" panel that lets you test out how your gamepad labels stacks up to what we're detecting |
Function/Menu Arrangement
classDiagram
YourGame <|--|> YourGameMenu
YourGameMenu <|--|> device_select
device_select: Choose Device
device_select: Player +Slot +Mouse +Keyboard
device_select: Player +Slot
device_select: Player +Slot
device_select: Player ...
device_select <|--|> device_select_modal
device_select_modal: Select Gamepad
device_select_modal: Change Input
device_select_modal: SDLDB Remapping
device_select_modal: Input Simulator
device_select_modal: Keyboard_Mouse Settings
device_select_modal <|--|> device_select_swapping
device_select_swapping: pad1
device_select_swapping: pad2
device_select_swapping: pad3...
device_select_swapping: back cancel
input_binding <|--|> device_select_modal
input_binding <|--|> input_binding_set_profile
input_binding: New Profile
input_binding: Choose Profile
input_binding: Action 1
input_binding: Action 2
input_binding: Action 3
input_binding: Action ...
input_binding: Axis DeadZone
input_binding: Button DeadZone
input_binding <|--|> input_binding_set_profile
input_binding_set_profile: Settings 1
input_binding_set_profile: Settings 2
input_binding_set_profile: Settings ...
input_binding <|--|> input_binding_choice
input_binding_choice: Select_From_List
input_binding_choice: Capture Input
input_binding_choice: Directionals +Rotate +Invert +Reverse
input_binding_choice: Remove Binding
input_binding_choice <|--|> input_binding_choice_pick
input_binding_choice_pick: Input 1
input_binding_choice_pick: Input 2
input_binding_choice_pick: Input 3
input_binding_choice_pick: ...
input_binding_choice <|--|> input_binding_choice_capture
device_select_modal <|--|> SDLDB_select
SDLDB_select: Search Area
SDLDB_select: SDLDB 1
SDLDB_select: SDLDB 2
SDLDB_select: SDLDB 3
SDLDB_select: SDLDB ...
device_select_modal <|--|> gamepad_test