clipboard: document all pub functions, adhere to vdoc style (#8243)

pull/8245/head
Larpon 2021-01-21 12:45:59 +01:00 committed by GitHub
parent 59c3e98c16
commit 62c2168b0b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 53 additions and 28 deletions

View File

@ -1,36 +1,37 @@
module clipboard module clipboard
// create a new clipboard // new returns a new `Clipboard` instance allocated on the heap.
// The `Clipboard` resources can be released with `free()`
pub fn new() &Clipboard { pub fn new() &Clipboard {
return new_clipboard() return new_clipboard()
} }
// copy some text into the clipboard // copy copies `text` into the clipboard.
pub fn (mut cb Clipboard) copy(text string) bool { pub fn (mut cb Clipboard) copy(text string) bool {
return cb.set_text(text) return cb.set_text(text)
} }
// get the text from the clipboard // paste returns current entry as a `string` from the clipboard.
pub fn (mut cb Clipboard) paste() string { pub fn (mut cb Clipboard) paste() string {
return cb.get_text() return cb.get_text()
} }
// clear the clipboard // clear_all clears the clipboard.
pub fn (mut cb Clipboard) clear_all() { pub fn (mut cb Clipboard) clear_all() {
cb.clear() cb.clear()
} }
// destroy the clipboard // destroy destroys the clipboard and free it's resources.
pub fn (mut cb Clipboard) destroy() { pub fn (mut cb Clipboard) destroy() {
cb.free() cb.free()
} }
// check if we own the clipboard // check_ownership returns `true` if the `Clipboard` has the content ownership.
pub fn (cb Clipboard) check_ownership() bool { pub fn (cb Clipboard) check_ownership() bool {
return cb.has_ownership() return cb.has_ownership()
} }
// check if clipboard can be used // is_available returns `true` if the clipboard is available for use.
pub fn (cb &Clipboard) is_available() bool { pub fn (cb &Clipboard) is_available() bool {
return cb.check_availability() return cb.check_availability()
} }

View File

@ -8,7 +8,7 @@ pub struct Clipboard {
pb voidptr pb voidptr
last_cb_serial i64 last_cb_serial i64
mut: mut:
foo int // TODO remove, for mut hack foo int // TODO remove, for mut hack
} }
fn C.darwin_new_pasteboard() voidptr fn C.darwin_new_pasteboard() voidptr
@ -62,6 +62,8 @@ fn (mut cb Clipboard) get_text() string {
return unsafe { utf8_clip.vstring() } return unsafe { utf8_clip.vstring() }
} }
// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
panic('Primary clipboard is not supported on non-Linux systems.') panic('Primary clipboard is not supported on non-Linux systems.')
} }

View File

@ -8,6 +8,8 @@ fn new_clipboard() &Clipboard {
return x11.new_clipboard() return x11.new_clipboard()
} }
// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
return x11.new_primary() return x11.new_primary()
} }

View File

@ -8,6 +8,8 @@ fn new_clipboard() &Clipboard {
return dummy.new_clipboard() return dummy.new_clipboard()
} }
// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
return dummy.new_primary() return dummy.new_primary()
} }

View File

@ -54,8 +54,8 @@ struct Clipboard {
max_retries int max_retries int
retry_delay int retry_delay int
mut: mut:
hwnd C.HWND hwnd C.HWND
foo int // TODO remove foo int // TODO remove
} }
fn (cb &Clipboard) get_clipboard_lock() bool { fn (cb &Clipboard) get_clipboard_lock() bool {
@ -178,6 +178,8 @@ fn (mut cb Clipboard) get_text() string {
return str return str
} }
// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
panic('Primary clipboard is not supported on non-Linux systems.') panic('Primary clipboard is not supported on non-Linux systems.')
} }

View File

@ -3,14 +3,18 @@ module dummy
pub struct Clipboard { pub struct Clipboard {
mut: mut:
text string // text data sent or received text string // text data sent or received
got_text bool // used to confirm that we have got the text got_text bool // used to confirm that we have got the text
is_owner bool // to save selection owner state is_owner bool // to save selection owner state
} }
// new_clipboard returns a new `Clipboard` instance allocated on the heap.
// The `Clipboard` resources can be released with `free()`
pub fn new_clipboard() &Clipboard { pub fn new_clipboard() &Clipboard {
return &Clipboard{} return &Clipboard{}
} }
// new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
return &Clipboard{} return &Clipboard{}
} }

View File

@ -157,12 +157,14 @@ struct Property {
data byteptr data byteptr
} }
// new_clipboard returns a new `Clipboard` instance allocated on the heap.
// The `Clipboard` resources can be released with `free()`
pub fn new_clipboard() &Clipboard { pub fn new_clipboard() &Clipboard {
return new_x11_clipboard(.clipboard) return new_x11_clipboard(.clipboard)
} }
// Initialize a new clipboard of the given selection type. // new_x11_clipboard initializes a new clipboard of the given selection type.
// We can initialize multiple clipboard instances and use them separately // Multiple clipboard instance types can be initialized and used separately.
fn new_x11_clipboard(selection AtomType) &Clipboard { fn new_x11_clipboard(selection AtomType) &Clipboard {
if selection !in [.clipboard, .primary, .secondary] { if selection !in [.clipboard, .primary, .secondary] {
panic('Wrong AtomType. Must be one of .primary, .secondary or .clipboard.') panic('Wrong AtomType. Must be one of .primary, .secondary or .clipboard.')
@ -225,6 +227,7 @@ fn (cb &Clipboard) take_ownership() {
C.XFlush(cb.display) C.XFlush(cb.display)
} }
// set_text stores `text` in the system clipboard.
pub fn (mut cb Clipboard) set_text(text string) bool { pub fn (mut cb Clipboard) set_text(text string) bool {
if cb.window == C.Window(C.None) { if cb.window == C.Window(C.None) {
return false return false
@ -265,8 +268,8 @@ fn (mut cb Clipboard) get_text() string {
return cb.text return cb.text
} }
// this function is crucial to handling all the different data types // transmit_selection is crucial to handling all the different data types.
// if we ever support other mimetypes they should be handled here // If we ever support other mimetypes they should be handled here.
fn (mut cb Clipboard) transmit_selection(xse &C.XSelectionEvent) bool { fn (mut cb Clipboard) transmit_selection(xse &C.XSelectionEvent) bool {
if xse.target == cb.get_atom(.targets) { if xse.target == cb.get_atom(.targets) {
targets := cb.get_supported_targets() targets := cb.get_supported_targets()
@ -301,8 +304,9 @@ fn (mut cb Clipboard) start_listener() {
} }
} }
C.SelectionClear { C.SelectionClear {
if unsafe { event.xselectionclear.window == cb.window } && unsafe { event.xselectionclear.selection == if unsafe { event.xselectionclear.window == cb.window } && unsafe {
cb.selection } event.xselectionclear.selection == cb.selection
}
{ {
cb.mutex.m_lock() cb.mutex.m_lock()
cb.is_owner = false cb.is_owner = false
@ -334,8 +338,9 @@ fn (mut cb Clipboard) start_listener() {
} }
} }
C.SelectionNotify { C.SelectionNotify {
if unsafe { event.xselection.selection == cb.selection && if unsafe {
event.xselection.property != C.Atom(C.None) } event.xselection.selection == cb.selection && event.xselection.property != C.Atom(C.None)
}
{ {
if unsafe { event.xselection.target == cb.get_atom(.targets) && !sent_request } { if unsafe { event.xselection.target == cb.get_atom(.targets) && !sent_request } {
sent_request = true sent_request = true
@ -349,10 +354,14 @@ fn (mut cb Clipboard) start_listener() {
sent_request = false sent_request = false
to_be_requested = C.Atom(0) to_be_requested = C.Atom(0)
cb.mutex.m_lock() cb.mutex.m_lock()
prop := unsafe { read_property(event.xselection.display, event.xselection.requestor, prop := unsafe {
event.xselection.property) } read_property(event.xselection.display, event.xselection.requestor,
unsafe { C.XDeleteProperty(event.xselection.display, event.xselection.requestor, event.xselection.property)
event.xselection.property) } }
unsafe {
C.XDeleteProperty(event.xselection.display, event.xselection.requestor,
event.xselection.property)
}
if cb.is_supported_target(prop.actual_type) { if cb.is_supported_target(prop.actual_type) {
cb.got_text = true cb.got_text = true
unsafe { unsafe {
@ -369,8 +378,10 @@ fn (mut cb Clipboard) start_listener() {
} }
} }
// Helpers /*
// Initialize all the atoms we need * Helpers
*/
// intern_atoms initializes all the atoms we need.
fn (mut cb Clipboard) intern_atoms() { fn (mut cb Clipboard) intern_atoms() {
cb.atoms << C.Atom(4) // XA_ATOM cb.atoms << C.Atom(4) // XA_ATOM
cb.atoms << C.Atom(31) // XA_STRING cb.atoms << C.Atom(31) // XA_STRING
@ -404,7 +415,7 @@ fn read_property(d &C.Display, w C.Window, p C.Atom) Property {
return Property{actual_type, actual_format, nitems, ret} return Property{actual_type, actual_format, nitems, ret}
} }
// Finds the best target given a local copy of a property. // pick_target finds the best target given a local copy of a property.
fn (cb &Clipboard) pick_target(prop Property) C.Atom { fn (cb &Clipboard) pick_target(prop Property) C.Atom {
// The list of targets is a list of atoms, so it should have type XA_ATOM // The list of targets is a list of atoms, so it should have type XA_ATOM
// but it may have the type TARGETS instead. // but it may have the type TARGETS instead.
@ -485,7 +496,8 @@ fn new_display() &C.Display {
return C.XOpenDisplay(C.NULL) return C.XOpenDisplay(C.NULL)
} }
// create a new PRIMARY clipboard (only supported on Linux) // new_primary returns a new X11 `PRIMARY` type `Clipboard` instance allocated on the heap.
// Please note: new_primary only works on X11 based systems.
pub fn new_primary() &Clipboard { pub fn new_primary() &Clipboard {
return new_x11_clipboard(.primary) return new_x11_clipboard(.primary)
} }