X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=blobdiff_plain;f=capi%2Fdali-toolkit%2Fpublic-api%2Fcontrols%2Ftext-view%2Ftext-view.h;h=6bf42fe8c8e2ed5ea16512fd7352306567310be3;hp=8d9a1568b29b373d23f9612f72fc60f185b25a1b;hb=ad49b1678c08f91af54531815a58f4c22a20271a;hpb=e2eda444afbe82e9591fe198eef339227f90a616 diff --git a/capi/dali-toolkit/public-api/controls/text-view/text-view.h b/capi/dali-toolkit/public-api/controls/text-view/text-view.h index 8d9a156..6bf42fe 100644 --- a/capi/dali-toolkit/public-api/controls/text-view/text-view.h +++ b/capi/dali-toolkit/public-api/controls/text-view/text-view.h @@ -18,7 +18,7 @@ // /** - * @addtogroup CAPI_DALI_FRAMEWORK + * @addtogroup CAPI_DALI_TOOLKIT_TEXT_VIEW_MODULE * @{ */ @@ -41,115 +41,62 @@ class TextView; } /** - * TextView is a layout container with alignment, multi-line wrapping and formatting support. + * @brief The TextView class is a UI Dali::Toolkit::Control designed to extend the capabilities of the basic Dali::TextActor. * - * Different multi-line and exceed policies could be chosen to represent the given text. - * \see Toolkit::TextView::SetMultilinePolicy \see Toolkit::TextView::SetExceedPolicy + * It provides support for multi-line wrapping, multi-language font detection, text alignment, scrolling and styling. * - * Multi-line policies: - * - * - * Exceed policies work in combination with multi-line policies: - * - * - * Text alignment could be set to align the whole text block inside the text view's boundary. \see Toolkit::TextView::SetTextAlignment. - * - * Line justification could be set to align lines inside a text block. \see Toolkit::TextView::SetLineJustification. - * - * A default font could be set through the \see Toolkit::TextView::SetFont method. If any font is set, text view automatically detects a suitable font for every character. - * - * Font priority: - * 1) Use the font specified in text decoration. - * 2) Use automatic font detection. - * - * Integration with other classes (GetSizeAndPositionTable ) - * - * Text decoration ( Color, Font, Size, italic and all features supported in TextActor ) + * See the \link text-view Text View \endlink page of the Programming Guide for more details and examples. */ class TextView : public Control { public: - //Signal Names - static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see SignalScrolled() - /** - * The names of custom properties installed by this control. - */ - // Property Names - static const char* const PROPERTY_TEXT; ///< name "text", type std::string - static const char* const PROPERTY_MULTILINE_POLICY; ///< name "multiline-policy", type std::string - static const char* const PROPERTY_WIDTH_EXCEED_POLICY; ///< name "width-exceed-policy", type std::string - static const char* const PROPERTY_HEIGHT_EXCEED_POLICY; ///< name "height-exceed-policy", type std::string - static const char* const PROPERTY_LINE_JUSTIFICATION; ///< name "line-justification", type std::string - static const char* const PROPERTY_FADE_BOUNDARY_LEFT; ///< name "fade-boundary-left", type int - static const char* const PROPERTY_FADE_BOUNDARY_RIGHT; ///< name "fade-boundary-right", type int - static const char* const PROPERTY_FADE_BOUNDARY_TOP; ///< name "fade-boundary-top", type int - static const char* const PROPERTY_FADE_BOUNDARY_BOTTOM; ///< name "fade-boundary-bottom", type int - static const char* const PROPERTY_LINE_HEIGHT_OFFSET; ///< name "line-height-offset", type float - static const char* const PROPERTY_HORIZONTAL_ALIGNMENT; ///< name "horizontal-alignment", type std::string - static const char* const PROPERTY_VERTICAL_ALIGNMENT; ///< name "vertical-alignment", type std::string + // Signal Names + static const char* const SIGNAL_TEXT_SCROLLED; ///< Signal emitted when the scroll position changes. @see ScrolledSignal() + + // Properties + static const Property::Index PROPERTY_MARKUP_ENABLED; ///< name "markup-enabled", @see SetMarkupProcessingEnabled(), type BOOLEAN + static const Property::Index PROPERTY_TEXT; ///< name "text", @see SetText(), type STRING + static const Property::Index PROPERTY_MULTILINE_POLICY; ///< name "multiline-policy", @see SetMultilinePolicy(), type STRING + static const Property::Index PROPERTY_WIDTH_EXCEED_POLICY; ///< name "width-exceed-policy", @see SetWidthExceedPolicy(), type STRING + static const Property::Index PROPERTY_HEIGHT_EXCEED_POLICY; ///< name "height-exceed-policy", @see SetHeightExceedPolicy(), type STRING + static const Property::Index PROPERTY_LINE_JUSTIFICATION; ///< name "line-justification", @see SetLineJustification(), type STRING + static const Property::Index PROPERTY_FADE_BOUNDARY; ///< name "fade-boundary", @see SetFadeBoundary(), type VECTOR4 + static const Property::Index PROPERTY_LINE_HEIGHT_OFFSET; ///< name "line-height-offset", @see SetLineHeightOffset(), type FLOAT + static const Property::Index PROPERTY_HORIZONTAL_ALIGNMENT; ///< name "horizontal-alignment", @see SetTextAlignment(), type STRING + static const Property::Index PROPERTY_VERTICAL_ALIGNMENT; ///< name "vertical-alignment", @see SetTextAlignment(), type STRING /** - * Structure used to retrieve Layout info per character. + * @brief Structure used to retrieve Layout info per character. */ struct CharacterLayoutInfo { /** - * Default constructor. + * @brief Default constructor. * * Initializes all members to their default values. */ CharacterLayoutInfo(); /** - * Empty destructor. + * @brief Empty destructor. * * @note Added to increase coverage. */ ~CharacterLayoutInfo(); /** - * Copy constructor. + * @brief Copy constructor. */ CharacterLayoutInfo( const CharacterLayoutInfo& characterLayoutInfo ); /** - * Assignment operator. + * @brief Assignment operator. */ CharacterLayoutInfo& operator=( const CharacterLayoutInfo& character ); /** - * Constructor. + * @brief Constructor. * * @param[in] size of the character. * @param[in] position of the character. @@ -166,17 +113,17 @@ public: float descender ); Size mSize; ///< Size of the group of characters. - Vector3 mPosition; ///< Position of the group of characters within the text view. - bool mIsNewLineChar:1; ///< Whether this group of characters represent a new line. + Vector3 mPosition; ///< Position of the character within the text view. + bool mIsNewLineChar:1; ///< Whether this character represent a new line. bool mIsRightToLeftCharacter:1; ///< Whether it's a right-to-left character. - bool mIsVisible:1; ///< Whether this group of characters is visible or not. + bool mIsVisible:1; ///< Whether this character is visible or not. float mDescender; ///< The character's descender which is the distance from the baseline to the bottom of the character }; - typedef std::vector CharacterLayoutInfoContainer; + typedef std::vector CharacterLayoutInfoContainer; ///< Container of layout info per character. /** - * Stores some info about a laid-out line. + * @brief Stores some info about a laid-out line. */ struct LineLayoutInfo { @@ -184,33 +131,37 @@ public: Size mSize; ///< Size of the current laid-out line. float mAscender; ///< The max ascender of the current laid-out line. }; - typedef std::vector LineLayoutInfoContainer; + typedef std::vector LineLayoutInfoContainer; ///< Container of layout info per line. + + /** + * @brief How text is laid out. + */ struct TextLayoutInfo { /** - * Default constructor. + * @brief Default constructor. */ TextLayoutInfo(); /** - * Empty destructor + * @brief Empty destructor. * * @note Added to increase coverage. */ ~TextLayoutInfo(); /** - * Copy constructor. + * @brief Copy constructor. */ TextLayoutInfo( const TextLayoutInfo& textLayoutInfo ); /** - * Assignment operator. + * @brief Assignment operator. */ TextLayoutInfo& operator=( const TextLayoutInfo& textLayoutInfo ); - CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character positions and sizes sorted by the characters' visual index. + CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< The table of character's positions and sizes sorted by the character's visual index. LineLayoutInfoContainer mLines; ///< For each laid-out line, it stores an index to the first character of the line. std::vector mCharacterLogicalToVisualMap; ///< The map to store the character's logical (input) index according to its visual (reordered) index. std::vector mCharacterVisualToLogicalMap; ///< The map to store the character's visual (reordered) index according to its logical (input) index. @@ -219,20 +170,23 @@ public: }; /** - * It represents a fade boundary. - * If Exceed policy is set to Fade all text which does not fit within the text-view fade boundary is faded out. Text which exceeds the text-view boundary becomes invisible. + * @brief This structure represents a fade boundary. + * + * If the Exceed policy is set to Fade all text which does not fit within the text-view fade boundary is faded out. Text which exceeds the text-view boundary becomes invisible. * The \e left, \e right, \e top and \e bottom values are positive, in pixels and set the distances between the text-view and fade boundaries. */ struct FadeBoundary { /** - * Default constructor. + * @brief Default constructor. + * * Initializes all values to 0. It means no fade boundary. */ FadeBoundary(); /** - * Constructor. + * @brief Constructor. + * * Initializes the fade boundary with the given values. * * @param[in] left value in pixels. @@ -242,36 +196,38 @@ public: */ FadeBoundary( PixelSize left, PixelSize right, PixelSize top, PixelSize bottom ); - PixelSize mLeft; - PixelSize mRight; - PixelSize mTop; - PixelSize mBottom; + PixelSize mLeft; ///< The left fade boundary + PixelSize mRight; ///< The right fade boundary + PixelSize mTop; ///< The top fade boundary + PixelSize mBottom; ///< The bottom fade bounday }; /** - * Define how to split the text in lines. - * SplitByNewLineChar will split the text in lines when a '\\n' character is found. - * SplitByWord has effect only when TextView size is assigned. - * It will split the text in lines when a '\\n' character is found or if a line exceeds the TextView's boundary. This option won't split a word in two. - * SplitByChar has effect only when TextView size is assigned. - * It will split the text in lines when a '\\n' character is found or if a line exceeds the TextView's boundary. This option might split a word in two. - * The default value is SplitByNewLineChar. + * @brief Define how to wrap the text in lines. + * + * \e SplitByNewLineChar will wrap the text in lines when a '\\n' character or a \
is found. + * \e SplitByWord has effect only when TextView size is assigned. + * It will wrap the text in lines when a '\\n' character or a \
is found or if a line exceeds the TextView's boundary. This option won't split a word in two. + * \e SplitByChar has effect only when TextView size is assigned. + * It will wrap the text in lines when a '\\n' character or a \
is found or if a line exceeds the TextView's boundary. This option might split a word in two. + * The default value is \e SplitByNewLineChar. */ enum MultilinePolicy { - SplitByNewLineChar, ///< Text lines will split when '\\n' character is found. - SplitByWord, ///< Text lines will split by word or if '\\n' character is found. It has effect only when TextView size is assigned. - SplitByChar ///< Text lines will split by char or if '\\n' character is found. It has effect only when TextView size is assigned. + SplitByNewLineChar, ///< Text lines will wrap when '\\n' character is found. + SplitByWord, ///< Text lines will wrap by word or if '\\n' character is found. It has effect only when TextView size is assigned. + SplitByChar ///< Text lines will wrap by char or if '\\n' character is found. It has effect only when TextView size is assigned. }; /** - * Define how to display the text when it doesn't fit inside the TextView. - * The default value is ShrinkToFit. + * @brief Define how to display the text when it doesn't fit inside the TextView after the line wrap. + * + * The default value is \e Original. */ enum ExceedPolicy { Original, ///< Will display the text in its original size. If a line, a word or a character is bigger than the TextView size it may exceed its boundary. - Truncate, ///< Will display the text in its original size. It won't display the text which exceeds the TextView boundary. + Truncate, ///< @deprecated. Use Fade instead. Fade, ///< Will display the text in its original size. It won't display the text which exceeds the TextView boundary. It fades the text out. Split, ///< Will split the text in a new line. ShrinkToFit, ///< Will shrink the text to fit the TextView boundary. @@ -279,8 +235,9 @@ public: }; /** - * Define how to justify lines inside the text area. - * The default value is Left. + * @brief Define how to justify lines inside the text area. + * + * The default value is \e Left. */ enum LineJustification { @@ -292,41 +249,56 @@ public: public: /** - * Create an TextView handle; this can be initialised with TextView::New() + * @brief Create a TextView handle; this can be initialised with TextView::New(). + * * Calling member functions with an uninitialised Dali::Object handle is not allowed. */ TextView(); /** - * Copy constructor. Creates another handle that points to the same real object + * @brief Copy constructor. + * + * Creates another handle that points to the same real object + * @param[in] handle The handle to copy from */ TextView( const TextView& handle ); /** - * Assignment operator. Changes this handle to point to another real object + * @brief Assignment operator. + * + * Changes this handle to point to another real object + * @param[in] handle The handle to copy from + * @return a reference to this */ TextView& operator=( const TextView& handle ); /** - * Create a TextView control with no text + * @brief Create a TextView control with no text. + * * @return A handle the TextView control. */ static TextView New(); /** - * Create a TextView control. + * @brief Create a TextView control. + * * @param[in] text to display. * @return A handle the TextView control. */ static TextView New( const std::string& text ); /** - * @copydoc TextView New( const std::string& text ) + * @brief Create a TextView control with styled text. + * + * @param[in] text The text with style to display. + * @return A handle the TextView control. */ static TextView New( const MarkupProcessor::StyledTextArray& text ); /** - * Downcast an Object handle to TextView. If handle points to a TextView the + * @brief Downcast an Object handle to TextView. + * + * If handle points to a TextView the * downcast produces valid handle. If not the returned handle is left uninitialized. * @param[in] handle Handle to an object * @return handle to a TextView or an uninitialized handle @@ -334,25 +306,28 @@ public: static TextView DownCast( BaseHandle handle ); /** - * Virtual destructor. + * @brief Virtual destructor. + * * Dali::Object derived classes typically do not contain member data. */ virtual ~TextView(); /** - * Replace the current text with a new text string. + * @brief Replace the current text with a new text string. + * * @param[in] text to display. The string may contain style tags. */ void SetText( const std::string& text ); /** - * Replace the current text with a new text string with style. - * @param[in] text with style to display. + * @brief Replace the current text with a new text string with style. + * + * @param[in] text The text with style to display. */ void SetText( const MarkupProcessor::StyledTextArray& text ); /** - * Inserts the given text in the specified position + * @brief Inserts the given text in the specified position. * * @param[in] position Where the given text is going to be added. * @param[in] text The text to be added. @@ -360,12 +335,15 @@ public: void InsertTextAt( std::size_t position, const std::string& text ); /** - * @copydoc InsertTextAt( std::size_t position, const std::string& text ) + * @brief Inserts the given text with style in the specified position. + * + * @param[in] position Where the given text is going to be added. + * @param[in] text The text with style to be added. */ void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text ); /** - * Replaces part of the text. + * @brief Replaces part of the text. * * It removes the specified number of characters from the given position and inserts the given text in the same specified position. * @@ -376,12 +354,18 @@ public: void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text ); /** - * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text ) + * @brief Replaces part of the text. + * + * It removes the specified number of characters from the given position and inserts the given text with style in the same specified position. + * + * @param[in] position of the first character to be removed and Where the given text is going to be added. + * @param[in] numberOfCharacters number of characters to be removed. + * @param[in] text The text with style to be added. */ void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text ); /** - * Removes the specified number of characters from the given position. + * @brief Removes the specified number of characters from the given position. * * @param[in] position of the first character to be removed. * @param[in] numberOfCharacters number of characters to be removed. @@ -389,26 +373,30 @@ public: void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters ); /** - * Get the currently displayed text. + * @brief Get the currently displayed text. + * * @return The currently displayed text. */ std::string GetText() const; /** - * Sets a line height offset. + * @brief Sets a line height offset. + * * The line height offset will be added to the font line height. * @param [in] offset The height offset in PointSize units. */ void SetLineHeightOffset( PointSize offset ); /** - * Retrieves the line height offset. + * @brief Retrieves the line height offset. + * * @return The line height offset in PointSize units. */ PointSize GetLineHeightOffset() const; /** - * Sets the given style to the current text. + * @brief Sets the given style to the current text. + * * By default all style settings are applied but a bit mask could be used to modify only certain style settings. * @note TextView doesn't store a copy of the given style, it applies the given style to the current text only. * Subsequent calls to SetText() will override any style set by this method. @@ -418,69 +406,80 @@ public: void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL ); /** - * Set the current text alignment. + * @brief Set the current text alignment. + * * Default alignment is (HorizontalCenter | VerticalCenter) * @param[in] align The new alignment option. */ void SetTextAlignment( Alignment::Type align ); /** - * Get the current text alignment combined into a single value. + * @brief Get the current text alignment combined into a single value. + * * The values can be tested by using the & operator * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ... + * @return the combined alignment */ Alignment::Type GetTextAlignment() const; /** - * Sets how to split the text in lines policy. - * @param policy The multi-line policy. SplitByNewLineChar is set by default. + * @brief Sets how to wrap the text in lines policy. + * + * @param policy The multi-line policy. \e SplitByNewLineChar is set by default. */ void SetMultilinePolicy( MultilinePolicy policy ); /** - * Gets the split in lines policy. + * @brief Gets the wrap in lines policy. + * * @return The multi-line policy. */ MultilinePolicy GetMultilinePolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's width. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width. + * * @param policy The exceed policy. Original is set by default. */ void SetWidthExceedPolicy( ExceedPolicy policy ); /** - * Gets the width exceed policy. + * @brief Gets the width exceed policy. + * * @return The exceed policy. */ ExceedPolicy GetWidthExceedPolicy() const; /** - * Sets how to display the text inside the TextView when it exceeds the text-view's height. + * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height. + * * @param policy The exceed policy. Original is set by default. */ void SetHeightExceedPolicy( ExceedPolicy policy ); /** - * Gets the height exceed policy. + * @brief Gets the height exceed policy. + * * @return The exceed policy. */ ExceedPolicy GetHeightExceedPolicy() const; /** - * Sets how to justify lines inside the text area. + * @brief Sets how to justify lines inside the text area. + * * @param justification The line justification. Left is set by default. */ void SetLineJustification( LineJustification justification ); /** - * Gets the line justification. + * @brief Gets the line justification. + * * @return The line justification. */ LineJustification GetLineJustification() const; /** - * Sets a fade boundary. + * @brief Sets a fade boundary. * * @see FadeBoundary. * @@ -489,7 +488,7 @@ public: void SetFadeBoundary( const FadeBoundary& fadeBoundary ); /** - * Retrieves the fade boundary. + * @brief Retrieves the fade boundary. * * @see FadeBoundary. * @@ -498,28 +497,28 @@ public: const FadeBoundary& GetFadeBoundary() const; /** - * Sets the ellipsize text. + * @brief Sets the ellipsize text. * * @param[in] ellipsizeText The new text. The string may contain style tags. By default the ellipsize text is '...' */ void SetEllipsizeText( const std::string& ellipsizeText ); /** - * Sets the ellipsize text. + * @brief Sets the ellipsize text with style. * * @param[in] ellipsizeText The new text with its style. */ void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText ); /** - * Retrieves the ellipsize text. + * @brief Retrieves the ellipsize text. * * @return The ellipsize text. */ std::string GetEllipsizeText() const; /** - * A mechanism to retrieve layout information from the TextView. + * @brief A mechanism to retrieve layout information from the TextView. * * It produces a vector of CharcterLayoutInfo structures which describe the size and position of each character, * two vectors which maps the logical and visual positions of the characters in a bidirectional text, the size @@ -532,7 +531,7 @@ public: void GetTextLayoutInfo( TextLayoutInfo& textLayoutInfo ); /** - * Allows modification of text-actor's position in the depth sort algorithm. + * @brief Allows modification of text-actor's position in the depth sort algorithm. * * @see Dali::RenderableActor::SetSortModifier() * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back. @@ -540,23 +539,40 @@ public: void SetSortModifier( float depthOffset ); /** - * Sets whether text-view renders text using a previously generated snapshot. + * @brief Sets whether text-view renders text using a previously generated snapshot. * - * Rendering long text using a snapshot may increase performance. The default value is \e true (render using a snapshot). + * Rendering long text using a snapshot may increase performance. The default value is \e false (render without using a snapshot). * * @param[in] enable Whether text-view is using a snapshot to render text. */ void SetSnapshotModeEnabled( bool enable ); /** - * Retrieves whether text-view is using a snapshot to render text + * @brief Retrieves whether text-view is using a snapshot to render text. * * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false. */ bool IsSnapshotModeEnabled() const; /** - * Enables or disables the text scroll. + * @brief Sets whether markup processing should be carried out. + * + * To use markup, applications need to SetMarkupProcessingEnabled first, then SetText(). + * + * @see SetText() + * @param[in] enable whether markup processing is carried out or not. + */ + void SetMarkupProcessingEnabled( bool enable ); + + /** + * @brief Retrieves whether text-view is processing markup text + * + * @return \e true if text-view markup processing is enabled, otherwhise it returns \e false. + */ + bool IsMarkupProcessingEnabled() const; + + /** + * @brief Enables or disables the text scroll. * * When scroll is enabled, snapshot mode will be enabled automatically. Equally, if scroll is disabled * the snapshot mode is restored to the previous value. @@ -566,14 +582,14 @@ public: void SetScrollEnabled( bool enable ); /** - * Retrieves whether the text scroll is enabled. + * @brief Retrieves whether the text scroll is enabled. * * @return \e true if the scroll is enabled. */ bool IsScrollEnabled() const; /** - * Sets a new scroll position. + * @brief Sets a new scroll position. * * The new scroll position set could be trimmed if the text doesn't cover the whole text-view. * i.e. If a text-view is 100x100 and a text is 200x100 a scroll position beyond 50x0 will be trimmed to 50x0. @@ -587,25 +603,25 @@ public: void SetScrollPosition( const Vector2& position ); /** - * Recrieves current scroll position. + * @brief Recrieves current scroll position. * * @return The scroll position. */ const Vector2& GetScrollPosition() const; /** - * Whether the last scroll position set was trimmed. + * @brief Whether the last scroll position set was trimmed. * * @return \e true if the last scroll position set was trimmed, otherwise \e false. */ bool IsScrollPositionTrimmed() const; public: - // Signals + /// @brief Signal types typedef SignalV2< void ( TextView textView, Vector2 scrollDelta ) > ScrolledSignalV2; /** - * Signal emitted when the scroll position changes. + * @brief Signal emitted when the text is scrolled inside the text-view. * * A callback with the following prototype can be connected to this signal. * @@ -613,19 +629,24 @@ public: * * \e textView is the handle of the text-view emitting the signal. * \e scrollDelta is the differente of the current scroll position with the previous one. + * @return The signal to connect to */ ScrolledSignalV2& ScrolledSignal(); public: // Not intended for application developers /** - * Creates a handle using the Toolkit::Internal implementation. + * @brief Creates a handle using the Toolkit::Internal implementation. + * @note Not intended for application developers + * * @param[in] implementation The Control implementation. */ TextView( Internal::TextView& implementation ); /** - * Allows the creation of this Control from an Internal::CustomActor pointer. + * @brief Allows the creation of this Control from an Internal::CustomActor pointer. + * @note Not intended for application developers + * * @param[in] internal A pointer to the internal CustomActor. */ TextView( Dali::Internal::CustomActor* internal );