Home > Gtk3, PyGObject, python > PyGObject: Gtk.Clipboard

PyGObject: Gtk.Clipboard

13 Aprile 2020

torna all’indice appunti

Clipboard

L’oggetto Gtk.Clipboard offre un’area di storage per una moltitudine di dati,
testo ed immagini comprese. L’utilizzo del clipboard permette di condividere dati tra applicazioni
differenti, semplicemente con azioni come copia/taglia ed incolla.
Queste azioni si ottengono generalmente con le scorciatoie da tastiera, utilizzando oggetti
Gtk.MenuItem, e connettendo le funzioni ai widget Gtk.Button.
Ogni clipboard viene identificato da un nome codificato come un Gdk.Atom.
Il clipboard di default corrisponde all’atom “CLIPBOARD”; un’altro clipboard utilizzato di
frequente è il “PRIMARY”, che, in X, di solito contiene il testo selezionato.

Per creare un Clipboard si utilizza il costruttore Gtk.Clipboard(**kwargs).

Segnali

Il segnale di riferimento per Gtk.Clipboard è “owner-change”, che viene emesso quando GTK+ riceve
un evento che indica che la proprietà della selezione associata al clipboard è cambiata.

Metodi

Di seguito i metodi utilizzabili con il widget Gtk.Clipboard:

get(selection)

Ritorna l’oggetto clipboard per la selezione data.
Parametri:
selection: un oggetto Gdk.Atom che identifica il
clipboard da usare;

>>> atom = Gdk.Atom.intern(atom_name="PRUMARY", only_if_exists=True)
>>> clipboard = Gtk.Clipboard.get(atom)

esistono anche delle costanti utilizzabili per lo stesso scopo, come ad esempio
Gdk.SELECTION_CLIPBOARD.

>>> newclipboard = Gtk.Clipboard.get(Gdk.SELECTION_CLIPBOARD)

get_default(display)

Ritorna il clipboard di default da usare con elementi che consentano azioni cut/copy/paste
e scorciatoie da tastiera (keyboard shortcuts).
Parametri:
display: è un oggetto Gdk.Display per il quale utilizziamo il clipboard;

>>> display = Gdk.Display.get_default()
>>> default_clipboard = Gtk.Clipboard.get_default(display)

get_for_display(display, selection)

Ritorna l’oggetto clipboard appropriato per la selezione data. Se non esiste alcun clipboard,
ne verrà creato uno nuovo. Una volta che il clipboard verrà creato, sarà persistente e di
proprietà di Gtk+.
Per elementi “Cut/copy/paste” e “keyboard shortcuts” dovrebbe essere usato sempre il default
clipboard, passando al costruttore selection=SELECTION_CLIPBOARD.
E’ possibile avere clipboard con nomi arbitrari, ma per convenzione si dovrebbe usare un
underscore come prefisso.
Parametri:
display: il Gdk.Display per il quale il clipboard viene richiesto
o creato;
selection: un Gdk.Atom che identifica il clipboard da usare;

clear()

Ripulisce il contenuto del clipboard.

get_display()

Ritorna l’oggetto Gdk.Display associato al clipboard.

get_owner()

Ritorna il proprietario del clipboard, se esiste, altrimenti None.

request_contents(target, callback, *user_data)

Richiede i contenuti del clipboard e una volta ricevuti, invoca la callback specificata.
Parametri:
target: l’oggetto Gdk.Atom rappresentante la forma nella quale il
proprietario del clipboard dovrebbe convertire la selezione;
callback: un oggetto Gtk.ClipboardReceivedFunc, ovvero una funzione
che viene invocata quando vengono ricevuti i risultati.
Se il recupero dei dati fallisce, il campo “length” di selection_data sarà negativo;
user_data: i dati da passare alla callback;

request_image(callback, *user_data)

Richiede il contenuto del clipboard come immagine. Quando l’immagine viene ricevuta, viene
convertita in GdkPixbuf.Pixbuf e la callback sarà invocata.
Il parametro pixbuf passato alla callback, conterrà il GdkPixbuf.Pixbuf
risultatante, se la richiesta avrà successo, altrimenti None.
Può infatti capitare che il clipboard sia vuoto, o contenga dati non convertibili in immagine.
Parametri:
callback: l’oggetto Gtk.ClipboardImageReceivedFunc, ovvero una
funzione da invocare quando l’immagine viene ricevuta;
user_data: i dati da passare alla callback;

request_rich_text(buffer, callback, *user_data)

Richede il contenuto del clipboard come rich text. Quando il risultato viene ricevuto,
viene invocata la callback passata come argomento. I parametri text e length
passati alla callback, conterranno rispettivamente il testo e la lunghezza dello stesso, in caso
di successo, altrimenti None.
Parametri:
buffer: l’oggetto Gtk.TextBuffer;
callback: un oggetto Gtk.ClipboardReceivedFunc, ovvero una funzione
che viene invocata quando vengono ricevuti i risultati;
user_data: i dati da passare alla callback;

request_targets(callback, *user_data)

Richiede il contenuto del clipboard come lista di targets supportati.
Una volta ricevuta la lista, viene invocata la callback.
Il parametro targets passato alla callback, conterrà i targets in caso di
successo della richiesta, o None in caso di fallimento.
Parametri:
callback: un oggetto Gtk.ClipboardReceivedFunc, ovvero una funzione
che viene invocata quando vengono ricevuti i risultati;
user_data: i dati da passare alla callback;

request_text(callback, *user_data)

Richiede il contenuto del clipboard come testo. Quando viene ricevuto, se necessario viene
convertito in UTF-8, dopodichè viene invocata la callback.
Il parametro text passato alla callback, conterrà il testo del clipboard.
in caso di successo, altrimenti None.
Parametri:
callback: un oggetto Gtk.ClipboardReceivedFunc, ovvero una funzione
che viene invocata quando vengono ricevuti i risultati;
user_data: i dati da passare alla callback;

request_uris(callback, *user_data)

Richiede il contenuto del clipboard come URIs. Una volta ricevuti, verrà invocata la callback.
Il parametro uris passato alla callback, conterrà la lista degli URIs in caso di
successo della richiesta, o None in caso di fallimento.
Parametri:
callback: un oggetto Gtk.ClipboardReceivedFunc, ovvero una funzione
che viene invocata quando vengono ricevuti i risultati;
user_data: i dati da passare alla callback;

set_can_store(targets)

Permette di salvare i dati del clipboard da quanlche parte, finchè l’applicazione esiste o quando
viene chiamato il metodo Gtk.Clipboard.store().
Questo valore viene resettato quando il proprietario del clipboard cambia.
Il luogo dove vengono salvati i dati dipende dal platform, a tal proposito vedere il metodo
Gdk.Display.store_clipboard.
Parametri:
targets: una lista di Gtk.TargetEntry,
contenente informazioni su che forms debbano essere salvati, o None, se tutte le forms debbano
essere salvate.

set_image(pixbuf)

Setta il contenuto del clipboard al GdkPixbuf.Pixbuf dato. GTK+ si prenderà la responsabilità di
rispondere alla richiesta ed eventualmente convertire l’immagine nel formato richiesto.
Parametri:
pixbuf: l’oggetto GdkPixbuf.Pixbuf da settare nel clipboard;

set_text(text, len)

Setta il contenuto del clipboard nella stringa specificata. GTK+ si prenderà la responsabilità
di rispondere alla richiesta ed eventualmente convertire il testo nel formato richiesto.
Parametri:
text: la stringa UTF-8 su cui settare il contenuto del clipboard;
len: la lunghezza del testo (int) da settare;

store()

Salva i dati del clipboard per potervi accedere ad applicazione terminata.

wait_for_contents(target)

Richiede i contenuti del clipboard usando il target dato. Questo metodo attende che i dati vengano
ricevuti usando il mainloop in modo che eventi, timeouts ecc, possano essere distribuiti durante l’attesa.
Parametri:
target: l’oggetto Gdk.Atom rappresentante la forma nella quale il
proprietario del clipboard, deve convertire la selezione;

wait_for_image()

Richiede i contenuti del clipboard come immagine e converte il risultato in GdkPixbuf.Pixbuf.
Questo metodo attende che i dati vengano ricevuti usando il mainloop in modo che eventi, timeouts
ecc, possano essere distribuiti durante l’attesa.

wait_for_rich_text(buffer)

Richiede i contenuti del clipboard come “rich text”. Questo metodo attende che i dati vengano
ricevuti usando il mainloop, in modo che eventi, timeouts, ecc, possano essere distribuiti durante
l’attesa.
Parametri:
buffer: un oggetto Gtk.TextBuffer;

wait_for_targets()

Ritorna True se sonon presenti targets (Gdk.Atom) nel clipboard, o None se assenti.
Se ritorna True, ritorna anche la lista dei targets.

wait_for_text()

Richiede il contenuto del clipboard come testo e lo converte in formato UTF-8, se necessario.
Questo metodo attende che i dati vengano ricevuti usando il mainloop, in modo che eventi,
timeouts, ecc, possano essere distribuiti durante l’attesa.

wait_for_uris()

Richiede il contenuto del clipboard come URIs.
Questo metodo attende che i dati vengano ricevuti usando il mainloop, in modo che eventi,
timeouts ecc, possano essere distribuiti durante l’attesa.

wait_is_image_available()

Test per accertarsi che ci sia un’immagine disponibile da incollare (paste).
Questo avviene richiedendo i targets atom e controllando che contenga uno dei targets immagine
supportati. Questo metodo attende che i dati vengano ricevuti usando il mainloop, in modo che
eventi, timeouts, ecc, possano essere distribuiti durante l’attesa.

wait_is_rich_text_available(buffer)

Test per accertarsi che ci sia un “rich text” disponibile da incollare (paste).
Questo avviene richiedendo i targets atom e controllando che contenga uno dei targets “rich text”
supportati. Questo metodo attende che i dati vengano ricevuti usando il mainloop, in modo che
eventi, timeouts, ecc, possano essere distribuiti durante l’attesa.
Parametri:
buffer: un oggetto Gtk.TextBuffer;

wait_is_target_available(target)

Controlla se un clipboard supporta i pasting data di un certo tipo.
Parametri:
target: un Gdk.Atom che indichi quale target cercare;

wait_is_text_available()

Test per accertarsi che ci sia testo disponibile da incollare (paste). Questo avviene richiedendo
i targets atom e controllando che contenga dei targets di testo supportati.

wait_is_uris_available()

Test per accertarsi che ci sia una lista di URI disponibile da incollare (paste). Questo avviene
richiedendo i targets atom e controllando che contenga uno dei targets URI.

Di seguito un codice d’esempio:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk, Gdk, GdkPixbuf


class GWindow(Gtk.Window):
    def __init__(self):
        super().__init__(title="Clipboard Example")
        self.set_default_size(400, 50)

        self.clipboard = Gtk.Clipboard.get(Gdk.SELECTION_CLIPBOARD)
        self.entry = Gtk.Entry()
        self.label = Gtk.Label()

        btn_c_text = Gtk.Button(label="Copy Text")
        btn_p_text = Gtk.Button(label="Paste Text")

        # layout
        box = Gtk.Box(spacing=6)
        box.set_homogeneous(True)
        box.pack_start(self.entry, True, True, 0)
        box.pack_start(btn_c_text, True, True, 0)
        box.pack_start(btn_p_text, True, True, 0)
        box.pack_start(self.label, True, True, 0)
        self.add(box)
        # bindings
        btn_c_text.connect("clicked", self.on_copy)
        btn_p_text.connect("clicked", self.on_paste)

    def on_copy(self, widget):
        text = self.entry.get_text()
        print("INFO: setting '%s' to clipboard..." % text)
        self.clipboard.set_text(text=text, len=-1)

    def on_paste(self, widget):
        text = self.clipboard.wait_for_text()
        if text:
            print("INFO: setting '%s' to label..." % text)
            self.label.set_text(text)
        else:
            print("INFO: No text on the clipboard.")


if __name__ == "__main__":
    win = GWindow()
    win.connect("destroy", Gtk.main_quit)
    win.show_all()
    Gtk.main()

link di riferimento:

torna all’indice degli appunti
Gtk3 Clipboard

Categorie:Gtk3, PyGObject, python Tag: , ,
I commenti sono chiusi.