Un Clipboard est créé par le constructeur :

  presse_papier = gtk.Clipboard(display, selection)

...où display est le gtk.gdk.Display associé avec le Clipboard désigné par le paramètre selection. La fonction suivante crée un Clipboard en utilisant le gtk.gdk.Display par défaut :

  presse_papier = gtk.clipboard_get(selection)

Enfin, un Clipboard peut aussi être créé par la méthode Widget :

  presse_papier = widget.get_clipboard(selection)

Le widget doit être "réalisé" et appartenir à la hiérarchie de la fenêtre racine.

Les widgets Entry, SpinButton et TextView possèdent des menus contextuels qui offrent la possibilité de couper ou copier le texte sélectionné et de le coller à partir du presse-papier "CLIPBOARD". De plus, des liens sont établis pour permettre des raccourcis clavier pour couper, copier et coller. Couper est activé par Control+X , copier par Control+C et coller par Control+V.

Les widgets (Entry et SpinButton) mettent en oeuvre l'interface Editable qui possède les méthodes suivantes pour couper, copier et coller de et vers le "CLIPBOARD" clipboard :

  editable.cut_clipboard()
  editable.copy_clipboard()
  editable.paste_clipboard()

Un Label sélectionnable (la propriété "selectable" vaut TRUE) permet aussi de copier le texte dans le presse-papier "CLIPBOARD"

en utilisant un menu contextuel ou le raccourci clavier Control+C.

Les TextBuffer ont des méthodes similaires bien qu'ils permettent aussi de préciser le presse-papier à utiliser :

  textbuffer.copy_clipboard(clipboard)

Le texte sélectionné sera copié dans le Clipboard indiqué par clipboard.

  textbuffer.cut_clipboard(clipboard, default_editable)

Le texte sélectionné sera copié dans clipboard. Si le paramètre default_editable vaut TRUE, le texte sélectionné sera aussi effacé du TextBuffer. Sinon, la methode cut_clipboard() fonctionnera comme la méthode copy_clipboard() .

  textbuffer.paste_clipboard(clipboard, override_location, default_editable)

Si le paramètre default_editable vaut TRUE, le contenu de clipboard sera inséré dans le TextBuffer à l'endroit indiqué par le paramètre override_location du TextIter

. Si default_editable vaut FALSE, la méthode paste_clipboard() n'insèrera pas le contenu de clipboard. Si le paramètre override_location vaut None, le contenu de clipboard sera inséré à l'emplacement du curseur.

Les TextBuffer possèdent aussi deux méthodes pour gérer un ensemble de Clipboard qui sont automatiquement affectés avec le contenu de la sélection en cours :

  textbuffer.add_selection_clipboard(clipboard)
  textbuffer.remove_selection_clipboard(clipboard)

Quand un TextBuffer est ajouté à un TextView, le presse-papiers "PRIMARY" est automatiquement ajouté aux presse-papiers choisis. L'application peut ajouter d'autres presse-papiers, (par exemple le presse-papier "CLIPBOARD").

Il est possible d'affecter des données au Clipboard par programme en utilisant l'une de ces méthodes :

  presse_papier.set_with_data(cibles, get_func, clear_func, donnees_utilisateur)

  presse_papier.set_text(text, len=-1)

La méthode set_with_data() indique quelles cibles de données sélectionnées sont acceptées et fournit les fonctions (get_func et clear_func) qui sont appelées quand les données sont appelées ou quand les données du presse-papiers sont modifiées. Le paramètre donnees_utilisateur est transmis à get_func où à clear_func quand elles sont appelées. Le paramètre cibles est une liste de 3-tuples contenant :

Les paramètres de get_func et de clear_func sont :

  def get_func(presse_papier, donnees_selection, info, data):

  def clear_func(presse_papier, data):

...où le paramètre presse_papier est le Clipboard, le paramètre donnees_selection est un objet SelectionData contenant les données, le paramètre info est l'entier assigné à l'application, associé à une cible et le paramètre data représente les données utilisateur.

La méthode set_text() est une méthode commode qui utilise la méthode set_with_data() pour placer les données texte dans un Clipboard avec pour cibles : "STRING", "TEXT", "COMPOUND_TEXT", et "UTF8_STRING". Elle utilise les fonctions internes get et clear pour gérer les données. Cette méthode est équivalente à :

  def my_set_text(self, texte, len=-1):
      targets = [ ("STRING", 0, 0),
                  ("TEXT", 0, 1),
                  ("COMPOUND_TEXT", 0, 2),
                  ("UTF8_STRING", 0, 3) ]
      def text_get_func(presse_papier, donnees_selection, info, data):
          selection.set_text(data)
          return
      def text_clear_func(presse_papier, data):
          del data
          return
      self.set_with_data(cibles, text_get_func, text_clear_func, texte)
      return

Une fois les données placées dans le presse-papiers, elles demeurent disponibles jusqu'à la fermeture de l'application ou jusqu'à leur remplacement.

Pour obtenir le comportement habituel du couper dans un presse-papiers, l'application doit supprimer le texte ou l'objet sélectionné après l'avoir recopié dans le presse-papiers.

Le contenu du Clipboard peut être récupéré avec la méthode suivante :

  clipboard.request_contents(target, callback, user_data=None)

Les contenus indiqués par target sont récupérés de manière asynchrone dans la fonction indiquée par le paramètre callback qui est appelé avec user_data. le paramètre callback a la forme :

  def callback(presse_papier, donnees_selection, data):

... où donnees_selection est un objet SelectionData conservant le contenu du presse_papier. data contient les données utilisateur. La méthode request_contents() est la façon la plus commune de récupérer le contenu d'un Clipboard. La méthode suivante est commode pour retrouver le contenu texte d'un Clipboard :

  clipboard.request_text(callback, user_data=None)

La chaîne texte est renvoyée à la fonction de rappel à la place d'un objet Selectiondata. Vous pouvez vérifier quelles cibles sont disponibles sur le Clipboard en employant la méthode :

  clipboard.request_targets(callback, user_data=None)

Les cibles sont retournées à la fonction de rappel comme un tuple d'objets gtk.gdk.Atom.

Deux méthodes pratiques sont fournies pour renvoyer le contenu du Clipboard de manière synchrone :

  donnees_selection = clipboard.wait_for_contents(cible)

  texte = clipboard.wait_for_text()

Pour illustrer l'utilisation d'un Clipboard, le programme clipboard.py récupère les éléments de texte qui sont coupés ou copiés vers le presse-papiers "CLIPBOARD" et sauvegarde les dix dernières entrées du presse-papiers. Il y a dix boutons qui permettent d'accéder au texte des entrées sauvegardées. Le texte du bouton affiche les seize premiers caractères du texte sauvé et les infobulles montrent les cibles que la zone de texte avait à l'origine. Quand on clique sur un bouton d'entrée, le texte sauvegardé associé s'inscrit dans la fenêtre de texte ; il est modifiable. Le bouton sous la fenêtre de texte sauvegarde le contenu actuel de la fenêtre dans le presse-papiers.

Figure 15.1, « Exemple de Clipboard » montre le programme clipboard.py en action :

Le programme d'exemple sonde le presse-papiers toutes les 1,5 secondes pour voir si le contenu a changé. Le programme peut être modifié pour dupliquer la totalité de contenu de cible et prendre le contrôle en employant la méthode set_with_data(). Plus tard, quand un autre programme place du contenu dans le presse-papiers, le paramètre clear_func sera appelé , il pourra être utilisé pour recharger le contenu du presse-papiers et en reprendre le contrôle .