moparisthebest
/
Simba
mirror of https://github.com/moparisthebest/Simba
1
0
Fork 0
Code Issues Releases Wiki Activity
Simba/Doc/mufasa_ps_handbook.tex

681 lines
18 KiB
TeX
Raw Blame History

\documentclass[a4paper]{report}
\usepackage{amsmath}
\usepackage{color}
\begin{document}
\title{Mufasa PascalScript Handbook}
\author{Merlijn Wajer \and Raymond van Veneti\"{e}
\and Benjamin J. Land}
\definecolor{typeGreen}{rgb}{0.0, 0.6, 0.0}
\definecolor{typeRed}{rgb}{0.6, 0.0, 0.0}
% Few defines to make methods easier.
% Most func/proc definitions still don't use this...
\def\pproc{\textbf{procedure}}
\def\pfunc{\textbf{function}}
\newcommand{\pvtype}[1]{{\color{typeGreen}{#1}};}
\newcommand{\pvtypel}[1]{{\color{typeGreen}{#1}}}
\newcommand{\pvname}[1]{{\color{typeRed}{#1}}:}
\newcommand{\mname}[1]{{\color{blue}{#1}}}
\newcommand{\pvtotal}[2]{{\pvname{#1}} {\pvtype{#2}}} %this might be better?
\maketitle
\tableofcontents
\chapter{Foreword}
This document provides a simple but helpful explanation on every function that
the Mufasa macro library exports to it's Interpreter, PS\footnote{Pascal
Script}. For a real in depth explanation, the Mufasa Handbook would be a better
place to look.
\chapter{Exceptions}
\section{Motivation}
Mufasa takes debugging to a new level by using exceptions for error handling,
this allows you to even catch possible errors in your script, thus allowing
the script to continue it's exection. We strongly believe Exceptions are the
way to go. They were implemented for a reason.
\section{When do we throw Exceptions}
There are a lot of occasions where Mufasa may throw exceptions.
Consider the following program:
\begin{verbatim}
program new;
var
bmp:integer;
x, y:integer;
begin
bmp:=bitmapfromstring(200, 200, '');
x := -1;
y := -1;
fastsetpixel(bmp, x, y, clwhite);
end.
\end{verbatim}
Now, when we execute this with MML, we get this:
\begin{verbatim}
Error: Exception: You are accessing an invalid point, (-1,-1) at bitmap[0] at line 8
\end{verbatim}
Further expanding the example:
\begin{verbatim}
program new;
var
bmp:integer;
x, y:integer;
begin
bmp:=bitmapfromstring(200, 200, '');
x := -1;
y := -1;
try
fastsetpixel(bmp, x, y, clwhite);
except
writeln('We failed to do a setpixel with x = ' + inttostr(x) +
', y = ' + inttostr(y));
end;
end.
\end{verbatim}
Results in:
\begin{verbatim}
Compiled succesfully in 8 ms.
We failed to do a setpixel with x = .-1, y = -1
Succesfully executed
\end{verbatim}
\subsection{Going beyond script debugging}
Exceptions are even in the very core of Mufasa. This greatly improves
debugging in general, as we will also be able to easily spot errors in Mufasa.
When they occured, what the values of the variables were, et cetera.
Let's look at a function known as ReturnData(), which returns the client data.
It for example checks if the points that are passed are consistent.
If they are not, an Exception is thrown. If Mufasa does not catch that
particular Exception\footnote{Which it doesn't, as a feature.}, then it will
be thrown in your script. This will indicate that somehow ReturnData got
invalid coordinates. Usually this Exception is not throw, as other functions
also check their input for sanity, and then it is possible to throw a more
detailed exception.
\subsection{How to Handle Exceptions}
An exception is handled with a \textbf{try} ... \textbf{except}
... \textbf{finally} statement.
See the example in the previous section for more details.
\chapter{Input}
\section{Mouse}
\subsection{Types}
A few variables are exported for working with Mufasa Mouse Functions.
TClickType, which defines the click type.
\begin{itemize}
\item \textbf{mouse\_Right} = 0
\item \textbf{mouse\_Left} = 1
\item \textbf{mouse\_Middle} = 2
\end{itemize}
TMousePress, which defines if the mouse button is to be down or up.
\begin{itemize}
\item \textbf{mouse\_Up}
\item \textbf{mouse\_Down}
\end{itemize}
% TClickType = (mouse_Left, mouse_Right, mouse_Middle);
% TMousePress = (mouse_Down, mouse_Up);
\subsection{MoveMouse}
\pproc \mname{MoveMouse}(\textbf{in } \pvname{x, y} \pvtypel{Integer});
MoveMouse moves the mouse pointer to the specified x and y coordinates.
\subsection{GetMousePos}
\pproc \mname{GetMousePos}(\textbf{out } \pvname{x, y} \pvtypel{Integer});
GetMousePos returns the current position of the mouse in \textbf{x} and
\textbf{y}.
\subsection{HoldMouse}
\pproc \mname{HoldMouse}(\pvname{x, y} \pvtype{Integer} \pvname{clickType}
\pvtypel{TClickType})
HoldMouse holds the given mouse button (clickType) down at the specified \textbf{x}, \textbf{y}
coordinate. If the mouse if not at the given \textbf{x}, \textbf{y} yet, the mouse position
will be set to \textbf{x}, \textbf{y}.
\subsection{ReleaseMouse}
\pproc \mname{ReleaseMouse}(\pvname{x, y} \pvtype{Integer} \pvname{clickType} \pvtypel{TClickType});
ReleaseMouse releases the given mouse button (clickType) at the specified \textbf{x}, \textbf{y}
coordinate. If the mouse if not at the given \textbf{x}, \textbf{y} yet, the mouse position
will be set to \textbf{x}, \textbf{y}.
\subsection{ClickMouse}
\pproc \mname{ClickMouse}(\pvname{x, y} \pvtype{Integer} \pvname{clickType}
\pvtypel{TClickType});
ClickMouse performs a click with the given mouse button (clickType) at the
specified x, y coordinate.
\section{Keyboard}
The Keyboard functions in Mufasa are listed here.
Most of them are quite basic and can use some improvement.
\subsection{Types}
Most of the low level Keyboard functions use Virtual Keys.
\subsection{Virtual Keys}
Virtual Keys originate from MS Windows, and we've added support for them.
Virtual Keys also work on non-Windows operating systems.
\begin{itemize}
\item UNKNOWN: 0
\item LBUTTON: 1
\item RBUTTON: 2
\item CANCEL: 3
\item MBUTTON: 4
\item XBUTTON1: 5
\item XBUTTON2: 6
\item BACK: 8
\item TAB: 9
\item CLEAR: 12
\item RETURN: 13
\item SHIFT: 16
\item CONTROL: 17
\item MENU: 18
\item PAUSE: 19
\item CAPITAL: 20
\item KANA: 21
\item HANGUL: 21
\item JUNJA: 23
\item FINAL: 24
\item HANJA: 25
\item KANJI: 25
\item ESCAPE: 27
\item CONVERT: 28
\item NONCONVERT: 29
\item ACCEPT: 30
\item MODECHANGE: 31
\item SPACE: 32
\item PRIOR: 33
\item NEXT: 34
\item END: 35
\item HOME: 36
\item LEFT: 37
\item UP: 38
\item RIGHT: 39
\item DOWN: 40
\item SELECT: 41
\item PRINT: 42
\item EXECUTE: 43
\item SNAPSHOT: 44
\item INSERT: 45
\item DELETE: 46
\item HELP: 47
\item 0: \$30
\item 1: \$31
\item 2: \$32
\item 3: \$33
\item 4: \$34
\item 5: \$35
\item 6: \$36
\item 7: \$37
\item 8: \$38
\item 9: \$39
\item A: \$41
\item B: \$42
\item C: \$43
\item D: \$44
\item E: \$45
\item F: \$46
\item G: \$47
\item H: \$48
\item I: \$49
\item J: \$4A
\item K: \$4B
\item L: \$4C
\item M: \$4D
\item N: \$4E
\item O: \$4F
\item P: \$50
\item Q: \$51
\item R: \$52
\item S: \$53
\item T: \$54
\item U: \$55
\item V: \$56
\item W: \$57
\item X: \$58
\item Y: \$59
\item Z: \$5A
\item LWIN: \$5B
\item RWIN: \$5C
\item APPS: \$5D
\item SLEEP: \$5F
\item NUMPAD0: 96
\item NUMPAD1: 97
\item NUMPAD2: 98
\item NUMPAD3: 99
\item NUMPAD4: 100
\item NUMPAD5: 101
\item NUMPAD6: 102
\item NUMPAD7: 103
\item NUMPAD8: 104
\item NUMPAD9: 105
\item MULTIPLY: 106
\item ADD: 107
\item SEPARATOR: 108
\item SUBTRACT: 109
\item DECIMAL: 110
\item DIVIDE: 111
\item F1: 112
\item F2: 113
\item F3: 114
\item F4: 115
\item F5: 116
\item F6: 117
\item F7: 118
\item F8: 119
\item F9: 120
\item F10: 121
\item F11: 122
\item F12: 123
\item F13: 124
\item F14: 125
\item F15: 126
\item F16: 127
\item F17: 128
\item F18: 129
\item F19: 130
\item F20: 131
\item F21: 132
\item F22: 133
\item F23: 134
\item F24: 135
\item NUMLOCK: \$90
\item SCROLL: \$91
\item LSHIFT: \$A0
\item RSHIFT: \$A1
\item LCONTROL: \$A2
\item RCONTROL: \$A3
\item LMENU: \$A4
\item RMENU: \$A5
\item BROWSER\_BACK: \$A6
\item BROWSER\_FORWARD: \$A7
\item BROWSER\_REFRESH: \$A8
\item BROWSER\_STOP: \$A9
\item BROWSER\_SEARCH: \$AA
\item BROWSER\_FAVORITES: \$AB
\item BROWSER\_HOME: \$AC
\item VOLUME\_MUTE: \$AD
\item VOLUME\_DOWN: \$AE
\item VOLUME\_UP: \$AF
\item MEDIA\_NEXT\_TRACK: \$B0
\item MEDIA\_PREV\_TRACK: \$B1
\item MEDIA\_STOP: \$B2
\item MEDIA\_PLAY\_PAUSE: \$B3
\item LAUNCH\_MAIL: \$B4
\item LAUNCH\_MEDIA\_SELECT: \$B5
\item LAUNCH\_APP1: \$B6
\item LAUNCH\_APP2: \$B7
\item OEM\_1: \$BA
\item OEM\_PLUS: \$BB
\item OEM\_COMMA: \$BC
\item OEM\_MINUS: \$BD
\item OEM\_PERIOD: \$BE
\item OEM\_2: \$BF
\item OEM\_3: \$C0
\item OEM\_4: \$DB
\item OEM\_5: \$DC
\item OEM\_6: \$DD
\item OEM\_7: \$DE
\item OEM\_8: \$DF
\item OEM\_102: \$E2
\item PROCESSKEY: \$E7
\item ATTN: \$F6
\item CRSEL: \$F7
\item EXSEL: \$F8
\item EREOF: \$F9
\item PLAY: \$FA
\item ZOOM: \$FB
\item NONAME: \$FC
\item PA1: \$FD
\item OEM\_CLEAR: \$FE
\item HIGHESTVALUE: \$FE
\item UNDEFINED: \$FF
\end{itemize}
\subsection{KeyDown}
\pproc \mname{KeyDown}(\pvname{key} \pvtypel{Word});
KeyDown sends a request to the Operating System to ``fake'' an event that
causes the Key to be ``down''.
\textbf{key} can be any Virtual Key\footnote{See the section on Virtual Keys}.
\subsubsection{Common pitfalls}
Don't forget that certain keys may require that shift, or another key,
is down as well.
\subsection{KeyUp}
\pproc \mname{KeyUp}(\pvname{key} \pvtypel{Word});
KeyUp sends a request to the Operating System to ``fake'' an event that
causes the Key to be ``up''.
\textbf{key} can be any Virtual Key.
\subsection{PressKey}
\pproc \mname{PressKey}(\pvname{key} \pvtypel{Word});
PressKey combines KeyDown and KeyUp, to fake a key press.
\subsection{SendKeys}
\pproc \mname{SendKeys}(\pvname{s} \pvtypel{String});
SendKeys takes a string \textbf{s}, and attempts to send it's complete contents to
the client. It currently only accepts characters ranging from ``A..z''.
\subsection{IsKeyDown}
\pfunc \mname{PressKey}(\pvname{key} \pvtypel{Word}): \pvtype{Boolean}
IsKeyDown returns true if the given VK key is ``down''.
\subsection{Notes}
There is no IsKeyUp, because this can easily be generated by inverting the
result of IsKeyDown:
\begin{verbatim}
not IsKeyDown (x)
\end{verbatim}
\chapter{Finding Routines}
\section{Colours}
\subsection{FindColor}
\pfunc \mname{FindColor} (\textbf{out} \pvname{x, y} \pvtype{Integer} \pvname{col, x1, y1, x2, y2}
\pvtypel{Integer}): \pvtype{Boolean}
FindColor returns true if the exact color given (col) is found in the box defined by x1, y1, x2, y2.
The point is returned in x and y. It searches from the top left to the bottom right and will stop
after matching a point.
\subsection{FindColorTolerance}
\pfunc \mname{FindColorTolerance}(\textbf{out} \pvname{x, y: } \pvtype{Integer}
\pvname{col, x1, y1, x2, y2, tol: }\pvtypel{Integer}): \pvtype{Boolean}
FindColorTolerance returns true if a colour within the given tolerance range (tol) of the given color (col)
is found in the box defined by x1, y1, x2, y2. Only the first point is returned in x and y.
Whether or not a color is within the tolerance range is determined by the CTS mode.
It searches from the top left to the bottom right and will stop after matching a point.
\subsection{FindColorsTolerance}
\pfunc \mname{FindColorsTolerance}( \textbf{out }\pvname{pts} \pvtype{TPointArray} \pvname
{col, x1, y1, x2, y2, tol} \pvtypel{Integer}): \pvtype{Boolean}
FindColorsTolerance returns true if at least one point was found. A point is found if it is within the
given tolerance range (tol) of the given color (col) and inside the box defined by x1, y1, x2, y2.
Whether or not a color is within the tolerance range is determined by the CTS mode.
It searches from the top left to the bottom right and will find all matching points in the area.
\section{Bitmaps}
% Dit doe je zelf maar
\section{DTMs}
Deformable Template Models are a special approach to finding
objects. One can specify several points, colours and tolerances
for these points.
\subsection{Types}
Mufasa's DTM type:
\begin{verbatim}
pDTM = packed record
l: Integer; // length
p: TPointArray; // points
c, t, asz, ash: TIntegerArray; // colours, tolerance, areasize/shape
bp: Array Of Boolean; // Bad Point ( = Not Point )
n: String; // Name
end;
\end{verbatim}
Deprecated DTM type:
\begin{verbatim}
TDTMPointDef = record
x, y, Color, Tolerance, AreaSize, AreaShape: integer;
end;
TDTMPointDefArray = Array Of TDTMPointDef;
TDTM = record
MainPoint: TDTMPointDef;
SubPoints: TDTMPointDefArray;
end;
\end{verbatim}
\subsection{FindDTM}
\pfunc \mname{FindDTM}(\pvname{DTM}\pvtype{Integer} \textbf{out}
\pvname{x, y} \pvtype{Integer} \pvname{x1, y1, x2, y2} \pvtypel{Integer}):
\pvtype{Boolean}
FindDTM is the most basic DTM finding function. It takes a box to search in,
defined by x1, y1, x2, y2; and if the DTM is found, it will set \textbf{x} and
\textbf{y} to the coordinate the DTM was found at and it will also return true.
Else, it returns false. Once a DTM is found, it will stop searching. In other words; it always returns
the first found DTM.
\subsection{FindDTMs}
\pfunc \mname{FindDTMs}(\pvname{DTM}\pvtype{Integer} \textbf{out} \pvname{Points}
\pvtype{TPointArray} \pvname{x1, y1, x2, y2} \pvtypel{Integer}):
\pvtype{Boolean}
FindDTMs is like FindDTM, but it returns an array of \textbf{x} and \textbf{y}, as the
\textbf{TPointArray} type.
\subsection{FindDTMRotatedSE}
\pfunc \mname{FindDTMRotatedSE}(\pvname{DTM}\pvtype{Integer} \textbf{out }
\pvname{x, y} \pvtype{Integer} \pvname{x1, y1, x2, y2} \pvtype{Integer}
\pvname{sAngle, eAngle, aStep} \pvtype{Extended} \textbf{out}
\pvname{aFound} \pvtypel{Extended}): \pvtype{Boolean}
FindDTMRotatedSE is behaves like FindDTM. Only, it will rotate the DTM between
sAngle and eAngle by aStep each time. It will also return the angle which the
DTM was found at. Start rotating at StartAngle.
\subsection{FindDTMRotatedAlternating}
\pfunc \mname{FindDTMRotatedAlternating}(\pvname{DTM}\pvtype{Integer}
\textbf{out }
\pvname{x, y} \pvtype{Integer} \pvname{x1, y1, x2, y2} \pvtype{Integer}
\pvname{sAngle, eAngle, aStep} \pvtype{Extended} \textbf{out}
\pvname{aFound} \pvtypel{Extended}): \pvtype{Boolean}
FindDTMRotated is behaves like FindDTM. Only, it will rotate the DTM between
sAngle and eAngle by aStep each time. It will also return the angle which the
DTM was found at. Starts at 0 degrees and alternatives between - and + aStep to search for the DTM.
\subsection{FindDTMsRotatedSE}
\pfunc \mname{FindDTMsRotatedSE}(\pvname{DTM}\pvtype{Integer} \textbf{var}
\pvname{Points} \pvtype{TPointArray} \pvname{x1, y1, x2, y2} \pvtype{Integer}
\pvname{sAngle, eAngle, aStep} \pvtype{Extended} \textbf{out}
\pvname{aFound} \pvtypel{T2DExtendedArray}): \pvtype{Boolean}
FindDTMsRotatedSE behaves like FindRotatedDTMSE, but finds all DTM occurances.
Since one point can be found on several angles, aFound is a 2d array.
\subsection{FindDTMsRotatedAlternating}
\pfunc \mname{FindDTMsRotatedAlternating}(\pvname{DTM}\pvtype{Integer} \textbf{var}
\pvname{Points} \pvtype{TPointArray} \pvname{x1, y1, x2, y2} \pvtype{Integer}
\pvname{sAngle, eAngle, aStep} \pvtype{Extended} \textbf{out}
\pvname{aFound} \pvtypel{T2DExtendedArray}): \pvtype{Boolean}
FindDTMsRotatedAlternating behaves like FindRotatedDTMAlternating,
but finds all DTM occurances.
Since one point can be found on several angles, aFound is a 2d array.
\subsection{DTMFromString}
\subsection{DTMToString}
\subsection{AddDTM}
\subsection{FreeDTM}
\pproc ps\_FreeDTM(\pvname{DTM}\pvtype{Integer})
FreeDTM frees a DTM with the given index \textbf{DTM}. If it does not exist, an
exception is raised.
\subsection{GetDTM}
\subsection{tDTMtopDTM}
\subsection{pDTMtopDTM}
\chapter{OCR}
\section{Finding text}
\section{Identifying text}
\subsection{BitmapFromText}
\subsection{MaskFromText}
\subsection{TPAFromText}
\subsection{rs\_GetUpText}
\subsection{rs\_GetUpTextAt}
\subsection{GetTextAt}
GetTextAt returns the text at the given X, Y.
minvspacing and maxvspacing define the minimum and maximum vertical spacing
between characters in the font, hspacing is the minimal space to split
characters on. If it is, for example, 0, and ``i'' will be split into two
characters.
%TODO: colours
\begin{verbatim}
function GetTextAt(atX, atY, minvspacing, maxvspacing, hspacing, color, tol, len: integer; font: string): string;
\end{verbatim}
\chapter{Clients}
\section{Window}
Simba can target running applicationsa/applets on your computer.
You simply use the crosshair to select the client, and it will then read and
send all its data from and to that application. Simba has also split up its
``Key and Mouse'' input and its ``Data Target``, which means you can send
mouse events to one window, while reading data from another.
\section{Bitmaps and other Raw Data}
Simba can also target data that is loaded in memory. Arrays, bitmaps and data
pointers. Obviously if you load any of these with Simba any mouse and key
events will not be send to that target, as it has no means of communicating
with your devices. Most likely mouse and key events will still be send to the
previous target.
% Complete TODO.
\section{Functions provided}
\subsection{GetClientDimensions}
\subsection{ActivateClient}
\subsection{IsTargetValid}
\subsection{SetTargetBitmap}
\subsection{SetImageTarget}
\subsection{SetTargetArray}
\subsection{SetEIOSTarget}
\subsection{SetKeyMouseTarget}
\subsection{GetImageTarget}
\subsection{GetKeyMouseTarget}
\subsection{FreeTarget}
\section{Freeze and UnFreeze}
% Files
\chapter{Files and Web}
\section{Files}
Files are used to load and save data to the hard drive.
Simba provides several functions to access files - that is, read
from them and write to them.
\subsection{CreateFile}
\subsection{OpenFile}
\subsection{RewriteFile}
\subsection{CloseFile}
\subsection{EndOfFile}
\subsection{FileSize}
\subsection{ReadFileString}
\subsection{WriteFileString}
\subsection{SetFileCharPointer}
\subsection{FilePointerPos}
\subsection{DirectoryExists}
\subsection{FileExists}
\subsection{WriteINI}
\subsection{ReadINI}
\subsection{DeleteINI}
\section{Web}
\subsection{OpenWebPage}
\chapter{Point Sorting and Math}
\section{Sorting functions}
Wizzyplugin stuff
\section{Math}
\chapter{Easter Eggs}
\section{Easter egg 1}
Nothing here! Do you really think we document Easter eggs?
????
HakunaMatata!
\end{document}
Reference in New Issue View Git Blame Copy Permalink