Struct imgui::drag_drop::DragDropTarget

pub struct DragDropTarget<'ui>(_);

Creates a target for drag drop data out of the last ID created.

fn show_ui(ui: &Ui<'_>) {
    // Drop something on this button please!
    ui.button("Hello, I am a drag Target!");
     
    if let Some(target) = DragDropTarget::new(ui) {
        // accepting an empty payload (which is really just raising an event)
        if let Some(_payload_data) = target.accept_payload_empty("BUTTON_DRAG", DragDropFlags::empty()) {
            println!("Nice job getting on the payload!");
        }
    
        // and we can accept multiple, different types of payloads with one drop target.
        // this is a good pattern for handling different kinds of drag/drop situations with
        // different kinds of data in them.
        if let Some(Ok(payload_data)) = target.accept_payload::<usize, _>("BUTTON_ID", DragDropFlags::empty()) {
            println!("Our payload's data was {}", payload_data.data);
        }
    }
}

Notice especially the "BUTTON_DRAG" and "BUTTON_ID" name – this is the identifier of this DragDropTarget; DragDropSources will specify an identifier when they send a payload, and these names must match up. Notice how a target can have multiple acceptances on them – this is a good pattern to handle multiple kinds of data which could be passed around.

DropDropTargets don’t do anything until you use one of the three accept_ methods on this struct. Each of these methods will spit out a _Payload struct with an increasing amount of information on the Payload. The absolute safest solution is accept_payload_empty.

Implementations

impl<'ui> DragDropTarget<'ui>

pub fn new(ui: &'ui Ui<'ui>) -> Option<Self>

Creates a new DragDropTarget, holding the Ui’s lifetime for the duration of its existence. This is required since this struct runs some code on its Drop to end the DragDropTarget code.

pub fn accept_payload_empty(
    &self,
    name: impl AsRef<str>,
    flags: DragDropFlags
) -> Option<DragDropPayloadEmpty>

Accepts an empty payload. This is the safest option for raising named events in the DragDrop API. See DragDropSource::begin for more information on how you might use this pattern.

Note: If you began this operation with begin_payload_unchecked it always incorrect to use this function. Use accept_payload_unchecked instead

pub fn accept_payload<T: 'static + Copy, Name: AsRef<str>>(
    &self,
    name: Name,
    flags: DragDropFlags
) -> Option<Result<DragDropPayloadPod<T>, PayloadIsWrongType>>

Accepts a payload with plain old data in it. This returns a Result, since you can specify any type. The sent type must match the return type (via TypeId) to receive an Ok.

Note: If you began this operation with begin_payload_unchecked it always incorrect to use this function. Use accept_payload_unchecked instead

pub unsafe fn accept_payload_unchecked(
    &self,
    name: impl AsRef<str>,
    flags: DragDropFlags
) -> Option<DragDropPayload>

Accepts a drag and drop payload which contains a raw pointer to c_void and a size in bytes. Users should generally avoid using this function if one of the safer variants is acceptable.

Safety

Because this pointer comes from ImGui, absolutely no promises can be made on its contents, alignment, or lifetime. Interacting with it is therefore extremely unsafe. Important: a special note needs to be made to the ACCEPT_BEFORE_DELIVERY flag – passing this flag will make this function return Some(DragDropPayload) even before the user has actually “dropped” the payload by release their mouse button.

In safe functions, this works just fine, since the data can be freely copied (or doesn’t exist at all!). However, if you are working with your own data, you must be extremely careful with this data, as you may, effectively, only have immutable access to it.

Moreover, if the DragDropSource has also used Condition::Once or similar when they sent the data, ImGui will assume its data is still valid even after your preview, so corrupting that data could lead to all sorts of unsafe behvaior on ImGui’s side. In summary, using this function for any data which isn’t truly Copy or “plain old data” is difficult, and requires substantial knowledge of the various edge cases.

pub fn pop(self)

Ends the current target. Ironically, this doesn’t really do anything in ImGui or in imgui-rs, but it might in the future.

Trait Implementations

impl<'ui> Debug for DragDropTarget<'ui>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for DragDropTarget<'_>

fn drop(&mut self)

Executes the destructor for this type.