@database ARexx-Befehle.guide
@remark $VER: ARexx-Befehle.guide 1.0.3
SETENV HYPERPENS 21213001

@Index TheIndex
@node Main "MicroPaint - ARexx-Befehle Guide 1.0.3"

@{" Einführung " link intro}

@{" Ein Beispiel-Skript " link sample}

@{" ARexx-Befehle " link cmd}

@{" Mitgelieferte ARexx-Skripte " link scripts}
@endnode

@node intro "Introduction"
@{b}Was ist ARexx?@{ub}

ARexx ist eine Sprache, mit der man Anwendungsprogramme kontrollieren kann.
Zu diesem Zweck werden Befehle an den ARexx-Port der Anwendung geschickt,
den diese zuvor einrichten muss.


@{b}Die ARexx-Fähigkeiten von MicroPaint@{ub}

Der zur Verfügung gestellte ARexx-Port heißt 'MicroPaint'. Die Standard-
Extension für ARexx-Skripte ist ".mprx".

MicroPaint kommt bereits mit einigen @{" Beispiel-Skripten " link scripts}.

Einige Befehle liefern über die ARexx-Variable result ein Ergebnis, falls
dies angefordert wurde. Befehle ohne Ergebnis liefern lediglich einen
Leerstring; andernfalls wird die gewünschte Information oder "ERROR" bei
einem Fehler zurückgegeben.
@endnode

@node sample "Ein Beispiel-Skript"
Das folgende Skript macht das aktuelle Bild 10 % heller:
@{i}                                        Zeilennummer (nicht eingeben)
/* Calibration */                       1
address 'MicroPaint'                    2
'CALIBRATE' 'RGB' '1.1' 0 255 0         3
@{ui}

Zeile eins ist nur ein Kommentar - dies wird vom ARexx-Interpreter "RexxMast"
so erwartet.

Zeile zwei sagt ARexx, dass die nächsten Befehle an den Port 'MicroPaint'
gesendet werden sollen.

Zeile drei führt die Kalibrierung aus. Hierfür sind mehrere Argumente
erforderlich, die ARexx an MicroPaint übergibt: Maske, Faktor, Bereich der
betroffenen Farbregister sowie ein optionaler Wert für Register, die den
Wert 0 enthalten.

Hinweise:

· Alle Argumente müssen durch Leerzeichen getrennt werden.

· Zeichenketten werden am besten in einfache Anführungszeichen gesetzt. Dies
  ist auf jeden Fall erforderlich, falls diese Leerzeichen enthalten.
@endnode

@node cmd "ARexx Commands"
Hinweise:

· Alle Parameter müssen in der angegebenen Reihenfolge erscheinen.

· Optionale Paramter werden in der Beschreibung in eckige Klammern ([ .. ])
  gesetzt. Diese dürfen jedoch nicht mit eingegeben werden.

· Wenn Argumente Leerzeichen enthalten, müssen sie in einfache und doppelte
  Anführungszeichen eingefasst werden.
  
  Beispiel: 'TEXT' x y '"Dies ist ein Beispiel."'
  
· Ergebnisse werden an die ARexx-Variable result übergeben, falls das Skript
  vor der Zeile "address 'MicroPaint'" die Zeile "options results" enthält.
  
  Bei einem Fehler wird die Zeichenkette "ERROR" geliefert.

  
@{b}ABOUT@{ub}

Dieser Befehl hat keine Argumente.

ABOUT zeigt den Info-Requester an.


@{b}CALIBRATE@{ub}

Dieser Befehl hat folgende Argumente:

  Maske             Dies ist eine beliebige Kombination der Buchstaben
                    R, G und B, die für die zu verändernden Farbkomponenten
                    rot, grün und blau stehen.
  Faktor            Mit diesem Faktor werden die aktuellen Inhalte der Farb-
                    register multipliziert (bzw. durch dessen Absolutwert
                    dividiert, falls er negativ ist).
  Register1         Diese Werte geben den Bereich der zu verändernden Farb-
  Register2         register an.
  [Nullwert]        Diesen Wert erhalten Farbregister, die den Wert 0 ent-
                    halten. Falls der Wert nicht angegeben ist, wird null
                    eingesetzt.

CALIBRATE entspricht dem Menübefehl "Tools/Kalibrieren".


@{b}CLS@{ub}

Dieser Befehl hat folgendes Argument:

  [Farbe]           Mit dieser Farbe (im Bereich 0..2^Bitplanes-1) wird der
                    Bildschirm gelöscht. Wird die Farbe nicht angegeben, wird
                    die Hintergrundfarbe benutzt.

CLS löscht den Bildschirm.


@{b}COLOUR@{ub}

Dieser Befehl hat folgendes Argument:

  Farbe             Die zu verwendende Farbe.
  
CLS legt das zu benutzende Farbregister fest.


@{b}FONT@{ub}

Dieser Befehl hat folgende Argumente:

  Name              Der zu verwendende Zeichensatz, z. B. 'topaz.font'.
  Größe             Die zu verwendende Zeichensatzgröße.
  [Stil]            Der Stil, z. B. 0 für normale Schrift.
  [Jam]             Der Zeichenmodus (drawmode).
  [Pen1]            Die Registernummer der Vordergrundfarbe.
  [Pen2]            Die Registernummer der Hintrgrundfarbe.
  
  Hinweis: Die Parameter müssen in der angegebenen Reihenfolge benutzt
           werden, z. B. kann man Jam nur angeben, wenn auch Stil schon
           definiert wurde. Wird ein optionaler Parameter nicht angegeben,
           werden die aktuellen Einstellungen benutzt.
           
FONT legt den Zeichensatz fest.


@{b}GETxxx@{ub}

Diese Befehle haben keine Argumente und geben alle ein Ergebnis zurück.

  Funktion     Ergebnis
  ----------------------------------------
  GETCOLOUR    aktuelle Farbe
  GETX         Cursorposition
  GETY         Cursorposition
  GETMAXX      Bildschirmbreite
  GETMAXY      Bildschirmhöhe
  GETDEPTH     Bildschirmtiefe
  GETID        Bildschirmmodus
  GETMODE      Zeichenmodus
  GETFILENAME  aktueller Dateiname oder ""

GETxxx gibt eine Information zurück.


@{b}IDNAME@{ub}

Dieser Befehl hat folgendes Argument:

  ID                Dieser Wert definiert die View Mode ID, deren Namen Sie
                    ermitteln möchten.
                    
Beispiel:           IDNAME 0 -> LoRes

IDNAME ermittelt den Namen zu einer Modus ID.


@{b}INPUT@{ub}

Dieser Befehl hat folgende Argumente:

  [Titel]           Dieser Wert definiert den Fenstertitel und darf maximal
                    20 Zeichen lang sein.
  [Frage 1]         Diese beiden Argumente definieren die Fragen, die in
  [Frage 2]         dem Fenster gestellt werden sollen und dürfen jeweils
                    nicht länger als 25 Zeichen sein.
  [Vorgabewert]     Dieser Wert wird in das Eingabefeld geschrieben.
  
INPUT übergibt den eingegebenen String.


@{b}INTEGERFORMAT@{ub}

Dieser Befehl hat folgendes Argument:

  Nummer            Dieser Wert ist die ganze Zahl, die Sie formatieren
                    möchten. Zur Formatierung wird - falls verfügbar - die
                    "locale.library" benutzt.
                    
Beispiel:           INTEGERFORMAT 1234 -> 1.234

INTEGERFORMAT formatiert eine natürliche Zahl.


@{b}MODENAME@{ub}

Dieser Befehl hat folgendes Argument:

  Modus             Dieser Wert definiert die Nummer des Modus, dessen Namen
                    Sie ermitteln möchten.
                    
MODENAME ermittelt den Namen eines Zeichenmodus.


@{b}OPEN@{ub}

Dieser Befehl hat folgendes Argument:

  Name               Dies ist der Name der zu öffnenden Datei. (Geben Sie "?"
                     an, wenn ein Dateirequester geöffnet werden soll.)
                     
OPEN öffnet eine Datei und liefert als Ergebnis deren Namen.


@{b}PLOT@{ub}

Dieser Befehl hat folgende Argumente:

  X                 Dieser Wert definiert die horizontale Position.
  Y                 Dieser Wert definiert die vertikale Position.
  [Farbe]           Dieser optionale Parameter bestimmt die zu verwendende
                    Farbe. Wird der Wert nicht angegeben, benutzt MicroPaint
                    die aktuelle Farbe.

PLOT zeichnet genau einen Punkt.


@{b}PRINT@{ub}

Dieser Befehl hat keine Argumente.

PRINT druckt das aktuelle Bild aus.


@{b}QUIT@{ub}

Dieser Befehl hat keine Argumente.

QUIT beendet MicroPaint ohne weitere Abfrage.


@{b}REQUEST@{ub}

Dieser Befehl hat folgende Argumente:

  [Titel]           Dieser Wert definiert den Titel des Requesters. Die
                    Übergabe eines leeren Strings ("") führt zu der Ver-
                    wendung eines Standardtitels.
  [Text]            Diese Zeichenkette definiert den darzustellenden Text.
                    Fügen Sie einen senkrechten Strich (|) ein, um eine
                    neue Zeile zu beginnen.
  [Knöpfe]          Dieser Wert definiert die darzustellenden Knöpfe.
                    Mehrere Knöpfe sind durch seknrechte Striche zu trennen.
                        
Beispiel:           'REQUEST' "Demo" '"Wählen Sie|eine Zahl:"' "1|2|3|keine"

REQUEST stellt einen Requester dar und übergibt als Ergebnis die Nummer des
        gewählten Knopfes bzw. 0, falls der rechte angeklickt wurde.
        

@{b}TEXT@{ub}

Dieser Befehl hat folgende Argumente:

  X                 Dieser Wert definiert die horizontale Position.
  Y                 Dieser Wert definiert die vertikale Position.
  Text              Dies ist der zu druckende Text.
  [Abstand]         Dieser optionale Parameter definiert den Zeichenabstand.
                    Wird er nicht angegeben, gelten die aktuellen Einstel-
                    lungen.
                    
TEXT gibt einen Text auf dem Bildschirm aus.
@endnode

@node scripts "Mitgelieferte ARexx-Skripte"
@{b}Brighter.mprx@{ub}

Dieses Skript macht das Bild 10 % heller.


@{b}ClearScreen.mprx@{ub}

Dieses Skript löscht den Bildschirm.

Hinweis: Dies ist nur eine einfache Demonstration des CLS-Befehls.


@{b}Darker.mprx@{ub}

Dieses Skript macht das Bild 10 % heller.


@{b}LessXXX.mprx@{ub}

Dieses Skript erhöht den Anteil der betroffenen Farbkomponente um 10 %.


@{b}MoreXXX.mprx@{ub}

Dieses Skript verringert den Anteil der betroffenen Farbkomponente um 10 %.


@{b}Quit.mprx@{ub}

Dieses Skript beendet MicroPaint.

Hinweis: Dies ist nur eine einfache Demonstration des QUIT-Befehls.


@{b}Test.mprx@{ub}

Dieses Skript testet alle MicroPaint-Befehle. Es sollte im CLI gestartet
werden, da es zum Teil Ergebnisse ausgibt.


@{b}TextDemo.mprx@{ub}

Dieses Skript schreibt eine Text in Times-Schrift auf den Bildschirm.

Hinweis: Dies ist nur eine einfache Demonstration der Befehl FONT und TEXT.
@endnode

@node TheIndex Index
@remark Index created with 'mkagidx' (C) Captain CrossBones
A

@{"ARexx-Befehle" link cmd}

B

@{"Beispiel-Skripten" link scripts}

E

@{"Ein Beispiel-Skript" link sample}
@{"Einführung" link intro}

M

@{"Mitgelieferte ARexx-Skripte" link scripts}
@endnode