Typography and Text

class Font:
    """
    Individual font file with specific weight, width, and slant.
    
    Parameters:
    - typeface: Typeface this font belongs to
    - weight: FontWeight, font weight (THIN to HEAVY)
    - width: FontWidth, font width (ULTRA_CONDENSED to ULTRA_EXPANDED) 
    - slant: FontSlant, font slant (UPRIGHT, OBLIQUE, ITALIC)
    """
    def __init__(self, typeface, weight=MEDIUM, width=NORMAL, slant=UPRIGHT): ...
    
    @property
    def name(self): ...  # Font name
    @property
    def family_name(self): ...  # Font family name
    @property  
    def full_name(self): ...  # Full font name
    
    # Font metrics
    def get_kerning(self, left_glyph, right_glyph): ...  # Kerning between glyphs
    def get_ligature(self, *glyphs): ...  # Ligature for glyph sequence
    
    # Text measurement
    def get_glyph_metrics(self, glyph, size): ...  # Individual glyph metrics
    def get_text_width(self, text, size): ...  # Text width in font units

class Typeface:
    """
    Collection of related fonts (regular, bold, italic, etc.).
    
    Parameters:
    - name: str, typeface name
    - *fonts: Font objects in this typeface family
    """
    def __init__(self, name, *fonts): ...
    
    def get_font(self, weight=MEDIUM, width=NORMAL, slant=UPRIGHT): ...  # Get specific font
    def get_matching_font(self, pattern): ...  # Get font matching pattern
    
    @property
    def fonts(self): ...  # All fonts in typeface

class TextStyle(Style):
    """
    Style class specifically for text formatting properties.
    
    Supports all typography attributes including font, color, spacing,
    alignment, and advanced OpenType features.
    """
    
    # Font properties
    font_family = Attribute(str)  # Font family name
    font_size = Attribute(Dimension)  # Text size
    font_weight = Attribute(FontWeight)  # Weight (normal, bold, etc.)
    font_width = Attribute(FontWidth)  # Width (condensed, expanded, etc.)
    font_slant = Attribute(FontSlant)  # Slant (upright, italic, oblique)
    
    # Color and appearance
    text_color = Attribute(Color)  # Text color
    background_color = Attribute(Color)  # Background color
    
    # Spacing and positioning
    line_spacing = Attribute(LineSpacing)  # Line height
    character_spacing = Attribute(Dimension)  # Letter spacing
    word_spacing = Attribute(Dimension)  # Word spacing
    
    # Text effects
    text_decoration = Attribute(TextDecoration)  # Underline, strikethrough, etc.
    text_transform = Attribute(TextTransform)  # Uppercase, lowercase, capitalize
    
    # Alignment
    text_align = Attribute(TextAlign)  # Horizontal alignment
    vertical_align = Attribute(VerticalAlign)  # Vertical alignment

class InlineStyle(TextStyle):
    """Style class for inline text elements with additional inline-specific properties."""

class StyledText(InlineFlowable):
    """
    Base class for text content with styling capabilities.
    
    All text in rinohtype documents is represented by StyledText
    or its subclasses, providing consistent styling interfaces.
    """
    
    def spans(self, container=None):
        """
        Generate text spans for rendering.
        
        Parameters:
        - container: Container for context-sensitive styling
        
        Yields:
        - (text_string, TextStyle) tuples for each styled span
        """
        ...
    
    def to_string(self, flowable_target): ...  # Convert to plain string
    
    @property
    def text_style(self): ...  # Get effective text style

class SingleStyledText(StyledText):
    """
    Text with uniform styling throughout.
    
    Most efficient text class for content with consistent formatting
    across the entire text string.
    
    Parameters:
    - text: str, the text content
    - style: TextStyle, styling to apply to entire text
    - parent: parent element
    """
    def __init__(self, text, style=None, parent=None): ...
    
    @property
    def text(self): ...  # Text content string

class MixedStyledText(StyledText):
    """
    Text with multiple styles applied to different parts.
    
    Supports complex formatting with different styles for different
    character ranges within the same text element.
    
    Parameters:
    - text_and_styles: list of (text, style) tuples or StyledText objects
    - style: TextStyle, base style for the entire element
    - parent: parent element
    """
    def __init__(self, text_and_styles, style=None, parent=None): ...
    
    def append(self, styled_text): ...  # Add more styled text
    def __add__(self, other): ...  # Concatenate with other styled text
    def __iadd__(self, other): ...  # In-place concatenation

class ConditionalMixedStyledText(MixedStyledText):
    """
    Mixed styled text with conditional content based on document context.
    
    Allows different text content or styling based on document properties,
    page context, or other conditional factors.
    """
    
    def __init__(self, condition, true_text, false_text, style=None, parent=None): ...

class WarnInline(SingleStyledText):
    """
    Inline text that generates warnings during processing.
    
    Used for deprecated features, missing references, or other
    issues that should be flagged but not prevent document generation.
    
    Parameters:
    - message: str, warning message to display
    - style: TextStyle, styling for the warning text
    - parent: parent element
    """
    def __init__(self, message, style=None, parent=None): ...

class Space(SingleStyledText):
    """
    Regular breakable space character.
    
    Represents normal word-separating spaces that can be used
    as line break opportunities during text layout.
    """
    def __init__(self, style=None, parent=None): ...

class FixedWidthSpace(SingleStyledText):
    """
    Non-breaking space with fixed width.
    
    Space that cannot be used as a line break point and maintains
    consistent width regardless of justification.
    
    Parameters:
    - width: Dimension, fixed width for the space
    - style: TextStyle, styling for the space
    - parent: parent element
    """
    def __init__(self, width, style=None, parent=None): ...

class NoBreakSpace(SingleStyledText):
    """
    Non-breaking space that prevents line breaks.
    
    Equivalent to HTML   - keeps adjacent words together
    on the same line.
    """
    def __init__(self, style=None, parent=None): ...

class Spacer(SingleStyledText):
    """
    Flexible space that expands to fill available width.
    
    Used for justified text and flexible spacing within lines.
    Can expand or contract based on justification requirements.
    """
    def __init__(self, style=None, parent=None): ...

class Tab(SingleStyledText):
    """
    Tab character for column alignment.
    
    Moves text to next tab stop position as defined in paragraph
    tab stop settings.
    """
    def __init__(self, style=None, parent=None): ...

class Newline(SingleStyledText):
    """
    Manual line break within paragraph.
    
    Forces line break without ending paragraph, similar to HTML <br>.
    """
    def __init__(self, style=None, parent=None): ...

class Superscript(MixedStyledText):
    """
    Superscript text positioned above baseline.
    
    Automatically adjusts font size and baseline position
    for proper superscript appearance.
    
    Parameters:
    - text: str or StyledText, content for superscript
    - style: TextStyle, additional styling
    - parent: parent element
    """
    def __init__(self, text, style=None, parent=None): ...

class Subscript(MixedStyledText):
    """
    Subscript text positioned below baseline.
    
    Automatically adjusts font size and baseline position
    for proper subscript appearance.
    
    Parameters:
    - text: str or StyledText, content for subscript  
    - style: TextStyle, additional styling
    - parent: parent element
    """
    def __init__(self, text, style=None, parent=None): ...

class InlineFlowable(Styled):
    """
    Base class for elements that can be embedded inline within text.
    
    Provides interface for inline elements like images, formulas,
    or custom inline content that flows with text.
    
    Parameters:
    - baseline: Dimension, baseline offset for vertical alignment
    - id: str, unique identifier
    - style: InlineStyle, styling for the inline element
    - parent: parent element
    - source: source location information
    """
    def __init__(self, baseline=None, id=None, style=None, parent=None, source=None): ...
    
    def flow_inline(self, container, last_descender, state=None):
        """
        Flow inline element within text line.
        
        Parameters:
        - container: Container context for flowing
        - last_descender: Dimension, descender from previous content
        - state: layout state for continuation
        
        Returns:
        - (width, height, baseline, state): layout result
        """
        ...
    
    def spans(self, container=None):
        """
        Generate spans for inline rendering.
        
        Yields:
        - text spans that represent this inline element
        """
        ...

class InlineFlowableStyle(Style):
    """Style class for inline flowable elements."""
    
    baseline = Attribute(Dimension)  # Baseline adjustment
    
class InlineFlowableException(Exception):
    """Exception raised by inline flowable processing."""

# Font weights
THIN = <FontWeight>
EXTRA_LIGHT = <FontWeight>
LIGHT = <FontWeight> 
NORMAL = <FontWeight>
MEDIUM = <FontWeight>
SEMI_BOLD = <FontWeight>
BOLD = <FontWeight>
EXTRA_BOLD = <FontWeight>
HEAVY = <FontWeight>

# Font widths
ULTRA_CONDENSED = <FontWidth>
EXTRA_CONDENSED = <FontWidth>
CONDENSED = <FontWidth>
SEMI_CONDENSED = <FontWidth>
NORMAL = <FontWidth>
SEMI_EXPANDED = <FontWidth>
EXPANDED = <FontWidth>
EXTRA_EXPANDED = <FontWidth>
ULTRA_EXPANDED = <FontWidth>

# Font slants
UPRIGHT = <FontSlant>
OBLIQUE = <FontSlant>
ITALIC = <FontSlant>

from rinohtype.text import SingleStyledText, TextStyle
from rinohtype.color import Color
from rinohtype.dimension import PT

# Create styled text
title_style = TextStyle(
    font_size=18*PT,
    font_weight=BOLD,
    text_color=Color(0, 0, 0.8),
    text_align='center'
)

title_text = SingleStyledText("Document Title", style=title_style)

# Body text with different styling
body_style = TextStyle(
    font_size=11*PT,
    line_spacing=1.2,
    text_align='justify'
)

body_text = SingleStyledText("This is the main content...", style=body_style)

from rinohtype.text import MixedStyledText, SingleStyledText
from rinohtype.color import RED

# Create text with mixed formatting
bold_style = TextStyle(font_weight=BOLD)
italic_style = TextStyle(font_slant=ITALIC)
emphasis_style = TextStyle(text_color=RED, font_weight=BOLD)

mixed_text = MixedStyledText([
    SingleStyledText("This is "),
    SingleStyledText("bold", style=bold_style),
    SingleStyledText(" and this is "),
    SingleStyledText("italic", style=italic_style),
    SingleStyledText(" and this is "),
    SingleStyledText("emphasized", style=emphasis_style),
    SingleStyledText(".")
])

from rinohtype.font import Typeface, Font
from rinohtype.fonts import find_font

# Load system font
times_typeface = Typeface('Times', 
    Font('Times-Roman', weight=NORMAL, slant=UPRIGHT),
    Font('Times-Bold', weight=BOLD, slant=UPRIGHT), 
    Font('Times-Italic', weight=NORMAL, slant=ITALIC),
    Font('Times-BoldItalic', weight=BOLD, slant=ITALIC)
)

# Use specific font
regular_font = times_typeface.get_font(weight=NORMAL, slant=UPRIGHT)
bold_font = times_typeface.get_font(weight=BOLD, slant=UPRIGHT)

# Apply font in style
font_style = TextStyle(
    typeface=times_typeface,
    font_weight=BOLD,
    font_size=12*PT
)

from rinohtype.text import Superscript, Subscript, NoBreakSpace

# Mathematical notation with super/subscripts
formula = MixedStyledText([
    SingleStyledText("E = mc"),
    Superscript("2"),
    SingleStyledText(" where c = 3×10"),
    Superscript("8"),
    SingleStyledText(" m/s")
])

# Chemical formula
chemical = MixedStyledText([
    SingleStyledText("H"),
    Subscript("2"),
    SingleStyledText("SO"),
    Subscript("4")
])

# Non-breaking spaces for proper formatting
formatted_text = MixedStyledText([
    SingleStyledText("Dr."),
    NoBreakSpace(),
    SingleStyledText("John"),
    NoBreakSpace(), 
    SingleStyledText("Smith")
])

from rinohtype.text import TextStyle
from rinohtype.dimension import PT

# Advanced text styling with OpenType features
advanced_style = TextStyle(
    font_size=12*PT,
    character_spacing=0.05*PT,  # Letter spacing
    word_spacing=0.25*PT,       # Word spacing
    line_spacing=1.4,           # Line height multiplier
    text_decoration='underline',  # Text decoration
    text_transform='capitalize'   # Text transformation
)

# Paragraph with tab stops for columns
from rinohtype.paragraph import TabStop, LEFT, RIGHT, CENTER

tabbed_style = TextStyle(
    tab_stops=[
        TabStop(50*PT, LEFT),
        TabStop(100*PT, CENTER),
        TabStop(150*PT, RIGHT)
    ]
)

from rinohtype.text import InlineFlowable, InlineFlowableStyle

class CustomInline(InlineFlowable):
    """Custom inline element."""
    
    def __init__(self, content, **kwargs):
        super().__init__(**kwargs)
        self.content = content
    
    def flow_inline(self, container, last_descender, state=None):
        # Custom inline layout logic
        width = self.calculate_width()
        height = self.calculate_height()
        baseline = self.calculate_baseline()
        return (width, height, baseline, None)
    
    def spans(self, container=None):
        # Generate spans for rendering
        yield (str(self.content), self.get_style('text'))

# Use custom inline element
custom_element = CustomInline("Special Content")
text_with_custom = MixedStyledText([
    SingleStyledText("Before "),
    custom_element,
    SingleStyledText(" after")
])