##

    Programmierfunktionen

    Allgemeine Programmierfunktionen
    Programmierfunktionen für Applications
    Programmierfunktionen für Katalog-files

    ____________________________________________________________________________

    Allgemeine Programmierfunktionen

    - Standard-Programmierfunktionen sind in jedem .gcad-Modell verwendbar,
    - können nur im Modus "MAN" erzeugt werden (oder aus Datei eingelesen werden);

    Standard-Programmierfunktionen sind:
    #-Kommentar, PRI, JUMP-Label, IF, WRITE, CALL, EXIT.

    # - Kommentar
    Das Zeichen # als erstes Zeichen einer Zeile definiert eine Kommentarzeile.

    PRI - Testausgaben von Texten / Variableninhalten:
    # nur zu Testzwecken im Meldungsfenster
    # Ausgabe der geometr. Struktur von Variablen (V), Punkten (P), Vektoren (D)
    #   Ausgabe anderer Objecttypen mit DUMP

    PRI "Text"
    PRI "Punkt1 =" P1
    PRI "Var 1 =" V1

    DUMP - Testausgaben:
    # nur zu Testzwecken im Meldungsfenster
    # Ausgabe von Listen, der geometr. Struktur von Objekten, ..
    # Siehe auch "PRI"

    DUMP      # Ausgabe der geom. Struktur eines Datenbank-objekts
    DUMP "GA"            # Ausgabe der Liste der graf. Attribute
    DUMP "DL"            # Ausgabe Display-Liste
    DUMP "AT"            # Ausgabe Linietypentabelle
    DUMP "TX"            # Ausgabe Texturen
    DUMP "SD"            # Ausgabe aller symbolischen Verzeichnisse

    # Beispiele:
    DUMP C22             # Ausgabe der geom. Struktur von Kreis C22

    JUMP - Programmverzweigung:
    JUMP Labelname
    ..
    :Labelname
    # Das Sprungziel. Achtung: muss auch betreffend
    # Gross / Kleinschreibung völlig ident sein.

    IF - Bedingte Verarbeitung:
    if Wert Bedingung Wert ; JUMP Labelname
     Es gibt folgende Bedingungen:
      EQ      gleich,
      NE      nicht gleich,
      LT      kleiner,
      GT      groesser,
      L_E     kleiner oder gleich,
      G_E     groesser oder gleich.

    # Beispiel Programmschleife
    V20=10
    :Next
    PRI "Var 20 =",V20
    V20=V20+10
    IF V20 LT 55 ; JUMP Next

    EXIT
      Beendet das Programm.

    CALL - Aufruf Befehlsdatei
    CALL "symDir/filename"
    # oder
    CALL "/absoluter-Filename"

    # Beispiel:
    CALL "Data/sample_prg_call_1.dat"
    PRI "V20=" V20
    C20=P(0 0 0) V20

    # File Data/sample_prg_call_1.dat:
    V20=12

    WRITE - in Datei schreiben:
    Mit Write kann in eine Datei ausgegeben werden;
     die Datei wird im Temorärverzeichnis von gcad angelegt,
     der Dateityp .write ist fix.
    Diese Dateien werden beim Laden des nächsten Modells automatisch gelöscht.
    Es werden alle Textzeilen von WRITE bis ENDWRITE
     in die Textdatei {filNam}.write ausgegeben.
    Die Datei kann mit dem Befehl CALL "{filNam}" geladen werden.

    # Beispiel Datei schreiben, lesen
    #JUMP L1
    PRI"WRITE-start"
    WRITE "TestPar1"
    V20=15
    V21=16
    ENDWRITE
    #
    :L1
    PRI "L1-start"
    CALL "TestPar1"
    PRI"V20="V20"; V21="V21
    #

    Programmierfunktionen für Applications

    - in Applications sind alle Standard-Programmierfunktionen verwendbar;
    - Applications sind Scriptprogramme (Files, direkt ausführbar) -
      - Dateityp ist ".gcap"
      siehe "Applications/Create"
    - Applications haben zusätzliche Programmfunktionen
    - Applications haben Eingabefenster
    - Applications Dateiverzeichnis

    Funktionen Menü Applications:

    Applications/Start
      Auswahl und Start des aktiven Programmes.
        Auswahl eines Programms:
          Verzeichnis:
          Dateityp:    .gcap
      Das zuletzt ausgewählte Programm kann mit Ctrl-P direkt gestartt werden.

      Das zuletzt gewählte Verzeichnis wird in Datei cfg/xa.rc gespeichert.

    Jedes Programm erhält automatisch ein Eingabefenster;
      jedes Eingabefenster erhält automatisch 3 Buttons:
      einen Update-, einen Cancel- und einen OK-Button.

      Update-Button:  (auch Rechte-Maustaste):
        das Programm wird abgearbeitet, aber nicht gespeichert.
      Cancel-Button:
        Programm abbrechen.
      OK-Button:  (auch Ctrl-Rechte-Maustaste):
        Programm abarbeiten, alle nicht-internen Objekte an das
        Hauptprogramm uebergeben.

    Applications/Edit
      Startet einen Texteditor fuer das aktive Programm.
      Weiter siehe "Allgemeine Programmstruktur"
      Das zuletzt ausgewählte Programm kann mit Ctrl-E direkt editiert werden.

    Applications/Create
      Ein neues Programm erzeugen.

      Verzeichnis/Dateiname der Programmfiles:
      {baseDir}/prg/{Programmname}.gcap

      Das Programm-Verzeichnis kann in Datei
      "{baseDir}/cfg/xa.rc"
      in Zeile 7 gesetzt / verändert werden.

    ____________________________________________________________________________
    Vorgangsweise neues Programm erzeugen / testen:
      Ein leeres Programm erzeugen (Create Application);
      Programmcode einfügen (zB Beispielcode); speichern (KEDit: Ctrl-S);
      Programm starten (mit Ctrl-P);  Cancel od OK.

    ____________________________________________________________________________
    Allgemeine Programmstruktur:

    # Block Declarationen
    INTERN ..
    # Siehe INTERN.
    DLG ..
    # Mit den DLG-Codes (Dialog) koennen Eingabefelder in das Eingabefenster
    # gesetzte werden.  Siehe Definition Eingabefenster.

    # Block DLG-Variablen initialisieren
    # Alle in Eingabefeldern ("DLG ..") verwendete Variablen muessen
    # hier deklariert werden.
    # Damit werden auch die Startwerte der Eingabefelder vorgegeben.
    ..

    # Block ProgramCode
    ..

    Directory-Applicationsprogramme:

    Standardverzeichnis ist das symbolische Verzeichnis "APPLI" -
      - siehe Symbolic filenames.

    Programmcodes:

    Standard-Programmierfunktionen
      #-Kommentar, PRI, JUMP-Label, IF, WRITE, CALL, EXIT

    Werden nur Application (.gcap) ausgewertet:
      ##-Kommentar, INTERN, NEW, evaluation-function, DEBUG, DLG.

    Kommentar
    Das Zeichen # als erstes Zeichen einer Zeile definiert eine Kommentarzeile.
    Zeilen mit # am Beginn existieren nur im Programm (.gcap);
    Zeilen mit ## am Beginn werden in das Hauptprogramm (.gcad) kopiert.

    INTERN {Bereich ..}
    Definition von Variablen, die nur fuer programminterne Berechnungen
     benoetigt werden und bei OK nicht in das Hauptmodell exportiert
     werden sollen.
     INTERN muss im ersten Programmteil (Declarations) stehen.

    Beispiel:
     INTERN P1-P20 P50 V1-V20 V33 L1-L3
     # Alle Punkte von P1 bis P20 sowie Punkt P50 (usw..)
     # werden nur intern benutzt; keine Ausgabe in das Hauptmodell.

    V{#}=NEW({objTyp},{startIndex})
      Liefert die nächste freie Objektnummer
      objTyp: V (Variable), P (Punkt), L (Linie), C (Kreis), D (Vektor),
              S (Kurve), A (Fläche)

      Beispiel:
      V1=NEW(P,20)
      # Liefert die erste freie Punktnummer ab Index 20 nach Variable-1.
      # Anwendung siehe Auswertungsfunktion (Spitze Klammern)

    Auswertungsfunktion (spitze Klammern)
    Ein zwischen spitzen Klammern befindlicher Ausdruck wird durch sein
    Ergebnis ersetzt. Es werden Variablen, Punkte und Vektoren evaluiert.
                  Ausgabe:
    <V#>    der Zahlenwert (Inhalt der Variablen)
    <P#>    P(xCoord yCoord zCoord)
    <D#>    D(xCoord yCoord zCoord)

    Beispiele:
     V1=10
     V2=20
     P<V1>=P(<V2> 0 0)
    ergibt:
     P10=P(20 0 0)

     P11=P(<X(P10)+1> 0 0)
    ergibt:
     P11=P(21 0 0)
      (Funktion X(P10) extrahiert die X-Koordinate aus Punkt P10).

     D10=DZ
     D11=D(0 0 <Z(D10)>)
    ergibt:
     D11=P(0 0 1)
      (Funktion Z(D10) extrahiert die Z-Koordinate aus Vektor D10).

    DEBUG ON¦OFF
      ON: Anzeige von Testausgaben;
      weiter zur nächsten Programmzeile mit der Esc-Taste.

    ____________________________________________________________________________

    Definition Eingabefenster:

    # Horizontale Trennlinie:
    DLG ---

    # Anzeige Zusatzinformationen:
    DLG TXT "{InfoText}"

    # Input von Zahlenwerten in numer. Variablen V:
    DLG V{#} "{InfoText}" {Feldbreite}
    # Infotext wird neben dem Eingabefenster angezeigt.

    # Input von Punkten in Punktvariablen P:
    DLG P{#} "{InfoText}" {Feldbreite}

    # Input von Vektoren in Vektorvariablen D:
    DLG D{#} "{InfoText}" {Feldbreite}

    # Auswahl Checkbox
    DLG CKB V{#} "{InfoText}"

    # Auswahl Radiobox
    DLG RDB V{#} "{InfoText}"
    # Radioboxen sind Checkboxen, die sich gegenseitig ausschliessen,
    # sie haben die gleiche Ausgabevariable.

    ----------------------------
    Beispiele:
    ----------------------------

    #-----------------------------
    # Beispiel Eingabe Wert
    DLG TXT Test1
    DLG V20 "TestVar"
    PRI "eingegebener Wert ist "V20

    #-----------------------------
    # Beispiel Eingabe Wert, Position, Checkbox, Radiobox
    # do not export:
    INTERN P1 P50 V1-V3
    # Text
    DLG TXT Test EingabeFenster

    # Eingabefelder für Variable, Punkt
    DLG V1 "Length - " 150
    DLG P1 "Position " 150
    DLG ---

    # Checkbox
    DLG CKB V2 "export"
    DLG ---

    # 3 Radioboxen
    DLG RDB V3 "Point"
    DLG RDB V3 "Line"
    DLG RDB V3 "Circ"

    # initialize all variables
    V1=60
    # set "export" not checked
    V2=0
    # preset to Circ.
    V3=3
    P1=P(0 0 0)

    PRI "V1 = "V1"; V2 = "V2"; V3 = "V3
    PRI "P1 = "P1
    #

    ____________________________________________________________________________
    Tastenzuordnung:
    Ctrl P    startet zuletzt ausgefuehrtes Programm;

    Ctrl E    editieren zuletzt ausgefuehrtes Programm;

    Esc: go into previous Eingabefeld;
         während Programmablauf: den Ablauf stoppen.
         im Debugmode: weiter mit nächster Programmzeile.

    Tab: nächstes Eingabefeld.

    Rechte-Maustaste: loest Update aus;

    Ctrl-Rechte-Maustaste: loest OK aus;

    ____________________________________________________________________________
    Beispielprogramme:

    #-----------------------------
    # create 10 points, without dialog:
    INTERN V1            # do not export V1
    V1=NEW(P,20)         # startindex
    V2=V1 + 10           # endIndex
    P<V1>=P(100 100 0)   # startpoint
    D20=D(100 0 0)       # offset
    :L1
    V1=V1 + 1
    P<V1>=P<V1 - 1> D20  # new point with offset D20
    IF V1 LT V2; JUMP L1
    #

    #-----------------------------
    # Example get value from user and export to model with new/unused ID.
    # do not export V1 - V19
    INTERN V1-19
    # setup dialog-window
    DLG TXT Test1
    DLG V1 "TestVar"
    # init the dialog-variable
    V1=10
    # get a new, uniq variable-ID
    V2=NEW(V,20)
    # export the value from the dialog-window with a new ID
    # add an object-name (use it for filtering)
    V<V2>=<V1>
    PRI "new var V" <V2> "=" <V1>
    #

    #-----------------------------
    # Example create new point with user-defined X-Value
    # do not export V1,V2 (internal use only)
    INTERN V1-2
    # get new poinIndex
    V1=NEW(P,20)
    DLG V2 "X-Coord - " 60
    # Init Variables
    V2=10
    P<V1>=P(<V2> 0 0)
    #

    #-----------------------------
    # Example create new point OR Circ
    INTERN V1-4 P1
    V3=NEW(P,20)
    V4=NEW(C,20)
    #
    DLG RDB V1 "Point"
    DLG RDB V1 "Circ"
    DLG P1 "select/indicate position" 150
    DLG V2 "radius" 100
    # preSet 1="Point", 2="Circ"
    V1=1
    P1=P(0 0 0)
    V2=10
    #
    if V1 EQ 2; JUMP L_Circ
    P<V3>=P(<X(P1)> <Y(P1)> <Z(P1)>)
    JUMP L_cont
    #
    :L_Circ
    C<V4>=P(<X(P1)> <Y(P1)> <Z(P1)>) <V2>
    :L_cont
    #

    #-----------------------------
    # Example create single chain of points;
    # the following line will be exported into model;
    ## create single chain of points
    # do not export the following variables with OK:
    INTERN P1 V1-10 D1
    # put textlines into the panel
    DLG TXT             Create linear point-pattern.
    DLG TXT Select or indicate Startpoint;
    DLG TXT Give offset (X-offset,y-offset,z-offset)
    DLG TXT Define nr of points;
    DLG TXT Update: Button or right mousebutton
    DLG TXT   in the mainWindow;
    DLG TXT OK: button or Crtl-Right mousebutton.
    # get Startpoint from user into P1;
    # inputfieldsize 150
    DLG P1 " Startpoint " 150
    # get pointoffset from user
    # Offset must be a Vektor (3 values !)
    DLG D1 " OffsetVec." 150
    # get nr of points from user
    DLG V1 " nr of points" 150
    #-------- init all dialog-variables----------
    P1=P(0 0 0)
    D1=D(10 0 0)
    V1=3
    #----------programCode ---------
    #DEBUG ON
    # get a new pointindex for the outputpoints
    # beginning with index 5 (preserve P1)
    V2=NEW(P,5)
    # init pointCounter
    V3=0
    # decode the startpoint
    V4=X(P1)
    V5=Y(P1)
    V6=Z(P1)
    # decode the offsetVector
    V7=X(D1)
    V8=Y(D1)
    V9=Z(D1)
    :Next
    # incr counter
    V3=V3+1
    # add offset
    V4=V4+V7
    V5=V5+V8
    V6=V6+V9
    # create point with next index v2
    P<V2>=P(<V4> <V5> <V6>)
    # increment pointindex
    V2=V2+1
    if V3 lt V1 ; jump Next
    #

    ____________________________________________________________________________
    Senden sie Fehlerberichte, Verbesserungsvorschläge
      an franz.reiter@cadcam.co.at