Label

Labels are primarily used for displaying non-editable text in windows, such as placing a title next to an Entry widget. You can set label text in the constructor or later with Label.setText or Label.setMarkup.

Label width adjusts automatically, and multi-line labels can be created by including line breaks (\n) in the text string.

Selectable Labels

Labels can be made selectable using Label.selectable, allowing users to copy the text to the clipboard. Only make labels with valuable information (like error messages) selectable.

Text Justification and Wrapping

The label text can be justified using Label.justify. Word-wrapping, activated with Label.wrap, ensures labels fit neatly within limited space.

Formatting Options

Label supports simple text formatting, allowing text to appear bold, colored, or larger by using the Label.setMarkup method with Pango Markup syntax. For example, <b>bold text</b> or <s>strikethrough text</s>.

Labels can also display clickable hyperlinks, styled similarly to web browsers with colored, underlined text. Links are created with HTML-like <a> tags and can include a title attribute, which shows as a tooltip.

label.setMarkup(
    "Go to <a href=\"https://www.org\" title=\"Our website\">GTK4 website</a> for more"
)

Mnemonics

Labels may contain mnemonics, which are underlined characters used for keyboard navigation. Create mnemonics by adding an underscore before the mnemonic character (e.g., "_File") and using Label.newWithMnemonic or Label.setTextWithMnemonic. Mnemonics activate any activatable widget within the label’s container, like a Button. If the target widget isn’t within the same container, use Label.mnemonicWidget to specify the target.

Example

samples/gtk/widgets/src/nativeMain/kotlin/org/gtkkn/samples/gtk/widgets/Label.kt

fun label(): Box {
    val hbox = Box(Orientation.HORIZONTAL, spacing = 10).apply {
        homogeneous = false
        marginStart = 16
        marginTop = 16
        marginEnd = 16
        marginBottom = 16
    }
    val vboxLeft = Box(orientation = Orientation.VERTICAL, spacing = 10).apply {
        homogeneous = false
        vexpand = true
        hexpand = true
    }
    val vboxRight = Box(orientation = Orientation.VERTICAL, spacing = 10).apply {
        homogeneous = false
        vexpand = true
        hexpand = true
    }

    hbox.append(vboxLeft)
    hbox.append(vboxRight)

    val button = getButton()
    vboxLeft.apply {
        append(getNormalLabel())
        append(getLeftJustifiedLabel())
        append(getRightJustifiedLabel())
        append(getMarkupLabel())
        append(getLabelWithMnemonic(button))
    }
    vboxRight.apply {
        append(getLineWrappedLabel())
        append(getLineWrappedFilledLabel())
        append(button)
    }

    return hbox
}

private fun getNormalLabel() =
    Label(str = "This is a normal label").apply {
        vexpand = true
        hexpand = true
    }

private fun getLeftJustifiedLabel() = Label("").apply {
    setText("This is a left-justified label.\nWith multiple lines.")
    vexpand = true
    hexpand = true
    justify = Justification.LEFT
}

private fun getRightJustifiedLabel() = Label("This is a right-justified label.\nWith multiple lines.").apply {
    vexpand = true
    hexpand = true
    justify = Justification.RIGHT
}

private fun getLineWrappedLabel() = Label(
    str = "This is an example of a line-wrapped label.  It should not be taking up the entire             width " +
        "allocated to it, but automatically wraps the words to fit.\n     It supports multiple paragraphs correctly, " +
        "and  correctly   adds many          extra  spaces. ",
).apply {
    vexpand = true
    hexpand = true
    wrap = true
    maxWidthChars = 32
}

private fun getLineWrappedFilledLabel() = Label(
    str = "This is an example of a line-wrapped, filled label. It should be taking up the entire              width " +
        "allocated to it.  Here is a sentence to prove my point.  Here is another sentence. Here comes the sun, do de" +
        " do de do.\n    This is a new paragraph.\n    This is another newer, longer, better paragraph.  It is " +
        "coming to an end, unfortunately.",
).apply {
    vexpand = true
    hexpand = true
    wrap = true
    justify = Justification.FILL
    maxWidthChars = 32
}

private fun getMarkupLabel() = Label("").apply {
    setMarkup(
        "Text can be <small>small</small>, <big>big</big>, <b>bold</b>, <i>italic</i> and even point to " +
            "somewhere in the <a href=\"https://www.gtk.org\" title=\"Click to find out more\">internets</a>.",
    )
    vexpand = true
    hexpand = true
    wrap = true
    maxWidthChars = 48
}

private fun getLabelWithMnemonic(button: Widget) =
    Label.newWithMnemonic("_Press Alt + P to select button to the right").apply {
        vexpand = true
        hexpand = true
        selectable = true
        mnemonicWidget = button
    }

private fun getButton() =
    Button(label = "It does nothing").apply {
        vexpand = true
        hexpand = true
    }