Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / Painting / OpalPaint32B-020+Version.LHA / OpalVision / Arexx.doc next >

Wrap

Text File | 1994-04-22 | 58.9 KB | 2,098 lines

ARexx functions for OpalPaint - Updated for OpalPaint v2.3. opal technology pty ltd (c) 1992 INTRODUCTION ARexx Overview To quote from the Amiga Version 2.0 System Documentation, Chapter 10, "ARexx is a programming language designed to offer flexibility to customise your working environment. ARexx acts as a central hub through which applications may send data and commands to each other. This allows software created by different companies to interact and, in turn, allows the user to create custom applications by integrating off-the-shelf software products." Please see Chapter 10 of your Amiga Version 2.0 documentation, or if you purchased ARexx for your Version 1.3 see the included manual, for a complete discussion of installing and using ARexx. In this document we will only discuss how OpalPaint interacts with ARexx. Also note that the Opal HotKey program acts as an ARexx host so that other programs running in the Amiga environment can access functions of the OpalVision. These functions include all the options available using the HotKey menu or function keys. See the Reference Manual for a further description of OpalHotKey ARexx support. Writing Scripts You can create and edit ARexx scripts using any Amiga text-based editor. Note that if you use a word-processor you will have to save it as a text-only or ASCII file. If ARexx is generating error messages for command arguments, try enclosing the arguments in quotes, this will happen if you try to use negative numbers as parameters (Arexx interprets the '-' sign as a subtraction operator). e.g. SetDrawMode 9 -20 Doesn't work SetDrawMode "9 -20" Works The spellings colour and color are interchangeable in OpalPaint ARexx commands. For example, ColourSource is equivalent to ColorSource. Also note that where a command accepts a text Message string it will also accept the '\n' sequence to signify a new line. This allows multiple lines of text to be displayed in the requester. E.g. to display 3 lines of text, use Okay "This is line 1 \nThis is line 2 \nWow!!!! Isn't this fun!!!" Note that if you wish to include a single quote in the Message string then use double quotes at the beginning and end, and visa versa. ARexx attempts to match quotes to determine where the string begins and ends. Filenames The default filename extension for OpalPaint ARexx macros is '.oprx'. NOTE: All scripts must start with a comment. ARexx Port The Port name for OpalPaint is: OpalPaint_Rexx Executing Scripts There are basically 2 ways to execute a script from within OpalPaint. The first method is to run the script from within OpalPaint using the Amiga Key and a function key, or the Amiga-A ARexx requester. The second method is to run the script externally to OpalPaint using the CLI or another ARexx-compatible program. Up to 30 macros can be installed using the Amiga-a ARexx control requester with one macro assigned to each function key. Once installed each macro can be executed by holding down either the Amiga, Control or Alt keys and pressing the corresponding function key. The current macro names will be stored in the 'opalpaint.prefs' configuration file when OpalPaint is exited. A one-off ARexx command can be executed by pressing Amiga-A, this will bring up a string requester enabling you to type in the name of the macro to be executed. Return Values OpalPaint will return an Error (RC=10) if illegal parameters are given or if an error occurs. For example if a script attempts to invert the stencil plane when it doesn't exist, or if there is insufficient memory to execute a function. Setup Every spare page has its own setup information stored for it. It is important to remember this, any modes or gradients etc that you set up for a page is local to that page, if the active page is changed, the setup information will also be changed. The setup data includes gradients, transparency settings, drawing mode and tools, stencil enables, Paint source, Grid setting, Texture settings, magnification, brush cut modes, line styles, Flood fill tolerances, anti-aliasing settings, colour stencil settings, magic wand setting, paper type, alpha settings, rubthrough modes, and fill modes. Drawing Commands Using ARexx you cannot draw any object larger than the visible display size (even if the page is larger). The drawing coordinates passed to ARexx are absolute coordinates within the current page. If a drawing function is performed outside the current viewing area, the view will automatically be paned to that section. Therefore as long as the object being drawn is smaller than the screen there will be no problem, if the object is larger OpalPaint will center the display the best that it can, and the drawing will be clipped to the visible area. Note that the current magnification level will also effect the size of the object that can be drawn. Also note that low ChipRAM (especially evident when only 1M of Chip RAM is installed) will result in the size of the drawing area being reduced as the Menu Bar rises up from the bottom of the screen. Symbols In the following command descriptions several labels will appear frequently. The meaning and acceptable range for these symbols are: PotNum = Paint Pot number. Range: 1 to 260 NozzleNum = Nozzle number (artist tool). Range: 1 to 10 PageNum = Spare Page number. Range: 1 to Number of Open Pages BrushNum = CutOut brush number. Range: 1 to 3 GradNum = Gradient number. Range: 1 to 8 DModeNum = DrawingMode number. Range: 1 to 18 for built in modes and 19 to 22 for spare (loadable) modes. SpareNum = Spare drawing mode number. Range: 1 to 4 NOTE: Any parameters in brackets [] are optional. Many commands also have a BOOLEAN parameter. A Boolean value is one that has only 2 states, True or False. OpalPaint treats 0 as False and any other value as True. e.g: A Typical command accepting a boolean value is: Trans 0 /* Turn transparency off */ Trans 1 /* Turn transparency on */ OpalPaint will also accept the words ENABLE (=1) and DISABLE (=0) in appropriate places. Commands will also accept other labels where noted. Summary of Commands User I/O Commands AskBool Okay AskFileName AskFont AskString AskInt GetPoint GetRect AskProp Drawing Commands Line Rectangle SolidRect Curve FloodFill Ellipse SolidEllipse Poly SolidPoly Point LastPoint FreeHand SolidFreeHand MagicWand ReadPixel KillMarquee MarqueeFill File I/O Load Save Loader Saver AllowSaves LoadComponents SaveComponents Brush Manipulation Double DoubleX DoubleY Halve HalveX HalveY FlipX FlipY Rotate90 Rotate BendH BendV ShearH ShearV Rescale Resize HandleCenter Handle CopyBrush ActiveBrush RescaleMethod BrushSize Feather MakeText CutMode PutBrush LoadBrush SaveBrush RectCut EllipseCut FloodCut FreeHandCut MagicWandCut PolyCut Spare Pages ClearPage SetPage CopyPage MovePage SwapPage PickPage DeletePage AddPage OpenPages PageName CurrPage SecondaryPage ClonePage PageSize PageRes Misc Zap Undo Again Magnify MagLevel ColourSource Key Refresh Busy NotBusy Version Panic RGBtoHSV HSVtoRGB GetPrefs SetPrefs WorkMode AntiAlias Grid TransType Trans WarpFactor WarpBrush FloodType FillMode LineStyle SetPen GetPen VideoMode Texture TextureType RubDirection RubMode CurrentFont Menu SaveSetUp RestoreSetUp CopySetUp Pan FindPixel FindNextPixel DisplayStatus DisplayPercent Pantograph Clone Stencils ClearSten SetSten DeleteSten InvertSten ExcludeAll StenEnable ColSten MaskSten SetColSten EnableColEntry AddStencil Alpha Commands AddAlpha AlphaPattern ImageToAlpha InvertAlpha DeleteAlpha Draw Modes SetSpare SetDrawMode Artist Tools SetATool ResetATool AToolWeight GetATool NozzleSize ActiveNozzle Paper Type SetPaper SmoothPaper PaperDepth Palette LoadPalette SavePalette SaveRow SetPot GetPot ActivePot SpreadPots Gradients ClearColGrad ClearTransGrad ColourDither TransDither GradType GradRange ColEven TransEven ColReverse TransReverse ColGradTag TransGradTag ActiveGrad DETAILED DESCRIPTIONS ActiveBrush Usage: ActiveBrush [BrushNum] Returns the brush number that is currently active (1 to 3) or -1 if a brush is currently not selected. If 'BrushNum' is specified then the active brush will be set to that number (1 to 3). ActiveGrad Usage: ActiveGrad [GradNum] Returns the currently active Gradient number (1 to 8). If 'GradNum' is specified, it sets the currently active gradient pair to 'GradNum'. Note that each gradient pair contains parallel colour and transparency gradients. GradNum must be in the range of 1 to 8. ActiveNozzle Usage: ActiveNozzle [NozzleNum] Returns the currently active nozzle number (1 to 10), or -1 if a nozzle is currently not selected. If 'NozzleNum' is specified, ActiveNozzle sets the specifed nozzle to be the active nozzle. ActivePot Usage: ActivePot [PotNum] Returns the active pot number, this is in the range of 1..260. If 'PotNum' is specified then the active pot will be changed to this value. AddAlpha Usage: AddAlpha Adds an alpha channel to the current image if it doesn't exist. An alpha channel will automatically added when entering Alpha edit mode. AddPage Usage: AddPage Width Height Resolution Add a new spare page with the deminsions given by 'width' and 'height'. 'Resolution' sets the display resolution of the page, this parameter is a set of flags, valid flags are: HIRES Hires INTERLACE Interlaced OVERSCAN Overscan These flags can be added together, i.e to open a hires interlaced page, Resolution = HIRES INTERLACE. AddStencil Usage: AddStencil Add a mask stencil plane to the current image if one doesn't already exist. A stencil will automatically added when entering Stencil edit mode. Again Usage: Again Repeat the last drawing operation. Same as the 'a' key. AllowSaves Usage: AllowSaves [Enable|Disable] Rexx command to disable saving. AlphaPattern Usage: AlphaPattern Pattern Choose the alpha background pattern (See the Alpha Paint Options menu). The allowable patterns are 1 to 6 or GreyScale or GrayScale. Examples: AlphaPattern 4 AlphaPattern GreyScale AntiAlias Usage: AntiAlias Enable [Level] The Enable parameter can be ENABLE (=1) to turn antialiasing on, or DISABLE (=0) to turn it off. Level sets the antialiasing level to be used and must be in the range of 0 to 100. AskBool Usage: AskBool Message Creates a requester containing the 'Message' text, as well as OK and CANCEL gadgets. The Message string can contain '\n' to start a new line in the text. The return value is a boolean value indicating whether the user hit OK or CANCEL, a true value is returned if OK is hit. Example: AskBool 'Are you sure?' if Result=0 then Okay 'I Guess not' else Okay 'You are!!' AskFileName Usage: AskFileName Hail Path FileName Bring up the OpalVision file requester. The 'Hail' string will be displayed at the top of the requester and the initial path and filename will be set the the values specified. If the user hits CANCEL, RC will be set to WARN (5) otherwise the selected filename (including) path will be returned. This command will return the selected path and filename as one string in standard AmigaDOS format. e.g. AskFileName 'Pick a file Images24: clowns' AskFont Usage: AskFont Bring up the font requester to allow the user to select a font. If the user hits CANCEL, RC will be set to WARN (5) otherwise the selected font name, size and style is returned. An example return string would be: topaz 8 0 The Style value is a set of flags, with the valid flags being: Underlined 1 Bold 2 Italic 4 These flags can be added together to get composite styles. For example, Underlined Bold will return the value 3, while bold italic will return the value 6. AskInt Usage: AskInt MinInt MaxInt Default HailText Brings up a requester containing a 'Message' text as well as string, OK and CANCEL gadgets. The Message string can contain '\n' to start a new line in the text. The string gadget can be used to enter an integer value only, 'MinInt' and 'MaxInt' set the minimum and maximum allowable values. Default value will define a number that initially shows in requestor. If the user hits CANCEL, RC will be set to WARN (5) otherwise the entered integer value will be returned. Example: AskInt 0 100 20 'Enter Tolerance' AskProp Usage: AskProp Min Max Default Message This command brings up a requester containing an OK and Cancel gadgets and a proportional (slider) gadget. 'Min' and 'Max' define the range of the slide, 'Default' is the starting position for the knob, and 'Message' will be displayed in the requester. Example: AskProp 0 100 50 'Enter Tolerance' AskString Usage: AskString Message Brings up a requester containing a 'Message' text as well as string, OK and CANCEL gadgets. The Message string can contain '\n' to start a new line in the text. The string gadget can be used to enter any text string. If the user hits CANCEL, RC will be set to WARN (5) otherwise the entered text will be returned. Example: AskString 'Whats your name?' AskString ARexx command now accepts a default string. The calling format is now: AskString Heading Default The 2 strings can contain spaces but need to be enclosed in quotes, ARexx strips off the first level of quotes, so the following trick has to be used to sucessfully quote the string: e.g. Example: AskString "'This is the heading' 'This is the default string'" To Keep compatibility with the old AskString, if a string is found that is not quoted and contains spaces, the entire string is treated as the heading for the requester. AToolWeight Usage: AToolWeight Weight Set the weight of the current selected Artist's Tool (nozzle). Weight is the value it should be changed to (0 to 100). BendH Usage: BendH Distance Bend the current cutout brush horizontally by the number of pixels specified by 'Distance'. BendV Usage: BendV Distance Bend the current cutout brush vertically by the number of pixels specified by 'Distance'. BrushSize Usage: BrushSize Returns the size of the current cutout brush. The value returned is in the form "W H" with the W and H values being in pixels. If the brush is not defined, -1 -1 is returned. Busy Usage: Busy Disable the menu bar and changes the mouse pointer to the busy sprite. Busy calls can be nested, i.e. multiple Busy commands can be issued and a corresponding number of NotBusy commands have to be issued to restore the pointer to its normal state. ClearColGrad Usage: ClearColGrad Clears the colour gradient of the current gradient pair. This is equivalent to the trashcan gadget in the gradient menu. ClearPage Usage: ClearPage Clears the current page to black. Note, the verification requester that normally appears when hitting the trashcan gradget on the main menu will not be displayed. ClearSten Usage: ClearSten Clears the mask stencil for the current page. ClearTransGrad Usage: ClearTransGrad Clears the transparency gradient for the current gradient pair. This is equivalent to the trashcan gadget in the gradient menu. Clone Usage: Clone Enable [X Y] Enables or Disables the Clone texture mode. If the X Y coordinates are specified, the clone crosshairs will be positioned at this point. ClonePage Usage: ClonePage [PageNum] Add a new spare page with the same dimensions and resolution as the specified page, if the page is not specified then the current page will be cloned. This is equivalent to the clone gadget in the spare page menu. ColEven Usage: ColEven Regularly spaces (evens out) the colour tags in the colour gradient of the current gradient pair. This is equivalent to the even space gadget in the gradient menu. ColGradTag Usage: ColGradTag Position R G B Adds a colour tag to the colour gradient in the current gradient pair. Position specifies the position of the tag within the gradient, where 0 corresponds to the start of the gradient (left hand of colour bar in the gradient menu) and 1 corresponds to the end of the gradient (right hand side). R,G,B sets the Red Green and Blue components for the colour of the tag (0-255) For example to create a gradient from white through blue to red in the 5th gradient pair, use: ActiveGrad 5 ColGradTag 0 255 255 255 ColGradTag 0.5 0 0 255 ColGradTag 1 255 0 0 ColourDither (or ColorDither) Usage: ColourDither Dither Set the colour dither for the colour gradient in the current gradient pair. Dither must be in the range of 0 to 100. ColourSource (or ColorSource) Usage: ColourSource Source If Source=PAINTPOT set the colour source to 'paint pot' else if Source=MULTICOLOUR or MULTICOLOR set the colour source to 'multicolour'. These settings correspond to those in the modes menu. See the Reference Manual for a full discussion of the differences between these settings. ColReverse Usage: ColReverse Reverses the direction of the colour gradient in the current gradient pair. This is equivalent to the reverse gadget in the gradient menu. ColSten Usage: ColSten Enable The Enable argument can be ENABLE (=1) to enable the use of the colour stencil, else DISABLE (=0) to disable it. This corresponds to the colour stencil enable gadget in the stencil menu. CopyBrush Usage: CopyBrush SourceBrushNum Copy the source brush (1 to 3) to the current selected cutout brush. CopyPage Usage: CopyPage SrcPageNum DestPageNum [Xoffset Yoffset] Copies the contents of the source page to the destination page. If the X and Y offset are specified, the source image will be shifted by that offset when it is copied into the destination page. The size of the destination page will not be modified. If the offsets are not specified, the command will copy the current page into the destination page, resizing the destination page if its not the same as the source. This is equivalent to the Copy gadget in the spare page requester. CopySetUp Usage: CopySetUp DestPageNum Copies the setup of the current page to the destination page. See the description of 'SetUp' above. CurrentFont Usage: CurrentFont The current font name, size and style is returned. An example return string would be: topaz 8 0 See AskFont for details on the format of this string. CurrPage Usage: CurrPage Return the current page number. Curve Usage: Curve X1 Y1 X2 Y2 X3 Y3 Draw a curve between the three points. CutMode Usage: CutMode BGMode [Alpha [HTol STol VTol Smooth]] This mode sets the options in the brush cut menu. Allowable values for BGMode are: NORMAL COLOUR or COLOR TOLERANCE If Alpha is ENABLE (=1), the alpha channel will be enabled for brush cutting. If HTol, STol, VTol and Smooth are specified, the cut tolerances and smooth factor will be set to these values. Htol, STol, VTol & Smooth must be in the range 0 to 100% DeleteAlpha Usage: DeleteAlpha Deletes the alpha channel for the current image. DeletePage Usage: DeletePage PageNum Delete the specified page. Equivalent to the Delete button in the Spare Pages Menu. DeleteSten Usage: DeleteSten Delete the mask stencil plane from the current image if one exists. DisplayPercent Usage: DisplayPercent Current Max Text This command will display 'text' as well as a percentage count on the status bar in the main menu. 'Current' can range from 0 to 'Max'. Max is the number of steps in an operation, and Current is the current step. For example if you have a function that takes 6 steps, you can use: DisplayPercent 3 6 'Scaling:' OpalPaint will determine the percentage by calculating Current/Max * 100. In the example above, 50% would be displayed. 'Text' cannot be longer than 7 characters. DisplayStatus Usage: DisplayStatus Text This command will print 'Text' into the status bar on the main menu. 'Text' cannot be longer than 11 characters. Double Usage: Double Double the current cutout brush size both horizontally and vertically. DoubleX Usage: DoubleX Double the current cutout brush size horizontally only. DoubleY Usage: DoubleY Double the current cutout brush size vertically only. Ellipse Usage: Ellipse Xc Yc a b Draw an ellipse centered around Xc,Yc with a horizontal dimension of 'a' and a vertical dimension of 'b'. To draw a circle, set 'a' and 'b' to the same value. EllipseCut Usage: EllipseCut Xc Yc a b Perform an elliptical brush cut centered around Xc,Yc with a horizontal dimension of 'a' and a vertical dimension of 'b'. To cut a circle, set 'a' and 'b' to the same value. The cutout will be placed in the currently selected cutout brush (1 to 3). EnableColEntry Usage: EnableColEntry ColEntry Enable Enable or disable a colour stencil entry. 'ColEntry' is the colour stencil to be modified (between 1 and 6). The Enable argument can be either ENABLE (=1) to Enable the stencil entry or DISABLE (=0) to disable it. ExcludeAll Usage: ExcludeAll Enable Sets or clears the ExcludeAll gadget in the stencil menu. The Enable argument can be either ENABLE (=1) to Exclude all colours in the image, or DISABLE (=0) to Include all colours by default. See the section in the OpalVision Reference Manual on Stencil Priority for further details of how stencils are combined and how priorities are determined. Feather Usage: Feather Radius Feather the current cutout brush using the radius given. Radius is measured in pixels. FillMode Usage: FillMode Mode Set the current fill mode, the allowable values for 'mode' are: SOLID = Solid fill GRADIENT = Gradient fill BRUSH = Brush warp fill FindNextPixel Usage: FindNextPixel This command should be called only after FindPixel. Returns the coordinates of the next pixel matching the colour given in FindPixel. '-1 -1' is returned if no pixels are found. FindNextPixel can be called repeatedly until it returns '-1 -1'. FindPixel Usage: FindPixel R G B Returns the coordinates of the first pixel encountered which has a colour value matching 'R G B'. Search starts at the top-left hand corner of the image. FlipX Usage: FlipX Flip the current cutout brush horizontally. FlipY Usage: FlipY Flip the current cutout brush vertically. FloodCut Usage: FloodCut X Y Cut a brush using a flood fill. The fill will start at X,Y. The cutout will be placed in the currently selected cutout brush (1 to 3). FloodFill Usage: FloodFill X Y Start a flood fill at X,Y. FloodType Usage: FloodType Type [HTol STol VTol] Set the current flood fill options. Allowable values for type are: NORMAL = Normal fill TOLERANCE = Tolerance fill If HTol,STol and VTol are specified the fill tolerances will be set to these values. Htol, STol & VTol must be in the range 0 to 100% FreeHand Usage: FreeHand [X Y X Y ....] Start freehand drawmode. If coordinates are specified a continuous line will be drawn between the coordinates. This command is used in conjunction with the Point and LastPoint commands. Note that for cutting, PolyCut is the equivalent of FreeHandCut, so FreeHandCut has not been included in the command set. FreeHandCut Usage: FreeHandCut [X Y X Y ...] Start a FreeHand cut into the current selected cutout brush. The vertice parameters are the same as the Poly command. This command is functionally identical to the PolyCut command and has been added only for consistency. Note that the filled polygon gadget will be highlighted after this command. The cutout will be placed in the currently selected cutout brush (1 to 3). GetATool Usage: GetATool NozzleNum Returns the artists tool name for the specified nozzle. NozzleNum must be in the range (1 to 10) GetPen Usage: GetPen Returns the colour of the current selected paintpot in R G B format. GetPoint Usage: GetPoint Ask the user to select a point on the image. When this command is executed, the mouse pointer changes to 'Point' and waits until the user selects a point using the mouse. The coordinates of the selected point are returned in X Y form relative to the top left corner of the image, NOT the position within the visible painting area. GetPot Usage: GetPot PotNum Returns the colour of the specified paint pot. The colour is returned in R G B format. GetPrefs Usage: GetPrefs Returns the current preferences settings. A single number is returned specifying the active preferences, the number is made up of flags, the current valid flags are: 1 = Don't save thumbnails. 2 = Do safe file writes. 4 = Unused Spare pages -> Disk. 8 = Unused brushes -> Disk. 16 = Outside of work area -> Disk. 32 = Fast feed back on. 64 = drag rectangles from center. 128 = drag circles from center. 256 = Don't save icons. 512 = Rectangles/circles aspect correct (be square). 1024 = Don't calculate brush outlines. 2048 = Don't Load setup struct with Image. 4096 = Allow brush build up. 8192 = Don't raise menu bar in overscan mode. 16384 = Disable tablet pen flicks. To test if a particular mode is set, use the ARexx logical AND operator, e.g.: Prefs = GetPrefs if (Prefs & 32) then FastFeedBack = 1 GetRect Usage: GetRect Ask the user to select a rectangular area of the image. When this command is executed, the mouse pointer changes to 'Rect' and waits until the user drags out a rectangle. Once the rectangle has been selected, the upper left and lower right coordinates of the rectangle are returned in X1 Y1 X2 Y2 form. GradRange Usage: GradRange X1 Y1 X2 Y2 This command is used to specify the gradient range for the 'Linear Free' and 'Radial Free' gradient modes. Normally OpalPaint asks the user to drag out a line or ellipse when these gradient modes are used, under ARexx control however this command is used instead, to specify the gradient range. Note that this command must be specified before the filled object is drawn. e.g To draw a circle with a 45 degree angle gradient across it. GradType LinearFree HSV /* Set up 'linear free' mode */ GradRange 120 90 180 150 SolidEllipse 150 120 30 30 GradType Usage: GradType Type [ColourSystem] Setup the gradient type options. 'Type' specifies one of the 6 possible gradient types in the gradient menu. Allowable values for 'type' are: HORIZONTAL = Horizontal Gradient VERTICAL = Vertical Gradient RADIAL = Radial Gradient HORIZONTALFIT = Horizontal Fit gradient. LINEARFREE = Linear Free Gradient RADIALFREE = Radial Free Gradient. Types LINEARFREE and RADIALFREE must also be used in conjunction with the GradRange command. If the 'ColourSystem' argument is specified, allowable values are RGB = RGB colour mode HSV = HSV colour mode Grid Usage: Grid Enable [W H [X Y]] Enable is used to turn the Grid on/off. If the argument is ENABLE (=1) grid is enabled, else if DISABLE (=0) it is disabled. If W and H are specified, the grid spacing is set to these values. If X and Y are specified, the grid origin is moved to that location. Halve Usage: Halve Halve the current cutout brush size both horizontally and vertically. HalveX Usage: HalveX Halve the current cutout brush size horizontally. HalveY Usage: HalveY Halve the current cutout brush size vertically. Handle Usage: Handle X Y Move the brush handle to location X,Y within the brush. e.g. ActiveBrush 1 /* Set the current cutout brush to B1 */ Handle 0 0 /* Handle to top left on brush 1 */ BrushSize Handle Result /* Handle to bottom right on brush 1 */ HandleCenter Usage: HandleCenter Center the handle within the current cutout brush. HSVtoRGB Usage: HSVtoRGB H S V Convert a colour specified in the HSV colour system to the RGB colour system. HSV values range from 0 to 65535, i.e. Actual Value 0 65535 -------------------------------------- Hue 0 degrees 359 degrees Saturation 0% 100% Value 0% 100% RGB values range from 0 to 255. ImageToAlpha Usage: ImageToAlpha Copies the current image into it's own alpha channel. InvertAlpha Usage: InvertAlpha Inverts the contents of the alpha channel. InvertSten Usage: InvertSten Invert the mask stencil for the current image. Key Usage: Key [[Qualifiers] Character] [KeyFileToken] Process a key as if it was typed on the keyboard. The allowable qualifiers are: AMIGA ALT CONTROL SHIFT The qualifiers may be freely mixed, e.g. CONTROL SHIFT is acceptable. 'Character' can either be a single character or a name for an unprintable character. The accepted key names are: LEFTARROW = Left Arrow key RIGHTARROW = Right Arrow key UPARROW = Up Arrow Key DOWNARROW = Down Arrow Key HELP = Help Key DEL = Delete key F1 to F10 = Function keys. e.g. key 'ALT SHIFT LEFTARROW' /* Rip up and Redo to left*/ With the addition of keyfiles in OpalPaint v2.3, this method of using keystokes for commands is no longer reliable if the ARexx script is to be used by different users. This is due to the fact that the user can now redefine the keyboard equivalents and hence you cannot assume that, Amiga Q for instance, will quit OpalPaint. To get around this problem, the 'key' command now accepts the same tokens that are used in the key file to define the keyboard command, for example to quit OpalPaint, the following command can be used: Key Quit It is suggested that you always use this format of the key command. All the available command tokens are defined in the key file OpalPaint:Prefs/OpalPaint.keys. KillMarquee Usage: KillMarquee Terminate the current Marquee without filling it. LastPoint Usage: LastPoint [X Y X Y...] This command is used to finish the drawing or cutting using freehand or polygon modes. To draw or cut freehand or a polygon, first enter the correct drawing mode, specify the points for drawing using Point and complete the object using last point. e.g. FreeHand X1 Y1 Point X2 Y1 X2-10 Y1+10 X1+10 Y1+10 LastPoint X1 Y1 Line Usage: Line X1 Y1 X2 Y2 Draw a line between point 1 (X1,Y1) and point 2 (X2,Y2). LineStyle Usage: LineStyle Style [Dots] Set the current line style. Allowable values of 'style' are: CONTINUOUS = Continuous SPACED = Every Nth TOTAL = Total Dots If Style = SPACED then 'Dots' specifies the spacing between dots on the line. If Style = TOTAL, 'Dots' specifies the total number of dots making up the line. Load Usage: Load FileName Load a file using the current loader. FileName must include the full path of the image name. LoadBrush Usage: LoadBrush FileName Load 'Filename' into the current selected cutout brush (1 to 3). LoadComponents Usage: LoadComponents [Components] Specify the image components which are loaded (as set in the 'Image', 'Stencil' and 'Alpha' buttons in the VLSI requestor). The allowable parameters are 'Image', 'Alpha' and 'Stencil' which can be specified in any combination and order. e.g. To load all image components: LoadComponents Image Stencil Alpha Loader Usage: Loader Name [Parameters] Set the current image loader. Allowable names for v2.3 of OpalPaint are Intelligent, IFF, FAST, JPEG, GIF, Rendition and VPB. 'Parameters' will be local to each loader, and these values will be passed directly to the loader. For example, the JPEG saver parameter is a quality factor. LoadPalette Usage: LoadPalette FileName Load a new palette set. If the saved palette was a complete set of 260 paint pots then all paint-pots will be replaced. If the saved palette only contains a single paint-pot row then the current paint-pot row will be replaced. To select the row to be replaced, first select any paint-pot in the row using the ActivePot command. MagicWand Usage: MagicWand X Y [Tolerance] Start a Magic Wand fill at X,Y (relative to the top left corner of the image). Tolerance must be in the range (0 to 100). This command can be issued several times to build up a marquee, each new call to MagicWand is equivalent to pressing the mouse button while holding down the shift key. The Marquee generated will not be filled until a 'MarqueeFill' command is issued. MagicWandCut Usage: MagicWandCut X Y [Tolerance] Start a Magic Wand cut at X,Y (relative to the top left corner of the image). Tolerance must be in the range (0 to 100). The cutout will be placed in the currently selected cutout brush (1 to 3). The brush will not be cut until a 'MarqueeFill' command is issued. MagLevel Usage: MagLevel Level Set the current magnification level. If the page is currently in magnify mode, the display will be refreshed at this level. Allowable Level's are 1,2,4,8 (and 16 in hires only). Magnify Usage: Magnify Enable The Enable argument can be ENABLE (=1) to turn magnify on, else DISABLE (=0) to turn magnify off. MakeText Usage: MakeText Font FontSize FontStyle Text Create text in the current cutout brush using the font specified and text string. The values for FontStyle are the same as those returned by AskFont. e.g. MakeText 'cgtimes 50 2 Hello' MarqueeFill Usage: MarqueeFill Fill the currently active marqueed area, returns an error if a marquee is not active. (Marquees are created using the magic wand tool). MaskSten Usage: MaskSten Enable If the Enable argument is ENABLE (=1) then enable the use of the mask stencil, else use DISABLE (=0) to disable it. This corresponds to the mask stencil enable gadget in the stencil requester. Menu Usage: Menu Enable If the Enable argument is ENABLE (=1) then display the menu/tool bar, else use DISABLE (=0) to make the menu bar disappear. MovePage Usage: MovePage SrcPageNum DestPageNum Move the source page to the destination page. This function simply shuffles the order of spare pages around. NotBusy Usage: NotBusy Disables the Busy mouse pointer and enables the menu bar. If there are nested Busy commands this command will 'unest' them and not change the mouse pointer until the number of NotBusy commands equals the number of Busy commands executed. NozzleSize Usage: NozzleSize [W H] Returns the size of the current selected nozzle. If W and H are specified, the size of the nozzle will be modified to this size. Okay Usage: Okay Message Brings up a requester containing the 'Message' text and an OK gadget only. The Message string can contain '\n' to start a new line in the text. e.g. Okay 'Operation complete' OpenPages Usage: OpenPages Returns the number of open pages. PageName Usage: PageName [PageNum] Returns the name of a page. If PageNum is not specified, the current page's name will be returned. A page is named by saving it. PageRes Usage: PageRes Returns the current page resolution. The returned value can contain any combination of the tokens HIRES, INTERLACE and OVERSCAN (as accepted by the AddPage and PageSize commands). PageSize Usage: PageSize [W H Modes Scale] Returns the current page size in W H format. If the optional parameters are specified, the page will be resized to the WxH and Modes will be used for the display mode (see AddPage for description of display Modes). The value of Scale determines the way in which the page is resized. If Scale is false (=0), the page is cropped to the new size, else the page is rescaled to fit the new size. Pan Usage: Pan X Y This command sets the X,Y location of the top left hand corner of the viewing area. This allows the displayed to be panned around within a larger image. Panic Usage: Panic Same as the panic button in the About requester. Sets single-pixel brush, continuous draw and Paint Mode. Switches off all options such as transparency, stencils, textures etc. Pantograph Usage: Pantograph Enable [X Y] Enables or Disables the pantograph texture mode. If the X Y coordinates are specified, the pantograph crosshairs will be positioned at this point. PaperDepth Usage: PaperDepth Depth Set the depth of the current paper type. Depth must be between 0 and 100. PickPage Usage: PickPage PageNum Change the active page to 'PageNum'. Point Usage: Point [X Y X Y ...] Specify points for freehand and Polygon drawing modes. (See LastPoint) Poly Usage: Poly [X Y X Y ...] Start poly drawing mode. If the vertices are given, lines will be drawn to the given points. Additional points can be given using the Point command, and the polygon is terminated using the LastPoint command. PolyCut Usage: PolyCut [X Y X Y ...] Start a Polygon cut into the current selected cutout brush. The vertice parameters are the same as the Poly command. The cutout will be placed in the currently selected cutout brush (1 to 3). PutBrush Usage: PutBrush X Y Draws the currently active brush or nozzle at X,Y location given. ReadPixel Usage: ReadPixel X Y Return the colour values of a given pixel. The return value is the pixel colour in R G B format. Rectangle Usage: Rectangle X1 Y1 X2 Y2 Draw a rectangle between Point1 (X1,Y1) and Point2 (X2,Y2). Point1 defines the top left-hand corner of the rectangle, Point2 defines the bottom right-hand corner. RectCut Usage: RectCut X1 Y1 X2 Y2 Make a rectangular cut into the current cutout brush. The vertice parameters are the same as Rectangle. The cutout will be placed in the currently selected cutout brush (1 to 3). Refresh Usage: Refresh Refresh the current display by updating the image in Amiga memory into the OpalVision Hardware. This command is rarely required however as OpalPaint will generally keep the displayed version the image consistent with that in memory. The only time this command will be required is to update the display after the palette data has been changed. OpalPaint does not do this automatically to increase the speed of modifying palette colours. Rescale Usage: Rescale %x %y Rescale the current cutout brush using percentage values. %x and %y define the percentage scaling for the x and y axis respectively. e.g. ActiveBrush 2 /* Make brush B2 active */ Rescale 50 50 /* Halve the current (B2) brush 2 */ ActiveBrush 3 /* Make brush B3 active */ Rescale 200 200 /* Double the current (B3) brush */ RescaleMethod Usage: RescaleMethod Method Set the rescaling method for the current cutout brush. Allowable values for 'Method' are: BLOCKY (Multiply pixels. Fastest) SMOOTH1 (Linear interpolation) SMOOTH2 (Cubic Spline interpolation. Slowest) ResetATool Usage: ResetATool Reset the current nozzle to its default 'solid' state. Has the same effect as the Solid gadget in the Artists Tools menu. Resize Usage: Resize W H Resize the current cutout brush to an absolute pixel size. e.g. ActiveBrush 2 /* Select brush B2 */ Resize 100 100 /* Resize brush 2 to 100 by 100 pixels */ RestoreSetUp Usage: RestoreSetUp Restore the setup information stored using SaveSetUp. Note, the same page should be active as when SaveSetup was called if you wish to restore the users setup back to the way it was before the macro was executed. If a different page is active the result will basically be the same as the CopySetup command. RGBtoHSV Usage: RGBtoHSV R G B Convert a colour specified in the RGB colour system to the HSV colour system (See HSVtoRGB). Rotate Usage: Rotate Angle Rotate the current brush by any angle. 'Angle' must be an integer value in degress. e.g. ActiveBrush 3 /* Select brush B3 as the current brush */ Rotate 45 /* Rotate Brush 3 by 45 degrees */ Rotate90 Usage: Rotate90 Rotate the current cutout brush 90 degrees anti-clockwise. RubDirection Usage: RubDirection Dir If 'Dir' is false (=0) the rub direction will be set to 'Secondary to Current' else the direction will be 'Current to Secondary'. This corresponds to the direction gadget in the spare page menu. RubMode Usage: RubMode RubType [XOffset YOffset] Set RubThough mode. Allowable values for the 'RubType' parameter are RELATIVE = Relative rubthrough mode ABSOLUTE = Absolute rubthrough mode. If 'XOffset' and 'YOffset' are specified, the rub through origin will be set to that location. These functions correspond to the gadgets in the spare page menu. Save Usage: Save FileName Save the current image using the filename given. The filename must include the full path of the image name. The currently active saver will be used to perform the save. SaveBrush Usage: SaveBrush FileName Save the current cutout brush in IFF format. Filename must include the full path of the brush file. SaveComponents Usage: SaveComponents [parameters] Specify the image components which are saved (as set in the 'Image', 'Stencil' and 'Alpha' buttons in the VLSI requestor). The allowable parameters are 'Image', 'Alpha' and 'Stencil' which can be specified in any combination and order. e.g. To save all image components: SaveComponents Image Stencil Alpha SavePalette Usage: SavePalette FileName Save the current palette (all 260 entries) and the mixing area to an IFF file. FileName must include the full path. Saver Usage: Saver [Parameters] Set the current image saver. Allowable names for v2.3 of OpalPaint are IFF, FAST, JPEG, VPB and Rendition. Parameters will be local to each loader, and these values will be passed directly to the loader. SaveRow Usage: SaveRow FileName Save the current Row of palette colours (20 entries) and the mixing area to an IFF file. FileName must include the full path. To select the active row, use ActivePot to select any paint pot within that row. SaveSetUp Usage: SaveSetUp Save the current Setup information to a temporary memory area. This includes the SetUp structure (see description above), the preferences values, the active paint pot and the colour palette. This is useful to make a snapshot of the users configuration before performing any operations, when your macro exits use RestoreSetUp to restore the configuration to the way it was. Note, if your using this technique you must be on the same page when you call SaveSetUp and RestoreSetUp. SecondaryPage Usage: SecondaryPage [PageNum] Returns the page number of the secondary page. If 'PageNum' is specified, the secondary page will be set to this page. SetATool Usage: SetATool AToolName [Weight] Load an artist tool into the current nozzle. AToolName specifies the tools to be loaded, and must be the name of a file in the OpalPaint:ArtistTools directory. Weight specifies the initial tool weight (0 to 100). e.g. ActiveNozzle 3 /* Select nozzle 3 to be active */ SetATool AirBrush 50 /* Nozzle 3 = airbush at 50% */ NozzleNum must be in the range (1 to 10). SetColSten Usage: SetColSten StenEntry Include R G B HTol STol VTol Modify a colour stencil entry. 'StenEntry' is the entry to be modified (1 to 6). If 'Include' is false (=0) the entry will be an Excluded colour, else it will be an included colour. R,G,B sets the stencil colour. HTol,STol,VTol sets the HSV tolerance range for the colour entry. SetDrawMode Usage: SetDrawMode DModeNum [Weight] Set the current drawing mode. DModeNum must be in the range 1 to 18 for built in modes and 19 to 22 for spare (loadable) modes. 'Weight' optionally sets the weight for the mode. The range of 'Weight ' will vary depending on the mode. The valid ranges are 0 to 100, -50 to 50 or 1 to 31, depending on whether the mode takes a normal range, split range or convolution window size. e.g. SetDrawMode 6 50 /* Posterise at 50% */ SetPage Usage: SetPage R G B Set the current page to a solid colour, R,G and B specifies the colour to be used. SetPaper Usage: SetPaper PaperName [Depth] Set the paper type for the current page. PaperName must be the name of a file in the OpalPaint:PaperTypes directory. Depth can be used to specify the 'roughness' of the paper, the range for Depth is 0 to 100. e.g. SetPaper RicePaper 50 SetPen Usage: SetPen R G B Set the current pen colour used for drawing. This function is equivalent to calling SetPot for the currently active paint pot. SetPot Usage: SetPot PotNum R G B Set the colour of a paint pot entry. PotNum must be in the range (1 to 260). SetPrefs Usage: SetPrefs Prefs Modify the preferences. 'Prefs' is a single integer value, see GetPrefs for flag values. SetSpare Usage: SetSpare SpareNum DModeName [Weight] Load a drawing mode into a 'spare mode' location. DModeName is the name of the mode to load, Weight can be used to set the mode weight and should be in the range 0 to 100. e.g. SetSpare 1 AddNoise SpareNum must be in the range (1 to 4). SetSten Usage: SetSten Set the mask stencil for the current image to a solid colour (all 1's). ShearH Usage: ShearH Distance Shear the current cutout brush horizontally by the number of pixels specified by 'Distance'. ShearV Usage: ShearV Distance Shear the current cutout brush vertically by the number of pixels specified by 'Distance'. SmoothPaper Usage: SmoothPaper Reset the paper type for the current page to smooth. SolidEllipse Usage: SolidEllipse Xc Yc a b Draw a solid ellipse centered around Xc,Yc with a horizontal dimension of 'a' and a vertical dimension of 'b'. To draw a solid circle, set 'a' and 'b' to the same value. SolidFreeHand Usage: SolidFreeHand [X Y X Y ...] Start Solid FreeHand drawing mode. If the vertices are given, lines will be drawn to the given points. Additional points can be given using the Point command, and the freehand outline is terminated using the LastPoint command. SolidPoly Usage: SolidPoly [X Y X Y ...] Start Solid poly drawing mode. If the vertices are given, lines will be drawn to the given points. Additional points can be given using the Point command, and the polygon is terminated using the LastPoint command. SolidRect Usage: SolidRect X1 Y1 X2 Y2 Draw a solid rectangle between Point1 (X1,Y1) and Point2 (X2,Y2). Point1 defines the top left-hand corner of the rectangle, Point2 defines the bottom right-hand corner. SpreadPots Usage: SpreadPots Pot1 Pot2 Create a spread of colour between Pot1 and Pot2. Equivalent to the Spread button in the Palette menu. Pot1 and Pot2 must be in the range 1 to 260. StenEnable Usage: StenEnable Enable This is the main stencil enable. If 'Enable' is false (=0) stencils will be disabled, else stencils are enabled. This enables/disables both the mask and colour stencils. This control corresponds to the STEN gadget on the main menu. SwapPage Usage: SwapPage SrcPageNum DestPageNum Swaps the order of two pages, this simply reorders the pages in memory. This is equivalent to the swap gadget in the spare page requester. Texture Usage: Texture Enable The Enable argument can be either ENABLE (=1) or DISABLE (=0). TextureType Usage: TextureType Mode [Tile] Set the current Texture modes. Valid values for mode are: BRUSH1 = Use brush 1 as texture. BRUSH2 = Use brush 2 as texture. BRUSH3 = Use brush 3 as texture. RUBTHROUGH = Rubthrough mode. PANTOGRAPH = Pantograph mode. CLONE = Clone mode. Allowable values for the Tile parameter are: TILE NOTILE Trans Usage: Trans Enable The Enable argument can be either ENABLE (=1) or DISABLE (=0). TransDither Usage: TransDither Dither Set the dither level for the transparency gradient in the current gradient pair. Dither must be in the range 0 to 100. TransEven Usage: TransEven Regularly spaces (evens out) the transparency tags in the transparency gradient of the current gradient pair. This is equivalent to the even space gadget in the gradient menu. TransGradTag Usage: TransGradTag Position Trans Adds a transparency tag to the transparency gradient in the current gradient pair. Position specifies the position of the tag within the gradient where 0 corresponds to the start of the gradient (left hand of colour bar in the gradient menu) and 1 corresponds to the end of the gradient (right hand side). Trans sets the transparency of the tag (0 to 100). For example to create a gradient from fully transparent through to solid and back to fully transparent: ActiveGrad 5 /* Select the 5th gradient pair as active */ TransGradTag 0 100 TransGradTag 0.5 0 TransGradTag 1 100 TransReverse Usage: TransReverse Reverses the direction of the transparency gradient in the current gradient pair. This is equivalent to the reverse gadget in the gradient menu. TransType Usage: TransType Type [Trans1 [Trans2 Trans3]]] Set transparency options. Valid values for 'Type' are: STANDARD = Standard RGB = RGB Transparency HSV = HSV Transparency ALPHA = Alpha transparency. The meaning of the tolerance values varies depending on the value of 'Type'. If Type is STANDARD, Tol1 sets the standard transparency value. If Type is RGB, then Tol1, Tol2 and Tol3 set the Red,Green and Blue transparencies respectively. If Type is HSV, then Tol1, Tol2 and Tol3 set the Hue, Saturation and Value transparencies respectively. If Type is ALPHA, then Tol1 sets the 'strength' of the alpha channel. Undo Usage: Undo Undo the last operation if possible. Note that the undo buffer will be lost if the display view is paned or the magnification level is changed. Version Usage: Version Return the version string for OpalPaint. The string will be of the form: $VER: OpalPaint 1.0 (14.10.92) VideoMode Usage: VideoMode This command is used to determine whether OpalPaint is running in PAL or NTSC mode. The returned value will be either 'PAL' or 'NTSC'. WarpBrush Usage: WarpBrush BrushNum Set the brush number used in the Warp/Fill mode. This command corresponds to the brush gadgets in the fill menu. BrushNum must be in the range (1 to 3). WarpFactor Usage: WarpFactor Factor Set the warp factor used in brush fill mode. Factor must be in the range 0 to 100. WorkMode Usage: WorkMode WMode Set the current work mode. 'WMode' can be: IMAGE = Image edit mode STENCIL = Stencil edit mode ALPHA = Alpha edit mode This command corresponds to the work mode gadgets on the main menu. Zap Usage: Zap Zap the current page. Example Script - Bevelled Box. /* Draw a bevelled drop box using OpalPaint. */ address 'OpalPaint_Rexx' options Results SaveSetUp GetRect parse var Result X1 Y1 X2 Y2 Depth = 10 /* Could use AskInt here */ GetPen RGBtoHSV Result Parse var Result Hue Sat Val /* Box body. Set up a diagonal HSV gradient */ FillMode Gradient ClearColGrad ClearTransGrad ColourDither 0 TransDither 0 HSVtoRGB Hue Sat Val ColGradTag 0 Result S2 = (Sat-(0.4*65535))%1 /* Note: %1 converts number to an integer */ S2 = MAX(S2,0) HSVtoRGB Hue S2 Val ColGradTag 0.5 Result HSVtoRGB Hue Sat Val ColGradTag 1 Result GradType LinearFree HSV GradRange X1+Depth Y1+Depth X2-Depth Y2-Depth SolidRect X1+Depth Y1+Depth X2-Depth Y2-Depth FillMode Solid /* Top */ V2 = (Val+0.1*65535)%1 V2 = MIN(V2,65535) HSVtoRGB Hue Sat V2 SetPen Result SolidPoly X1 Y1 X2 Y1 X2-Depth Y1+Depth X1+Depth Y1+Depth X1 Y1 LastPoint /* Right */ V2 = (Val-0.15*65535)%1 V2 = MAX(V2,0) HSVtoRGB Hue Sat V2 SetPen Result SolidPoly X2 Y1 X2 Y2 X2-Depth Y2-Depth X2-Depth Y1+Depth X2 Y1 LastPoint /* Left */ V2 = (Val+0.15*65535)%1 V2 = MIN(V2,65535) HSVtoRGB Hue Sat V2 SetPen Result SolidPoly X1 Y1 X1+Depth Y1+Depth X1+Depth Y2-Depth X1 Y2 X1 Y1 LastPoint /* Bottom */ V2 = (Val-0.1*65535)%1 V2 = MAX(V2,0) HSVtoRGB Hue Sat V2 SetPen Result SolidPoly X2 Y2 X1 Y2 X1+Depth Y2-Depth X2-Depth Y2-Depth X2 Y2 LastPoint RestoreSetUp