This is a "cheat sheet" for "file_dropper" extension by YellowAfterlife.
The extension can be found on itch.io.
The source code can be found on GitHub.
Sets up the drag and drop operations for the game window.
Should be called before you expect user to attempt dragging and dropping objects onto the window (usually on Game Start).
Harmless if called more than once.
Returns whether successful (I'm not aware of circumstances that could cause this function to fail).
After calling this function above,
the game window will indicate to the system that it's happy to accept objects
and the user will be able to drag and drop files/folders from Explorer/etc.
Doing so will dispatch one async events (see below).
For basic functionality, you only have to handle the file_drop events.
Async events
I'm so sorry about the naming of these,
people keep asking me to add more events
and it's hard to plan ahead.
These are Async - System events.
Drag:
Dispatches when the mouse enters the game window
while dragging one or more files.
This one dispatches before the batch of file_drag_enter_file events.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drag_enter_start"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
Dispatches for each file when the mouse enters the game window
while dragging one or more files.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drag_enter_file"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
-
async_load[?"filename"]
An absolute path to the file.
Probably don't start reading it just yet, the user might change their mind.
Dispatches when the mouse enters the game window
while dragging one or more files.
This will set effect and permission to drop to defaults
(file_dropper_set_default_effect, file_dropper_set_default_allow).
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drag_enter"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
For example, if you want to only allow specific file types,
you could do
Repeatedly dispatches as the mouse is over the window while dragging files.
You can take this opportunity to call file_dropper_set_allow
and/or file_dropper_set_effect
to indicate to the user whether they can drop a file at this specific spot
and what would happen if they did.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drag_over"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
Dispatches when the mouse subsequently leaves the game window
without dropping anything off.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drag_leave"
Drop:
Dispatches at the beginning of a drop operation.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drop_start"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
Note that mouse button flags are no longer set at this point
(likely because drop happens on mouse release).
-
async_load[?"file_count"]
The number of files that are being dropped off.
Dispatches once for each file in the batch.
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drop"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
-
async_load[?"filename"]
An absolute path to the file.
Note that in GMS1.4, you'll need an extension to read files outside of game/save directory
(e.g. non-sandboxed filesystem)
Dispatches at the end of a drop operation.
If you are displaying a "drop zone",
async_load will contain the following fields:
-
async_load[?"event_type"] is "file_drop_end"
-
async_load[?"x"], async_load[?"y"]
Mouse coordinates (screen-space, like display_mouse_get_*)
-
async_load[?"key_state"]
Currently held mouse button and modifier key flags.
-
async_load[?"file_count"]
The number of files that have been dropped off.
Misc:
In the above async events, can be one or more of the following (combined with bit-wise OR):
-
file_dropper_mk_lbutton
-
file_dropper_mk_rbutton
-
file_dropper_mk_mbutton
-
file_dropper_mk_shift
-
file_dropper_mk_control
-
file_dropper_mk_alt
Extra functions
You don't have to use these unless you want more control over the process.
Changes whether the drop operation is currently allowed.
You should usually call this in response to file_drag_over event.
Returns whether the drop operation is currently allowed.
Changes the effect of the drop operation as displayed to the user:
-
file_dropper_effect_none
A "no" icon
-
file_dropper_effect_copy
-
file_dropper_effect_move
Note that this will not automatically remove the original file - that's on you.
-
file_dropper_effect_link
Returns the current effect of the drop operation as it would be displayed to the user.
The following get/set the state
at the beginning of the drag operation
(before GML code has an opportunity to call the above):
Changes whether dropping is allowed at the beginning of a drag operation.
Returns whether dropping is allowed at the beginning of a drag operation.
Returns the drop effect at the beginning of a drag operation.