libinftext-0.6 Reference Manual: InfTextBuffer

## InfTextBuffer InfTextBuffer — Interface for the text storage of an InfTextSession |

## Stability Level

Unstable, unless otherwise indicated

## Functions

const gchar * | inf_text_buffer_get_encoding ()
guint | inf_text_buffer_get_length ()
InfTextChunk * | inf_text_buffer_get_slice ()
void | inf_text_buffer_insert_text ()
void | inf_text_buffer_insert_chunk ()
void | inf_text_buffer_erase_text ()
InfTextBufferIter * | inf_text_buffer_create_begin_iter ()
InfTextBufferIter * | inf_text_buffer_create_end_iter ()
void | inf_text_buffer_destroy_iter ()
gboolean | inf_text_buffer_iter_next ()
gboolean | inf_text_buffer_iter_prev ()
gpointer | inf_text_buffer_iter_get_text ()
guint | inf_text_buffer_iter_get_offset ()
guint | inf_text_buffer_iter_get_length ()
gsize | inf_text_buffer_iter_get_bytes ()
guint | inf_text_buffer_iter_get_author ()
void | inf_text_buffer_text_inserted ()
void | inf_text_buffer_text_erased ()

## Signals

void | text-erased | Run First
void | text-inserted | Run First

## Types and Values

| InfTextBuffer
struct | InfTextBufferIface
| InfTextBufferIter

## Object Hierarchy

        GInterface
        ╰── InfTextBuffer

## Prerequisites

InfTextBuffer requires InfBuffer and GObject.

## Known Implementations

InfTextBuffer is implemented by InfTextDefaultBuffer and InfTextFixlineBuffer.

## Includes

    #include <libinftext/inf-text-buffer.h>

## Description

InfTextBuffer is an interface on top of InfBuffer which represents a text buffer in a similar way as GtkTextBuffer. InfTextBuffer can be used as the buffer of an InfTextSession, allowing the session to insert text written by remote users and access text written by local users and send it to everyone else.

See InfTextDefaultBuffer for a simple implementation based on InfTextChunk. However, in GUI collaborative editing clients this interface should be implemented in a more sophisticated way, such that the text of a document is not stored twice in memory. InfTextGtkBuffer does this for GTK+ based user interfaces.

## Functions

### inf_text_buffer_get_encoding ()

    const gchar *
    inf_text_buffer_get_encoding (InfTextBuffer *buffer);

Returns the character encoding that the buffer uses. This means that all InfTextChunk return values are encoded in this encoding and all InfTextChunk parameters are expected to be encoded in that encoding.

#### Parameters

buffer | A InfTextBuffer. |

#### Returns

The character encoding for `buffer` .

### inf_text_buffer_get_length ()

    guint
    inf_text_buffer_get_length (InfTextBuffer *buffer);

Returns the number of characters in `buffer` .

#### Parameters

buffer | A InfTextBuffer. |

#### Returns

The length of `buffer` .

### inf_text_buffer_get_slice ()

    InfTextChunk *
    inf_text_buffer_get_slice (InfTextBuffer *buffer,
                               guint pos,
                               guint len);

Reads `len` characters, starting at `pos` , from the buffer, and returns them as a InfTextChunk.

#### Parameters

buffer | A InfTextBuffer. |
pos | Character offset of where to start extracting. |
len | Number of characters to extract. |

#### Returns

A InfTextChunk.

### inf_text_buffer_insert_text ()

    void
    inf_text_buffer_insert_text (InfTextBuffer *buffer,
                                 guint pos,
                                 gconstpointer text,
                                 gsize bytes,
                                 guint len,
                                 InfUser *user);

Inserts `text` into `buffer` as written by `author` . `text` must be encoded in the character encoding of the buffer, see `inf_text_buffer_get_encoding()`.

#### Parameters

buffer | A InfTextBuffer. |
pos | A character offset into `buffer` . |
text | A pointer to the text to insert. |
bytes | The length (in bytes) of `text` . |
len | The length (in characters) of `text` . |
user | A InfUser that has inserted the new text, or `NULL`. |

### inf_text_buffer_insert_chunk ()

    void
    inf_text_buffer_insert_chunk (InfTextBuffer *buffer,
                                  guint pos,
                                  InfTextChunk *chunk,
                                  InfUser *user);

Inserts a InfTextChunk into `buffer` . `user` must not necessarily be the author of `chunk` (`chunk` may even consist of multiple segments). This happens when undoing a delete operation that erased another user's text.

#### Parameters

buffer | A InfTextBuffer. |
pos | A character offset into `buffer` . |
chunk | A InfTextChunk. |
user | A InfUser inserting `chunk` , or `NULL`. |

### inf_text_buffer_erase_text ()

    void
    inf_text_buffer_erase_text (InfTextBuffer *buffer,
                                guint pos,
                                guint len,
                                InfUser *user);

Erases characters from the text buffer.

#### Parameters

buffer | A InfTextBuffer. |
pos | The position to begin deleting characters from. |
len | The amount of characters to delete. |
user | A InfUser that erases the text, or `NULL`. |

### inf_text_buffer_create_begin_iter ()

    InfTextBufferIter *
    inf_text_buffer_create_begin_iter (InfTextBuffer *buffer);

Creates a InfTextBufferIter pointing to the first segment of `buffer` . A InfTextBufferIter is used to traverse the buffer contents in steps of so-called segments each of which is written by the same user. The function returns `NULL` if there are no segments (i.e. the buffer is empty).

The iterator stays valid as long as the buffer remains unmodified and must be freed with `inf_text_buffer_destroy_iter()` before.

#### Parameters

buffer | A InfTextBuffer. |

#### Returns

A InfTextBufferIter to be freed by `inf_text_buffer_destroy_iter()` when done using it, or `NULL`.

### inf_text_buffer_create_end_iter ()

    InfTextBufferIter *
    inf_text_buffer_create_end_iter (InfTextBuffer *buffer);

Creates a InfTextBufferIter pointing to the last segment of `buffer` . A InfTextBufferIter is used to traverse the buffer contents in steps of so-called segments each of which is written by the same user. The function returns `NULL` if there are no segments (i.e. the buffer is empty).

The iterator stays valid as long as the buffer remains unmodified and must be freed with `inf_text_buffer_destroy_iter()` before.

#### Parameters

buffer | A InfTextBuffer. |

#### Returns

A InfTextBufferIter to be freed by `inf_text_buffer_destroy_iter()` when done using it, or `NULL`.

### inf_text_buffer_destroy_iter ()

    void
    inf_text_buffer_destroy_iter (InfTextBuffer *buffer,
                                  InfTextBufferIter *iter);

Destroys a InfTextBufferIter created by `inf_text_buffer_create_begin_iter()` or `inf_text_buffer_create_end_iter()`.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

### inf_text_buffer_iter_next ()

    gboolean
    inf_text_buffer_iter_next (InfTextBuffer *buffer,
                               InfTextBufferIter *iter);

Moves `iter` to point to the next segment in the buffer. If `iter` already points to the last segment, `iter` is left unmodified and the function returns `FALSE`.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

Whether `iter` was moved.

### inf_text_buffer_iter_prev ()

    gboolean
    inf_text_buffer_iter_prev (InfTextBuffer *buffer,
                               InfTextBufferIter *iter);

Moves `iter` to point to the previous segment in the buffer. If `iter` already points to the first segment, `iter` is left unmodified and the function returns `FALSE`.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

Whether `iter` was moved.

### inf_text_buffer_iter_get_text ()

    gpointer
    inf_text_buffer_iter_get_text (InfTextBuffer *buffer,
                                   InfTextBufferIter *iter);

Returns the text of the segment `iter` points to. It is encoded in `buffer` 's encoding (see `inf_text_buffer_get_encoding()`).

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

The text of the segment `iter` points to. Free with `g_free()` when done using it.

### inf_text_buffer_iter_get_offset ()

    guint
    inf_text_buffer_iter_get_offset (InfTextBuffer *buffer,
                                     InfTextBufferIter *iter);

Returns the offset of the first character in the segment `iter` points to, in characters.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

The offset of the first character in the segment `iter` points to.

### inf_text_buffer_iter_get_length ()

    guint
    inf_text_buffer_iter_get_length (InfTextBuffer *buffer,
                                     InfTextBufferIter *iter);

Returns the length of the segment `iter` points to, in characters.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

The number of characters of the segment `iter` points to.

### inf_text_buffer_iter_get_bytes ()

    gsize
    inf_text_buffer_iter_get_bytes (InfTextBuffer *buffer,
                                    InfTextBufferIter *iter);

Returns the length of the segment `iter` points to, in bytes.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

The number of bytes of the segment `iter` points to.

### inf_text_buffer_iter_get_author ()

    guint
    inf_text_buffer_iter_get_author (InfTextBuffer *buffer,
                                     InfTextBufferIter *iter);

Returns the user ID of the user that has written the segment `iter` points to.

#### Parameters

buffer | A InfTextBuffer. |
iter | A InfTextBufferIter pointing into `buffer` . |

#### Returns

The user ID of the user that wrote the segment `iter` points to.

### inf_text_buffer_text_inserted ()

    void
    inf_text_buffer_text_inserted (InfTextBuffer *buffer,
                                   guint pos,
                                   InfTextChunk *chunk,
                                   InfUser *user);

Emits the “text-inserted” signal. This is meant to be used by interface implementations in their `insert_text` function, or when text was inserted by other means.

#### Parameters

buffer | A InfTextBuffer. |
pos | A character offset into `buffer` . |
chunk | A InfTextChunk. |
user | A InfUser inserting `chunk` , or `NULL`. |

### inf_text_buffer_text_erased ()

    void
    inf_text_buffer_text_erased (InfTextBuffer *buffer,
                                 guint pos,
                                 InfTextChunk *chunk,
                                 InfUser *user);

Emits the “text-erased” signal. This is meant to be used by interface implementations in their `erase_text` function, or when text was erased by other means.

#### Parameters

buffer | A InfTextBuffer. |
pos | The position to begin deleting characters from. |
chunk | A InfTextChunk containing the erased text. |
user | A InfUser that erases the text, or `NULL`. |

## Types and Values

### InfTextBuffer

    typedef struct _InfTextBuffer InfTextBuffer;

InfTextBuffer is an opaque data type. You should only access it via the public API functions.

### struct InfTextBufferIface

    struct InfTextBufferIface {
      /* Virtual table */
      const gchar* (*get_encoding)(InfTextBuffer* buffer);

      guint(*get_length)(InfTextBuffer* buffer);

      InfTextChunk*(*get_slice)(InfTextBuffer* buffer,
                                guint pos,
                                guint len);

      void(*insert_text)(InfTextBuffer* buffer,
                         guint pos,
                         InfTextChunk* chunk,
                         InfUser* user);

      void(*erase_text)(InfTextBuffer* buffer,
                        guint pos,
                        guint len,
                        InfUser* user);

      InfTextBufferIter*(*create_begin_iter)(InfTextBuffer* buffer);

      InfTextBufferIter*(*create_end_iter)(InfTextBuffer* buffer);

      void(*destroy_iter)(InfTextBuffer* buffer,
                          InfTextBufferIter* iter);

      gboolean(*iter_next)(InfTextBuffer* buffer,
                           InfTextBufferIter* iter);

      gboolean(*iter_prev)(InfTextBuffer* buffer,
                           InfTextBufferIter* iter);

      gpointer(*iter_get_text)(InfTextBuffer* buffer,
                               InfTextBufferIter* iter);

      guint(*iter_get_offset)(InfTextBuffer* buffer,
                              InfTextBufferIter* iter);

      guint(*iter_get_length)(InfTextBuffer* buffer,
                              InfTextBufferIter* iter);

      gsize(*iter_get_bytes)(InfTextBuffer* buffer,
                             InfTextBufferIter* iter);

      guint(*iter_get_author)(InfTextBuffer* buffer,
                              InfTextBufferIter* iter);

      /* Signals */
      void(*text_inserted)(InfTextBuffer* buffer,
                           guint pos,
                           InfTextChunk* chunk,
                           InfUser* user);

      void(*text_erased)(InfTextBuffer* buffer,
                         guint pos,
                         InfTextChunk* chunk,
                         InfUser* user);
    };

This structure contains virtual functions and signal handlers of the InfTextBuffer interface.

#### Members

`get_encoding` () | Virtual function which returns the character coding of the buffer. |
`get_length` () | Virtual function to return the total length of the text in the buffer, in characters. |
`get_slice` () | Virtual function to extract a slice of text from the buffer. |
`insert_text` () | Virtual function to insert text into the buffer. |
`erase_text` () | Virtual function to remove text from the buffer. |
`create_begin_iter` () | Virtual function to create a InfTextBufferIter at the beginning of the buffer, used for traversing through buffer segments. |
`create_end_iter` () | Virtual function to create a InfTextBufferIter at the end of the buffer, used for traversing through buffer segments. |
`destroy_iter` () | Virtual function to destroy an iterator created with the `create_begin_iter` and `create_end_iter` functions. |
`iter_next` () | Virtual function to advance a InfTextBufferIter to the next segment. |
`iter_prev` () | Virtual function to retreat a InfTextBufferIter to the previous segment. |
`iter_get_text` () | Virtual function to obtain the text of a segment a InfTextBufferIter points to. |
`iter_get_offset` () | Virtual function to obtain the offset of the first character in the segment a InfTextBufferIter points to. |
`iter_get_length` () | Virtual function to obtain the length of a segment a InfTextBufferIter points to. |
`iter_get_bytes` () | Virtual function to obtain the number of bytes in a segment a InfTextBufferIter points to. |
`iter_get_author` () | Virtual function to obtain the author of the segment a InfTextBufferIter points to. |
`text_inserted` () | Default signal handler of the “text-inserted” signal. |
`text_erased` () | Default signal handler of the “text-erased” signal. |

### InfTextBufferIter

    typedef struct _InfTextBufferIter InfTextBufferIter;

InfTextBufferIter is an opaque data type. You should only access it via the public API functions.

## Signal Details

### The `“text-erased”` signal

    void
    user_function (InfTextBuffer *inftextbuffer,
                   guint          arg1,
                   InfTextChunk  *arg2,
                   InfUser       *arg3,
                   gpointer       user_data)

#### Parameters

inftextbuffer | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“text-inserted”` signal

    void
    user_function (InfTextBuffer *inftextbuffer,
                   guint          arg1,
                   InfTextChunk  *arg2,
                   InfUser       *arg3,
                   gpointer       user_data)

#### Parameters

inftextbuffer | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run First

## See Also

InfTextDefaultBuffer