libinftextgtk-0.6 Reference Manual: InfTextGtkBuffer

## InfTextGtkBuffer InfTextGtkBuffer — Synchronizing a text session with a GtkTextBuffer |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfTextGtkBuffer * | inf_text_gtk_buffer_new ()
GtkTextBuffer * | inf_text_gtk_buffer_get_text_buffer ()
void | inf_text_gtk_buffer_set_active_user ()
InfTextUser * | inf_text_gtk_buffer_get_active_user ()
InfTextUser * | inf_text_gtk_buffer_get_author ()
InfTextUser * | inf_text_gtk_buffer_get_user_for_tag ()
gboolean | inf_text_gtk_buffer_is_author_toggle ()
gboolean | inf_text_gtk_buffer_forward_to_author_toggle ()
gboolean | inf_text_gtk_buffer_backward_to_author_toggle ()
void | inf_text_gtk_buffer_set_wake_on_cursor_movement ()
gboolean | inf_text_gtk_buffer_get_wake_on_cursor_movement ()
void | inf_text_gtk_buffer_ensure_author_tags_priority ()
void | inf_text_gtk_buffer_set_saturation_value ()
void | inf_text_gtk_buffer_set_fade ()
gdouble | inf_text_gtk_buffer_get_saturation ()
gdouble | inf_text_gtk_buffer_get_value ()
void | inf_text_gtk_buffer_set_show_user_colors ()
gboolean | inf_text_gtk_buffer_get_show_user_colors ()
void | inf_text_gtk_buffer_show_user_colors ()

## Properties

InfTextUser * | active-user | Read / Write
gdouble | alpha | Read / Write
GdkColor * | background | Read / Write
GtkTextBuffer * | buffer | Read / Write / Construct Only
gdouble | saturation | Read / Write
gboolean | show-user-colors | Read / Write
InfUserTable * | user-table | Read / Write / Construct Only
gdouble | value | Read / Write
gboolean | wake-on-cursor-movement | Read / Write

## Types and Values

struct | InfTextGtkBuffer
struct | InfTextGtkBufferClass

## Object Hierarchy

        GObject
        ╰── InfTextGtkBuffer

## Implemented Interfaces

InfTextGtkBuffer implements InfBuffer and InfTextBuffer.

## Includes

    #include <libinftextgtk/inf-text-gtk-buffer.h>

## Description

InfTextGtkBuffer is an implementation of the InfTextBuffer interface. It can therefore be used as a backend for InfTextSessions to store their text. The buffer is implemented by using a GtkTextBuffer as storage. This way the text document can be displayed using a GtkTextView such that only one copy of the text is held in memory, which is used both by the user interface toolkit and the text synchronization functionality.

If external changes are made to the GtkTextBuffer, for example by a user typing into a GtkTextView, then the text is synchronized to other participants of the session. For this purpose, `inf_text_gtk_buffer_set_active_user()` should be called with a user that was previously joined into the session using `inf_session_proxy_join_user()`. If there is no local user in the session, no modifications to the buffer must be made because they cannot be synchronized to other participants.

This class also takes care of setting background colors for the text to indicate which user wrote what text, by adding corresponding GtkTextTags to the document. The function `inf_text_gtk_buffer_set_show_user_colors()` to turn on or off the colored background. Even if background coloring is turned off, the text is still tagged according to the authorship, so that coloring can be turned on at a later point or so that the authorship can still be queried for other means, such as in a "blame" kind of functionality.

## Functions

### inf_text_gtk_buffer_new ()

    InfTextGtkBuffer *
    inf_text_gtk_buffer_new (GtkTextBuffer *buffer,
                             InfUserTable *user_table);

Creates a new InfTextGtkBuffer wrapping `buffer` . It implements the InfTextBuffer interface by using `buffer` to store the text. User colors are read from the users from `user_table` .

#### Parameters

buffer | The underlaying GtkTextBuffer. |
user_table | The InfUserTable containing the participating users. |

#### Returns

A InfTextGtkBuffer.

### inf_text_gtk_buffer_get_text_buffer ()

    GtkTextBuffer *
    inf_text_gtk_buffer_get_text_buffer (InfTextGtkBuffer *buffer);

Returns the underlaying GtkTextBuffer.

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

A GtkTextBuffer.

### inf_text_gtk_buffer_set_active_user ()

    void
    inf_text_gtk_buffer_set_active_user (InfTextGtkBuffer *buffer,
                                         InfTextUser *user);

Sets the active user for `buffer` . The active user is the user by which edits not issued through the InfTextBuffer interface are performed (for example, edits by the user when the underlaying buffer is displayed in a GtkTextView).

Note that such modifications should not be performed when no active user is set. Note also the active user must be available and have the `INF_USER_LOCAL` flag set.

#### Parameters

buffer | A InfTextGtkBuffer. |
user | A InfTextUser, or `NULL`. |

### inf_text_gtk_buffer_get_active_user ()

    InfTextUser *
    inf_text_gtk_buffer_get_active_user (InfTextGtkBuffer *buffer);

Returns the current active user for `buffer` .

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

A InfTextUser.

### inf_text_gtk_buffer_get_author ()

    InfTextUser *
    inf_text_gtk_buffer_get_author (InfTextGtkBuffer *buffer,
                                    GtkTextIter *location);

Returns the InfTextUser which wrote the character at `location` . If there is no such user, then `NULL` is returned.

#### Parameters

buffer | A InfTextGtkBuffer. |
location | A GtkTextIter which is not the end iterator. |

#### Returns

A InfTextUser, or `NULL`.

### inf_text_gtk_buffer_get_user_for_tag ()

    InfTextUser *
    inf_text_gtk_buffer_get_user_for_tag (InfTextGtkBuffer *buffer,
                                          GtkTextTag *tag);

If `tag` is an author tag, i.e. used by `buffer` to mark text that a certain user has written, then this function returns the InfTextUser whose text is marked by `tag` . If `tag` is not an author tag then the function returns `NULL`.

#### Parameters

buffer | A InfTextGtkBuffer. |
tag | A GtkTextTag from `buffer` 's underlying GtkTextBuffer's tag table. |

#### Returns

A InfTextUser, or `NULL`.

### inf_text_gtk_buffer_is_author_toggle ()

    gboolean
    inf_text_gtk_buffer_is_author_toggle (InfTextGtkBuffer *buffer,
                                          const GtkTextIter *iter,
                                          InfTextUser **user_on,
                                          InfTextUser **user_off);

This function returns `TRUE` if the author of the text in `buffer` changes at `iter` , or `FALSE` otherwise. If it returns `TRUE`, then the user who authored the text to the right hand side of `iter` is stored in `user_on` (if non-`NULL`) and the author of the text to the left hand side of `iter` is stored in `user_off` (if non-`NULL`). Both can also be set to `NULL` if there is unowned text in the buffer or if `iter` is at the start or end of the buffer.

#### Parameters

buffer | A InfTextGtkBuffer. |
iter | A GtkTextIter pointing into `buffer` 's underlying GtkTextBuffer. |
user_on | A location to store a InfTextUser, or `NULL`. |
user_off | Another location to store a InfTextUser, or `NULL`. |

#### Returns

Whether text attribution changes at `iter` .

### inf_text_gtk_buffer_forward_to_author_toggle ()

    gboolean
    inf_text_gtk_buffer_forward_to_author_toggle
                                   (InfTextGtkBuffer *buffer,
                                    GtkTextIter *iter,
                                    InfTextUser **user_on,
                                    InfTextUser **user_off);

Moves `iter` to the next point in `buffer` 's underlying GtkTextBuffer where the text has been written by another user. If `iter` points to the end of the buffer, then the function does nothing and returns `FALSE`. Otherwise it returns `TRUE` and sets `user_on` to the user which has written the text on the right hand side of the location `iter` has been moved to (if non-`NULL`) and `user_off` to the user which has written the left hand side of the location `iter` has been moved to.

#### Parameters

buffer | A InfTextGtkBuffer. |
iter | A GtkTextIter pointing into `buffer` 's underlying GtkTextBuffer. |
user_on | A location to store a InfTextUser, or `NULL`. |
user_off | Another location to store a InfTextUser, or `NULL`. |

#### Returns

`TRUE` if `iter` was moved, or `FALSE` otherwise.

### inf_text_gtk_buffer_backward_to_author_toggle ()

    gboolean
    inf_text_gtk_buffer_backward_to_author_toggle
                                   (InfTextGtkBuffer *buffer,
                                    GtkTextIter *iter,
                                    InfTextUser **user_on,
                                    InfTextUser **user_off);

Moves `iter` to the previous point in `buffer` 's underlying GtkTextBuffer where the text has been written by another user. If `iter` points to the beginning of the buffer, then the function does nothing and returns `FALSE`. Otherwise it returns `TRUE` and sets `user_on` to the user which has written the text on the right hand side of the location `iter` has been moved to (if non-`NULL`) and `user_off` to the user which has written the left hand side of the location `iter` has been moved to.

#### Parameters

buffer | A InfTextGtkBuffer. |
iter | A GtkTextIter pointing into `buffer` 's underlying GtkTextBuffer. |
user_on | A location to store a InfTextUser, or `NULL`. |
user_off | Another location to store a InfTextUser, or `NULL`. |

#### Returns

`TRUE` if `iter` was moved, or `FALSE` otherwise.

### inf_text_gtk_buffer_set_wake_on_cursor_movement ()

    void
    inf_text_gtk_buffer_set_wake_on_cursor_movement
                                   (InfTextGtkBuffer *buffer,
                                    gboolean wake);

This function spcecifies whether movement of the insertion point or selection bound of the underlying text buffer causes the active user (see `inf_text_gtk_buffer_set_active_user()`) to become active when its status is `INF_USER_INACTIVE`.

If `wake` is `TRUE`, then the user status changes to `INF_USER_ACTIVE` in that case. If `wake` is `FALSE`, then the user status stays `INF_USER_INACTIVE`, and its caret-position and selection-length properties will be no longer be synchronized to the buffer marks until the user is set active again.

#### Parameters

buffer | A InfTextGtkBuffer. |
wake | Whether to make inactive users active on cursor movement. |

### inf_text_gtk_buffer_get_wake_on_cursor_movement ()

    gboolean
    inf_text_gtk_buffer_get_wake_on_cursor_movement
                                   (InfTextGtkBuffer *buffer);

Returns whether movement of the insertion point or selection bound of the underlying text buffer causes whether the active user (see `inf_text_gtk_buffer_set_active_user()`) to become active when its status is `INF_USER_INACTIVE`. See also `inf_text_gtk_buffer_set_wake_on_cursor_movement()`.

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

Whether to make inactive users active when the insertion mark is moved.

### inf_text_gtk_buffer_ensure_author_tags_priority ()

    void
    inf_text_gtk_buffer_ensure_author_tags_priority
                                   (InfTextGtkBuffer *buffer);

Ensures that all author tags have the lowest priority of all tags in the underlying GtkTextBuffer's tag table. Normally you do not need to use this function if you do not set the priority for your tags explicitely. However, if you do (or are forced to do, because you are using a library that does this, such as GtkSourceView), then you can call this function afterwards to make sure all the user tags have the lowest priority.

#### Parameters

buffer | A InfTextGtkBuffer. |

### inf_text_gtk_buffer_set_saturation_value ()

    void
    inf_text_gtk_buffer_set_saturation_value
                                   (InfTextGtkBuffer *buffer,
                                    gdouble saturation,
                                    gdouble value);

Sets the saturation and value to use for user colors in a HSV color model. The hue is defined by each user's individual color. The reason why S and V are set locally the same for all users is that they can be adjusted depending on one's theme: Dark themes want dark user colors, bright themes want bright ones.

#### Parameters

buffer | A InfTextGtkBuffer. |
saturation | Saturation to use for user colors. |
value | Value to use for user colors. |

### inf_text_gtk_buffer_set_fade ()

    void
    inf_text_gtk_buffer_set_fade (InfTextGtkBuffer *buffer,
                                  gdouble alpha,
                                  const GdkColor *background);

This functions can be used to mix the user background color with another background color, `background` . Usually `background` is meant to be set to the background color of the GtkTextView showing the buffer.

An `alpha` value of 1.0 means to fully show the user background color, a value of 0.0 means to show the given background color. Values inbetween interpolate linearly between the two colors in RGB color space.

The default value for `alpha` is 1.0.

#### Parameters

buffer | A InfTextGtkBuffer. |
alpha | An alpha value between 0.0 and 1.0. |
background | The background color of the text. |

### inf_text_gtk_buffer_get_saturation ()

    gdouble
    inf_text_gtk_buffer_get_saturation (InfTextGtkBuffer *buffer);

Returns the saturation part of the HSV user color.

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

The saturation used for user colors.

### inf_text_gtk_buffer_get_value ()

    gdouble
    inf_text_gtk_buffer_get_value (InfTextGtkBuffer *buffer);

Returns the value part of the HSV user color.

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

The value used for user colors.

### inf_text_gtk_buffer_set_show_user_colors ()

    void
    inf_text_gtk_buffer_set_show_user_colors
                                   (InfTextGtkBuffer *buffer,
                                    gboolean show);

If `show` is `TRUE` (the default), then the user color is used as background for newly written text by that user. Otherwise, newly written text has no background color.

Note that this setting is for newly written text only. If you want to show or hide user colors for existing text use `inf_text_gtk_buffer_show_user_colors()`.

#### Parameters

buffer | A InfTextGtkBuffer. |
show | Whether to show user colors or not. |

### inf_text_gtk_buffer_get_show_user_colors ()

    gboolean
    inf_text_gtk_buffer_get_show_user_colors
                                   (InfTextGtkBuffer *buffer);

Returns whether newly written text is attributed with the author's user color or not.

#### Parameters

buffer | A InfTextGtkBuffer. |

#### Returns

`TRUE` if user color is applied to newly written text, or `FALSE` otherwise.

### inf_text_gtk_buffer_show_user_colors ()

    void
    inf_text_gtk_buffer_show_user_colors (InfTextGtkBuffer *buffer,
                                          gboolean show,
                                          GtkTextIter *start,
                                          GtkTextIter *end);

If `show` is `FALSE`, then don't show user colors (which user wrote what text) as the background of the text, in the range from `start` to `end` . If `show` is `TRUE`, show user colors if they have previously been hidden via a call to this function with `show` being `FALSE`.

#### Parameters

buffer | A InfTextGtkBuffer. |
show | Whether to show or hide user colors. |
start | Beginning of the range for which to show or hide user colors. |
end | End of the range for which to show or hide user colors. |

## Types and Values

### struct InfTextGtkBuffer

    struct InfTextGtkBuffer;

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

### struct InfTextGtkBufferClass

    struct InfTextGtkBufferClass {
    };

This structure does not contain any public fields.

## Property Details

### The `“active-user”` property

      “active-user”              InfTextUser *

The user currently inserting text locally.

Flags: Read / Write

### The `“alpha”` property

      “alpha”                    gdouble

The translucency of the user color.

Flags: Read / Write

Allowed values: [0,1]

Default value: 1

### The `“background”` property

      “background”               GdkColor *

The global background color.

Flags: Read / Write

### The `“buffer”` property

      “buffer”                   GtkTextBuffer *

The underlaying GtkTextBuffer.

Flags: Read / Write / Construct Only

### The `“saturation”` property

      “saturation”               gdouble

Saturation of user colors in a HSV color model.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0.35

### The `“show-user-colors”` property

      “show-user-colors”         gboolean

Whether to show user colors initially for newly written text.

Flags: Read / Write

Default value: TRUE

### The `“user-table”` property

      “user-table”               InfUserTable *

A user table of the participating users.

Flags: Read / Write / Construct Only

### The `“value”` property

      “value”                    gdouble

Value of user colors in a HSV color model.

Flags: Read / Write

Allowed values: [0,1]

Default value: 1

### The `“wake-on-cursor-movement”` property

      “wake-on-cursor-movement”  gboolean

Whether to make inactive users active when the insertion mark in the TextBuffer moves.

Flags: Read / Write

Default value: FALSE

## See Also

InfTextBuffer