Hello, this is the documentation for flet_introduction - a powerful extension for Flet that allows you to easily create beautiful and interactive onboarding/introduction screens for your applications.

This extension is a “bridge” to the popular Flutter library introduction_screen, providing you with all its flexibility in the familiar Flet Python syntax.

🌟 Features.

** Fully dynamic pages: Create pages using strings for text and standard Flet controls (ft.Image, ft.Row, ft.Column) for images and footers.

• Resource-independent:** Work with your images (assets) just like any other Flet application. No more copying files inside the extension!
• Flexible customization of indicators:** Easily change the color, size and shape of indicator dots using simple dictionaries.
• Event management:** Handle on_done and skip events with common Python functions.
• Programmatic navigation:** Control the screen with code to navigate to any page by its index.
• Customize animations:** Choose from several built-in animations for page turning.

📦 Installation

pip install flet_introduction # Hypothetical installation team

🚀 Getting started (Simple example)

This is a minimal example to get you started. It creates a simple three-page introduction screen.

Important points to get started:.

1. Create a folder called assets/images next to your main.py and put the images there.
2. Use page.theme_mode = ft.ThemeMode.LIGHT to make the background light.
3. Don't forget to set expand=True for IntroductionScreen so that it fills the entire screen.

import flet as ft
from flet_introduction import IntroductionScreen, PageViewModel

def main(page: ft.Page):
    page.title = "Example Intro"
    page.theme_mode = ft.ThemeMode.LIGHT 

    def on_done_click(e):
        page.clean()
        page.add(ft.Text("Welcome!", size=30))
        page.update()
        
    def on_skip_click(e):
        on_done_click(e)

    # Створюємо список сторінок
    pages = [
        PageViewModel(
            title="Welcome to Flet!",
            body="Example code for introduction_screen extension",
            image=ft.Image(src="/images/flet_logo.png", width=250),
            title_style={"size": 28, "weight": "bold"},
            body_style={"size": 18, "color": ft.Colors.BLACK54},
        ),
        PageViewModel(
            title="Powerful",
            body="You can easily create pages using familiar Flet controls.",
            image=ft.Image(src="/images/flutter_logo.png", width=250),
            title_style={"size": 28, "weight": "bold"},
        ),
        PageViewModel(
            title="Ready to get started?",
            body="Tap Done to return to the main screen.",
            image=ft.Image(src="/images/rocket.png", width=250),
            title_style={"size": 28, "weight": "bold"},
        ),
    ]

    intro_screen = IntroductionScreen(
        pages=pages,
        on_done=on_done_click,
        on_skip=on_skip_click,
        
        expand=True, # REQUIRED
        show_skip_button=True,
        
        done_text="Done",
        skip_text="Skip",
        next_text="Next",
    )
    
    page.add(intro_screen)

ft.app(target=main, assets_dir="assets")

🛠️ Advanced use

Here's an example that demonstrates more advanced features: custom page footer, programmatic navigation, and changing the shape of indicators.

import flet as ft
from flet_introduction import IntroductionScreen, PageViewModel, AnimationCurve

def main(page: ft.Page):
    page.title = "Extended Intro example"
    page.theme_mode = ft.ThemeMode.LIGHT

    def on_done_click(e):
        page.clean()
        page.add(ft.Text("You have completed your presentation!", size=30))
        page.update()

    pages = [
        PageViewModel(
            title="Page 1",
            body="Example page",
            image=ft.Image(src="/images/page1.png", width=250),
        ),
        PageViewModel(
            title="Custom footer",
            body="This button at the bottom will take you back to the first page.",
            image=ft.Image(src="/images/page2.png", width=250),
        ),
    ]

    intro_screen = IntroductionScreen(
        pages=pages,
        on_done=on_done_click,
        expand=True,
        done_text="Done",
        next_text="Next",
        
        curve=AnimationCurve.EASE_OUT,
        
        dots_decorator={
            "color": ft.Colors.GREY_300,
            "active_color": ft.Colors.PURPLE,
            "size": {"width": 10, "height": 10},
            "active_size": {"width": 25, "height": 10},

            "active_shape": {
                "type": "rounded_rectangle",
                "radius": 5.0
            }
        },
    )
    
    page.add(intro_screen)

ft.app(target=main, assets_dir="assets")

📖 API Reference

Клас IntroductionScreen

The main control for creating a presentation screen.

Властивість	Тип	Опис
pages	List[PageViewModel]	A list of PageViewModel objects representing each page.
on_done	Callable	The function called when you click the Done button.
on_skip	Callable	The function called when you click the Skip button.
ref	Ref	Links to access control methods, e.g. go_to_page().
expand	bool	True to stretch the control to the entire available space.
show_skip_button	bool	Shows or hides the "Skip" button.
done_text	str	Text for the "Done" button.
skip_text	str	Text for the "Skip" button.
next_text	str	Text for the "Next" button.
curve	AnimationCurve	Sets the flipping animation.
dots_decorator	Dict	Сatcher to customize the appearance of indicators (see below).

• go_to_page(page_index: int): Programmatically goes to the page at the specified index.

Class PageViewModel.

A data class that describes a single page.

Властивість	Тип	Опис
title	str	Title page.
body	str	Main text page.
image	ft.Image	Flet image widget to display on the page.
footer	ft.Control	Any Flet control that will be displayed at the bottom of the page (footer).

Enum AnimationCurve

Used for the property curve in IntroductionScreen.

• EASE_IN
• EASE_OUT
• EASE_IN_OUT
• LINEAR
• BOUNCE_IN
• BOUNCE_OUT
• ELASTIC_IN

---