github.com/Seikaijyu/gio@v0.0.1/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 are registered with SourceOps, data targets with TargetOps.
     6  //   - A data source receives a RequestEvent when a transfer is initiated.
     7  //     It must respond with an OfferOp.
     8  //   - The target receives a DataEvent when transferring to it. It must close
     9  //     the event data 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  	"github.com/Seikaijyu/gio/internal/ops"
    24  	"github.com/Seikaijyu/gio/io/event"
    25  	"github.com/Seikaijyu/gio/op"
    26  )
    27  
    28  // SourceOp registers a tag as a data source for a MIME type.
    29  // Use multiple SourceOps if a tag supports multiple types.
    30  type SourceOp struct {
    31  	Tag event.Tag
    32  	// Type is the MIME type supported by this source.
    33  	Type string
    34  }
    35  
    36  // TargetOp registers a tag as a data target.
    37  // Use multiple TargetOps if a tag supports multiple types.
    38  type TargetOp struct {
    39  	Tag event.Tag
    40  	// Type is the MIME type accepted by this target.
    41  	Type string
    42  }
    43  
    44  // OfferOp is used by data sources as a response to a RequestEvent.
    45  type OfferOp struct {
    46  	Tag event.Tag
    47  	// Type is the MIME type of Data.
    48  	// It must be the Type from the corresponding RequestEvent.
    49  	Type string
    50  	// Data contains the offered data. It is closed when the
    51  	// transfer is complete or cancelled.
    52  	// Data must be kept valid until closed, and it may be used from
    53  	// a goroutine separate from the one processing the frame..
    54  	Data io.ReadCloser
    55  }
    56  
    57  func (op SourceOp) Add(o *op.Ops) {
    58  	data := ops.Write2(&o.Internal, ops.TypeSourceLen, op.Tag, op.Type)
    59  	data[0] = byte(ops.TypeSource)
    60  }
    61  
    62  func (op TargetOp) Add(o *op.Ops) {
    63  	data := ops.Write2(&o.Internal, ops.TypeTargetLen, op.Tag, op.Type)
    64  	data[0] = byte(ops.TypeTarget)
    65  }
    66  
    67  // Add the offer to the list of operations.
    68  // It panics if the Data field is not set.
    69  func (op OfferOp) Add(o *op.Ops) {
    70  	if op.Data == nil {
    71  		panic("invalid nil data in OfferOp")
    72  	}
    73  	data := ops.Write3(&o.Internal, ops.TypeOfferLen, op.Tag, op.Type, op.Data)
    74  	data[0] = byte(ops.TypeOffer)
    75  }
    76  
    77  // RequestEvent requests data from a data source. The source must
    78  // respond with an OfferOp.
    79  type RequestEvent struct {
    80  	// Type is the first matched type between the source and the target.
    81  	Type string
    82  }
    83  
    84  func (RequestEvent) ImplementsEvent() {}
    85  
    86  // InitiateEvent is sent to a data source when a drag-and-drop
    87  // transfer gesture is initiated.
    88  //
    89  // Potential data targets also receive the event.
    90  type InitiateEvent struct{}
    91  
    92  func (InitiateEvent) ImplementsEvent() {}
    93  
    94  // CancelEvent is sent to data sources and targets to cancel the
    95  // effects of an InitiateEvent.
    96  type CancelEvent struct{}
    97  
    98  func (CancelEvent) ImplementsEvent() {}
    99  
   100  // DataEvent is sent to the target receiving the transfer.
   101  type DataEvent struct {
   102  	// Type is the MIME type of Data.
   103  	Type string
   104  	// Open returns the transfer data. It is only valid to call Open in the frame
   105  	// the DataEvent is received. The caller must close the return value after use.
   106  	Open func() io.ReadCloser
   107  }
   108  
   109  func (DataEvent) ImplementsEvent() {}