Indikátor načítania

SecureLoadingIndicator (Jetpack Compose), SecureLoadingView (XML/View) a SecureLoadingOverlay sú voliteľné komponenty knižnice zobrazujúce animovaný indikátor načítania počas spracovania platby. Po naviazaní na ComgateSecureSession sa komponenta zobrazuje a skrýva automaticky v závislosti od stavu platby.

Tip

Komponenta je voliteľná — platba prebehne korektne aj bez nej. Slúži výhradne na vizuálnu spätnú väzbu pre používateľa.

Štruktúra

Indikátor načítania sa skladá z dvoch vizuálnych prvkov:

• Animovaný spinner — kruhový spinner s plynule otáčajúcim sa oblúkom 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žitie v Jetpack Compose

import cz.comgate.sdk.compose.*

val loadingState = rememberLoadingIndicatorState(session)

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

rememberLoadingIndicatorState(session) vytvorí LoadingIndicatorState, automaticky naviaže komponentu na session a zapamätá si ju počas rekompozícií. Nie je potrebné volať žiadnu inicializáciu navyše.

Použitie v XML (View)

Pridajte 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á integrácia so 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é správanie možno kedykoľvek zakázať — napríklad ak si zobrazenie načítania riadite sami:

// Compose (cez state)
loadingState.isLoadingEnabled = false

// View
binding.loadingView.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

Komponentu možno ovládať nezávisle od session — napríklad pre vlastné načítacie scenáre nesúvisiace s platbou:

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

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

Preklad textového popisku

Predvolený text pod spinnerom je automaticky odvodený z jazyka zvolenej platobnej session — žiadne ručné nastavenie nie je nutné.

Vlastný text popisku možno nastaviť takto:

// Compose (cez LoadingIndicatorState)
loadingState.setLoadingText("Zpracováváme platbu…")

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

Po nastavení vlastného textu sa automatický preklad zo session na tento popisok už neuplatní — ani pri zmene jazyka platby.

Popisok možno skryť odovzdaním null alebo prázdneho reťazca:

loadingState.setLoadingText(null)

Štylizácia

Metody

Všetky nižšie uvedené metódy sú dostupné v update bloku composable SecureLoadingIndicator (priamy prístup k inštancii SecureLoadingView) aj pri priamom volaní na View.

Podmnožina označená ako iba View nie je exponovaná cez LoadingIndicatorState ani cez update blok Compose.

Metóda	Parameter	Popis
setSpinnerColor(color)	Int	Farba otáčejícího se oblouku.
setTrackColor(color)	Int	Farba statické dráhy spinneru.
setStrokeWidthDp(dp)	Float	Hrúbka oblúka aj dráhy v dp.
setSpinnerSizeDp(dp)	Float	Priemer spinnera v dp.
setLoadingText(text)	String?	Text popisku pod spinnerem. null alebo "" popisek skryje.
setLoadingTextColor(color)	Int	Farba textu popisku.
setLoadingTextSizeSp(sp)	Float	Veľkosť textu popisku v sp.
setLoadingBackgroundColor(color)	Int	Farba pozadí celé komponenty.
setLoadingCornerRadiusDp(dp)	Float	Zaoblenie rohov pozadia v dp.
setLoadingPaddingDp(horizontalDp, verticalDp)	Float, Float	Vnútorné odsadenie komponenty v dp.
setLoadingTextGapDp(dp)	Float	Medzera medzi spinnerom a popiskom 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 skrátenú sadu metód: setSpinnerColor, setTrackColor, setStrokeWidthDp, setSpinnerSizeDp, setLoadingText, setLoadingTextColor a setLoadingTextSizeSp. Zvyšné metódy (pozadie, zaoblenie rohov, odsadenie atď.) sú dostupné výhradne cez update blok — viď ukážka nižšie.

Prí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	Hrúbka oblúka aj dráhy.
app:loadingSpinnerSize	dimension	48dp	Priemer spinnera.
app:loadingText	string	(preklad session)	Vlastný text popisku. Ak nie je uvedený, použije sa preložený text zo session.
app:loadingTextColor	color	#666666	Farba textu popisku.
app:loadingTextSize	dimension	14sp	Veľkosť textu popisku.
app:loadingTextGap	dimension	8dp	Medzera medzi spinnerom a popiskom.
app:loadingBackgroundColor	color	Priehľadná	Farba pozadia celej komponenty.
app:loadingCornerRadius	dimension	0dp	Zaoblenie rohov pozadia.
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.