Add-BTText

SYNOPSIS

Add text to the toast.

SYNTAX

1
Add-BTText -ContentBuilder <ToastContentBuilder> [-Text] <String[]> [-MaxLines <Int32>] [-Language <String>]
2
[-PassThru] [<CommonParameters>]
Copied!

DESCRIPTION

The Add-BTText function adds custom text to a toast notification via a content builder object.

EXAMPLES

EXAMPLE 1

1
$Builder = New-BTContentBuilder
2
Add-BTText -ContentBuilder $Builder -Text 'First Line of Text'
Copied!
This example adds one custom text element to the toast content builder object stored in the $Builder variable using the ContentBuilder parameter explicitly.

EXAMPLE 2

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text'
Copied!
This example adds one custom text element to the toast content builder object stored in the $Builder variable by piping it into the Add-BTText function.

EXAMPLE 3

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text', 'Second Line of Text'
Copied!
This example adds two custom text elements to a toast content builder object with a single call of the Add-BTText function.

EXAMPLE 4

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text'
3
$Builder | Add-BTText -Text 'Second Line of Text'
Copied!
This example adds two custom text elements to a toast content builder object with two discrete calls of the Add-BTText function.

EXAMPLE 5

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text' -PassThru |
3
Add-BTText -Text 'Second Line of Text' -PassThru |
4
Add-BTText -Text 'Third Line of Text'
Copied!
This example adds three custom text elements to a toast content builder object using multiple calls of the Add-BTText function on the pipeline.
The PassThru parameter is used to pass the toast content builder down the pipeline. Note that this is not required at the end of the pipeline as the builder object being added to is already stored in a variable.

EXAMPLE 6

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text'
3
$Builder | Add-BTText -Text 'Second Line of Text'
4
$Builder | Add-BTText -Text 'Third Line of Text'
5
$Builder | Add-BTText -Text 'Fourth Line of Text'
Copied!
This example attempts to add four custom text elements to a toast content builder object.
Only the first three of these elements will be added and the fourth will generate a warning stating that the maximum number of lines has been reached.

EXAMPLE 7

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text' -MaxLines 1
3
$Builder | Add-BTText -Text 'Second Line of Text',
4
'Third Line of Text',
5
'Fourth Line of Text'
Copied!
This example sets the max lines for the first custom text element to 1, overriding the default value of 2.
This means the toast notification can now accept four custom text elements, each with a max line count of 1, for a total line count of 4.

EXAMPLE 8

1
$Builder = New-BTContentBuilder
2
$Builder | Add-BTText -Text 'First Line of Text' -Language en-NZ
Copied!
This example specifies that the language included in the text element is New Zealand English using the relevant BCP-47 code, en-NZ.

PARAMETERS

-ContentBuilder

The toast content builder object that represents the toast notification being constructed.
1
Type: ToastContentBuilder
2
Parameter Sets: (All)
3
Aliases:
4
5
Required: True
6
Position: Named
7
Default value: None
8
Accept pipeline input: True (ByValue)
9
Accept wildcard characters: False
Copied!

-Text

Custom text to display on the tile.
1
Type: String[]
2
Parameter Sets: (All)
3
Aliases:
4
5
Required: True
6
Position: 1
7
Default value: None
8
Accept pipeline input: False
9
Accept wildcard characters: False
Copied!

-MaxLines

The maximum number of lines the text element is allowed to display.
1
Type: Int32
2
Parameter Sets: (All)
3
Aliases:
4
5
Required: False
6
Position: Named
7
Default value: 0
8
Accept pipeline input: False
9
Accept wildcard characters: False
Copied!

-Language

The target locale of the toast notification, specified as a BCP-47 language tags such as "en-US" or "fr-FR". The locale specified here overrides any other specified locale, such as that in binding or visual.
1
Type: String
2
Parameter Sets: (All)
3
Aliases:
4
5
Required: False
6
Position: Named
7
Default value: None
8
Accept pipeline input: False
9
Accept wildcard characters: False
Copied!

-PassThru

Returns an object that represents the item with which you're working. By default, this cmdlet doesn't generate any output.
1
Type: SwitchParameter
2
Parameter Sets: (All)
3
Aliases:
4
5
Required: False
6
Position: Named
7
Default value: False
8
Accept pipeline input: False
9
Accept wildcard characters: False
Copied!

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

Microsoft.Toolkit.Uwp.Notifications.ToastContentBuilder

You can pipe a toast content builder object to Add-BTText.

System.String

You can provide multiple strings at once, but they cannot be piped.

OUTPUTS

None

The Add-BTText function does not provide any output by default.
You can optionally use the PassThru parameter to output the updated toast content builder object, which enables chaining functions together.

NOTES

A toast notification can contain a maximum of four reserved lines of text. By default this means you can include three customer text elements as the first, which acts like a heading, automatically reserves 2 lines.
You can override this behavior using the MaxLines parameter, specifically by setting the first line to a maximum of 1 line.
This function will ignore any text elements that would exceed this limit and output a warning stating this.

RELATED LINKS