Indikátor načítání

SecureLoadingIndicator (Jetpack Compose), SecureLoadingView (XML/View) a SecureLoadingOverlay jsou volitelné komponenty knihovny zobrazující animovaný indikátor načítání během zpracování platby. Po navázání na ComgateSecureSession se komponenta zobrazuje a skrývá automaticky v závislosti na stavu platby.

Tip

Komponenta je volitelná — platba proběhne korektně i bez ní. Slouží výhradně k vizuální zpětné vazbě pro uživatele.

Struktura

Indikátor načítání se skládá ze dvou vizuálních prvků:

• Animovaný spinner — kruhový spinner s plynule otáčejícím se obloukem nad statickou dráhou
• Textový popisek — volitelný text zobrazený pod spinnerem; výchozí text se automaticky odvozuje z jazyka session

Ve výchozím stavu je komponenta skrytá (visibility GONE) a zobrazí se teprve při zahájení zpracování platby.

Použití v Jetpack Compose

import cz.comgate.sdk.compose.*

val loadingState = rememberLoadingIndicatorState(session)

SecureLoadingIndicator(
    state = loadingState,
    modifier = Modifier
        .fillMaxWidth()
        .padding(top = 12.dp)
)

rememberLoadingIndicatorState(session) vytvoří LoadingIndicatorState, automaticky naváže komponentu na session a zapamatuje ji po dobu rekomposic. Není třeba volat žádnou inicializaci navíc.

Použití v XML (View)

Přidejte SecureLoadingView do layoutu:

<cz.comgate.sdk.SecureLoadingView
    android:id="@+id/loadingView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_marginTop="12dp"
    app:loadingSpinnerColor="#1E88E5"
    app:loadingTrackColor="#BBDEFB"
    app:loadingStrokeWidth="5dp"
    app:loadingSpinnerSize="52dp"
    app:loadingBackgroundColor="#F5F9FF"
    app:loadingCornerRadius="12dp"
    app:loadingPaddingHorizontal="16dp"
    app:loadingPaddingVertical="20dp" />

Poté v kódu aktivity nebo fragmentu naváže komponentu na session:

binding.loadingView.setup(session)

Automatická integrace se session

Po navázání (setup(session) nebo rememberLoadingIndicatorState(session)) se komponenta chová automaticky:

• Zobrazí se, jakmile zahájí zpracování platby (uživatel stiskl platební tlačítko)
• Skryje se, jakmile dorazí terminální výsledek platby (Paid, Cancelled, Failed)

Automatické chování lze kdykoliv zakázat — například pokud si zobrazení načítání řídíte sami:

// Compose (přes state)
loadingState.isLoadingEnabled = false

// View
binding.loadingView.isLoadingEnabled = false

Informace

Při isLoadingEnabled = false jsou metody show() / hide() stále plně funkční. Zakázáno je pouze automatické zobrazeni řízené stavem platby.

Manuální ovládání

Komponentu lze ovládat nezávisle na session — například pro vlastní načítací scénáře nesouvisející s platbou:

// Compose
loadingState.show()
loadingState.hide()

// View
binding.loadingView.show()
binding.loadingView.hide()

---

SecureLoadingOverlay

SecureLoadingOverlay je alternativní varianta indikátoru načítání. Na rozdíl od SecureLoadingView, která se vkládá přímo do layoutu, se SecureLoadingOverlay zobrazuje jako plovoucí panel vykreslený nad celou obrazovkou se ztmaveným pozadím.

Nejde o View — nevkládáte ji do XML layoutu ani do Compose stromu. Vytvoříte ji jako běžný objekt v kódu.

Tip

Komponenta je volitelná — platba proběhne korektně i bez ní.

Použití

Vytvořte instanci, volitelně nakonfigurujte styl a zavolejte setup(session, activity):

import cz.comgate.sdk.ui.SecureLoadingOverlay

val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setup(session, this)   // 'this' je Activity / AppCompatActivity

Po zavolání setup se overlay zobrazuje a skrývá automaticky:

• Zobrazí se, jakmile zahájí zpracování platby
• Skryje se, jakmile dorazí terminální výsledek platby (Paid, Cancelled, Failed)
• Odváže se, jakmile je aktivita zničena (automaticky, pokud aktivita implementuje LifecycleOwner, což AppCompatActivity splňuje)

Informace

Pokud aktivita neimplementuje LifecycleOwner, volejte detach() ručně v onDestroy.

Ztmavení pozadí

Vlastnost dimAmount (typ Float, výchozí hodnota 0.5) určuje průhlednost ztmaveného pozadí za overlayem:

loadingOverlay.dimAmount = 0.0f   // bez ztmavení
loadingOverlay.dimAmount = 0.5f   // výchozí — poloprůhledně černé
loadingOverlay.dimAmount = 1.0f   // plně černé

Stylizace

Stylovací rozhraní SecureLoadingOverlay je totožné s rozhraním SecureLoadingView. Všechny metody lze volat před i po zavolání setup:

Metoda	Popis	Výchozí
setSpinnerColor(color: Int)	Barva otáčejícího se oblouku	#4287f5
setTrackColor(color: Int)	Barva statické dráhy	#E0E0E0
setStrokeWidthDp(dp: Float)	Šířka tahu spinneru v dp	4f
setSpinnerSizeDp(dp: Float)	Velikost spinneru v dp	48f
setLoadingText(text: String?)	Text pod spinnerem; null nebo prázdný řetězec text skryje	automaticky z překladu session
setLoadingTextColor(color: Int)	Barva textu	#666666
setLoadingTextSizeSp(sp: Float)	Velikost textu v sp	14f
setLoadingTextGapDp(dp: Float)	Mezera mezi spinnerem a textem v dp	8f
setLoadingFontFamily(family: String)	Název rodiny písma (např. "sans-serif-medium")	systémové
setLoadingTypeface(typeface: Typeface)	Přímé nastavení fontu	systémové
setLoadingBackgroundColor(color: Int)	Barva pozadí karty; Color.TRANSPARENT pro spinner bez karty	bílá
setLoadingCornerRadiusDp(dp: Float)	Zaoblení rohů karty v dp	12f
setLoadingPaddingDp(horizontalDp: Float, verticalDp: Float)	Vnitřní odsazení karty v dp	24f × 24f

Příklad:

val loadingOverlay = SecureLoadingOverlay()
loadingOverlay.setSpinnerColor(Color.parseColor("#1E88E5"))
loadingOverlay.setTrackColor(Color.parseColor("#BBDEFB"))
loadingOverlay.setStrokeWidthDp(4f)
loadingOverlay.setSpinnerSizeDp(52f)
loadingOverlay.setLoadingCornerRadiusDp(16f)
loadingOverlay.setLoadingPaddingDp(28f, 28f)
loadingOverlay.dimAmount = 0.6f
loadingOverlay.setup(session, this)

Automatická integrace se session

Automatické chování lze zakázat vlastností isLoadingEnabled — například pokud si zobrazení načítání řídíte sami:

loadingOverlay.isLoadingEnabled = false

Informace

Při isLoadingEnabled = false jsou metody show() / hide() stále plně funkční. Zakázáno je pouze automatické zobrazení řízené stavem platby.

Manuální ovládání

Overlay lze zobrazit a skrýt nezávisle na session — například pro vlastní načítací scénáře nesouvisející s platbou:

loadingOverlay.show(activity)
loadingOverlay.hide()

Odpojení od session

loadingOverlay.detach()

detach() odstraní posluchač na session a skryje případný zobrazený overlay. Při použití AppCompatActivity se volá automaticky při onDestroy.

Překlad textového popisku

Výchozí text pod spinnerem je automaticky odvozený z jazyka zvolené platební session — žádné ruční nastavení není nutné.

Vlastní text popisku lze nastavit takto:

// Compose (přes LoadingIndicatorState)
loadingState.setLoadingText("Zpracováváme platbu…")

// View
binding.loadingView.setLoadingText("Zpracováváme platbu…")

Po nastavení vlastního textu se automatický překlad ze session na tento popisek již neuplatní — ani při změně jazyka platby.

Popisek lze skrýt předáním null nebo prázdného řetězce:

loadingState.setLoadingText(null)

Stylování

Metody

Všechny níže uvedené metody jsou dostupné při přímém volání na View.

V Compose je část metod dostupná přes LoadingIndicatorState a kompletní sada je dostupná přes update blok composable SecureLoadingIndicator (přímý přístup k instanci SecureLoadingView).

Metoda	Parametr	Popis
setSpinnerColor(color)	Int	Barva otáčejícího se oblouku.
setTrackColor(color)	Int	Barva statické dráhy spinneru.
setStrokeWidthDp(dp)	Float	Tloušťka oblouku i dráhy v dp.
setSpinnerSizeDp(dp)	Float	Průměr spinneru v dp.
setLoadingText(text)	String?	Text popisku pod spinnerem. null nebo "" popisek skryje.
setLoadingTextColor(color)	Int	Barva textu popisku.
setLoadingTextSizeSp(sp)	Float	Velikost textu popisku v sp.
setLoadingBackgroundColor(color)	Int	Barva pozadí celé komponenty.
setLoadingCornerRadiusDp(dp)	Float	Zaoblení rohů pozadí v dp.
setLoadingPaddingDp(horizontalDp, verticalDp)	Float, Float	Vnitřní odsazení komponenty v dp.
setLoadingTextGapDp(dp)	Float	Mezera mezi spinnerem a popiskem v dp.
setLoadingFontFamily(family)	String	Rodina písma popisku (např. "sans-serif-medium").
setLoadingTypeface(typeface)	Typeface	Písmo popisku pomocí instance Typeface.

Informace

LoadingIndicatorState v Compose exponuje zkrácenou sadu metod: setSpinnerColor, setTrackColor, setStrokeWidthDp, setSpinnerSizeDp, setLoadingText, setLoadingTextColor a setLoadingTextSizeSp. Zbývající metody (pozadí, zaoblení rohů, odsazení atd.) jsou dostupné výhradně přes update blok — viz ukázka níže.

Příklad v Compose (update blok)

SecureLoadingIndicator(
    state = loadingState,
    modifier = Modifier.fillMaxWidth(),
    update = {
        setSpinnerColor(Color.parseColor("#FF0000"))
        setTrackColor(Color.parseColor("#FFEBEE"))
        setStrokeWidthDp(4f)
        setSpinnerSizeDp(48f)
        setLoadingBackgroundColor(Color.WHITE)
        setLoadingCornerRadiusDp(12f)
        setLoadingPaddingDp(16f, 20f)
    }
)

XML atributy

XML atribut	Formát	Výchozí hodnota	Popis
app:loadingSpinnerColor	color	#4287f5	Barva otáčejícího se oblouku.
app:loadingTrackColor	color	#E0E0E0	Barva statické dráhy spinneru.
app:loadingStrokeWidth	dimension	4dp	Tloušťka oblouku i dráhy.
app:loadingSpinnerSize	dimension	48dp	Průměr spinneru.
app:loadingText	string	(překlad session)	Vlastní text popisku. Pokud není uveden, použije se přeložený text ze session.
app:loadingTextColor	color	#666666	Barva textu popisku.
app:loadingTextSize	dimension	14sp	Velikost textu popisku.
app:loadingTextGap	dimension	8dp	Mezera mezi spinnerem a popiskem.
app:loadingBackgroundColor	color	Průhledná	Barva pozadí celé komponenty.
app:loadingCornerRadius	dimension	0dp	Zaoblení rohů pozadí.
app:loadingPaddingHorizontal	dimension	16dp	Horizontální vnitřní odsazení.
app:loadingPaddingVertical	dimension	16dp	Vertikální vnitřní odsazení.
app:loadingEnabled	boolean	true	Povoluje/zakazuje automatické zobrazení při zpracování platby.