###

##

    Script programs / Application

    General programming-functions
    Programming-functions for Applications
    Programming-functions for Catalog-files

    General programming-functions

    - General-programming-functions can be used in all .gcad-Models;
    - can be created only in mode "MAN" (or be read from file)

    General programming-functions are:
    #-Comment, PRI, JUMP-Label, IF, WRITE, CALL, EXIT.

    # - Comment
    # as the first character of a line defines a commentline.

    ObjectName:
    ObjectName is comment added to a Definition-codeline;
    - create in MAN: add "# name1 [name2 ..]" at end of code; see Example;
    - create in CAD: add "name1 [name2 ..]" into inputfield ObjectName
    - can be used to filter objects. See ../../doc/html/Search_de.htm - "has infotext"
    -
    Example ObjectName:
    V20=4  # rad pin
    V21=10 # rad head
    V22=16 # len pin
    V23=6 # len head
    C20=P(0 0) VAL(V20)
    C21=P(0 0 -V23) VAL(V21)
    C22=P(0 0 V22) VAL(V20)
    A20=SRU C20 C22
    A21=SRU C21 C20
    P20=P(25,0)
    L20=P(0,0) P20
    -
    select checkbox "Search/Name"
    - key "len" into "has infotext:"; press button "search/update"
    - key "pin" into "has infotext:"; press button "search/update"

    PRI - Testoutput of text / variables:
    # output into message-window only for tests
    # output of the geometric structure of variables (V), points (P), vectors (D)
    #   output of other objecttypes with DUMP

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

    DUMP - Testoutput:
    # output into message-window only for tests
    # output of lists, the geometric structure of Cobjects, ..
    # see also "PRI"

    DUMP      # output geometric structure of database-object
    DUMP "GA"            # output Grafic_Attributes_list
    DUMP "DL"            # output display-list
    DUMP "AT"            # output linetypetable
    DUMP "TX"            # output textures
    DUMP "SD"            # output all symbolic directories

    # Beispiele:
    DUMP C22             # output geometric structure of circle C22

    JUMP - program-branching:
    JUMP Labelname
    ..
    :Labelname
    # where to go. Must be absolute identical - check case.

    IF - conditional processing:
    if value condition value ; JUMP Labelname
     possible conditions are:
      EQ      equal,
      NE      not equal,
      LT      less than,
      GT      greater than,
      L_E     less or equal,
      G_E     greater or equal.

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

    EXIT
      Exit program.

    CALL - execute commandfile
    CALL "symDir/filename"
    # or
    CALL "/absolute-filename"

    # Example:
    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 - write into file:
    The file will be created in the temporary directory;
     the filetype is ".write".
    Thisfiles will be deleted always when starting a new model.
    All lines between WRITE and ENDWRITE will be written into file {filNam}.write.
    This files can be loaded with CALL "{filNam}".

    # Example write file, read file.
    #JUMP L1
    PRI"WRITE-start"
    WRITE "TestPar1"
    V20=15
    V21=16
    ENDWRITE
    #
    :L1
    PRI "L1-start"
    CALL "TestPar1"
    PRI"V20="V20"; V21="V21
    #

    Programming-functions for Applications

    - in Applications all general programming-functions can be used;
    - Applications are scriptprograms (files) -
      - filetype is ".gcap"
      see "Applications/Create"
    - Applications have additional Programfunktions
    - Applications have input-forms
    - Applications files-directory

    Functions Menu Applications:

     Applications / Start
       Selection and start of a program.
         Directory:  {any_direcory}
         Filetyp:    .gcap
       The program selected last can be started directly with Ctrl-P.

       The directory of the program selected last is stored in file cfg/xa.rc.

    Each program will automatically get a window;
       each window automatically gets 3 buttons:
       an Update, a Cancel and an OK button.

        Update button:  (also rightMouseButton)
         the program is processed and displayed, but not saved.
        Cancel button:
         Cancel the program.
        OK button:  (also Ctrl-rightMouseButton)
         Program is processed, all non-internal objects are transferred
         to the main program.

     Applications / Edit
       Starts a text editor for the active program.
       For further details, see "General program structure" below
       The program selected last can be edited directly with Ctrl-E.

     Applications / Create
       Creates a new program.

       Directory/file name of the executable files:
       {baseDir}/prg/{Programname}.gcap

       The program directory can be set/modified only in line 7 of file:
         "{baseDir}/cfg/xa.rc"

     How to create / test a new program:
       Create an empty program (Create);
       Insert code (eg from examples); save (KEdit: Ctrl-S);
       Start program (with Ctrl-P); Cancel or OK.

    General programme structure:

    # block Declarations
    INTERN ..
    # See INTERN.
    DLG ..
    # The DLG codes (dialogue) can place input fields in the form.
    # See definition Input form.

    # block initialize DLG-variables
    # All variables used in input fields ( "DLG ..") must
    # be declared here.
    # This will also define the primary values of the fields specified.
    ..

    # Block Program Code
    ..

    Directory-applicationprograms:

    Default-directory is the symbolic directory "APPLI" -
      - see Symbolic filenames.

    Program Codes:

    Will be evaluated in all modelfiles (.gcad files):
    #-comment, PRI, JUMP-Label, IF, WRITE, CALL, EXIT

    Will be evaluated only in applications (.gcap files):
    ##-comment, INTERN, NEW, evaluation-function, DLG, DEBUG.

    Will be evaluated only in catalog-modelfiles:
    CALL CTLG.

    Comment
    The # character as the first character of a line defines a comment line.
    Lines with one # at the beginning exist only in the program (.gcap);
    Lines with two ## at the beginning are copied into the main program (.gcad).

    INTERN {range ..}
      Definition of variables that are needed only for calculations inside
      the program; these are not exported into the main model.
      INTERN must be within the first part of the programme (Declarations).

    Example:
      INTERN P1-P20 P50 V1-V20 V33 L1-L3
      # All points from P1 to P20 and point P50 and ...
      # are only used internally, no export into the main model.

    V{#}=NEW({objTyp},{startIndex})
       Returns the next free object number
       objTyp: V (variable), P (point), L (line), C (circle), D (vector),
               S (curve), A (area)

       Example:
       V1=NEW(P,20)
       # Returns the first free point index number > 20 into variable 1.
       # Application: see the evaluation function (top brackets)

    Evaluation function (top brackets)
     An expression between brackets is replaced by its result.
     Variables, points and vectors can be used.
                  Output:
    <V#>    the num. value (the content of the variable)
    <P#>    P(xCoord yCoord zCoord)
    <D#>    D(xCoord yCoord zCoord)

    Examples:
     V1=10
     V2=20
     P<V1>=P(<V2> 0 0)
    gives:
     P10=P(20 0 0)

     P11=P(<X(P10)+1> 0 0)
    gives:
     P11=P(21 0 0)
       (Function X(P10) extracts the X-coordinate from point P10).

     D10=DZ
     D11=D(0 0 <Z(D10)>)
    gives:
     D11=P(0 0 1)
       (Function Z(D10) extracts the Z coordinate from vector D10).

    DEBUG ON|OFF
      ON: Display of test output;
      continue to the next program line with the Esc key.

    Definition Input form:

    # Horizontal ruler:
    DLG ---

    # Display additional information:
    DLG TXT "{InfoText}"

    # Input from numerical values into V variables:
    DLG V{#} "{InfoText}" {fieldWidth}
    # Info text is next to the input field.

    # Input of points in point variables P:
    DLG P{#} "{InfoText}" {fieldWidth}

    # Input of vectors in vector variables D:
    DLG D{#} "{InfoText}" {fieldWidth}

    # Select checkbox
    DLG CKB V{#} "{InfoText}"

    # Select radiobox
    DLG RDB V{#} "{InfoText}"
    # radioboxes are checkboxes, which are mutually exclusive,
    # they have same output variable.

    ----------------------------
    Examples:
    ----------------------------

    #-----------------------------
    # Example input value
    DLG TXT Test1
    DLG V20 "TestVar"
    PRI "value is "V20

    #-----------------------------
    # Example input value, Position, Checkbox, Radiobox
    # do not export:
    INTERN P1 P50 V1-V3
    # Text
    DLG TXT Test Form

    # input value position
    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
    #

    Key assignment:

    Ctrl P     starts last executed program;

    Ctrl E     edit last executed program;

    Esc: go into previous input field;
         during program execution: stop the process.
         in debug mode: continue with next program line.

    Tab: next input field.

    Right/outer mouse button: starts Update;

    Ctrl-right/outer mouse button: starts OK;

    Example programs:

    #-----------------------------
    # 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
    #

    Send bug reports and suggestions for improvement
      to franz.reiter@cadcam.co.at