Indikátor načítania

SecureLoadingIndicator (Jetpack Compose), SecureLoadingView (XML/View) a SecureLoadingOverlay jsou volitelné komponenty knižnice zobrazující animovaný indikátor načítania počas spracovania 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ýhradne k vizuální spätnej väzbe pro používateľe.

Struktura

Indikátor načítanie 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; predvolené text se automaticky odvozuje z jazyka session

Ve predvoleném stavu je komponenta skrytá (visibility GONE) a zobrazí se až pri začatí spracovania 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 alebo fragmentu naváže komponentu na session:

binding.loadingView.setup(session)

Automatická integrace se session

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

• Zobrazí se, jakmile zahájí spracovania platby (používateľ stiskl platební tlačidlo)
• Skryje se, jakmile dorazí terminální výsledek platby (Paid, Cancelled, Failed, alebo Pending)

Automatické chování lze kedykoľvek zakázat — například ak si zobrazení načítanie řídíte sami:

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

// View
binding.loadingView.isLoadingEnabled = false

Informácie

Pri isLoadingEnabled = false jsou metody show() / hide() stále plně funkční. Zakázáno je iba automatické zobrazenie ří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()

Překlad textového popisku

Predvolený text pod spinnerem je automaticky odvozený z jazyka zvolené platební session — žádné ruční nastavenie 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 nastavenie vlastního textu se automatický překlad ze session na tento popisek už neuplatní — ani pri změně jazyka platby.

Popisek lze skryť předáním null alebo prázdného reťazca:

loadingState.setLoadingText(null)

Stylování

Metody

Všechny níže uvedené metody jsou dostupné v update bloku composable SecureLoadingIndicator (přímý přístup k instanci SecureLoadingView) i pri přímém volání na View.

Podmnožina označená jako iba View není exponována přes LoadingIndicatorState ani přes update blok Compose.

Metoda	Parametr	Popis
setSpinnerColor(color)	Int	Farba otáčejícího se oblouku.
setTrackColor(color)	Int	Farba 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 alebo "" popisek skryje.
setLoadingTextColor(color)	Int	Farba textu popisku.
setLoadingTextSizeSp(sp)	Float	Velikost textu popisku v sp.
setLoadingBackgroundColor(color)	Int	Farba 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. (iba View)
setLoadingFontFamily(family)	String	Rodina písma popisku (napr. "sans-serif-medium"). (iba View)
setLoadingTypeface(typeface)	Typeface	Písmo popisku pomocí instance Typeface. (iba View)

Informácie

LoadingIndicatorState v Compose exponuje zkrácenou sadu metod: setSpinnerColor, setTrackColor, setStrokeWidthDp, setSpinnerSizeDp, setLoadingText, setLoadingTextColor a setLoadingTextSizeSp. Zbývající metody (pozadí, zaoblenie rohů, odsazení atd.) jsou dostupné výhradne 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 atribúty

XML atribút	Formát	Predvolené hodnota	Popis
app:loadingSpinnerColor	color	#4287f5	Farba otáčejícího se oblouku.
app:loadingTrackColor	color	#E0E0E0	Farba 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. Ak není uveden, použije se přeložený text ze session.
app:loadingTextColor	color	#666666	Farba textu popisku.
app:loadingTextSize	dimension	14sp	Velikost textu popisku.
app:loadingTextGap	dimension	8dp	Mezera mezi spinnerem a popiskem.
app:loadingBackgroundColor	color	Průhledná	Farba pozadí celé komponenty.
app:loadingCornerRadius	dimension	0dp	Zaoblení rohů pozadí.
app:loadingPaddingHorizontal	dimension	16dp	Horizontální vnútorné odsadenie.
app:loadingPaddingVertical	dimension	16dp	Vertikální vnútorné odsadenie.
app:loadingEnabled	boolean	true	Povoluje/zakazuje automatické zobrazenie pri spracovaní platby.

---

SecureLoadingOverlay

SecureLoadingOverlay je alternatívna varianta indikátora načítania. Na rozdiel od SecureLoadingView, ktorá sa vkladá priamo do layoutu, sa SecureLoadingOverlay zobrazuje ako plávajúci panel vykreslený nad celou obrazovkou so stmavenым pozadím.

Nejde o View — nevkladáte ju do XML layoutu ani do Compose stromu. Vytvoríte ju ako bežný objekt v kóde.

Tip

Komponenta je voliteľná — platba prebehne korektne aj bez nej.

Použitie

Vytvorte inštanciu, voliteľne nakonfigurujte štýl a zavolajte setup(session, activity):

import cz.comgate.sdk.ui.SecureLoadingOverlay

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

Po zavolaní setup sa overlay zobrazuje a skrýva automaticky:

• Zobrazí sa, keď sa začne spracovanie platby
• Skryje sa, keď dorazí terminálny výsledok platby (Paid, Cancelled, Failed)
• Odpojí sa, keď je aktivita zničená (automaticky, ak aktivita implementuje LifecycleOwner, čo AppCompatActivity spĺňa)

Informácie

Ak aktivita neimplementuje LifecycleOwner, volajte detach() ručne v onDestroy.

Stmavenie pozadia

Vlastnosť dimAmount (typ Float, predvolená hodnota 0.5) určuje priehľadnosť stmaveného pozadia za overlayom:

loadingOverlay.dimAmount = 0.0f   // bez stmavenia
loadingOverlay.dimAmount = 0.5f   // predvolené — polopriehľadne čierne
loadingOverlay.dimAmount = 1.0f   // plne čierne

Štýlovanie

Štýlovacie rozhranie SecureLoadingOverlay je totožné s rozhraním SecureLoadingView. Všetky metódy možno volať pred aj po zavolaní setup:

Metóda	Popis	Predvolené
setSpinnerColor(color: Int)	Farba otáčajúceho sa oblúka	#4287f5
setTrackColor(color: Int)	Farba statickej dráhy	#E0E0E0
setStrokeWidthDp(dp: Float)	Šírka ťahu spinnera v dp	4f
setSpinnerSizeDp(dp: Float)	Veľkosť spinnera v dp	48f
setLoadingText(text: String?)	Text pod spinnerom; null alebo prázdny reťazec text skryje	automaticky z prekladu session
setLoadingTextColor(color: Int)	Farba textu	#666666
setLoadingTextSizeSp(sp: Float)	Veľkosť textu v sp	14f
setLoadingTextGapDp(dp: Float)	Medzera medzi spinnerom a textom v dp	8f
setLoadingFontFamily(family: String)	Názov rodiny písma (napr. "sans-serif-medium")	systémové
setLoadingTypeface(typeface: Typeface)	Priame nastavenie fontu	systémové
setLoadingBackgroundColor(color: Int)	Farba pozadia karty; Color.TRANSPARENT pre spinner bez karty	biela
setLoadingCornerRadiusDp(dp: Float)	Zaoblenie rohov karty v dp	16f
setLoadingPaddingDp(horizontalDp: Float, verticalDp: Float)	Vnútorné odsadenie karty v dp	28f × 28f

Prí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á integrácia so session

Automatické správanie možno zakázať vlastnosťou isLoadingEnabled — napríklad ak si zobrazenie načítania riadi te sami:

loadingOverlay.isLoadingEnabled = false

Informácie

Pri isLoadingEnabled = false sú metódy show() / hide() stále plne funkčné. Zakázané je iba automatické zobrazenie riadené stavom platby.

Manuálne ovládanie

Overlay možno zobraziť a skryť nezávisle od session — napríklad pre vlastné načítacie scenáre nesúvisiace s platbou:

loadingOverlay.show(activity)
loadingOverlay.hide()

Odpojenie od session

loadingOverlay.detach()

detach() odstráni poslucháča na session a skryje prípadný zobrazený overlay. Pri použití AppCompatActivity sa volá automaticky pri onDestroy.