USING AREXX IN FINAL COPY The use ARexx in Final Copy you must have ARexx installed on your computer and be familiar with the ARexx language. ARexx is considered a feature for "advanced" users. An ARexx macro program is usually created in a text editor, but can also be created in Final Copy and saved as an ASCII file. Each Final Copy document window has its own ARexx port. The name of this port always begins with "FinalC." and ends with a number indicating the order in which the window was opened. For example, the first window opened has an ARexx port name of "FinalC.1"; the second window opened has a port name of "FinalC.2". SENDING SCRIPTS TO ARexx You can create as many ARexx scripts as you want for Final Copy. Up to 10 ARexx scripts can be assigned to Final Copy's "Macros" menu. These scripts can be accessed by choosing the appropriate menu item or by pressing one of the F1-F10 function keys. The names for these scripts must begin with "AMacro-" and end with a number from 1 to 10 (AMacro-2). These scripts must exist in the same drawer that the Final Copy program is in. Another 10 ARexx scripts can be accessed by pressing the ALT key and one of the F1-F10 function keys. The names for these scripts must begin with "AMacro-" and end with a number from 11 to 20. These names will not appear in Final Copy's ARexx menu. These scripts must exist in the same drawer that the Final Copy program is in. An ARexx macro can be executed within Final Copy using the "Other" menu item in the "Macros" menu. When you choose the "Other" menu item, a file requester will appear which you use to locate the script to be executed. ARexx Other AM AMacro-1 F1 AMacro-2 F2 AMacro-3 F3 AMacro-4 F4 AMacro-5 F5 AMacro-6 F6 AMacro-7 F7 AMacro-8 F8 AMacro-9 F9 AMacro-10 F10 ARexx errors Final Copy returns one of the following numbers in the ARexx variable "TC" after each ARexx command it processes. 0 = No errors 5 = Warning 10 = Command failed 20 = Command has invalid arguments 100 = Unknown or invalid command 200 = Can't open fearexx.libary COMMANDS SYNTAX In the list below each command is lighted follwed by any parameters it requires, and a description of what the command does. Bracket characters "< and > " indicate required parameters. The vertical bar character "|" separates commands for documentation purposes only. Parenthesis characters "(" and ")" indicate optional parameters. MENU COMMANDS Most of Final Copy's macro commands duplicate an equivalent menu command. These commands let you execute Final Copy menu commands from within macro programs. "PROJECT" MENU COMMANDS New Create a new document window Open (filename) If "filename" is not given, present the "Open" requester. If "filename" is given, open that file. If "filename" is given, it must include a complete path name. Save (filename) Save document to disk. If document has not be saved before, display the file requester. SaveAS Present the file requester to get a name to copy the current document file to. Pring(final|draft|postscript|fsfile|prompt) If no argument is present, print a document in Final mode. Project New AN Open AO Save AS Save as AW Print AP Print Merge Page Setup Preferences > About > Quit AQ Page Set up Present the "Page Setup" requester. Preferences < display|ASC11|startup|speller|hyphenation|document|colours> Present the specified preference requester. Quit (force) Close the current window and quit the program, if this is the only document open. If there are changes to be saved, the program will ask if changes are to be saved. "EDIT" MENU COMMANDS Cut Copy the selected range of text to the Clipboard and then clear the selected range of text from the document. Copy Copy the selected range of text to the Clipboard. Paste Paste Clipboard text in the document at the insertion point. Clear Clear the selected range of text from the document. SelectAll Select all text in the part of the document (body, header, or footer) currently being edited. Insert Insert the specified item into the document. UpdateDate Update the date strings in the selected range of paragraphs. UpdateTime Update the time strings in the selected range of paragraphs. CopyRuler Copy the ruler settings of the paragraph the insertion point is in. PasteRuler Change the ruler settings of the paragraph the insertion point is in, or the selected paragraphs, to the ruler settings from the previous CopyRuler command. "PAGE" MENU COMMANDS View(25|50|75|100|125|150|200|400|normal) Change the view size. Insert Page Break Insert a forced page break at the insertion point. Remove Page Break Remove a forced page break from the current paragraph. Go To Page (page) Scroll the documents to the page specified by "Page". If "Page" is not specified, present the "Go To Page" requester. This does not change the location of the insertion point. Display the "Go To Page" requester. Find Cursor Scroll to the insertion point. "TEXT" MENU COMMANDS Font(fontname) Change the text font to the specified font. If "Fontname" is not specified, the "Open Font" requester is displayed. "Fontname" may contain an optional path. If there is no path, the font is looked for in the default font drawer. FontSize(size) Change the font size. If the "size " parameter is not specified, open the "Font Size" requester. Leading(size) Change the leading size. If the "size" parameter is not specified, open the "Leading Size" requester. Style Change the font style. Position Change text position. Width(value) Change text width. If the "width" parameter is not given, the "Text Width" requester is displayed.' Case Change the font case. FontColour (colourname) Change the font colour to "Colourname". "Colourname" is the name of a colour as shown in the "Text Colour" requester. If "Colourname" is not specified, display the "Text Colour" requester. Oblique (value) Change the "Text Oblique Percent" value. If "Value" is not specified, display the "Oblique Percent" requester. TypeSpecs Display the "Type Specs" requester. Paragraph Display the "Paragraph" requester. "GRAPHICS" MENU COMMANDS See "Insert" under the Edit menu commands Insert ILBM(position page left top width height) (LINKED) Insert an ILBM Graphic into the document using the current IFF ILBM settings. The graphic will become the current object. Filename is the complete path name of the graphic to be inserted. If POSITION is specified, then the next five parameters specify the size and position of the graphic. If POSITION and its associated parameters are not specified, then the program will determine the size and position. page is the page number of the page (starting with page 1) that the graphic is to be placed. left is left edge of graphic top is the top edge of graphic width is width of graphic height is height of graphic Left, Top, Width, and Height are specified in ruler measurements or micropoints (see the SetMeasure command). If -1 is specified for any of these settings, the program will determine a value to use. If LINKED is specified, a link to the graphic will be saved with the document. If it is not specified, the entire graphic data will be saved. Return in the ARexx variable "Result" the object ID of the new graphic. Example: InsertILBM 'Work:Pictures/Bunny' position 2 3 2'-1''-1 will insert the graphic "Bunny" on page 2, with its left edge at 3 inches, top edge at 2 inches. The program will determine the width and height to be used. Graphic (IFF|line|box|oval) Display the specified "Settings" requester. ObjectToBack (objectID) Send the graphic object with id "ObjectID" to the back of all other graphic objects. The object will become the current object. If "ObjectID" is not specified or is 0, then the current object will be sent to the back. ObjectToFront(objectID) Send the graphic object with id "ObjectID" to the front of all other graphic objects. The object will become the current object. If "ObjectID" is not specified or is 0, then the current object will be sent to the front. Lock - Lock the selected graphic objects in place so that they can not be moved or resized. DeleteObject(objectID) Delete the graphic objects specified by "ObjectID". If "ObjectID" is not specified or is 0, then all selected objects will be deleted. "EXTRA" MENU COMMANDS Find(text) Display the "Find " Requester. If the "Find" requester is already open, find the text specified in the "text" parameter. See also the "SetFind" command. FindNext Find the next occurrence of text. In order for this command to work, the "Find" requester must be open. SetFind(IgnoreCase|Same Case)(WrapAround|NoWrapAround) Sets the options for the "Find" requester. Two options may be specified on the line in any order. FindReplace Display the "Find/Replace" requester. Speller Display the "Speller" requester. Thesaurus Display the "Thesaurus" requester. Statistics Display the "Statistics" requester. Sort(lowtohigh|hightolow) Sort a selected range of paragraphs. "lowtohigh" will sort the paragraphs from low to high values. "hightolow" will sort the paragraphs from high to low values. If the sort type is not specified, "lowtohigh" is used. "Styles" menu commands StyleSheet Change the stylesheet of current paragraph or selected paragraphs. Define - Display the "Define Styles" requester. No Style - Set the style to "No Style". Stylename - Set the style to "Stylename". "Stylename", if used, must be the name of an existing style. EDITING COMMANDS Editing commands simulate editing a document from the keyboard. Final copy provides the following editing macros: Type Enter characters specified in "text" at the insertion point. Backspace Erase the character to the left of the insertion point, and move the insertion point and text to the right of the insertion point one character to the left. Delete Erase the character to the right of the insertion point. If a range of text is selected, delete the text in the range. NewParagraph Creates a new paragraph - same as pressing the RETURN key. EditBody Edit the document's body. EditLeftMaster Edit the document's Left Master page. EditRightMaster Edit the document's Right Master page. Cursor Move the insertion point in the specified direction. Additional action is determined by the status of the ALT, SHIFT and CTRL keys. See AltDown, AltUp, ShiftDown, ShiftUp, CtrlDown, and CtrlUp AltDown Used with the "Cursor" command. Sets the ALT key status to DOWN. AltUp Used with the "Cursor" command. Sets the ALT key status to UP. CtrlDown Used with the "Cursor" command. Sets the CTRL key status to DOWN. CtrlUp Used with the "Cursor" command. Sets the CTRL key status to UP ShiftDown Used with the "Cursor" command. Sets the SHIFT key status to DOWN. ShiftUp Used with the "Cursor" command. Sets the SHIFT key status to UP. RULER COMMANDS These commands set values normally set in the ruler and in the "Paragraph" requester. SetMeasure Set the units that ruler measurements will be given in and returned in. If "ruler" is specified, the units will be expected to be in, and will be returned in, the units that the "Ruler Measure" is set to in the "Display Preferences" (inches, metric, or pica). If "micropoints" is specified, then the units will be in micropoints (720 micropoints - 1 inch). The default measure is set to "ruler". Indent First line indent. LeftMargin Left margin RightMargin Right margin HotZone Hyphenation "Hot Zone". Hyphen (On|Off) Turn "On" or "Off" paragraph hyphenation. Justify Paragraph justification SetTab Set a tab stop at "position". Spacing Line spacing ShowRulers Show or hide rulers. PAGE SETUP COMMANDS These commands set values specified in Final Copy's "Page Setup" requester. Details on these settings can be found in Chapter 4. ColumnGap Distance between columns. Columns<#> Number of columns (1-6) CustomHeight Height of a custom page. CustomWidth Width of a custom page. PrintArea "Print Area" margins. EditArea "Print Area" margins. First Page <#> First page number (0-99999). FooterHeight Height of footer area. HeaderHeight Height of header area LeftRightPages(yes|no) "Left/Right" pages option - default is "yes". PageType Page type. Title Page (yes|no) Title page option - default is "yes". PRINT PREFERENCES COMMANDS These commands set values found in the Print requester and its Preference windows. PrintAll Indicate all pages are to be printed. PrintRange Indicate the range of pages to be printed PrintCopies Set the number of copies that are to be printed. PrintDensity Set the Graphic dithering value. PrintSettings (continuous)|singlesheet)gfxprinter|psprinter|psfile) (fronttoback | backtofront) (all | oddonly | evenonly) Set the document's "Print Settings". PrintShade Set the Print Threshold option Postscript (parallel | serial) (greyscale | colour) (tall | wide) Set the Postscript Preferences. PostScriptFile Set the filename to use when printing to a Postscript file. DRAWING COMMANDS These commands are used to draw graphic objects. In the commands that follow: "Page" is the page number of a page (1st page is page 1) on which the graphic is to be drawn. "Left" is the left edge of the graphic "Top" is the top edge of the graphic. "Width" is the width of the graphic "Height" is the height of the graphic. CurrentObject Ret;urn in the ARexx variable. "Result" the object id of the current graphic object. If there is no current object, "Result" is set to 0. Drawbox (BEVEL). Draw a box in the document using the current "Box Settings". The box will become the current object. BEVEL, if specified, indicates the box is to have rounded corners. DrawOval Drawn an oval in the document using the current "Oval Settings". The oval will become the current object. DrawLine (ARROW) Draw a line using the current "Line Settings". The line will become the current object. x1, y1, x2, and y2 specify the coordinates of the endpoints of the line. ARROW, if specified indicates the line is to have an ARROW drawn at the x2/y2 endpoint. GetObjectCoords (objectid) Return in the ARexx variable "Result" the coordinates for the graphic object specified by "objectid". If "objectid" is not specified or is 0, then the function will return the coordinates for the current object. The coordinates will be returned as a string in the format: "Page left top width height" - boxes, ovals and ILBMs. "Page x1 y1 x2 y2" - lines. SetObjectCoords,objectid page left top width height> Set the coordinates for the box, oval, or IFF ILBM object specified by "objectid". If "objectid" is specified as 0, the current object will be set. SetObjectCoords ,objectid page x1 y1 x 2 y2> Set the coordinates for the line object specified by "objectid". If "objectid" is specified as O, the current object will be set. GetObjectParams (objectid) Return in "Result" parameters for the graphic object specified by "objectid". If "objectid" is not specified or is 0, then the function will return the parameters for the current object. "objectid" will become the current object. Parameters are returned as a string in the format. "Textflow Flowdist Linked Transparent Lineweight LineColour Fillcolour". Values returned will be similar to those found in the graphic's settings requester (Chapter 8). In some instances the value will be a number the equates to a position of one of this requester's radio buttons within its group. SetObjectParams (objectid) Change the parameters of the object specified by "objectid". If "objectid" is 0, the current object is changed. The object specified by "objectid" will become the current object. GetObjectType Return in "Result" the type of object specified by "objectid". If "objectid" is not specified or O, the type of the current object will be returned. Possible return values are 1 for IFF ILBMs 2 for Lines 3 for Arrow-tipped lines 4 for Boxes 5 for Bevelled boxes 6 for Ovals SelecObject (objectid)(multiple) Select the object and make it the current object. If "objectid" is not specified, or is 0, then all objects will be deslected. If "Multiple" is specified, then the object will be selected in addition to others that are already selected. FirstObject Return in "Result" the object id of the first graphic object in Final Copy's list of objects. If there are no graphic objects, "Result" will be 0. NextObject Return in "Result" the object id of the graphic object following the object specified by "objectid". If "objectid" is 0, then the object id of the object following the current object is returned. If there are no graphic objects after the specified object, then the result is set 0. Redraw Reformat tne redraw the screen. This should be called after all graphic objects have been drawn and/or moved to update the screen display. MISCELLANEOUS COMMANDS Most of the following commands do not duplicate any of Final Copy's normal features. Their purpose is to provide flexibility to using ARexx with Final Copy. ClearDoc (force) Clear the current document from the window. If "force" is supplied as a parameter, and there are changes to the document that have not been saved, the program will ask if you want to save them. See NOTE. under Close below. Close (force) Close the current document. If "force" is supplied as a parameter, and there are changes to the document that have not been saved, the program will ask if you want to save them. NOTE. If there are any changes to the document that have not been saved, the program will ask if you want them saved. If "force" is specified, the program will close/clear the document regardless of any unsaved changes, and will not ask if changes are to be saved. Extract Return in the ARexx variable "Result" the text in a selected range. Text in a range is only returned through the end of a paragraph. For this to work the "Options Results" statement must be present. Status