mirror of https://github.com/Gnucash/gnucash
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
329 lines
17 KiB
329 lines
17 KiB
<refentry id="gsf-GsfClipData">
|
|
<refmeta>
|
|
<refentrytitle>GsfClipData</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>GSF Library</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>GsfClipData</refname><refpurpose>Object to hold clipboard data from a VT_CF section</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv><title>Synopsis</title>
|
|
|
|
<synopsis>
|
|
|
|
|
|
|
|
enum <link linkend="GsfClipFormat">GsfClipFormat</link>;
|
|
enum <link linkend="GsfClipFormatWindows">GsfClipFormatWindows</link>;
|
|
<link linkend="GsfClipData">GsfClipData</link>;
|
|
<link linkend="GsfClipDataClass">GsfClipDataClass</link>;
|
|
<link linkend="GsfClipData">GsfClipData</link>* <link linkend="gsf-clip-data-new">gsf_clip_data_new</link> (<link linkend="GsfClipFormat">GsfClipFormat</link> format,
|
|
<link linkend="GsfBlob">GsfBlob</link> *data_blob);
|
|
<link linkend="GsfClipFormat">GsfClipFormat</link> <link linkend="gsf-clip-data-get-format">gsf_clip_data_get_format</link> (<link linkend="GsfClipData">GsfClipData</link> *clip_data);
|
|
<link linkend="GsfBlob">GsfBlob</link>* <link linkend="gsf-clip-data-get-data-blob">gsf_clip_data_get_data_blob</link> (<link linkend="GsfClipData">GsfClipData</link> *clip_data);
|
|
<link linkend="GsfClipFormatWindows">GsfClipFormatWindows</link> <link linkend="gsf-clip-data-get-windows-clipboard-format">gsf_clip_data_get_windows_clipboard_format</link>
|
|
(<link linkend="GsfClipData">GsfClipData</link> *clip_data,
|
|
<link linkend="GError">GError</link> **error);
|
|
<link linkend="gconstpointer">gconstpointer</link> <link linkend="gsf-clip-data-peek-real-data">gsf_clip_data_peek_real_data</link> (<link linkend="GsfClipData">GsfClipData</link> *clip_data,
|
|
<link linkend="gsize">gsize</link> *ret_size,
|
|
<link linkend="GError">GError</link> **error);
|
|
|
|
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<para>
|
|
OLE2 files may contain clipboard data in the
|
|
<literal>VT_CF</literal> property of the metadata in a
|
|
<literal>SummaryInfo</literal> section. This data is used, among
|
|
other things, to represent a thumbnail or pre-rendered version of
|
|
the data in the file. <classname>GsfClipData</classname> is an
|
|
object that holds such clipboard data.
|
|
</para>
|
|
|
|
<para>
|
|
You can get a <classname>GsfClipData</classname> object from the
|
|
<link linkend="GValue"><type>GValue</type></link> returned by <link linkend="gsf-doc-prop-get-val"><function>gsf_doc_prop_get_val()</function></link>, after you have done
|
|
<literal>gsf_doc_meta_data_lookup (meta_data,
|
|
GSF_META_NAME_THUMBNAIL)</literal>. The resulting <link linkend="GsfClipData"><type>GsfClipData</type></link>
|
|
object, if it exists, contains the thumbnail data. In turn, the
|
|
thumbnail data may be in different formats, as specified by the
|
|
<link linkend="GsfClipFormat"><type>GsfClipFormat</type></link> enumeration.
|
|
</para>
|
|
|
|
<para>
|
|
Internally, <link linkend="GsfClipData"><type>GsfClipData</type></link> stores the thumbnail data plus any extra
|
|
information in a <link linkend="GsfBlob"><type>GsfBlob</type></link> object. <link linkend="GsfClipData"><type>GsfClipData</type></link> provides a
|
|
convenience function, <link linkend="gsf-clip-data-peek-real-data"><function>gsf_clip_data_peek_real_data()</function></link>, to extract
|
|
the thumbnail data directly. If you need to use the raw binary
|
|
data instead of the data specific to the thumbnail, you can use
|
|
<link linkend="gsf-clip-data-get-data-blob"><function>gsf_clip_data_get_data_blob()</function></link> to get the <link linkend="GsfBlob"><type>GsfBlob</type></link> object and
|
|
handle it yourself.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Details</title>
|
|
<refsect2>
|
|
<title><anchor id="GsfClipFormat"/>enum GsfClipFormat</title>
|
|
<indexterm><primary>GsfClipFormat</primary></indexterm><programlisting>typedef enum {
|
|
GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD = -1,
|
|
GSF_CLIP_FORMAT_MACINTOSH_CLIPBOARD = -2,
|
|
GSF_CLIP_FORMAT_GUID = -3,
|
|
GSF_CLIP_FORMAT_NO_DATA = 0,
|
|
GSF_CLIP_FORMAT_CLIPBOARD_FORMAT_NAME = 1, /* in the file it's actually any positive integer */
|
|
GSF_CLIP_FORMAT_UNKNOWN /* this is our own value for unknown types or invalid data */
|
|
} GsfClipFormat;
|
|
</programlisting>
|
|
<para>
|
|
A <link linkend="GsfClipData"><type>GsfClipData</type></link> stores all its thumbnail data and associated
|
|
information in an internal <link linkend="GsfBlob"><type>GsfBlob</type></link> object. The
|
|
<type>GsfClipFormat</type> enumeration represents the possible
|
|
formats for this data blob.
|
|
</para><variablelist role="enum">
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD</literal></term>
|
|
<listitem><simpara>The thumbnail data is stored in
|
|
Windows clipboard format. The particular sub-format can be in any of
|
|
the values in the <link linkend="GsfClipFormatWindows"><type>GsfClipFormatWindows</type></link> enumeration. When a
|
|
<link linkend="GsfClipData"><type>GsfClipData</type></link> is in <parameter>GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD</parameter>, you can use
|
|
<link linkend="gsf-clip-data-get-windows-clipboard-format"><function>gsf_clip_data_get_windows_clipboard_format()</function></link> to get the sub-format
|
|
in which the data is actually stored.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_MACINTOSH_CLIPBOARD</literal></term>
|
|
<listitem><simpara>The thumbnail data is stored in
|
|
Macintosh clipboard format, usually PICT.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_GUID</literal></term>
|
|
<listitem><simpara>The thumbnail data contains a GUID specifying
|
|
the OLE component which can be used to render it. Please refer to
|
|
the OLE2 format documentation for details.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_NO_DATA</literal></term>
|
|
<listitem><simpara>There is no thumbnail data.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_CLIPBOARD_FORMAT_NAME</literal></term>
|
|
<listitem><simpara>The thumbnail data contains a
|
|
null-terminated string with a Windows clipboard format name. Please refer to
|
|
the OLE2 format documentation for details.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_UNKNOWN</literal></term>
|
|
<listitem><simpara>The thumbnail data is in an unknown format,
|
|
but is nevertheless stored in a <link linkend="GsfBlob"><type>GsfBlob</type></link>.
|
|
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="GsfClipFormatWindows"/>enum GsfClipFormatWindows</title>
|
|
<indexterm><primary>GsfClipFormatWindows</primary></indexterm><programlisting>typedef enum {
|
|
GSF_CLIP_FORMAT_WINDOWS_ERROR = -1, /* our own value */
|
|
GSF_CLIP_FORMAT_WINDOWS_UNKNOWN = -2, /* our own value */
|
|
GSF_CLIP_FORMAT_WINDOWS_METAFILE = 3, /* CF_METAFILEPICT */
|
|
GSF_CLIP_FORMAT_WINDOWS_DIB = 8, /* CF_DIB */
|
|
GSF_CLIP_FORMAT_WINDOWS_ENHANCED_METAFILE = 14 /* CF_ENHMETAFILE */
|
|
} GsfClipFormatWindows;
|
|
</programlisting>
|
|
<para>
|
|
When a <link linkend="GsfClipData"><type>GsfClipData</type></link> is in GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD
|
|
format, it can be in any of the subformats specified by the
|
|
<type>GsfClipFormatWindows</type> enumeration. Use
|
|
<link linkend="gsf-clip-data-get-windows-clipboard-format"><function>gsf_clip_data_get_windows_clipboard_format()</function></link> to determine this
|
|
sub-format.
|
|
</para>
|
|
|
|
<para>
|
|
For all of these values, the <link linkend="gsf-clip-data-peek-real-data"><function>gsf_clip_data_peek_real_data()</function></link>
|
|
function lets you access the data directly.
|
|
</para><variablelist role="enum">
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_ERROR</literal></term>
|
|
<listitem><simpara>The OLE file is probably corrupt.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_UNKNOWN</literal></term>
|
|
<listitem><simpara>The specific clipboard format is
|
|
unknown to libgsf.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_METAFILE</literal></term>
|
|
<listitem><simpara>The data is in Windows Metafile
|
|
format. While OLE files store extra header data in this case, the
|
|
<link linkend="gsf-clip-data-peek-real-data"><function>gsf_clip_data_peek_real_data()</function></link> function will let you access the WMF
|
|
data directly, and it will ignore the extra header bytes.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_DIB</literal></term>
|
|
<listitem><simpara>The data is in Windows
|
|
Device-Independent Bitmap format.
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><literal>GSF_CLIP_FORMAT_WINDOWS_ENHANCED_METAFILE</literal></term>
|
|
<listitem><simpara>The data is in Windows
|
|
Enhanced Metaflie format.
|
|
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="GsfClipData"/>GsfClipData</title>
|
|
<indexterm><primary>GsfClipData</primary></indexterm><programlisting>typedef struct {
|
|
GObject object;
|
|
|
|
GsfClipDataPrivate *priv;
|
|
} GsfClipData;
|
|
</programlisting>
|
|
<para>
|
|
Object used to represent a VT_CF property in the OLE stream.
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="GsfClipDataClass"/>GsfClipDataClass</title>
|
|
<indexterm><primary>GsfClipDataClass</primary></indexterm><programlisting>typedef struct {
|
|
GObjectClass parent_class;
|
|
} GsfClipDataClass;
|
|
</programlisting>
|
|
<para>
|
|
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gsf-clip-data-new"/>gsf_clip_data_new ()</title>
|
|
<indexterm><primary>gsf_clip_data_new</primary></indexterm><programlisting><link linkend="GsfClipData">GsfClipData</link>* gsf_clip_data_new (<link linkend="GsfClipFormat">GsfClipFormat</link> format,
|
|
<link linkend="GsfBlob">GsfBlob</link> *data_blob);</programlisting>
|
|
<para>
|
|
Creates a new <link linkend="GsfClipData"><type>GsfClipData</type></link> object. This function acquires a reference to the
|
|
<parameter>data_blob</parameter>, so you should unref the blob on your own if you no longer need it
|
|
directly.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>format</parameter> :</term>
|
|
<listitem><simpara> Format for the data inside the <parameter>data_blob</parameter>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>data_blob</parameter> :</term>
|
|
<listitem><simpara> Object which holds the binary contents for the <link linkend="GsfClipData"><type>GsfClipData</type></link>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A newly-created <link linkend="GsfClipData"><type>GsfClipData</type></link>.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gsf-clip-data-get-format"/>gsf_clip_data_get_format ()</title>
|
|
<indexterm><primary>gsf_clip_data_get_format</primary></indexterm><programlisting><link linkend="GsfClipFormat">GsfClipFormat</link> gsf_clip_data_get_format (<link linkend="GsfClipData">GsfClipData</link> *clip_data);</programlisting>
|
|
<para>
|
|
Queries the clipboard data format of a <link linkend="GsfClipData"><type>GsfClipData</type></link>. The format refers to the data
|
|
blob inside the <parameter>clip_data</parameter>; use <link linkend="gsf-clip-data-get-data-blob"><function>gsf_clip_data_get_data_blob()</function></link> to get that data blob.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>clip_data</parameter> :</term>
|
|
<listitem><simpara> A <link linkend="GsfClipData"><type>GsfClipData</type></link>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The format in which the <link linkend="GsfClipData"><type>GsfClipData</type></link>'s data blob is stored.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gsf-clip-data-get-data-blob"/>gsf_clip_data_get_data_blob ()</title>
|
|
<indexterm><primary>gsf_clip_data_get_data_blob</primary></indexterm><programlisting><link linkend="GsfBlob">GsfBlob</link>* gsf_clip_data_get_data_blob (<link linkend="GsfClipData">GsfClipData</link> *clip_data);</programlisting>
|
|
<para>
|
|
Queries the data blob that actually stores a <link linkend="GsfClipData"><type>GsfClipData</type></link>'s binary data.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>clip_data</parameter> :</term>
|
|
<listitem><simpara> A <link linkend="GsfClipData"><type>GsfClipData</type></link>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A new reference to the <link linkend="GsfBlob"><type>GsfBlob</type></link> that stores this <parameter>clip_data</parameter>'s
|
|
binary data. You must use <link linkend="g-object-unref"><function>g_object_unref()</function></link> to dispose of that data blob when
|
|
you are done with it.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gsf-clip-data-get-windows-clipboard-format"/>gsf_clip_data_get_windows_clipboard_format ()</title>
|
|
<indexterm><primary>gsf_clip_data_get_windows_clipboard_format</primary></indexterm><programlisting><link linkend="GsfClipFormatWindows">GsfClipFormatWindows</link> gsf_clip_data_get_windows_clipboard_format
|
|
(<link linkend="GsfClipData">GsfClipData</link> *clip_data,
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
|
<para>
|
|
Queries the Windows clipboard data format for a <link linkend="GsfClipData"><type>GsfClipData</type></link>. The <parameter>clip_data</parameter> must
|
|
have been created with <link linkend="GSF-CLIP-FORMAT-WINDOWS-CLIPBOARD:CAPS"><type>GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD</type></link>.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>clip_data</parameter> :</term>
|
|
<listitem><simpara> A <link linkend="GsfClipData"><type>GsfClipData</type></link>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
|
<listitem><simpara> Location to store error, or <literal>NULL</literal>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> A <link linkend="GsfClipFormatWindows"><type>GsfClipFormatWindows</type></link> value.
|
|
|
|
Possible errors: <link linkend="GSF-ERROR-INVALID-DATA:CAPS"><type>GSF_ERROR_INVALID_DATA</type></link> if the data blob in the <parameter>clip_data</parameter> is
|
|
smaller than it should be; in this case GSF_CLIP_FORMAT_WINDOWS_ERROR will be returned.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gsf-clip-data-peek-real-data"/>gsf_clip_data_peek_real_data ()</title>
|
|
<indexterm><primary>gsf_clip_data_peek_real_data</primary></indexterm><programlisting><link linkend="gconstpointer">gconstpointer</link> gsf_clip_data_peek_real_data (<link linkend="GsfClipData">GsfClipData</link> *clip_data,
|
|
<link linkend="gsize">gsize</link> *ret_size,
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
|
<para>
|
|
Queries a pointer directly to the clipboard data of a <link linkend="GsfClipData"><type>GsfClipData</type></link>. The
|
|
resulting pointer is not necessarily the same data pointer that was passed to
|
|
<link linkend="gsf-blob-new"><function>gsf_blob_new()</function></link> prior to creating the <parameter>clip_data</parameter>. For example, if the data is
|
|
in <link linkend="GSF-CLIP-FORMAT-WINDOWS-CLIPBOARD:CAPS"><type>GSF_CLIP_FORMAT_WINDOWS_CLIPBOARD</type></link> format, then it will have extra header
|
|
bytes in front of the actual metafile data. This function will skip over
|
|
those header bytes if necessary and return a pointer to the "real" data.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>clip_data</parameter> :</term>
|
|
<listitem><simpara> A <link linkend="GsfClipData"><type>GsfClipData</type></link>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>ret_size</parameter> :</term>
|
|
<listitem><simpara> Location to return the size of the returned data buffer.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
|
<listitem><simpara> Location to store error, or <literal>NULL</literal>.
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Pointer to the real clipboard data. The size in bytes of this
|
|
buffer is returned in the <parameter>ret_size</parameter> argument.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para>
|
|
<link linkend="GsfBlob"><type>GsfBlob</type></link>, <link linkend="GsfDocMetaData"><type>GsfDocMetaData</type></link>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|