Top | ![]() |
![]() |
![]() |
![]() |
ClutterText is an actor that displays custom text using Pango as the text rendering engine.
ClutterText also allows inline editing of the text if the
actor is set editable using clutter_text_set_editable()
.
Selection using keyboard or pointers can be enabled using
clutter_text_set_selectable()
.
ClutterText is available since Clutter 1.0
ClutterActor *
clutter_text_new (void
);
Creates a new ClutterText actor. This actor can be used to display and edit text.
Since: 1.0
ClutterActor * clutter_text_new_full (const gchar *font_name
,const gchar *text
,const ClutterColor *color
);
Creates a new ClutterText actor, using font_name
as the font
description; text
will be used to set the contents of the actor;
and color
will be used as the color to render text
.
This function is equivalent to calling clutter_text_new()
,
clutter_text_set_font_name()
, clutter_text_set_text()
and
clutter_text_set_color()
.
font_name |
a string with a font description |
|
text |
the contents of the actor |
|
color |
the color to be used to render |
Since: 1.0
ClutterActor * clutter_text_new_with_text (const gchar *font_name
,const gchar *text
);
Creates a new ClutterText actor, using font_name
as the font
description; text
will be used to set the contents of the actor.
This function is equivalent to calling clutter_text_new()
,
clutter_text_set_font_name()
, and clutter_text_set_text()
.
Since: 1.0
ClutterActor *
clutter_text_new_with_buffer (ClutterTextBuffer *buffer
);
Creates a new entry with the specified text buffer.
Since: 1.10
void clutter_text_set_buffer (ClutterText *self
,ClutterTextBuffer *buffer
);
Set the ClutterTextBuffer object which holds the text for this widget.
Since: 1.10
ClutterTextBuffer *
clutter_text_get_buffer (ClutterText *self
);
Get the ClutterTextBuffer object which holds the text for this widget.
Since: 1.10
void clutter_text_set_text (ClutterText *self
,const gchar *text
);
Sets the contents of a ClutterText actor.
If the “use-markup” property was set to TRUE
it
will be reset to FALSE
as a side effect. If you want to
maintain the “use-markup” you should use the
clutter_text_set_markup()
function instead
self |
||
text |
the text to set. Passing |
[allow-none] |
Since: 1.0
void clutter_text_set_markup (ClutterText *self
,const gchar *markup
);
Sets markup
as the contents of a ClutterText.
This is a convenience function for setting a string containing Pango markup, and it is logically equivalent to:
1 2 3 |
/* the order is important */ clutter_text_set_text (CLUTTER_TEXT (actor), markup); clutter_text_set_use_markup (CLUTTER_TEXT (actor), TRUE); |
self |
||
markup |
a string containing Pango markup.
Passing |
[allow-none] |
Since: 1.0
const gchar *
clutter_text_get_text (ClutterText *self
);
Retrieves a pointer to the current contents of a ClutterText actor.
If you need a copy of the contents for manipulating, either
use g_strdup()
on the returned string, or use:
1 |
copy = clutter_text_get_chars (text, 0, -1); |
Which will return a newly allocated string.
If the ClutterText actor is empty, this function will return
an empty string, and not NULL
.
the contents of the actor. The returned string is owned by the ClutterText actor and should never be modified or freed.
[transfer none]
Since: 1.0
void clutter_text_set_activatable (ClutterText *self
,gboolean activatable
);
Sets whether a ClutterText actor should be activatable.
An activatable ClutterText actor will emit the “activate” signal whenever the 'Enter' (or 'Return') key is pressed; if it is not activatable, a new line will be appended to the current content.
An activatable ClutterText must also be set as editable using
clutter_text_set_editable()
.
Since: 1.0
gboolean
clutter_text_get_activatable (ClutterText *self
);
Retrieves whether a ClutterText is activatable or not.
Since: 1.0
void clutter_text_set_attributes (ClutterText *self
,PangoAttrList *attrs
);
Sets the attributes list that are going to be applied to the ClutterText contents.
The ClutterText actor will take a reference on the PangoAttrList passed to this function.
Since: 1.0
PangoAttrList *
clutter_text_get_attributes (ClutterText *self
);
Gets the attribute list that was set on the ClutterText actor
clutter_text_set_attributes()
, if any.
the attribute list, or NULL
if none was set. The
returned value is owned by the ClutterText and should not be unreferenced.
[transfer none]
Since: 1.0
void clutter_text_set_color (ClutterText *self
,const ClutterColor *color
);
Sets the color of the contents of a ClutterText actor.
The overall opacity of the ClutterText actor will be the
result of the alpha value of color
and the composited
opacity of the actor itself on the scenegraph, as returned
by clutter_actor_get_paint_opacity()
.
Since: 1.0
void clutter_text_get_color (ClutterText *self
,ClutterColor *color
);
Retrieves the text color as set by clutter_text_set_color()
.
Since: 1.0
void clutter_text_set_ellipsize (ClutterText *self
,PangoEllipsizeMode mode
);
Sets the mode used to ellipsize (add an ellipsis: "...") to the text if there is not enough space to render the entire contents of a ClutterText actor
Since: 1.0
PangoEllipsizeMode
clutter_text_get_ellipsize (ClutterText *self
);
Returns the ellipsizing position of a ClutterText actor, as
set by clutter_text_set_ellipsize()
.
Since: 1.0
void clutter_text_set_font_name (ClutterText *self
,const gchar *font_name
);
Sets the font used by a ClutterText. The font_name
string
must either be NULL
, which means that the font name from the
default ClutterBackend will be used; or be something that can
be parsed by the pango_font_description_from_string()
function,
like:
1 2 3 4 5 6 7 8 |
// Set the font to the system's Sans, 10 points clutter_text_set_font_name (text, "Sans 10"); // Set the font to the system's Serif, 16 pixels clutter_text_set_font_name (text, "Serif 16px"); // Set the font to Helvetica, 10 points clutter_text_set_font_name (text, "Helvetica 10"); |
Since: 1.0
const gchar *
clutter_text_get_font_name (ClutterText *self
);
Retrieves the font name as set by clutter_text_set_font_name()
.
a string containing the font name. The returned string is owned by the ClutterText actor and should not be modified or freed
Since: 1.0
void clutter_text_set_font_description (ClutterText *self
,PangoFontDescription *font_desc
);
Sets font_desc
as the font description for a ClutterText
The PangoFontDescription is copied by the ClutterText actor
so you can safely call pango_font_description_free()
on it after
calling this function.
Since: 1.2
PangoFontDescription *
clutter_text_get_font_description (ClutterText *self
);
Retrieves the PangoFontDescription used by self
a PangoFontDescription. The returned value is owned by the ClutterText actor and it should not be modified or freed
Since: 1.2
void clutter_text_set_password_char (ClutterText *self
,gunichar wc
);
Sets the character to use in place of the actual text in a password text actor.
If wc
is 0 the text will be displayed as it is entered in the
ClutterText actor.
Since: 1.0
gunichar
clutter_text_get_password_char (ClutterText *self
);
Retrieves the character to use in place of the actual text
as set by clutter_text_set_password_char()
.
Since: 1.0
void clutter_text_set_justify (ClutterText *self
,gboolean justify
);
Sets whether the text of the ClutterText actor should be justified on both margins. This setting is ignored if Clutter is compiled against Pango < 1.18.
Since: 1.0
gboolean
clutter_text_get_justify (ClutterText *self
);
Retrieves whether the ClutterText actor should justify its contents on both margins.
Since: 0.6
PangoLayout *
clutter_text_get_layout (ClutterText *self
);
Retrieves the current PangoLayout used by a ClutterText actor.
a PangoLayout. The returned object is owned by the ClutterText actor and should not be modified or freed.
[transfer none]
Since: 1.0
void clutter_text_set_line_alignment (ClutterText *self
,PangoAlignment alignment
);
Sets the way that the lines of a wrapped label are aligned with respect to each other. This does not affect the overall alignment of the label within its allocated or specified width.
To align a ClutterText actor you should add it to a container that supports alignment, or use the anchor point.
Since: 1.0
PangoAlignment
clutter_text_get_line_alignment (ClutterText *self
);
Retrieves the alignment of a ClutterText, as set by
clutter_text_set_line_alignment()
.
Since: 1.0
void clutter_text_set_line_wrap (ClutterText *self
,gboolean line_wrap
);
Sets whether the contents of a ClutterText actor should wrap, if they don't fit the size assigned to the actor.
Since: 1.0
gboolean
clutter_text_get_line_wrap (ClutterText *self
);
Retrieves the value set using clutter_text_set_line_wrap()
.
Since: 1.0
void clutter_text_set_line_wrap_mode (ClutterText *self
,PangoWrapMode wrap_mode
);
If line wrapping is enabled (see clutter_text_set_line_wrap()
) this
function controls how the line wrapping is performed. The default is
PANGO_WRAP_WORD
which means wrap on word boundaries.
Since: 1.0
PangoWrapMode
clutter_text_get_line_wrap_mode (ClutterText *self
);
Retrieves the line wrap mode used by the ClutterText actor.
See clutter_text_set_line_wrap_mode()
.
Since: 1.0
void clutter_text_set_max_length (ClutterText *self
,gint max
);
Sets the maximum allowed length of the contents of the actor. If the current contents are longer than the given length, then they will be truncated to fit.
self |
||
max |
the maximum number of characters allowed in the text actor; 0 to disable or -1 to set the length of the current string |
Since: 1.0
gint
clutter_text_get_max_length (ClutterText *self
);
Gets the maximum length of text that can be set into a text actor.
See clutter_text_set_max_length()
.
Since: 1.0
void clutter_text_set_selectable (ClutterText *self
,gboolean selectable
);
Sets whether a ClutterText actor should be selectable.
A selectable ClutterText will allow selecting its contents using the pointer or the keyboard.
Since: 1.0
gboolean
clutter_text_get_selectable (ClutterText *self
);
Retrieves whether a ClutterText is selectable or not.
Since: 1.0
void clutter_text_set_selection (ClutterText *self
,gssize start_pos
,gssize end_pos
);
Selects the region of text between start_pos
and end_pos
.
This function changes the position of the cursor to match
start_pos
and the selection bound to match end_pos
.
self |
||
start_pos |
start of the selection, in characters |
|
end_pos |
end of the selection, in characters |
Since: 1.0
gchar *
clutter_text_get_selection (ClutterText *self
);
Retrieves the currently selected text.
a newly allocated string containing the currently
selected text, or NULL
. Use g_free()
to free the returned
string.
Since: 1.0
void clutter_text_set_selection_bound (ClutterText *self
,gint selection_bound
);
Sets the other end of the selection, starting from the current cursor position.
If selection_bound
is -1, the selection unset.
Since: 1.0
gint
clutter_text_get_selection_bound (ClutterText *self
);
Retrieves the other end of the selection of a ClutterText actor, in characters from the current cursor position.
Since: 1.0
void clutter_text_set_single_line_mode (ClutterText *self
,gboolean single_line
);
Sets whether a ClutterText actor should be in single line mode or not. Only editable ClutterTexts can be in single line mode.
A text actor in single line mode will not wrap text and will clip the visible area to the predefined size. The contents of the text actor will scroll to display the end of the text if its length is bigger than the allocated width.
When setting the single line mode the “activatable” property is also set as a side effect. Instead of entering a new line character, the text actor will emit the “activate” signal.
Since: 1.0
gboolean
clutter_text_get_single_line_mode (ClutterText *self
);
Retrieves whether the ClutterText actor is in single line mode.
Since: 1.0
void clutter_text_set_use_markup (ClutterText *self
,gboolean setting
);
Sets whether the contents of the ClutterText actor contains markup in Pango's text markup language.
Setting “use-markup” on an editable ClutterText will not have any effect except hiding the markup.
See also “use-markup”.
Since: 1.0
gboolean
clutter_text_get_use_markup (ClutterText *self
);
Retrieves whether the contents of the ClutterText actor should be parsed for the Pango text markup.
Since: 1.0
void clutter_text_set_editable (ClutterText *self
,gboolean editable
);
Sets whether the ClutterText actor should be editable.
An editable ClutterText with key focus set using
clutter_actor_grab_key_focus()
or clutter_stage_set_key_focus()
will receive key events and will update its contents accordingly.
Since: 1.0
gboolean
clutter_text_get_editable (ClutterText *self
);
Retrieves whether a ClutterText is editable or not.
Since: 1.0
void clutter_text_insert_text (ClutterText *self
,const gchar *text
,gssize position
);
Inserts text
into a ClutterActor at the given position.
If position
is a negative number, the text will be appended
at the end of the current contents of the ClutterText.
The position is expressed in characters, not in bytes.
Since: 1.0
void clutter_text_insert_unichar (ClutterText *self
,gunichar wc
);
Inserts wc
at the current cursor position of a
ClutterText actor.
Since: 1.0
void clutter_text_delete_chars (ClutterText *self
,guint n_chars
);
Deletes n_chars
inside a ClutterText actor, starting from the
current cursor position.
Somewhat awkwardly, the cursor position is decremented by the same number of characters you've deleted.
Since: 1.0
void clutter_text_delete_text (ClutterText *self
,gssize start_pos
,gssize end_pos
);
Deletes the text inside a ClutterText actor between start_pos
and end_pos
.
The starting and ending positions are expressed in characters, not in bytes.
Since: 1.0
gboolean
clutter_text_delete_selection (ClutterText *self
);
Deletes the currently selected text
This function is only useful in subclasses of ClutterText
Since: 1.0
gchar * clutter_text_get_chars (ClutterText *self
,gssize start_pos
,gssize end_pos
);
Retrieves the contents of the ClutterText actor between
start_pos
and end_pos
, but not including end_pos
.
The positions are specified in characters, not in bytes.
a newly allocated string with the contents of
the text actor between the specified positions. Use g_free()
to free the resources when done
Since: 1.0
void clutter_text_set_cursor_color (ClutterText *self
,const ClutterColor *color
);
Sets the color of the cursor of a ClutterText actor.
If color
is NULL
, the cursor color will be the same as the
text color.
Since: 1.0
void clutter_text_get_cursor_color (ClutterText *self
,ClutterColor *color
);
Retrieves the color of the cursor of a ClutterText actor.
Since: 1.0
void clutter_text_set_selection_color (ClutterText *self
,const ClutterColor *color
);
Sets the color of the selection of a ClutterText actor.
If color
is NULL
, the selection color will be the same as the
cursor color, or if no cursor color is set either then it will be
the same as the text color.
Since: 1.0
void clutter_text_get_selection_color (ClutterText *self
,ClutterColor *color
);
Retrieves the color of the selection of a ClutterText actor.
Since: 1.0
void clutter_text_set_selected_text_color (ClutterText *self
,const ClutterColor *color
);
Sets the selected text color of a ClutterText actor.
If color
is NULL
, the selected text color will be the same as the
selection color, which then falls back to cursor, and then text color.
Since: 1.8
void clutter_text_get_selected_text_color (ClutterText *self
,ClutterColor *color
);
Retrieves the color of selected text of a ClutterText actor.
Since: 1.8
void clutter_text_set_cursor_position (ClutterText *self
,gint position
);
Sets the cursor of a ClutterText actor at position
.
The position is expressed in characters, not in bytes.
Since: 1.0
gint
clutter_text_get_cursor_position (ClutterText *self
);
Retrieves the cursor position.
Since: 1.0
void clutter_text_set_cursor_visible (ClutterText *self
,gboolean cursor_visible
);
Sets whether the cursor of a ClutterText actor should be visible or not.
The color of the cursor will be the same as the text color
unless clutter_text_set_cursor_color()
has been called.
The size of the cursor can be set using clutter_text_set_cursor_size()
.
The position of the cursor can be changed programmatically using
clutter_text_set_cursor_position()
.
Since: 1.0
gboolean
clutter_text_get_cursor_visible (ClutterText *self
);
Retrieves whether the cursor of a ClutterText actor is visible.
Since: 1.0
void clutter_text_set_cursor_size (ClutterText *self
,gint size
);
Sets the size of the cursor of a ClutterText. The cursor
will only be visible if the “cursor-visible” property
is set to TRUE
.
Since: 1.0
guint
clutter_text_get_cursor_size (ClutterText *self
);
Retrieves the size of the cursor of a ClutterText actor.
Since: 1.0
void clutter_text_get_cursor_rect (ClutterText *self
,ClutterRect *rect
);
Retrieves the rectangle that contains the cursor.
The coordinates of the rectangle's origin are in actor-relative coordinates.
Since: 1.16
gboolean
clutter_text_activate (ClutterText *self
);
Emits the “activate” signal, if self
has been set
as activatable using clutter_text_set_activatable()
.
This function can be used to emit the ::activate signal inside a “captured-event” or “key-press-event” signal handlers before the default signal handler for the ClutterText is invoked.
Since: 1.0
gint clutter_text_coords_to_position (ClutterText *self
,gfloat x
,gfloat y
);
Retrieves the position of the character at the given coordinates.
Return: the position of the character
Since: 1.10
gboolean clutter_text_position_to_coords (ClutterText *self
,gint position
,gfloat *x
,gfloat *y
,gfloat *line_height
);
Retrieves the coordinates of the given position
.
self |
||
position |
position in characters |
|
x |
return location for the X coordinate, or |
[out] |
y |
return location for the Y coordinate, or |
[out] |
line_height |
return location for the line height, or |
[out] |
Since: 1.0
void clutter_text_set_preedit_string (ClutterText *self
,const gchar *preedit_str
,PangoAttrList *preedit_attrs
,guint cursor_pos
);
Sets, or unsets, the pre-edit string. This function is useful for input methods to display a string (with eventual specific Pango attributes) before it is entered inside the ClutterText buffer.
The preedit string and attributes are ignored if the ClutterText actor is not editable.
This function should not be used by applications
self |
||
preedit_str |
the pre-edit string, or |
[allow-none] |
preedit_attrs |
the pre-edit string attributes. |
[allow-none] |
cursor_pos |
the cursor position for the pre-edit string |
Since: 1.2
void clutter_text_get_layout_offsets (ClutterText *self
,gint *x
,gint *y
);
Obtains the coordinates where the ClutterText will draw the PangoLayout representing the text.
self |
||
x |
location to store X offset of layout, or |
[out] |
y |
location to store Y offset of layout, or |
[out] |
Since: 1.8
struct ClutterText { };
The ClutterText struct contains only private data.
Since: 1.0
struct ClutterTextClass { /* signals, not vfuncs */ void (* text_changed) (ClutterText *self); void (* activate) (ClutterText *self); void (* cursor_event) (ClutterText *self, const ClutterGeometry *geometry); void (* cursor_changed) (ClutterText *self); };
The ClutterTextClass struct contains only private data.
Since: 1.0