# 2. Erste Schritte #

← Installation · Inhalt · Gemeinsame Basis →

Ziel: eine erste Komponente in fünf Minuten anzeigen und anschließend das Schema verstehen, das für alle Komponenten identisch ist.

## 2.1 Die Demoanwendung öffnen #

Die Demoanwendung (`pbtoolboxai_demo`) und die Bibliothek `pbtoolboxai.pbl` werden im Format PowerBuilder 10 ausgeliefert — dem ältesten Format, das alle unterstützten Versionen noch lesen können.

1. Öffnen Sie den Workspace `pbtoolboxai_demo.pbw` in Ihrer PowerBuilder-Version.
2. PowerBuilder bietet an, die Bibliotheken zu migrieren: nehmen Sie an. Die Migration konvertiert `pbtoolboxai_demo.pbl` und `pbtoolboxai.pbl` in das Format Ihrer Version.
3. Führen Sie einen Full Build des Ziels aus und starten Sie es: Das Schaufenster öffnet sich mit den Komponentenkacheln.

Erst diese Migration liefert Ihnen ein `pbtoolboxai.pbl` im Format Ihres PowerBuilder: Genau diese migrierte Datei fügen Sie anschließend der Library list Ihrer eigenen Anwendungen hinzu.

> ⚠️ Die Migration ist eine Einbahnstraße: Eine nach PowerBuilder 2025 migrierte Bibliothek lässt sich nicht mehr in PowerBuilder 10 öffnen. Migrieren Sie eine Kopie des ausgelieferten Ordners und bewahren Sie das Original auf.

## 2.2 Die Komponente setzen #

1. Öffnen Sie ein Fenster (neu oder vorhanden).
2. Insert → Control → User Object → wählen Sie `u_pbt_statictext` aus `pbtoolboxai.pbl`.
3. Benennen Sie es `uo_texte` und legen Sie seine Größe fest.

Im Painter zeigt das Steuerelement einen grauen Rahmen mit „PBToolboxAI component (rendered at runtime)“: Die eigentliche Darstellung erfolgt erst zur Laufzeit.

> 💡 Um die Events der Komponente abzufangen, erstellen Sie besser ein abgeleitetes Userobject (`u_pbt_statictext` → `uo_mon_texte`) und schreiben die Event-Skripte dort. Sie können sie auch direkt auf dem im Fenster gesetzten Steuerelement schreiben.

## 2.3 Sie steuern #

Im Event `open` des Fensters:

    // Inhalt (der Text akzeptiert Rich-Auszeichnung: [b], [color=...], [br]...)
    uo_texte.is_text = "Willkommen bei [b]PBToolboxAI[/b]!"

    // Formatierung: alles ist eine EIGENSCHAFT, kein Setter
    uo_texte.is_align    = uo_texte.ALIGN_CENTER
    uo_texte.is_valign   = uo_texte.VALIGN_CENTER
    uo_texte.ii_font_size = 14
    uo_texte.il_text_color = RGB(0, 103, 192)

Das war alles: Die Komponente stellt sich dar, übernimmt das Design und reagiert auf Interaktionen.

### Konstanten statt Zeichenketten #

Jede Eigenschaft mit vordefinierten Werten stellt Konstanten auf der Komponente bereit. Die IDE vervollständigt sie automatisch und sie bewahren Sie vor Tippfehlern:

    uo_texte.is_align = uo_texte.ALIGN_CENTER      // anstelle von "center"
    uo_texte.is_theme_style = uo_texte.THEME_STYLE_OFFICE2007
    uo_texte.is_theme_mode  = uo_texte.THEME_MODE_DARK

## 2.4 Events empfangen #

Die Komponenten melden typisierte PB-Events. Schreiben Sie die Skripte auf Ihrem Steuerelement (oder auf Ihrem abgeleiteten Userobject):

    // Event ue_clicked von uo_texte
    MessageBox("PBToolboxAI", "Text angeklickt")

    // Event ue_hyperlink von uo_texte -- ausgeloest durch [hyperlink=...]
    // as_url = die angeklickte Adresse
    Run("explorer.exe " + as_url)

## 2.5 Das Schema, für alle Komponenten identisch #

Schritt | Sie tun | Die Komponente tut
--- | --- | ---
Erstellung | Das Userobject setzen | Erstellt sich, stellt Ihre Befehle in die Warteschlange
Konfiguration | Eigenschaften zuweisen / `of_add_*` aufrufen | Wendet sie an, auch bevor sie bereit ist
Bereit | (nichts) | Löst `ue_ready` aus
Interaktion | (nichts) | Löst typisierte `ue_*`-Events aus
Größenänderung | (nichts) | Folgt der Größe des Userobjects
Zurücksetzen | `of_reset()` | Kehrt in den Neuzustand zurück
Schließen | Das Fenster schließen | Zerstört sich sauber

Sie müssen sich nie um HTML, JSON oder den Zustand „bereit / nicht bereit“ kümmern.

## 2.6 Ein vollständiges Beispiel #

    // ---- Event open des Fensters -----------------------------------------
    // Fasst die Aenderungen in EINEM einzigen Repaint zusammen (kein Flackern)
    uo_texte.of_set_redraw(false)

    uo_texte.is_text        = "Umsatz: [b][color=#2e7d32]1 240 500 €[/color][/b]" &
                              + "[br][size-=15]Aktualisiert am " + String(Today(), "dd/mm/yyyy") + "[/size-=15]"
    uo_texte.is_align       = uo_texte.ALIGN_CENTER
    uo_texte.is_valign      = uo_texte.VALIGN_CENTER
    uo_texte.ii_padding     = 12
    uo_texte.ii_corner_radius = 6
    uo_texte.is_tooltip     = "Kumuliert seit dem 1. Januar"

    uo_texte.of_set_redraw(true)

## 2.7 Rückgabecodes #

Alle Methoden `of_*` liefern einen `long` zurück:

    long ll_rc

    ll_rc = uo_texte.of_reset()
    if ll_rc < 0 then
        // -2 = Komponente nicht erstellt (Runtime fehlt) ; -5 = ungueltiges Argument
        f_log(uo_texte.of_get_last_error())
    end if

In der Praxis wird der Rückgabewert oft ignoriert (Konfigurationsfehler sind selten) und man stützt sich auf `ue_ready` / `ue_runtime_missing`.

Die Zuweisung einer Eigenschaft liefert nichts zurück (es ist eine PowerScript-Zuweisung): Ein ungültiger Wert wird von der Komponente ignoriert, ohne Ausnahme.

## 2.8 Und danach #

- Gemeinsame Basis: Eigenschaften-Engine, Items, ausführlicher Lebenszyklus.
- Designs und Erscheinungsbild: der gesamten Anwendung eine visuelle Identität geben.
- Komponentenreferenz: eine Seite je Komponente der v1.

← Installation · Inhalt · Gemeinsame Basis →