File: gtk-Clipboards.Rd

package info (click to toggle)
rgtk2 2.20.36-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 33,540 kB
  • sloc: ansic: 137,163; makefile: 2; sh: 1
file content (236 lines) | stat: -rw-r--r-- 10,836 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
\alias{gtk-Clipboards}
\alias{GtkClipboard}
\alias{gtkClipboard}
\alias{GtkClipboardReceivedFunc}
\alias{GtkClipboardTextReceivedFunc}
\alias{GtkClipboardImageReceivedFunc}
\alias{GtkClipboardTargetsReceivedFunc}
\alias{GtkClipboardRichTextReceivedFunc}
\alias{GtkClipboardURIReceivedFunc}
\alias{GtkClipboardGetFunc}
\alias{GtkClipboardClearFunc}
\name{gtk-Clipboards}
\title{Clipboards}
\description{Storing data on clipboards}
\section{Methods and Functions}{
\code{\link{gtkClipboardGet}(selection = "GDK_SELECTION_CLIPBOARD")}\cr
\code{\link{gtkClipboardGetForDisplay}(display, selection = "GDK_SELECTION_CLIPBOARD")}\cr
\code{\link{gtkClipboardGetDisplay}(object)}\cr
\code{\link{gtkClipboardSetWithData}(object, targets, get.func, user.data = NULL)}\cr
\code{\link{gtkClipboardSetWithOwner}(object, targets, get.func, owner = NULL)}\cr
\code{\link{gtkClipboardGetOwner}(object)}\cr
\code{\link{gtkClipboardClear}(object)}\cr
\code{\link{gtkClipboardSetText}(object, text, len = -1)}\cr
\code{\link{gtkClipboardSetImage}(object, pixbuf)}\cr
\code{\link{gtkClipboardRequestContents}(object, target, callback, user.data = NULL)}\cr
\code{\link{gtkClipboardRequestText}(object, callback, user.data = NULL)}\cr
\code{\link{gtkClipboardRequestImage}(object, callback, user.data = NULL)}\cr
\code{\link{gtkClipboardRequestTargets}(object, callback, user.data = NULL)}\cr
\code{\link{gtkClipboardRequestRichText}(object, buffer, callback, user.data)}\cr
\code{\link{gtkClipboardRequestUris}(object, callback, user.data)}\cr
\code{\link{gtkClipboardWaitForContents}(object, target)}\cr
\code{\link{gtkClipboardWaitForText}(object)}\cr
\code{\link{gtkClipboardWaitForImage}(object)}\cr
\code{\link{gtkClipboardWaitForRichText}(object, buffer)}\cr
\code{\link{gtkClipboardWaitForUris}(object)}\cr
\code{\link{gtkClipboardWaitIsTextAvailable}(object)}\cr
\code{\link{gtkClipboardWaitIsImageAvailable}(object)}\cr
\code{\link{gtkClipboardWaitIsRichTextAvailable}(object, buffer)}\cr
\code{\link{gtkClipboardWaitIsUrisAvailable}(object)}\cr
\code{\link{gtkClipboardWaitForTargets}(object)}\cr
\code{\link{gtkClipboardWaitIsTargetAvailable}(object, target)}\cr
\code{\link{gtkClipboardSetCanStore}(object, targets)}\cr
\code{\link{gtkClipboardStore}(object)}\cr
\code{gtkClipboard(display, selection = "GDK_SELECTION_CLIPBOARD")}
}
\section{Hierarchy}{\preformatted{GObject
   +----GtkClipboard}}
\section{Detailed Description}{    The \code{\link{GtkClipboard}} object represents a clipboard of data shared
    between different processes or between different widgets in
    the same process. Each clipboard is identified by a name encoded as a
    \code{\link{GdkAtom}}. (Conversion to and from strings can be done with
    \code{\link{gdkAtomIntern}} and \code{\link{gdkAtomName}}.) The default clipboard
    corresponds to the "CLIPBOARD" atom; another commonly used clipboard
    is the "PRIMARY" clipboard, which, in X, traditionally contains
    the currently selected text.
    
    To support having a number of different formats on the clipboard
    at the same time, the clipboard mechanism allows providing
    callbacks instead of the actual data.  When you set the contents
    of the clipboard, you can either supply the data directly (via
    functions like \code{\link{gtkClipboardSetText}}), or you can supply a
    callback to be called at a later time when the data is needed (via
    \code{\link{gtkClipboardSetWithData}} or \code{\link{gtkClipboardSetWithOwner}}.)
    Providing a callback also avoids having to make copies of the data
    when it is not needed.
    \code{\link{gtkClipboardSetWithData}} and \code{\link{gtkClipboardSetWithOwner}}
    are quite similar; the choice between the two depends mostly on
    which is more convenient in a particular situation.
    The former is most useful when you want to have a blob of data
    with callbacks to convert it into the various data types that you
    advertise. When the \code{clear.func} you provided is called, you
    simply free the data blob. The latter is more useful when the
    contents of clipboard reflect the internal state of a \code{\link{GObject}}
    (As an example, for the PRIMARY clipboard, when an entry widget
    provides the clipboard's contents the contents are simply the
    text within the selected region.) If the contents change, the
    entry widget can call \code{\link{gtkClipboardSetWithOwner}} to update
    the timestamp for clipboard ownership, without having to worry
    about \code{clear.func} being called.
    
    Requesting the data from the clipboard is essentially
    asynchronous. If the contents of the clipboard are provided within
    the same process, then a direct function call will be made to
    retrieve the data, but if they are provided by another process,
    then the data needs to be retrieved from the other process, which
    may take some time. To avoid blocking the user interface, the call
    to request the selection, \code{\link{gtkClipboardRequestContents}} takes a
    callback that will be called when the contents are received (or
    when the request fails.) If you don't want to deal with providing
    a separate callback, you can also use \code{\link{gtkClipboardWaitForContents}}.
    What this does is run the GLib main loop recursively waiting for
    the contents. This can simplify the code flow, but you still have
    to be aware that other callbacks in your program can be called
    while this recursive mainloop is running.
    
    Along with the functions to get the clipboard contents as an
    arbitrary data chunk, there are also functions to retrieve
    it as text, \code{\link{gtkClipboardRequestText}} and
    \code{\link{gtkClipboardWaitForText}}. These functions take care of
    determining which formats are advertised by the clipboard
    provider, asking for the clipboard in the best available format
    and converting the results into the UTF-8 encoding. (The standard
    form for representing strings in GTK+.)
  }
\section{Structures}{\describe{\item{\verb{GtkClipboard}}{
\emph{undocumented
}

}}}
\section{Convenient Construction}{\code{gtkClipboard} is the equivalent of \code{\link{gtkClipboardGetForDisplay}}.}
\section{User Functions}{\describe{
\item{\code{GtkClipboardReceivedFunc(clipboard, selection.data, data)}}{
    A function to be called when the results of \code{\link{gtkClipboardRequestContents}}
    are received, or when the request fails.

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{selection.data}}{a \code{\link{GtkSelectionData}} containing the data was received.
If retrieving the data failed, then then length field
of \code{selection.data} will be negative.}
\item{\code{data}}{the \code{user.data} supplied to \code{\link{gtkClipboardRequestContents}}.}
}


}
\item{\code{GtkClipboardTextReceivedFunc(clipboard, text, data)}}{
    A function to be called when the results of \code{\link{gtkClipboardRequestText}}
    are received, or when the request fails.

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{text}}{the text received, as a UTF-8 encoded string, or \code{NULL}
if retrieving the data failed.}
\item{\code{data}}{the \code{user.data} supplied to \code{\link{gtkClipboardRequestText}}.}
}


}
\item{\code{GtkClipboardImageReceivedFunc(clipboard, pixbuf, data)}}{
    A function to be called when the results of \code{\link{gtkClipboardRequestImage}}
    are received, or when the request fails.
  Since 2.6

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{pixbuf}}{the received image}
\item{\code{data}}{the \code{user.data} supplied to \code{\link{gtkClipboardRequestImage}}.}
}


}
\item{\code{GtkClipboardTargetsReceivedFunc(clipboard, atoms, n.atoms, data)}}{
    A function to be called when the results of \code{\link{gtkClipboardRequestTargets}}
    are received, or when the request fails.
  Since 2.4

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{atoms}}{the supported targets, as list of \code{\link{GdkAtom}}, or \code{NULL}
if retrieving the data failed.}
\item{\code{n.atoms}}{the length of the \code{atoms} list.}
\item{\code{data}}{the \code{user.data} supplied to \code{\link{gtkClipboardRequestTargets}}.}
}


}
\item{\code{GtkClipboardRichTextReceivedFunc()}}{
\emph{undocumented
}




}
\item{\code{GtkClipboardURIReceivedFunc()}}{
\emph{undocumented
}




}
\item{\code{GtkClipboardGetFunc(clipboard, selection.data, info, user.data.or.owner)}}{
A function that will be called to provide the contents of the selection.
If multiple types of data were advertised, the requested type can
be determined from the \code{info} parameter or by checking the target field
of \code{selection.data}. If the data could successfully be converted into
then it should be stored into the \code{selection.data} object by
calling \code{\link{gtkSelectionDataSet}} (or related functions such
as \code{\link{gtkSelectionDataSetText}}). If no data is set, the requestor
will be informed that the attempt to get the data failed.

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{selection.data}}{a \code{\link{GtkSelectionData}} argument in which the requested
data should be stored.}
\item{\code{info}}{the info field corresponding to the requested
target from the \code{\link{GtkTargetEntry}} list passed to
\code{\link{gtkClipboardSetWithData}} or \code{\link{gtkClipboardSetWithOwner}}.}
\item{\code{user.data.or.owner}}{the \code{user.data} argument passed to \code{\link{gtkClipboardSetWithData}}, or
the \code{owner} argument passed to \code{\link{gtkClipboardSetWithOwner}}}
}


}
\item{\code{GtkClipboardClearFunc(clipboard, user.data.or.owner)}}{
A function that will be called when the contents of the clipboard are changed
or cleared. Once this has called, the \code{user.data.or.owner} argument
will not be used again.

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}}}
\item{\code{user.data.or.owner}}{the \code{user.data} argument passed to \code{\link{gtkClipboardSetWithData}}, or
the \code{owner} argument passed to \code{\link{gtkClipboardSetWithOwner}}}
}


}
}}
\section{Signals}{\describe{\item{\code{owner-change(clipboard, event, user.data)}}{
The ::owner-change signal is emitted when GTK+ receives an
event that indicates that the ownership of the selection
associated with \code{clipboard} has changed.
  Since 2.6

\describe{
\item{\code{clipboard}}{the \code{\link{GtkClipboard}} on which the signal is emitted}
\item{\code{event}}{the \code{GdkEventOwnerChange} event}
\item{\code{user.data}}{user data set when the signal handler was connected.}
}


}}}
\references{\url{https://developer.gnome.org/gtk2/stable/gtk2-Clipboards.html}}
\author{Derived by RGtkGen from GTK+ documentation}
\keyword{internal}