ClutterTextBuffer

## ClutterTextBuffer ClutterTextBuffer — Text buffer for ClutterText |

## Synopsis

    #define             CLUTTER_TEXT_BUFFER_MAX_SIZE
    struct              ClutterTextBuffer;
    struct              ClutterTextBufferClass;
    ClutterTextBuffer * clutter_text_buffer_new             (void);
    ClutterTextBuffer * clutter_text_buffer_new_with_text   (const gchar *text,
                                                             gssize text_len);
    void                clutter_text_buffer_set_text        (ClutterTextBuffer *buffer,
                                                             const gchar *chars,
                                                             gint n_chars);
    const gchar *       clutter_text_buffer_get_text        (ClutterTextBuffer *buffer);
    gsize               clutter_text_buffer_get_bytes       (ClutterTextBuffer *buffer);
    guint               clutter_text_buffer_get_length      (ClutterTextBuffer *buffer);
    void                clutter_text_buffer_set_max_length  (ClutterTextBuffer *buffer,
                                                             gint max_length);
    gint                clutter_text_buffer_get_max_length  (ClutterTextBuffer *buffer);
    guint               clutter_text_buffer_insert_text     (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             const gchar *chars,
                                                             gint n_chars);
    guint               clutter_text_buffer_delete_text     (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             gint n_chars);
    void                clutter_text_buffer_emit_inserted_text
                                                            (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             const gchar *chars,
                                                             guint n_chars);
    void                clutter_text_buffer_emit_deleted_text
                                                            (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             guint n_chars);

## Object Hierarchy

      GObject
       +----ClutterTextBuffer

## Properties

      "length"                   guint                 : Read
      "max-length"               gint                  : Read / Write
      "text"                     gchar*                : Read

## Signals

      "deleted-text"                                   : Run First
      "inserted-text"                                  : Run First

## Description

The ClutterTextBuffer class contains the actual text displayed in a ClutterText widget.

A single ClutterTextBuffer object can be shared by multiple ClutterText widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc.

ClutterTextBuffer may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application's concept of undo/redo.

## Details

### CLUTTER_TEXT_BUFFER_MAX_SIZE

    #define CLUTTER_TEXT_BUFFER_MAX_SIZE        G_MAXUSHORT

Maximum size of text buffer, in bytes.

Since 1.10

### struct ClutterTextBuffer

    struct ClutterTextBuffer;

The ClutterTextBuffer structure contains private data and it should only be accessed using the provided API.

Since 1.10

### struct ClutterTextBufferClass

    struct ClutterTextBufferClass {
      /* Signals */
      void         (*inserted_text)          (ClutterTextBuffer *buffer,
                                              guint              position,
                                              const gchar       *chars,
                                              guint              n_chars);

      void         (*deleted_text)           (ClutterTextBuffer *buffer,
                                              guint              position,
                                              guint              n_chars);

      /* Virtual Methods */
      const gchar* (*get_text)               (ClutterTextBuffer *buffer,
                                              gsize             *n_bytes);

      guint        (*get_length)             (ClutterTextBuffer *buffer);

      guint        (*insert_text)            (ClutterTextBuffer *buffer,
                                              guint              position,
                                              const gchar       *chars,
                                              guint              n_chars);

      guint        (*delete_text)            (ClutterTextBuffer *buffer,
                                              guint              position,
                                              guint              n_chars);
    };

The ClutterTextBufferClass structure contains only private data.

`inserted_text` () | default handler for the "inserted-text" signal
`deleted_text` () | default hanlder for the "deleted-text" signal
`get_text` () | virtual function
`get_length` () | virtual function
`insert_text` () | virtual function
`delete_text` () | virtual function

Since 1.10

### clutter_text_buffer_new ()

    ClutterTextBuffer * clutter_text_buffer_new             (void);

Create a new ClutterTextBuffer object.

Returns : | A new ClutterTextBuffer object.

Since 1.10

### clutter_text_buffer_new_with_text ()

    ClutterTextBuffer * clutter_text_buffer_new_with_text   (const gchar *text,
                                                             gssize text_len);

Create a new ClutterTextBuffer object with some text.

`text` : | initial buffer text. [allow-none]
`text_len` : | initial buffer text length, or -1 for null-terminated.
Returns : | A new ClutterTextBuffer object.

Since 1.10

### clutter_text_buffer_set_text ()

    void                clutter_text_buffer_set_text        (ClutterTextBuffer *buffer,
                                                             const gchar *chars,
                                                             gint n_chars);

Sets the text in the buffer.

This is roughly equivalent to calling `clutter_text_buffer_delete_text()` and `clutter_text_buffer_insert_text()`.

Note that `n_chars` is in characters, not in bytes.

`buffer` : | a ClutterTextBuffer
`chars` : | the new text
`n_chars` : | the number of characters in `text`, or -1

Since 1.10

### clutter_text_buffer_get_text ()

    const gchar *       clutter_text_buffer_get_text        (ClutterTextBuffer *buffer);

Retrieves the contents of the buffer.

The memory pointer returned by this call will not change unless this object emits a signal, or is finalized.

`buffer` : | a ClutterTextBuffer
Returns : | a pointer to the contents of the widget as a string. This string points to internally allocated storage in the buffer and must not be freed, modified or stored.

Since 1.10

### clutter_text_buffer_get_bytes ()

    gsize               clutter_text_buffer_get_bytes       (ClutterTextBuffer *buffer);

Retrieves the length in bytes of the buffer. See `clutter_text_buffer_get_length()`.

`buffer` : | a ClutterTextBuffer
Returns : | The byte length of the buffer.

Since 1.10

### clutter_text_buffer_get_length ()

    guint               clutter_text_buffer_get_length      (ClutterTextBuffer *buffer);

Retrieves the length in characters of the buffer.

`buffer` : | a ClutterTextBuffer
Returns : | The number of characters in the buffer.

Since 1.10

### clutter_text_buffer_set_max_length ()

    void                clutter_text_buffer_set_max_length  (ClutterTextBuffer *buffer,
                                                             gint max_length);

Sets the maximum allowed length of the contents of the buffer. If the current contents are longer than the given length, then they will be truncated to fit.

`buffer` : | a ClutterTextBuffer
`max_length` : | the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range [ 0, `CLUTTER_TEXT_BUFFER_MAX_SIZE` ].

Since 1.10

### clutter_text_buffer_get_max_length ()

    gint                clutter_text_buffer_get_max_length  (ClutterTextBuffer *buffer);

Retrieves the maximum allowed length of the text in `buffer`. See `clutter_text_buffer_set_max_length()`.

`buffer` : | a ClutterTextBuffer
Returns : | the maximum allowed number of characters in ClutterTextBuffer, or 0 if there is no maximum.

Since 1.10

### clutter_text_buffer_insert_text ()

    guint               clutter_text_buffer_insert_text     (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             const gchar *chars,
                                                             gint n_chars);

Inserts `n_chars` characters of `chars` into the contents of the buffer, at position `position`.

If `n_chars` is negative, then characters from chars will be inserted until a null-terminator is found. If `position` or `n_chars` are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values.

Note that the position and length are in characters, not in bytes.

`buffer` : | a ClutterTextBuffer
`position` : | the position at which to insert text.
`chars` : | the text to insert into the buffer.
`n_chars` : | the length of the text in characters, or -1
Returns : | The number of characters actually inserted.

Since 1.10

### clutter_text_buffer_delete_text ()

    guint               clutter_text_buffer_delete_text     (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             gint n_chars);

Deletes a sequence of characters from the buffer. `n_chars` characters are deleted starting at `position`. If `n_chars` is negative, then all characters until the end of the text are deleted.

If `position` or `n_chars` are out of bounds, then they are coerced to sane values.

Note that the positions are specified in characters, not bytes.

`buffer` : | a ClutterTextBuffer
`position` : | position at which to delete text
`n_chars` : | number of characters to delete
Returns : | The number of characters deleted.

Since 1.10

### clutter_text_buffer_emit_inserted_text ()

    void                clutter_text_buffer_emit_inserted_text
                                                            (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             const gchar *chars,
                                                             guint n_chars);

Emits the "inserted-text" signal on `buffer`.

Used when subclassing ClutterTextBuffer

`buffer` : | a ClutterTextBuffer
`position` : | position at which text was inserted
`chars` : | text that was inserted
`n_chars` : | number of characters inserted

Since 1.10

### clutter_text_buffer_emit_deleted_text ()

    void                clutter_text_buffer_emit_deleted_text
                                                            (ClutterTextBuffer *buffer,
                                                             guint position,
                                                             guint n_chars);

Emits the "deleted-text" signal on `buffer`.

Used when subclassing ClutterTextBuffer

`buffer` : | a ClutterTextBuffer
`position` : | position at which text was deleted
`n_chars` : | number of characters deleted

Since 1.10

## Property Details

### The `"length"` property

      "length"                   guint                 : Read

The length (in characters) of the text in buffer.

Allowed values: <= 65535

Default value: 0

Since 1.10

### The `"max-length"` property

      "max-length"               gint                  : Read / Write

The maximum length (in characters) of the text in the buffer.

Allowed values: [0,65535]

Default value: 0

Since 1.10

### The `"text"` property

      "text"                     gchar*                : Read

The contents of the buffer.

Default value: ""

Since 1.10

## Signal Details

### The `"deleted-text"` signal

    void                user_function                      (ClutterTextBuffer *buffer,
                                                            guint              position,
                                                            guint              n_chars,
                                                            gpointer           user_data)      : Run First

This signal is emitted after text is deleted from the buffer.

`buffer` : | a ClutterTextBuffer
`position` : | the position the text was deleted at.
`n_chars` : | The number of characters that were deleted.
`user_data` : | user data set when the signal handler was connected.

Since 1.10

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

    void                user_function                      (ClutterTextBuffer *buffer,
                                                            guint              position,
                                                            gchar             *chars,
                                                            guint              n_chars,
                                                            gpointer           user_data)      : Run First

This signal is emitted after text is inserted into the buffer.

`buffer` : | a ClutterTextBuffer
`position` : | the position the text was inserted at.
`chars` : | The text that was inserted.
`n_chars` : | The number of characters that were inserted.
`user_data` : | user data set when the signal handler was connected.

Since 1.10