Writing a Slide

In CuP, each "screen" you present is a Slide written in Compose Multiplatform.

Creating a Slide

To create a Slide, use the Slide function:

val helloWorld by Slide {
    Text("Hello, World!", fontSize = 24.sp)
}

kotlin

A Slide must have a unique name, which is used by CuP to handle navigation. The Slide function uses a Kotlin Property Delegate to create a Slide with the same name as the variable that holds it.

You can provide the name yourself with the Slide constructor:

val helloWorld = Slide(name = "myFirstSlide") {
    Text("Hello, World!", fontSize = 24.sp)
}

kotlin

The name of a Slide should not contain spaces or special characters as it is used in the URL of the presentation when it is exported to the web.

Animating the Slide content

A Slide can have multiple steps.

val mySlide by Slide(
    stepCount = 4
) { step ->
    /*...*/
}

kotlin

How a slide displays each of these steps and animates the transition between them is up to you.

Steps will range from 0 up to excluding stepCount. With stepCount = 4, the first step is 0, and the last is therefore 3.

Here’s an example of a Slide with 2 steps, and only showing the subtitle on second step:

val title by Slide(
    stepCount = 2
) { step ->
    Text("How to CuP?", fontSize = 24.sp)
    AnimatedVisibility(visible = step >= 1) { (1)
        Text("You'll see, it's easy!")
    }
}

kotlin

1	The use of `>=` rather than `==` allows to add steps later without breaking the slide.

Displaying styled text

CuP provides two utilities to make easier to display styled text in a Slide.

Styled text

While Compose allows you to style your text efficiently with AnnotatedString, building one can be verbose. For example, to create a simple styled text with an inline content:

Text(buildAnnotatedString {
    append("Hello, ")
    withStyle(SpanStyle(fontWeight = FontWeight.Bold)) {
        append("my friend")
    }
    append(" ")
    appendInlineContent("foobar")
    append("!")
})

kotlin

CuP provides the styled function, which allows you to create the same string in a much more readable way:

Text(styled { "Hello, ${+b}my friend${-b} ${IC("foobar")}!" })

kotlin

The styled function allows you to use markers that define the beginning (with ${+marker}) and end (with ${-marker}) of that marker’s style. It also allows you to insert inline content (with ${IC("id")}).

The default stylesheet only contains two markers:

b: to make text bold.
i: to make text italic.

You can extend this and provide your own SpanStylesheet:

object MyStyleSheet : SpanStyleSheet() {
    val em by registerMarker(SpanStyle(
        fontWeight = FontWeight.Bold,
        fontSize = 1.2.em
    ))
}

@Composable
fun Title() {
    Text(
        styled(MyStyleSheet) { "There is ${+em}so much${-em} to do!" },
        fontSize = 32.sp
    )
}

kotlin

Bullet Points

Bullet points are a standard way of presenting a list of items in presentations. CuP provides a BulletPoints composable function that animates each item as it appears:

BulletPoints {
    BulletPoint(visible = step >= 1) {
        Text("The first item.")
    }
    BulletPoint(visible = step >= 2) {
        Text("The second item.")
    }
}

kotlin

Bullet points are not part of the core of CuP. They are part of different artefacts, because they depend on the Compose material or material3 libraries.

So, whether you are using material or material3 you would need to import the proper dependency. See Widgets: Material section.

Configuring a Slide ratio & transitions

If you want to configure all your slides ratio and transitions throughout your presentation, you should do it in the presentation configuration.

By default, the screen ratio of a Slide is 4/3. This is to prevent long sentences that span across the entire screen.
If you want to have more space, you can configure a Slide to have a wider ratio.

val helloWorld by Slide(
    specs = SlideSpecs(size = SLIDE_SIZE_16_9) (1)
) {
    Text("Hello, World!", fontSize = 24.sp)
}

kotlin

1	Set the size of the slide to the default 16/9 size.

You can also configure the Slide’s transitions:

val helloWorld by Slide(
    specs = SlideSpecs(
        startTransitions = TransitionSet.fade, (1)
        endTransitions = TransitionSet.fade (2)
    )
) {
    Text("Hello, World!", fontSize = 24.sp)
}

kotlin

1	When transitioning between the previous slide and this slide, or vice versa.
2	When transitioning between this slide and the next slide, or vice versa.

Creating a custom Slide transition

To create a Slide custom transition, you need to provide a TransitionSet.

You can draw inspiration from:

The default provided transitions (moveHorizontal, moveVertical, & fade).
This demo transition (that implements a 3D rotation transition).

Previewing a Slide content

By running the app

You can run the desktop application either by executing the ./gradlew run command or by running the main function in the IDE.

CuP will remember the size and position of its window, as well as the current slide and step displaying.
This allows you to preview your slide simply by running the app on the JVM. This is, at the moment, the easier way to preview and work on a slide.

With the preview annotation

The @Preview annotation is currently only compatible with Desktop JVM. You therefore cannot use the @Preview annotation in the commonMain source set when targeting the web.

CuP provides the PresentationPreview composable that allows you to preview a Slide with the Compose preview annotation:

@Preview
fun helloWorldPreview() {
    PresentationPreview(
        slide = helloWorld,
        step = 1
    ) { slides ->
        Presentation(slides)
    }
}

kotlin

Preloading some Slide content

A slide composable content only runs when the slide is displayed.

You may need to prepare some content so that you don’t have to do it when the slide displays (to avoid janks). To do so, you can declare a PreparedSlide instead of a Slide:

// The content you want to preload.
class Content { /*...*/ }
suspend fun loadContent(): Content { TODO() }

val contentDemo by PreparedSlide(
    stepCount = 1
) {
    val content by remember { mutableStateOf<Content?>(null) }
    LaunchedEffect(Unit) {
        content = loadContent()
    }

    slideContent { step ->
        Text("Some amazing content:", fontSize = 24.sp)

        AnimatedVisibility(visible = step >= 1) {
            if (content == null) Text("Loading...")
            else ContentDisplay(content)
        }
    }
}

kotlin

You must not display anything in the "prepare" section of the PreparedSlide or you will break your presentation!

Attaching user data to a slide

You can attach custom user data to a Slide that can be consumed by your presentation decoration or by a plugin. For example, let’s say that you want your presentation decoration to display a text banner over certain slides.

You first need to create a DataMapElement:

data class Banner(
    val text: String,
) : DataMapElement<Banner>(Key) { (1)
    companion object Key : DataMap.Key<Banner> (2)
}

kotlin

1	A data class to be attached to a Slide must implement `DataMapElement`.
2	Each `DataMapElement` must have a corresponding `DataMap.Key`.

You can now attach this user data to a Slide:

val whatever by Slide(
    user = Banner("Work In Progress!")
) {
    /* Slide content */
}

kotlin

You can combine multiple DataMapElement into a DataMap:

With the plus operator:

val whatever by Slide(
    user = Banner("Work In Progress!") + SpeakerNotesMD("Amazing!")
) {}

kotlin

With the dataMapOf function:

val whatever by Slide(
    user = dataMapOf(
        Banner("Work In Progress!"),
        SpeakerNotesMD("Amazing!")
    )
) {}

kotlin