[text] Use cached length when possible

Since clutter_text_set_text() measures the length of the text
each time, we should use the cached length instead of recomputing
the text length each time. This should save us some time when
dealing with long, multi-byte texts.

[tests] Add unit for the ClutterText:password-char property

Check that the contents of the Text actor are unaffected by the
:password-char property; that the accessors are correct; and finally
that the initial value for a newly constructed Text actor is valid.

[docs] Update the Text section

After the 979b6794 commit, the section for ClutterText needs
updating on the renamed and removed accessors.

[text] Coalesce text visibility and password character

Using two properties to set a password entry can be construed as
both cumbersome and a gtk-ism. And rightly so on both counts.

The :text-visible property has also conflicting semantics with the
:cursor-visible one: while the latter hides the cursor, the former
changes the display of the contents of the Text actor. It is, thus,
not a matter of "visibility" but of "rendering".

Instead of setting the :text-visible and :invisible-char properties
to have a password text field, the Text actor should just have a
single :password-char property holding a Unicode character. If the
value of the :password-char is non-zero, the Text actor will use the
Unicode character to render the contents of the text entry.

This commit removes the following methods:

  clutter_text_set_text_visible()
  clutter_text_get_text_visible()
  clutter_text_set_invisible_char()
  clutter_text_get_invisible_char()

And the following properties:

  ClutterText:text-visible
  ClutterText:invisible-char

In favour of:

  clutter_text_set_password_char()
  clutter_text_get_password_char()

And:

  ClutterText:password-char

Thus making obvious what use the property and accessor methods are
for and simplifying the process of creating a simple password text
field to:

  text = clutter_text_new ();
  clutter_text_set_password_char (CLUTTER_TEXT (text), '*');

Allow localizations to change the text direction

The locale translators of Clutter are also the ones that should set
the default direction of the text in a Clutter user interface.

This commit adds a translatable string that defines the direction
of the text; the translation authors will change it to the correct
value and that will determine the default direction.

The default text direction can be overridden by using the
CLUTTER_TEXT_DIRECTION environment variable, or by using the
--clutter-text-direction command line switch. In any other case,
the locale will determine the text direction, as it should.

Clean up the update_pango_context() function

Logically split the various operations with whitespace so that
it's clear what does what.

Pass the PangoContext, not the MainContext

When updating the PangoContext with the current options (font name,
options, resolution) pass the PangoContext instead of the Clutter
MainContext structure pointer.

Revert the logic of the PangoContext check

The branch that creates the global PangoContext should only run
if there is no global PangoContext already.

Remove the binding pool entry from the list

When removing a binding entry from the binding pool we should not
only remove it from the hash table, but also from the linked list
we use to iterate over inside the block/unblock_action() pair.

Remove BindingPool::list_actions()

The clutter_binding_pool_list_actions() was not implemented. The
utility of a call listing all the action names is also debatable:
all the functions related to the key bindings take the key symbol
and modifiers -- except the block_action() and unblock_action()
pair.

Add ClutterActor::create_pango_context()

Sometimes an actor needs to set specific font rendering options on
the PangoContext without changing settings for every other text-rendering
actor.

In order to do this, we need a new public method to create a Pango
context object -- preset with all the default settings -- owned by the
developer and not shared with the rest of Clutter.

This new method is called clutter_actor_create_pango_context(); while
it does not strictly depend on a ClutterActor, it is a good idea to
have it inside the ClutterActor API to map the current get_pango_context()
method and in case we start storing screen-specific data to the Actor
itself during the 1.x API cycle.

Rename the PangoContext creation functions

The _clutter_context_create_pango_context() should create a new
context; the function returning the PangoContext stored inside the
MainContext structure should be named _get_pango_context() instead.

Whitespace fixes

[docs] Add the new API to the BindingPool section

Add the clutter_binding_pool_override_* family of functions to
the BindingPool section of the Clutter API reference.

Allow overriding actions inside a BindingPool

As of now, a key binding installed into a BindingPool is always there
and cannot be changed.

This is problematic for sub-classes trying to override the callback
or the action for a given key binding.

This commit adds the ability to override the closure for an existing
key binding inside a binding pool -- assumed the caller knows the
key symbol and modifiers used to install the key binding in the first
place.

[text] Add select-all binding

Bind Ctrl+A to the "select all" action.

[docs] Add clutter_text_activate()

Add the last unused symbol to the ClutterText section.

[docs] Remove ClutterLabel and ClutterEntry sections

Remove the sections for the Label and the Entry actors, which
have been replaced by ClutterText.

[docs] Document the newly added functions

Document the ClutterBackend font name accessors, and the
clutter_actor_get_pango_context() getter method.

Add the ability to set the text direction

The direction of the text depends on the locale, and it is the
basic setting needed to enable internationalization of user
interfaces.

This commit allows setting the direction of the PangoContext instance
used by Clutter by using the CLUTTER_TEXT_DIRECTION environment
variable, or by passing the --clutter-text-direction command line
argument. Valid values are:

        ltr     - for left-to-right locales
        rtl     - for right-to-left locales

The default is LTR.

Ideally, this should be a value set by the localization teams on the
PO file, but this step requires some build system surgery to allow
the translation of the Clutter strings.

Return the default font name if no font name is set

When calling clutter_backend_get_font_name(), if no default font
name has previously been set, we just set the default and return
a pointer to it - like we do for the font options.

Use the default font from the Backend

Instead of storing the default font name and size as a pre-processor
macro, use the newly added ClutterBackend API to retrieve the current
default font from the backend.

Store the default font name inside ClutterBackend

The default backend stores some of the global defaults, like the
font options, text resolution, double click settings. It should also
store the default font name, to allow various text-based actors to
share the same settings.

When the font name changes, the ::font-changed signal is emitted,
to allow actors to pick up the change.

Update the PangoContext on backend changes

When the ClutterBackend notifies of changes in the resolution or
font options, update the PangoContext stored by Clutter's main
context. This allows changing the backend font-related settings at
runtime.

Store the PangoContext inside the main context

The PangoContext should be stored once, and inside the main
Clutter context. Each actor for which clutter_actor_get_pango_context()
has been called will hold a reference on the Pango context as well.

This makes it possible to update the text rendering for Clutter
by using only public API.

Do not leak the PangoContext

We hold a reference on the PangoContext we use for an actor, so
we should remove the reference inside the dispose implementation.

Create the PangoContext of the Text actor

Instead of creating a single, private PangoContext for every
Text actor, use the newly added clutter_actor_get_pango_context()
function.

Add a per-actor PangoContext

Rendering text inside an actor is pretty much impossible without
using internal API to create the various pieces like the PangoContext
and the font map.

Each actor should have the ability to create a PangoContext, which
is the only object needed to generate layouts and change the various
Pango settings.

This commit adds a clutter_actor_get_pango_context() function that
creates a PangoContext inside the ClutterActor private data and allows
the creation of PangoLayouts when needed. If the actor already
has a PangoContext, the same instance is returned.

The PangoContext is created only on demand.

Add signals for Backend options

The ClutterBackend instance at the moment lacks the ability to
notify runtime changes of the font options and the resolution.

For this reason, this commit adds a ::resolution-changed and a
::font-changed signals to the Backend class.

The ::resolution-changed signal is emitted when set_resolution()
is called with a different DPI; ::font-changed is emitted when the
cairo_font_options_t* changes from the default.

Use "" as the default value for the :text property

This follows the convention of GtkLabel/GtkEntry in GTK+ and the old
ClutterEntry.

It makes it easier to use strlen/strcmp etc on the output, since we can
assume that it is always a string.

This commit also updates the test unit for ClutterText to verify that
the clutter_text_get_text() function also returns an empty string when
a ClutterText actor has been created.

Do not include cogl-pango.h multiple times

The clutter-private.h header already includes cogl-pango.h with
the correct inclusion path, because the main context stores a
pointer to the font map.

There is no need for clutter-text.c to include cogl-pango.h
again since it already includes clutter-private.h.

Fix the selection behaviour around the 0th glyph

After fixing the cursor position issues around the initial
glyph of the layout, the selection position needs fixing as
well.

The fix is similar: check if the position of the selection
is 0 and provide a fast path by setting the offset to 0.

[tests] Make the layout cache fail at the right place

The GTest report output allows the developer to know where exactly
a test unit failure happened. The test-text-cache unit makes it
very hard to pinpoint the exact failure location because it relies
on the output to be printed out - which is not the case when the
tests are run as part of a make check.

This commit makes each sub-test inside the unit fail exactly where
the check function fails, which makes it easier to know which sub-test
did actually fail.

[docs] Add clutter_text_set_selection to gtk-doc

Insert the newly added symbol to the ClutterText section in
the API reference.

Add ClutterText::set_selection()

The clutter_text_set_selection() function is a convenience
method for setting the cursor position and the selection
boundary to a given position in a single call, with sanity
checks for the positions.

Fix ClutterText::get_selection()

The clutter_text_get_selection() function was not checking the
passed argument, and was still accessing the contents of the
Text actor using clutter_text_get_text().

This commit also adds the last few gtk-doc annotations missing
from ClutterText.

[docs] Add more gtk-doc annotations

Almost reaching full documentation.

Use clutter_text_activate()

Instead of repeating the same code for the ::activate signal
emission, use the clutter_text_activate() function inside the
'activate' key binding handler.

Add ClutterText::activate()

The clutter_text_activate() function will emit the ::activate
signal if the :activatable property is set.

This function is useful for subclasses or application code, for
example if we are going to use ::captured-event or ::key-press-event
signal handlers to intercept the Return key and emit the ::activate
signal ourselves.

[docs] Add more gtk-doc annotations for ClutterText

Document the ClutterText constructors and the :editable, :selectable
and :activatable properties accessors.

[docs] Annotate properties and fix signals docs

Annotate the properties without gtk-doc description, to get the
"Since" attribute.

Also, fix the ::cursor-event and ::activate signals documentation.

[docs] Add :cursor-size property accessors

Add the ClutterText:cursor-size property accessors to the
known gtk-doc symbols for the ClutterText section.

Allow selecting with line-start and line-end bindings

Instead of installing the line-start and line-end key bindings
using the bare ClutterBindingPool API, we can use the internal
clutter_text_add_move_binding(), which automatically installs
the same key binding with the Shift modifier mask.

This allows selecting when pressing Shift+Home or Shift+End.

The selection behaviour is still incorrect around the zeroeth
position, with all the text after the first line being selected.

Add :cursor-size property to ClutterText

We can control the width of the cursor when painting by using
a simple property.

The magic -1 number passed to the setter method will reset the
cursor size to the default one of 2px.

The getter method will return an unsigned integer with the
current size.

Remove unused page up/down key bindings

Moving the text by a "page" depends on being able to define a
"page size" in terms of lines of text. Since we don't define
something similar to an Adjustment that allows us to handle this
behaviour, we should defer the paging implementation to a higher
level class based on ClutterText.

Fix line start and line end key binding behaviour

Another fix for the key navigation behaviour around the zeroeth
glyph in the layout.

This commit adds a fast path for for the zero index when the
cursor position is set as zero, in case we are using the line-start
or line-end key bindings, similarly to what we did in commit
be64cbcdc22952ce2fa9f902e153e3bd9f4a08c9 for the move-up and
move-down bindings.

Fix up/down key navigation

The behaviour of ClutterText around the initial position is still
a little bit erratic.

This commit fixes the key navigation with Up and Down arrows around
the first line of text.

Use units in position_to_coords()

We loose precision with a direct conversion for PangoUnits to
pixels, so we should do the conversion as needed, inside the
callers of clutter_text_position_to_coords().

Constify the cursor geometry in ::cursor-event

We don't allow changing the cursor geometry inside the ::cursor-event
signal handlers; for starters, it would make binding the signal a
huge mess, and it would also potentially break the whole actor.

[docs] Add annotations for ClutterText structures

ClutterText and ClutterTextClass were missing annotations for
gtk-doc to pick up.

Remove ClutterLabel and ClutterEntry

Both ClutterLabel and ClutterEntry have been deprecated by
ClutterText.

[docs] Update the API reference

Add all the unused API to the sections file; there are still
some undocumented bits, but clutter-unused.txt is empty for
the time being.

Also, add ClutterText to the main XML document and remove
ClutterLabel and ClutterEntry.

Fix documentation issues

Provide a description for the ClutterText section, and fix some
misnamed arguments inside the header file.

Lazily create the PangoContext on Text::init

If we create the PangoContext for ClutterText inside the class
initialization we might not have a Clutter main context yet.

Ideally, we should store the Pango context inside the main context
and create it on clutter_init(), but for now we can lazily create
the PangoContext when we initialize a ClutterText instance for the
first time.

Remove ClutterEntry and ClutterLabel from the build

For the time being, just don't include them or compile them; the
files will be removed from the repository as soon as all the
documentation annotations have been ported over to ClutterText.

Update the micro-bench tests to ClutterText

Test the ClutterText rendering speed instead of ClutterLabel's.

Update the interactive tests to ClutterText

Instead of using ClutterLabel, use ClutterText to display some
text where needed.

Do not compile the opacity and entry interactive tests

The test-opacity interactive test is superceded by the equivalent
units inside the conformance test suite.

The test-entry interactive test is superceded by the test-text one.

Update ignore file

Add the conformance test units for ClutterText.

Update the paint opacity unit test

ClutterText behaviour with regards to the paint opacity has been
changed by commit 07e19fff5ffa9617413fa6c3715914513fec3793.

We need to update the test suite for the paint opacity to reflect
that change as well.

Allow only synthetic events with keyval 0

We allow KeyEvents with a key symbol of '0' to fall through only
if they are marked as synthetic. Otherwise we discard them without
mercy.

Synthetic events are useful to test ClutterText behaviour; in fact,
we do use them inside the test suite exactly for that reason.

Do not use contractions when not needed

I understand we are not Pascal developers, and we don't have to
use cute and cuddly names like "i_am_an_integer_counter", but
a ClutterButtonEvent should be stored inside an "event" variable.
Using "bev" instead? Mmmh, not so much.

Use the paint opacity when painting a ClutterText

ClutterText should use the paint opacity for both text and
cursor.

ClutterLabel had the wrong behaviour, as it set the actor's
opacity using the text color's alpha channel, and ClutterEntry
completely disregarded the actor's opacity when painting the
cursor.

This commit harmonizes the ClutterText behaviour to always
use a composition of the actor's paint opacity and the text
and cursor alpha channel values, thus behaving more
consistently with the rest of Clutter.

Add documentation annotations

ClutterText is heavily under-documented. This commit ports most of
the API documentation from ClutterLabel and ClutterEntry to
ClutterText.

Code style fixes

Fix the arguments alignment whenever not consistent with the
coding style rules.

Remove unused types

Since ClutterText now uses ClutterBindingPool there is no more
need for the internal key mapping types.

Remove units for Entry and Label

ClutterText should supercede all unit tests for ClutterLabel and
ClutterEntry.

Truncate selections on text insertion

When inserting text on a key press event we should also truncate
the selection.

We should not truncate the selection when inserting any Unicode
character, since changing the selection also changes the cursor
position - and one of the invariants we inherited from ClutterEntry
is that inserting characters programmatically does not change the
cursor position.

Change the binding propagation when truncating a selection

If a selection has been truncated inside a key binding handler,
we should just return and let the usual key event handler continue.

This fixes the case where we deleted a selection using the Delete
or the Backspace keys.

Comment out the mapping API

The test-text interactive test for ClutterText should not use
the mapping API, since ClutterText does not have it anymore.

Use ClutterBindPool inside ClutterText

ClutterText should use the newly added ClutterBindingPool API to
handle key events, instead of its homegrown code.

This commit removes the action/mapping code and defers the entire
key binding matching to a ClutterBindingPool created inside the
Text class initialization function.

Add Text::get_chars() implementation and tests

The clutter_text_get_chars() function returns a section of the
contents of the Text actor, delimited by a start and an end position.

This commit adds the implementation for that function and a test
unit that guarantees the offset-to-bytes computations are correct.

Do not namespace internal data structures

Since the internal data structures are not exported (duh!), we
can eschew the namespacing and save us some characters.

Add comments in the test suite

Comment why we need to enable the editability of the Text actor
inside the test suite.

This should clarify commit ea508ea528d61ae478d8bc4c88f54a89304f18e8

Move internal data structures on top

Try to keep the declarations section of the source files clean and
possibly consistent.

Coding style consistency

Channel mitch's spirit.

This is also how I get to have the highest commit count on Clutter's
repository.

Implement Text:max-length

The :max-length property establishes the maximum available
length for the Text actor's contents, in characters.

Update the ClutterText test unit

Whenever we are sending specially crafted KeyEvents to a ClutterText
we also need to set it editable, since the event handling code depends
on the editability setting.

Use the stored contents length in ::delete_chars()

Instead of recomputing it, we can reuse the contents length we
compute and store inside clutter_text_set_text().

Improve the safety checks inside the text setters

We should check that the contents of the Text actor are
not NULL when computing the offsets in bytes.

Add :cursor-color-set property declaration

The :cursor-color-set property is a read-only property that
reflects whether the ClutterText actor is going to use the
color set inside the :cursor-color property when painting
the cursor.

General whitespace fixes in ClutterText

Let's keep whitespace fixes to their own commit to avoid
polluting git-blame.

Replace offset_to_bytes() implementation

We should re-use the offset_to_bytes() implementation from ClutterEntry
as it guaranteed some behaviour and sanity checks that we want to keep
inside ClutterText.

Add a separate test unit for ClutterText

Instead of changing the unit for ClutterEntry, we add a new
test unit specifically for ClutterText so that we can later tweak
it specifically for the behaviour changes needed to make ClutterText
work better.

Add text editing methods

Port the text editing methods from ClutterEntry, so that
ClutterText exposes the same API.

Add missing basic constructor

ClutterText should have an empty constructor, mostly for
bindings to use, that just proxies call to g_object_new()
without setting any property.

Initialize the cursor position

By default, the cursor position is initialized to -1, meaning
"place the cursor always at the end of the text".

Add text-visibility accessors for ClutterText

A ClutterText can be put in "password mode" by setting the
text as "invisible": every character inside the Text actor's
contents will be replaced when building the Pango layout with
a specific Unicode character.

The Unicode character is set to '*' by default, but the user
can be changed using the provided API.

Move test-threads to ClutterText

The test-threads interactive test is a good candidate for the
switch from ClutterLabel to ClutterText to verify that the
behaviour of the two classes is the same.

Correctly initialize the initial state of ClutterText

Some of the values in ClutterText have an initial state that
does not match a zero-ed out ClutterTextPrivate structure.

Merge the ClutterLabel properties into ClutterText

ClutterText should have the same properties as ClutterLabel.

While at it, we can finally fix the disconnect between the wrap
and wrap-mode properties and its accessors, that we perpetuated
from GtkLabel.

The ClutterText:line-wrap property and ClutterText:line-wrap-mode
are mapped to the set_line_wrap(), get_line_wrap() and
set_line_wrap_mode(), get_line_wrap_mode() accessor functions
respectively. This should simplify bindings the Vala ones that
map a property into a method.

Add Text::get_chars() method declaration

Add the declaration for a clutter_text_get_chars() function that
returns a portion of the contents of a Text actor.

Add Actor::grab_key_focus() method

Bug 1003 - Add clutter_actor_take_key_focus()

The grab_key_focus() method is just a simple wrapper around
clutter_stage_take_key_focus() that removes the need to get
the ClutterStage of an actor in order to set the key focus.

Based on a patch by Xan López.

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>
Signed-off-by: Øyvind Kolås <pippin@linux.intel.com>

Merge Label and Entry API into ClutterText

ClutterText should expose both ClutterLabel and ClutterEntry
functionality using an API that matches the one provided by
those two classes.

Expose the Text accessors as public API

Fix up the header to expose ClutterText accessors for the main
properties, matching ClutterLabel.

Update the ClutterText interactive test

Use ClutterText's own API instead of relying on the Label's API.

ClutterText is not meant to be a subclass of ClutterLabel.

Coalesce ClutterLabel API usage

ClutterText replaces ClutterLabel, so it should expose the same
kind of API - ideally with the minimal amount of changes, so that
the porting is trivial.

Group all the integer private fields

Integer fields using the ": <bits>" notation should be packed
together so that the compiler can optimize the structure size
correctly.

Use internal headers

Since ClutterText is part of Clutter, it can use the internal
and private headers instead of the catch-all clutter.h.

Initial import of the Text actor from Tidy

The TidyText actor is meant as a replacement for both ClutterLabel
and ClutterText.

Any text-displaying and editing actor should derive from ClutterText
and implement the various visual cues to differentiate the editable
from the non-editable state. Those visual cues usually belong to
a high-level toolkit, especially if themeing is involved.