TextLayout.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
 
#include "CoreMinimal.h"
#include "UObject/ObjectMacros.h"
#include "Misc/Attribute.h"
#include "Layout/Margin.h"
#include "Framework/Text/TextRunRenderer.h"
#include "Framework/Text/TextLineHighlight.h"
#include "Framework/Text/IRun.h"
#include "Styling/SlateTypes.h"
 
#include "TextLayout.generated.h"
 
#define TEXT_LAYOUT_DEBUG 0
 
class IBreakIterator;
class ILayoutBlock;
class ILineHighlighter;
class IRunRenderer;
enum class ETextHitPoint : uint8;
enum class ETextShapingMethod : uint8;
 
UENUM( BlueprintType )
namespace ETextJustify
{
    enum Type : int
    {
        Left,
 
        Center,
 
        Right,
 
        InvariantLeft,
 
        InvariantRight,
    };
}
 
 
UENUM( BlueprintType )
enum class ETextWrappingPolicy : uint8
{
    DefaultWrapping = 0,
 
    AllowPerCharacterWrapping,
};
 
UENUM( BlueprintType )
enum class ETextFlowDirection : uint8
{
    Auto = 0,
 
    LeftToRight,
 
    RightToLeft,
 
    Culture,
};
 
SLATE_API ETextFlowDirection GetDefaultTextFlowDirection();
 
struct FTextLocation
{
public:
    FTextLocation( const int32 InLineIndex = 0, const int32 InOffset = 0 )
        : LineIndex( InLineIndex )
        , Offset( InOffset )
    {
 
    }
 
    FTextLocation( const FTextLocation& InLocation, const int32 InOffset )
        : LineIndex( InLocation.GetLineIndex() )
        , Offset(FMath::Max(InLocation.GetOffset() + InOffset, 0))
    {
 
    }
 
    bool operator==( const FTextLocation& Other ) const
    {
        return
            LineIndex == Other.LineIndex &&
            Offset == Other.Offset;
    }
 
    bool operator!=( const FTextLocation& Other ) const
    {
        return
            LineIndex != Other.LineIndex ||
            Offset != Other.Offset;
    }
 
    bool operator<( const FTextLocation& Other ) const
    {
        return this->LineIndex < Other.LineIndex || (this->LineIndex == Other.LineIndex && this->Offset < Other.Offset);
    }
 
    int32 GetLineIndex() const { return LineIndex; }
    int32 GetOffset() const { return Offset; }
    bool IsValid() const { return LineIndex != INDEX_NONE && Offset != INDEX_NONE; }
 
    friend inline uint32 GetTypeHash(const FTextLocation& InSubject)
    {
        return HashCombine(InSubject.LineIndex, InSubject.Offset);
    }
 
private:
    int32 LineIndex;
    int32 Offset;
};
 
class FTextSelection
{
 
public:
 
    FTextLocation LocationA;
 
    FTextLocation LocationB;
 
public:
 
    FTextSelection()
        : LocationA(INDEX_NONE)
        , LocationB(INDEX_NONE)
    {
    }
 
    FTextSelection(const FTextLocation& InLocationA, const FTextLocation& InLocationB)
        : LocationA(InLocationA)
        , LocationB(InLocationB)
    {
    }
 
    const FTextLocation& GetBeginning() const
    {
        if (LocationA.GetLineIndex() == LocationB.GetLineIndex())
        {
            if (LocationA.GetOffset() < LocationB.GetOffset())
            {
                return LocationA;
            }
 
            return LocationB;
        }
        else if (LocationA.GetLineIndex() < LocationB.GetLineIndex())
        {
            return LocationA;
        }
 
        return LocationB;
    }
 
    const FTextLocation& GetEnd() const
    {
        if (LocationA.GetLineIndex() == LocationB.GetLineIndex())
        {
            if (LocationA.GetOffset() > LocationB.GetOffset())
            {
                return LocationA;
            }
 
            return LocationB;
        }
        else if (LocationA.GetLineIndex() > LocationB.GetLineIndex())
        {
            return LocationA;
        }
 
        return LocationB;
    }
};
 
class FTextLayout
    : public TSharedFromThis<FTextLayout>
{
public:
 
    struct FBlockDefinition
    {
        FTextRange ActualRange;
        TSharedPtr< IRunRenderer > Renderer;
    };
 
    struct FBreakCandidate
    {
        FTextRange ActualRange;
        FTextRange TrimmedRange;
        FVector2D ActualSize;
        float TrimmedWidth;
        float FirstTrailingWhitespaceCharWidth;
 
        int16 MaxAboveBaseline;
        int16 MaxBelowBaseline;
 
        int8 Kerning;
 
#if TEXT_LAYOUT_DEBUG
        FString DebugSlice;
#endif
    };
 
    class FRunModel
    {
    public:
 
        SLATE_API FRunModel( const TSharedRef< IRun >& InRun);
 
    public:
 
        SLATE_API TSharedRef< IRun > GetRun() const;;
 
        SLATE_API void BeginLayout();
        SLATE_API void EndLayout();
 
        SLATE_API FTextRange GetTextRange() const;
        SLATE_API void SetTextRange( const FTextRange& Value );
        
        SLATE_API int16 GetBaseLine( float Scale ) const;
        SLATE_API int16 GetMaxHeight( float Scale ) const;
 
        SLATE_API FVector2D Measure( int32 BeginIndex, int32 EndIndex, float Scale, const FRunTextContext& InTextContext );
 
        SLATE_API int8 GetKerning( int32 CurrentIndex, float Scale, const FRunTextContext& InTextContext );
 
        static SLATE_API int32 BinarySearchForBeginIndex( const TArray< FTextRange >& Ranges, int32 BeginIndex );
 
        static SLATE_API int32 BinarySearchForEndIndex( const TArray< FTextRange >& Ranges, int32 RangeBeginIndex, int32 EndIndex );
 
        SLATE_API TSharedRef< ILayoutBlock > CreateBlock( const FBlockDefinition& BlockDefine, float InScale, const FLayoutBlockTextContext& InTextContext ) const;
 
        SLATE_API void ClearCache();
 
        SLATE_API void AppendTextTo(FString& Text) const;
        SLATE_API void AppendTextTo(FString& Text, const FTextRange& Range) const;
 
    private:
 
        TSharedRef< IRun > Run;
        TArray< FTextRange > MeasuredRanges;
        TArray< FVector2D > MeasuredRangeSizes;
    };
 
    struct ELineModelDirtyState
    {
        typedef uint8 Flags;
        enum Enum
        {
            None = 0,
            WrappingInformation = 1<<0,
            TextBaseDirection = 1<<1, 
            ShapingCache = 1<<2,
            All = WrappingInformation | TextBaseDirection | ShapingCache,
        };
    };
 
    struct FLineModel
    {
    public:
 
        SLATE_API FLineModel( const TSharedRef< FString >& InText );
 
        TSharedRef< FString > Text;
        FShapedTextCacheRef ShapedTextCache;
        TextBiDi::ETextDirection TextBaseDirection;
        TArray< FRunModel > Runs;
        TArray< FBreakCandidate > BreakCandidates;
        TArray< FTextRunRenderer > RunRenderers;
        TArray< FTextLineHighlight > LineHighlights;
        ELineModelDirtyState::Flags DirtyFlags;
    };
 
    struct FLineViewHighlight
    {
        FVector2D Offset;
        float Width;
        TSharedPtr< ILineHighlighter > Highlighter;
    };
 
    struct FLineView
    {
        TArray< TSharedRef< ILayoutBlock > > Blocks;
        TArray< FLineViewHighlight > UnderlayHighlights;
        TArray< FLineViewHighlight > OverlayHighlights;
        FVector2D Offset;
        FVector2D Size;
        float TextHeight;
        float JustificationWidth;
        FTextRange Range;
        TextBiDi::ETextDirection TextBaseDirection;
        int32 ModelIndex;
    };
 
    struct FTextOffsetLocations
    {
    friend class FTextLayout;
 
    public:
        SLATE_API int32 TextLocationToOffset(const FTextLocation& InLocation) const;
        SLATE_API FTextLocation OffsetToTextLocation(const int32 InOffset) const;
        SLATE_API int32 GetTextLength() const;
 
    private:
        struct FOffsetEntry
        {
            FOffsetEntry(const int32 InFlatStringIndex, const int32 InDocumentLineLength)
                : FlatStringIndex(InFlatStringIndex)
                , DocumentLineLength(InDocumentLineLength)
            {
            }
 
            int32 FlatStringIndex;
 
            int32 DocumentLineLength;
        };
 
        TArray<FOffsetEntry> OffsetData;
    };
 
public:
 
    SLATE_API virtual ~FTextLayout();
 
    inline const TArray< FTextLayout::FLineView >& GetLineViews() const { return LineViews; }
    inline const TArray< FTextLayout::FLineModel >& GetLineModels() const { return LineModels; }
 
    SLATE_API FVector2D GetSize() const;
 
    SLATE_API FVector2D GetViewSize() const;
 
    SLATE_API FVector2D GetDrawSize() const;
 
    SLATE_API FVector2D GetWrappedSize() const;
 
    SLATE_API FVector2D GetWrappedDrawSize() const;
 
    inline float GetWrappingWidth() const { return WrappingWidth; }
    SLATE_API void SetWrappingWidth( float Value );
 
    inline ETextWrappingPolicy GetWrappingPolicy() const { return WrappingPolicy; }
    SLATE_API void SetWrappingPolicy(ETextWrappingPolicy Value);
 
    inline float GetLineHeightPercentage() const { return LineHeightPercentage; }
    SLATE_API void SetLineHeightPercentage( float Value );
 
    inline bool GetApplyLineHeightToBottomLine() const { return ApplyLineHeightToBottomLine; }
    SLATE_API void SetApplyLineHeightToBottomLine( bool Value );
 
    inline ETextJustify::Type GetJustification() const { return Justification; }
    SLATE_API void SetJustification( ETextJustify::Type Value );
 
    SLATE_API ETextJustify::Type GetVisualJustification() const;
 
    inline ETextTransformPolicy GetTransformPolicy() const { return TransformPolicy; }
    SLATE_API void SetTransformPolicy(ETextTransformPolicy Value);
 
    inline float GetScale() const { return Scale; }
    SLATE_API void SetScale( float Value );
 
    inline ETextShapingMethod GetTextShapingMethod() const { return TextShapingMethod; }
    SLATE_API void SetTextShapingMethod( const ETextShapingMethod InTextShapingMethod );
 
    inline ETextFlowDirection GetTextFlowDirection() const { return TextFlowDirection; }
    SLATE_API void SetTextFlowDirection( const ETextFlowDirection InTextFlowDirection );
 
    SLATE_API void SetTextOverflowPolicy(const TOptional<ETextOverflowPolicy> InTextOverflowPolicy);
 
    inline FMargin GetMargin() const { return Margin; }
    SLATE_API void SetMargin( const FMargin& InMargin );
 
    SLATE_API void SetVisibleRegion( const FVector2D& InViewSize, const FVector2D& InScrollOffset );
 
    SLATE_API void SetLineBreakIterator( TSharedPtr<IBreakIterator> InLineBreakIterator );
 
    SLATE_API void SetDebugSourceInfo(const TAttribute<FString>& InDebugSourceInfo);
 
    SLATE_API void ClearLines();
 
    struct FNewLineData
    {
        FNewLineData(TSharedRef<FString> InText, TArray<TSharedRef<IRun>> InRuns)
            : Text(MoveTemp(InText))
            , Runs(MoveTemp(InRuns))
        {
        }
 
        TSharedRef<FString> Text;
        TArray<TSharedRef<IRun>> Runs;
    };
 
    SLATE_API void AddLine( const FNewLineData& NewLine );
 
    SLATE_API void AddLines( const TArray<FNewLineData>& NewLines );
 
    SLATE_API void ClearRunRenderers();
 
    SLATE_API void SetRunRenderers( const TArray< FTextRunRenderer >& Renderers );
 
    SLATE_API void AddRunRenderer( const FTextRunRenderer& Renderer );
 
    SLATE_API void RemoveRunRenderer( const FTextRunRenderer& Renderer );
 
    SLATE_API void ClearLineHighlights();
 
    SLATE_API void SetLineHighlights( const TArray< FTextLineHighlight >& Highlights );
 
    SLATE_API void AddLineHighlight( const FTextLineHighlight& Highlight );
 
    SLATE_API void RemoveLineHighlight( const FTextLineHighlight& Highlight );
 
    SLATE_API virtual void UpdateIfNeeded();
 
    SLATE_API virtual void UpdateLayout();
 
    SLATE_API virtual void UpdateHighlights();
 
    SLATE_API void DirtyRunLayout(const TSharedRef<const IRun>& Run);
 
    SLATE_API void DirtyLayout();
 
    SLATE_API bool IsLayoutDirty() const;
 
    SLATE_API int32 GetLineViewIndexForTextLocation(const TArray< FTextLayout::FLineView >& LineViews, const FTextLocation& Location, const bool bPerformInclusiveBoundsCheck) const;
 
    SLATE_API FTextLocation GetTextLocationAt( const FVector2D& Relative, ETextHitPoint* const OutHitPoint = nullptr ) const;
 
    SLATE_API FTextLocation GetTextLocationAt( const FLineView& LineView, const FVector2D& Relative, ETextHitPoint* const OutHitPoint = nullptr ) const;
 
    SLATE_API FVector2D GetLocationAt( const FTextLocation& Location, const bool bPerformInclusiveBoundsCheck ) const;
 
    SLATE_API bool SplitLineAt(const FTextLocation& Location);
 
    SLATE_API bool JoinLineWithNextLine(int32 LineIndex);
 
    SLATE_API bool InsertAt(const FTextLocation& Location, TCHAR Character);
 
    SLATE_API bool InsertAt(const FTextLocation& Location, const FString& Text);
 
    SLATE_API bool InsertAt(const FTextLocation& Location, TSharedRef<IRun> InRun, const bool bAlwaysKeepRightRun = false);
 
    SLATE_API bool RemoveAt(const FTextLocation& Location, int32 Count = 1);
 
    SLATE_API bool RemoveLine(int32 LineIndex);
 
    SLATE_API bool IsEmpty() const;
 
    SLATE_API int32 GetLineCount() const;
 
    SLATE_API void GetAsText(FString& DisplayText, FTextOffsetLocations* const OutTextOffsetLocations = nullptr) const;
 
    SLATE_API void GetAsText(FText& DisplayText, FTextOffsetLocations* const OutTextOffsetLocations = nullptr) const;
 
    SLATE_API void GetTextOffsetLocations(FTextOffsetLocations& OutTextOffsetLocations) const;
 
    SLATE_API void GetSelectionAsText(FString& DisplayText, const FTextSelection& Selection) const;
 
    SLATE_API FTextSelection GetGraphemeAt(const FTextLocation& Location) const;
 
    SLATE_API FTextSelection GetWordAt(const FTextLocation& Location) const;
 
protected:
 
    SLATE_API FTextLayout();
 
    SLATE_API void CalculateTextDirection();
 
    SLATE_API void CalculateLineTextDirection(FLineModel& LineModel) const;
 
    SLATE_API ETextJustify::Type CalculateLineViewVisualJustification(const FLineView& LineView) const;
 
    SLATE_API void CreateWrappingCache();
 
    SLATE_API void CreateLineWrappingCache(FLineModel& LineModel);
 
    SLATE_API void FlushTextShapingCache();
 
    SLATE_API void FlushLineTextShapingCache(FLineModel& LineModel);
 
    SLATE_API void DirtyAllLineModels(const ELineModelDirtyState::Flags InDirtyFlags);
 
    SLATE_API void ClearView();
 
    SLATE_API void TransformLineText(FLineModel& LineModel) const;
 
    SLATE_API virtual void BeginLayout();
 
    SLATE_API void BeginLineLayout(FLineModel& LineModel);
 
    SLATE_API virtual void EndLayout();
 
    SLATE_API void EndLineLayout(FLineModel& LineModel);
 
    virtual TSharedRef<IRun> CreateDefaultTextRun(const TSharedRef<FString>& NewText, const FTextRange& NewRange) const = 0;
 
private:
 
    SLATE_API float GetWrappingDrawWidth() const;
 
    SLATE_API void FlowLayout();
    SLATE_API void MarginLayout();
 
    SLATE_API void FlowLineLayout(const int32 LineModelIndex, const float WrappingDrawWidth, TArray<TSharedRef<ILayoutBlock>>& SoftLine);
 
    SLATE_API void FlowHighlights();
 
    SLATE_API void JustifyLayout();
 
    SLATE_API void CreateLineViewBlocks( int32 LineModelIndex, const int32 StopIndex, const float WrappedLineWidth, const TOptional<float>& JustificationWidth, int32& OutRunIndex, int32& OutRendererIndex, int32& OutPreviousBlockEnd, TArray< TSharedRef< ILayoutBlock > >& OutSoftLine );
 
    SLATE_API FBreakCandidate CreateBreakCandidate( int32& OutRunIndex, FLineModel& Line, int32 PreviousBreak, int32 CurrentBreak );
 
    SLATE_API void GetAsTextAndOffsets(FString* const OutDisplayText, FTextOffsetLocations* const OutTextOffsetLocations) const;
 
protected:
    
    struct ETextLayoutDirtyState
    {
        typedef uint8 Flags;
        enum Enum
        {
            None = 0,
            Layout = 1<<0,
            Highlights = 1<<1, 
            All = Layout | Highlights,
        };
    };
 
    struct FTextLayoutSize
    {
        FTextLayoutSize()
            : DrawWidth(0.0f)
            , WrappedWidth(0.0f)
            , Height(0.0f)
        {
        }
 
        FVector2D GetDrawSize() const
        {
            return FVector2D(DrawWidth, Height);
        }
 
        FVector2D GetWrappedSize() const
        {
            return FVector2D(WrappedWidth, Height);
        }
 
        float DrawWidth;
 
        float WrappedWidth;
 
        float Height;
    };
 
    int32 CachedLayoutGeneration = 0;
 
    TArray< FLineModel > LineModels;
 
    TArray< FLineView > LineViews;
 
    TSet< int32 > LineViewsToJustify;
 
    ETextLayoutDirtyState::Flags DirtyFlags;
 
    ETextShapingMethod TextShapingMethod;
 
    ETextFlowDirection TextFlowDirection;
 
    float Scale;
 
    float WrappingWidth;
 
    ETextWrappingPolicy WrappingPolicy;
 
    ETextTransformPolicy TransformPolicy;
 
    FMargin Margin;
 
    ETextJustify::Type Justification;
 
    float LineHeightPercentage;
 
    bool ApplyLineHeightToBottomLine;
 
    FTextLayoutSize TextLayoutSize;
 
    float OverHeight;
 
    FVector2D ViewSize;
 
    FVector2D ScrollOffset;
 
    TSharedPtr<IBreakIterator> LineBreakIterator;
 
    TSharedRef<IBreakIterator> GraphemeBreakIterator;
 
    TSharedRef<IBreakIterator> WordBreakIterator;
 
    TUniquePtr<TextBiDi::ITextBiDi> TextBiDiDetection;
 
    TAttribute<FString> DebugSourceInfo;
 
    TOptional<ETextOverflowPolicy> TextOverflowPolicyOverride;
 
};