RTF tools

RTF tools — Tools for reading and writing Rich Text Format

Stability Level

Unstable, unless otherwise indicated

Functions

Types and Values

enum RtfError
#define RTF_ERROR

Includes

#include <osxcart/rtf.h>

Description

Rich Text Format is a file format for storing marked-up text. It has been around for more than twenty years at the time of writing, but is still used as a native format by various programs and controls on Mac OS X, Windows, and NeXTSTEP.

For more information, see the Wikipedia page on RTF.

Functions

rtf_error_quark ()

GQuark
rtf_error_quark (void);

The error domain for RTF serializer errors.

Returns

The string rtf-error-quark as a

GQuark.

[transfer none]


rtf_register_serialize_format ()

GdkAtom
rtf_register_serialize_format (GtkTextBuffer *buffer);

Registers the RTF text serialization format with buffer . This allows the contents of buffer to be exported to Rich Text Format (MIME type text/rtf).

Parameters

buffer

a text buffer

 

Returns

a GdkAtom representing the serialization format, to be passed to gtk_text_buffer_serialize().

[transfer none]


rtf_register_deserialize_format ()

GdkAtom
rtf_register_deserialize_format (GtkTextBuffer *buffer);

Registers the RTF text deserialization format with buffer . This allows Rich Text Format files to be imported into buffer . See rtf_register_serialize_format().

Parameters

buffer

a text buffer

 

Returns

a GdkAtom representing the deserialization format, to be passed to gtk_text_buffer_deserialize().

[transfer none]


rtf_text_buffer_import_file ()

gboolean
rtf_text_buffer_import_file (GtkTextBuffer *buffer,
                             GFile *file,
                             GCancellable *cancellable,
                             GError **error);

Deserializes the contents of file to buffer . Only a small subset of RTF features are supported: those corresponding to features of GtkTextBuffer or those that can be emulated in a GtkTextBuffer. All unsupported features are ignored.

This function automatically registers the RTF deserialization format and deregisters it afterwards, so there is no need to call rtf_register_deserialize_format().

This function also supports OS X and NeXTSTEP's RTFD packages. If filename ends in .rtfd, is a directory, and contains a file called TXT.rtf, then it is assumed to be an RTFD package.

If cancellable is triggered from another thread, the operation is cancelled.

Parameters

buffer

the text buffer into which to import text

 

file

a GFile pointing to an RTF text file

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

return location for an error, or NULL

 

Returns

TRUE if the operation was successful, FALSE if not, in which case error is set.

Since: 1.1


rtf_text_buffer_import ()

gboolean
rtf_text_buffer_import (GtkTextBuffer *buffer,
                        const gchar *filename,
                        GError **error);

Deserializes the contents of filename to buffer . For more information, see rtf_text_buffer_import_file().

Parameters

buffer

the text buffer into which to import text

 

filename

path to an RTF text file

 

error

return location for an error, or NULL

 

Returns

TRUE if the operation was successful, FALSE if not, in which case error is set.


rtf_text_buffer_import_from_string ()

gboolean
rtf_text_buffer_import_from_string (GtkTextBuffer *buffer,
                                    const gchar *string,
                                    GError **error);

Deserializes the contents of string to buffer . See rtf_text_buffer_import_file() for details.

If string contains references to external files, such as images, then these will be resolved relative to the current working directory. That's usually not what you want. If you want to load images, then you must change the current working directory appropriately before calling this function, or embed the images in the RTF code, or use rtf_text_buffer_import() or rtf_text_buffer_import_file().

Parameters

buffer

the text buffer into which to import text

 

string

a string containing an RTF document

 

error

return location for an error, or NULL

 

Returns

TRUE if the operation was successful, FALSE if not, in which case error is set.


rtf_text_buffer_export_file ()

gboolean
rtf_text_buffer_export_file (GtkTextBuffer *buffer,
                             GFile *file,
                             GCancellable *cancellable,
                             GError **error);

Serializes the contents of buffer to an RTF text file, file . Any formatting and embedded pixbufs in buffer are preserved, but embedded widgets will not be. If the buffer was imported from RTF text written by another application, the result will be quite different; none of the advanced formatting features that RTF is capable of representing, such as styles, are preserved across loading and saving.

This function automatically registers the RTF serialization format and deregisters it afterwards, so there is no need to call rtf_register_serialize_format().

The operation can be cancelled by triggering cancellable from another thread.

Parameters

buffer

the text buffer to export

 

file

a GFile to export to

 

cancellable

optional GCancellable object, or NULL.

[allow-none]

error

return location for an error, or NULL

 

Returns

TRUE if the operation succeeded, FALSE if not, in which case error is set.

Since: 1.1


rtf_text_buffer_export ()

gboolean
rtf_text_buffer_export (GtkTextBuffer *buffer,
                        const gchar *filename,
                        GError **error);

Serializes the contents of buffer to an RTF text file, filename . See rtf_text_buffer_export_file() for more information.

Parameters

buffer

the text buffer to export

 

filename

a filename to export to

 

error

return location for an error, or NULL

 

Returns

TRUE if the operation succeeded, FALSE if not, in which case error is set.


rtf_text_buffer_export_to_string ()

gchar *
rtf_text_buffer_export_to_string (GtkTextBuffer *buffer);

Serializes the contents of buffer to a string in RTF format. See rtf_text_buffer_export() for details.

Parameters

buffer

the text buffer to export

 

Returns

a string containing RTF text. The string must be freed with g_free() when you are done with it.

Types and Values

enum RtfError

The different codes which can be thrown in the RTF_ERROR domain.

Members

RTF_ERROR_FAILED

A generic error.

 

RTF_ERROR_INVALID_RTF

The file was not correct RTF.

 

RTF_ERROR_MISSING_PARAMETER

A numerical parameter was missing from a control word which requires one.

 

RTF_ERROR_MISSING_BRACE

Not all groups were closed before the end of the file.

 

RTF_ERROR_EXTRA_CHARACTERS

There was junk after the last '}'.

 

RTF_ERROR_BAD_VERSION

The RTF file was an incompatible version.

 

RTF_ERROR_UNDEFINED_COLOR

A color was used which was not defined in the color table.

 

RTF_ERROR_UNDEFINED_FONT

A font was used which was not defined in the font table.

 

RTF_ERROR_UNDEFINED_STYLE

A style was used which was not defined in the stylesheet.

 

RTF_ERROR_BAD_HEX_CODE

Incorrect characters were encountered when expecting hexadecimal digits (0-9, A-F)

 

RTF_ERROR_BAD_PICT_TYPE

An invalid type of bitmap was specified.

 

RTF_ERROR_BAD_FONT_SIZE

A negative font size was specified.

 

RTF_ERROR_UNSUPPORTED_CHARSET

A character set with no iconv equivalent was specified.

 

RTF_ERROR

#define RTF_ERROR rtf_error_quark()

The domain of errors raised by RTF processing in Osxcart.