gioui.org@v0.6.1-0.20240506124620-7a9ce51988ce/io/transfer/transfer.go (about)

     1  // Package transfer contains operations and events for brokering data transfers.
     2  //
     3  // The transfer protocol is as follows:
     4  //
     5  //   - Data sources use [SourceFilter] to receive an [InitiateEvent] when a drag
     6  //     is initiated, and an [RequestEvent] for each initiation of a data transfer.
     7  //     Sources respond to requests with [OfferCmd].
     8  //   - Data targets use [TargetFilter] to receive an [DataEvent] for receiving data.
     9  //     The target must close the data event after use.
    10  //
    11  // When a user initiates a pointer-guided drag and drop transfer, the
    12  // source as well as all potential targets receive an InitiateEvent.
    13  // Potential targets are targets with at least one MIME type in common
    14  // with the source. When a drag gesture completes, a CancelEvent is sent
    15  // to the source and all potential targets.
    16  //
    17  // Note that the RequestEvent is sent to the source upon drop.
    18  package transfer
    19  
    20  import (
    21  	"io"
    22  
    23  	"gioui.org/io/event"
    24  )
    25  
    26  // OfferCmd is used by data sources as a response to a RequestEvent.
    27  type OfferCmd struct {
    28  	Tag event.Tag
    29  	// Type is the MIME type of Data.
    30  	// It must be the Type from the corresponding RequestEvent.
    31  	Type string
    32  	// Data contains the offered data. It is closed when the
    33  	// transfer is complete or cancelled.
    34  	// Data must be kept valid until closed, and it may be used from
    35  	// a goroutine separate from the one processing the frame.
    36  	Data io.ReadCloser
    37  }
    38  
    39  func (OfferCmd) ImplementsCommand() {}
    40  
    41  // SourceFilter filters for any [RequestEvent] that match a MIME type
    42  // as well as [InitiateEvent] and [CancelEvent].
    43  // Use multiple filters to offer multiple types.
    44  type SourceFilter struct {
    45  	// Target is a tag included in a previous event.Op.
    46  	Target event.Tag
    47  	// Type is the MIME type supported by this source.
    48  	Type string
    49  }
    50  
    51  // TargetFilter filters for any [DataEvent] whose type matches a MIME type
    52  // as well as [CancelEvent]. Use multiple filters to accept multiple types.
    53  type TargetFilter struct {
    54  	// Target is a tag included in a previous event.Op.
    55  	Target event.Tag
    56  	// Type is the MIME type accepted by this target.
    57  	Type string
    58  }
    59  
    60  // RequestEvent requests data from a data source. The source must
    61  // respond with an OfferCmd.
    62  type RequestEvent struct {
    63  	// Type is the first matched type between the source and the target.
    64  	Type string
    65  }
    66  
    67  func (RequestEvent) ImplementsEvent() {}
    68  
    69  // InitiateEvent is sent to a data source when a drag-and-drop
    70  // transfer gesture is initiated.
    71  //
    72  // Potential data targets also receive the event.
    73  type InitiateEvent struct{}
    74  
    75  func (InitiateEvent) ImplementsEvent() {}
    76  
    77  // CancelEvent is sent to data sources and targets to cancel the
    78  // effects of an InitiateEvent.
    79  type CancelEvent struct{}
    80  
    81  func (CancelEvent) ImplementsEvent() {}
    82  
    83  // DataEvent is sent to the target receiving the transfer.
    84  type DataEvent struct {
    85  	// Type is the MIME type of Data.
    86  	Type string
    87  	// Open returns the transfer data. It is only valid to call Open in the frame
    88  	// the DataEvent is received. The caller must close the return value after use.
    89  	Open func() io.ReadCloser
    90  }
    91  
    92  func (DataEvent) ImplementsEvent() {}
    93  
    94  func (SourceFilter) ImplementsFilter() {}
    95  func (TargetFilter) ImplementsFilter() {}