## inf-text-buffer inf-text-buffer |

## Synopsis

                        InfTextBuffer;
    struct              InfTextBufferIface;
                        InfTextBufferIter;
    const gchar *       inf_text_buffer_get_encoding        (InfTextBuffer *buffer);
    guint               inf_text_buffer_get_length          (InfTextBuffer *buffer);
    InfTextChunk *      inf_text_buffer_get_slice           (InfTextBuffer *buffer,
                                                             guint pos,
                                                             guint len);
    void                inf_text_buffer_insert_text         (InfTextBuffer *buffer,
                                                             guint pos,
                                                             gconstpointer text,
                                                             gsize bytes,
                                                             guint len,
                                                             InfUser *user);
    void                inf_text_buffer_insert_chunk        (InfTextBuffer *buffer,
                                                             guint pos,
                                                             InfTextChunk *chunk,
                                                             InfUser *user);
    void                inf_text_buffer_erase_text          (InfTextBuffer *buffer,
                                                             guint pos,
                                                             guint len,
                                                             InfUser *user);
    InfTextBufferIter * inf_text_buffer_create_iter         (InfTextBuffer *buffer);
    void                inf_text_buffer_destroy_iter        (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    gboolean            inf_text_buffer_iter_next           (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    gboolean            inf_text_buffer_iter_prev           (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    gpointer            inf_text_buffer_iter_get_text       (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    guint               inf_text_buffer_iter_get_length     (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    gsize               inf_text_buffer_iter_get_bytes      (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    guint               inf_text_buffer_iter_get_author     (InfTextBuffer *buffer,
                                                             InfTextBufferIter *iter);
    void                inf_text_buffer_text_inserted       (InfTextBuffer *buffer,
                                                             guint pos,
                                                             InfTextChunk *chunk,
                                                             InfUser *user);
    void                inf_text_buffer_text_erased         (InfTextBuffer *buffer,
                                                             guint pos,
                                                             InfTextChunk *chunk,
                                                             InfUser *user);

## Object Hierarchy

      GInterface
       +----InfTextBuffer

## Prerequisites

InfTextBuffer requires InfBuffer and GObject.

## Known Implementations

InfTextBuffer is implemented by InfTextDefaultBuffer.

## Signals

      "text-erased"                                    : Run First
      "text-inserted"                                  : Run First

## Description

## Details

### InfTextBuffer

    typedef struct _InfTextBuffer InfTextBuffer;

### struct InfTextBufferIface

    struct InfTextBufferIface {
      GTypeInterface parent;

      /* 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_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_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);
    };

### InfTextBufferIter

    typedef struct _InfTextBufferIter InfTextBufferIter;

### 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.

`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`.

`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.

`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()`.

`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.

`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.

`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_iter ()

    InfTextBufferIter * inf_text_buffer_create_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.

`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_iter()`.

`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`.

`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`.

`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()`).

`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_length ()

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

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

`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.

`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.

`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.

`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.

`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`.

## Signal Details

### The `"text-erased"` signal

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

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

### The `"text-inserted"` signal

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

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