NOTE! NOTE! NOTE! Users of MachIV should note these changes: 1. Unless specified on the command line or in the Tool Types, MachV will try to read an ENVARC:MachV/MachV.prefs preference file. If that is not found, it will try ENVARC:MachIV/MachIV.prefs. 2. Note the functions that have been renamed below. You will have to rename these in your macros. 3. Also note the functions that have been removed and delete these from your macros. 4 You will need to change all win_activate"" functions to win_activate"M". 5. If you are upgrading from MachIV, all changes are listed here. These changes have also been made to the MachV.guide file. 6. AllTitles and AllTasks have been removed from the disk. They have been replaced by "Select Title" in SetMachV. See SetMachV #14 below. ========================================================================= MachV and SetMachV - Version 5.0 MachV now has (and requires) the library mach.library. With this library and the included header files, programmers can now access many of MachV's features and settings. SetMachV itself uses just this library to completely control MachV. See programmers docs for more details. ========================================================================= Functions Removed ----------------- Several macro functions have been removed. If you have any of these in your configuration, you should delete them. All Graphics functions - MachV is not pretending to be a graphics utility. With the increased number of graphic modes available, it is better to use a separate utility program. Msc_Patch_Newlook - This is replaced by the program ScreenDebut included on the disk. Set_Key - This was used mainly to set the middle mouse button to the shift key. Do this in the 'Miscellaneous Features' window. Set_SetMachV_Path - The path and name for SetMachV is now a command line or icon ToolType option. Set_Month_Names and - These are available through the appropriate Set_Day_Names language catalogs or machv.txt file. ========================================================================= Functions Renamed ----------------- The following functions have been renamed: Before Now ------ --- Clk_Meter_Reset Clk_Reset_Meter Scr_Kill Scr_Kill_Screen Scr_Select Scr_Select_Screen Win_Change Win_Change_Window Win_Kill Win_Kill_Window Win_Layer Win_Layer_Windows Win_Move Win_Move_Window Win_Select Win_Select_Window Win_Size Win_Size_Window Since the prefixes are not needed, this makes some functions clearer and unambiguous. e.g. 'Win_Kill' and 'Scr_Kill' are ambiguous as just 'Kill'. Kill_Window and Kill_Screen is clearer. Note that not all ambiguities have been removed. The following must include their prefixes: Clk_To_Front Win_To_Front Scr_To_Front Win_Back_To_Front Scr_Back_To_Front Win_Front_To_Back Scr_Front_To_Back See below for On_Off functions that have been renamed. ========================================================================= Function Changes ---------------- All window functions operate on the window as selected in this manner: Top window - win_function For compatibility with 4.2 win_function"T" win_function"T,arg2,arg3,..." Active window - win_function"" For compatibility with 4.2 win_function"A" win_function"A,arg2,arg3,..." win_function",arg2,arg3,..." For compatibility with 4.2 Under mouse window - win_function"M" win_function"M,arg2,arg3,..." Titled window - win_function"title" win_function"title,arg2,arg3,..." While window functions select the window the same way as in previous versions (except win_activate), you should use 'T', 'A' and 'M' for top, active and (under) mouse. There is only the remote possiblity of a conflict if you must specify a window whose title is one of these single characters. In these cases you could use: win_function"(A)" win_function"(M)" win_function"(T)" Note: You will need to change any win_activate"" functions to win_activate"M" If there is no window under the mouse, the top window will become active. On Off Functions ---------------- All on/off functions have been changed to be a little less tedious to type and to be clearer. The argument can now be 'On' or 'Off' as well as '1' or '0'. 'Tog' will toggle the feature as will no argument. Before Now ------ --- Clk_On_Off"1" Clk_Clock"On" Mac_On_Off"0" Mac_Macros"Off" Mou_Sun_On_Off"" Mac_SunMouse"Tog" Mou_To_Menu_On_Off"1" Mou_To_Menu"On" Mou_FreezeVert_On_Off"0" Mou_FreezeVert"Off" Mou_FreezeHorz_On_Off Mou_FreezeHorz"Tog" Msc_HoldQuals_On_Off"1" Msc_HoldQuals"On" Msc_Speak_On_Off"0" Msc_Speak"Off" Msc_Keys_On_Off"" Msc_FreezeKeys"Tog" Msc_Debug_On_Off"1" Msc_Debug"On" Because no argument is the same as 'Tog', and because prefixes are not always required, and because keywords are case insensitive, 'Clk_Clock"Tog"' is equivalent to 'clock'. Macro Names ----------- The following functions previously accepted only a macro name. They now can accept wildcards. Mac_Execute_Named"name" Mac_Delete"name" Msc_Set_Flags"xx,name" Example: Mac_Execute_Named"test#?" beep"5" This will queue up all macros that have a name beginning with 'test'. When the queued macros have executed, this macro will continue at the 'beep"5"'. This has the potential to be quite dangerous - USE WITH CAUTION! Msc_Set_Flags has been changed slightly. Previously it actually toggled the desired flag. Now it sets it unless a third argument of '0' is supplied. Example: Msc_Set_Flags"40,#?,0" This clears the 'Disabled' flag in all macros. Msc_Set_Flags"80,#?" This sets the 'Write Protected' flag in all macros. Msc_Beep -------- Beep and Key Click each have a volume setting in 'Miscellaneous Features'. The Beep volume can be over-ridden by a second argument to Msc_Beep. Msc_Beep"1,64" one beep, full volume. Msc_Beep"2,32" two beeps, half volume. Msc_Beep",64" one beep, full volume. Mac_Macros and Msc_Suspend -------------------------- When either of these functions are executed and disable macros or suspend MachV, the SAME hotkey must be used to re-enable. ========================================================================= New Functions ------------- Msc_Meter Msc_PutMsg_ARexx Msc_Send_Upkeys Msc_Status Msc_Trace Set_Variable Win_Wait_Window Win_Window_Open Msc_Meter --------- Turn the meter on or off. The meter can now be used to measure time if the rate is set to 0. You may have the meter on in different configurations and keep track of how much time you spend in each configuration or program. Time is not counted when the screen is blanked, but online costs are. Msc_Meter"On" Msc_Meter"Off" Msc_Meter"Tog" Msc_PutMsg_ARexx ---------------- Send a command directly to an ARexx port. With this function, you can avoid using 'run rx command'. This function is synchronous! It will not return until replied to by the receiving process. Msc_PutMsg_ARexx"PORTNAME,command" Examples: Msc_PutMsg_ARexx"TURBOTEXT0,openfile ${ttxfile}" Msc_PutMsg_ARexx"EMACS1,(fill-paragraph nil)" Msc_PutMsg_ARexx"rexx_ced,cedtofront" Note new 3rd argument documented in fixes.doc. Briefly, if supplied, the message to the ARexx port will request a result and use that argument as the name of an environment variable to store it. Msc_Send_Upkeys --------------- Set, clear or toggle the 'Send Up Keys' flag. When set, an up key message is sent for each key down that is sent from a macro. This doubles the time required to send keystrokes, but some programs expect to receive key up messages. Msc_Send_Upkeys"On" Msc_Send_Upkeys"Off" Msc_Send_Upkeys"Tog" Msc_Status (from ARexx only) ---------- Check the condition of various flags with: Msc_Status"N" "N" may be one of the following: sunmouse 0 splines 14 keyactivate 1 quick blank 15 mouse to menu 2 speak messages 16 menu wrap 3 debug 17 window cycle 4 button swap 18 auto poptop 5 hold quals 19 keyclick 6 hotkeys enabled 20 clock 7 send up keys 21 vertical clock 8 nocapslock 22 clock top window 9 remove lf 23 clock float 10 crlf 24 clock gadgets 11 freeze vert 25 seconds 12 freeze horz 26 meter 13 keysoff 26 Msc_Status returns a '1' in the ARexx variable RESULT if the flag is set. Example: address 'MACHV' 'status"17"' if RESULT = 1 then say 'debugging is on' else say 'debugging is off' Msc_Trace --------- As a debugging aid, you can have each macro dumped as it executes to a console window or serial port. This is not to be confused with 'Debug' which runs SetMachV when an error is detected. Select 'Trace Serial' and 'Trace Console' in the 'Miscellaneous Features' window, or set it with the Msc_Trace function. Msc_Trace"Tog,S" Toggle serial tracing. Msc_Trace"Tog,C" Toggle console tracing. Msc_Trace"off,S" Serial tracing off. Msc_Trace"off,C" Console tracing off. Msc_Trace"on,S" Serial tracing on. Msc_Trace"on,C" Console tracing on. As each function is executed, the remaining portion of the macro will be sent. If you executed the macro 'win_back_to_front win_activate"T"', you will see: win_back_to_front win_activate"T" win_activate"T" Console Tracing A window will be opened for output. This window will close when a Msc_Trace function turns off tracing. Pressing Ctrl-C will remove MachV. Serial Tracing Output will be sent to the serial device at whatever rate you have selected by 'Prefs/Serial' or your terminal program. You can run a terminal program to receive this output. Set_Variable ------------ Environment variables may be set with this function: Set_Variable"test,abcd" Set the variable 'test' to 'abcd' Set_Variable"test," Deletes the variable 'test' See below for more information. Win_Wait_Window --------------- A macro can wait for a window to become active before continuing. This is better than using a pause function which may wait too long or little. MachV continues to function normally while waiting, but you should not call another wait function before it returns. The title can be an AmigaDos pattern if desired. Example: win_send_menu"A,Quit" wait_window"AppTitle#?" "O" This sends a menu selection of 'Quit' to the active window, waits for a window titled 'AppTitle...' to become active, then sends the letter 'O' (which may simulate clicking on an 'Okay' gadget). When wait_window returns, it still may not be safe to do a function like send_menu - the menu strip or user port may not be set yet. These cases are especially likely if other tasks are also running. You may follow the window title with a 'U' or 'M' or both. When the desired window becomes active, MachV will wait until the menu or port is set, or upto 2 seconds. The order of 'U' or 'M' does not matter. wait_window"$terminus1,U,M" The maximum waiting period may also be changed (1 - 9 seconds): wait_window"$Workbench,M,U,4" or wait_window"$Workbench,M,,5" A program may still change a menu strip or user port after wait_window returned but before you could send a message. A pause may be necessary: wait_window"Serial,U" pau_seconds".5" "bbo" This will wait for the window 'Serial' to become active, then the user port to be set, then it will pause for .5 seconds, then send the keystrokes 'bbo'. You can match an untitled window by using two vertical bars in the title. e.g. wait_window"||" Abort a wait_window function by pressing ESC. Note that this returns when the desired window becomes active or immediately if it is already active. Win_Window_Open --------------- Test to see if a window is open: Win_Window_Open"title" This returns a '1' in the ARexx variable RESULT if the window is open. ========================================================================= Comments -------- Comments may be placed between functions by enclosing them within /* */. Mou_XY"340,110" /* move to next gadget */ Mou_lbd Mou_lbu ========================================================================= ARexx ----- Macros sent to MachV from ARexx programs may now be executed synchronously or asynchronously. An asynchronous macro will return before it has actually begun execution. To do this, simply prefix the macro with a "0". Examples: address 'MachV' 'clk_clock"off"' synchronous address 'MachV' '0 clk_clock"off"' asynchronous When this is executed from the shell, the prompt will return immediately: address 'MachV' '0 pau_seconds"3" clk_clock"off"' As many macros as you wish may be sent to MachV. They will be executed in turn. ========================================================================= Macro Toggling -------------- The vertical bar "|" used to separate a macro in half now can separate into more sections. Each section will be executed in turn. For example, when this macro is executed the first time, win_send_menu"A,Icon" | win_send_menu"A,Name" | win_send_menu"A,Date" | win_send_menu"A,Size" the menu selection with the text "Icon" will be sent to the active window. The next time, the "Name" selection will be sent, and so on. This macro can be useful - it alternately sends ctrl-s and ctrl-q which can start and stop output to the shell or in a term program. "\Cs" | "\Cq" ========================================================================= Auto Execution -------------- There is an "Auto Execute" flag in the "Flags" window. This gets set when you enter an Exe_Auto macro or you may set it yourself. A macro need not have Exe_Auto if this flag is set, but it does need the time. "03:30" exe_cmd"run updatedb sys: dh0: dh1:" This will execute at 3:30am if the "Auto Execute" flag is set. The flag must be set or the macro will not execute, even if exe_auto is included. If you have other configurations, be sure that you also set the 'Global' flag. ========================================================================= No Execute Message ------------------ If this flag is set, the message "Executing Macro" will not be displayed in the clock when that particular macro is being executed. ========================================================================= Text Pasting ------------ The 'Char Burst' option has been eliminated. In its place, you may choose to not have up keys sent. Up keys are not normally required but programs have the right to expect that when it receives a key pressed, it will also receive a key up. In 'Clip Features', you may select 'Send Up Keys'. You may also set, clear or toggle this with the macro function Msc_Send_Upkeys. ========================================================================= Clip Viewer ----------- When the clipboard viewer is open and Clp_View is run a second time, the viewer will close and reopen on the front screen. Previously, it would bring the screen it was on to the front. ========================================================================= Variables --------- Environment variables can now be used as function arguments or output as text. These can be set with the PAU_FIX_INPUT and PAU_VAR_INPUT functions, the SET_VARIABLE"name,value,optional flags" function, or, if using global variables, from the shell using "setenv name value". A special variable "MachVar" is set when an icon is dropped into the clock. The variable will be set to the fully qualified name of the icon. This variable is local to MachV. Environment variables can be either global - accessible from anywhere, or local - accessible only from MachV. The variable format is ${varname}. This will expand to the value of varname when the function executes. For example, if "window" was set to "Workbench", this would bring it to the front: Win_To_Front"${window}" Possible uses: -------------- Pau_Fix_Input"1,clipunit" Clp_Paste"${clipunit}" This pauses for you to enter one number. That number is then set to the variable "clipunit" which is then used as an argument for Clp_Paste. Using this as a macro, you can paste from clipboard units 0 - 9. pau_var_input",file" exe_cmd"${editor} ${file}" This pauses for a variable number of keystrokes which are stored in the variable "file" when you press ESC. The program whose name is stored in "editor" is then run using the file name as an argument. Note the ',' in ",file". The first argument (abort key) is optional, it defaults to ESC (hex 45). This could have been written: pau_var_input"45,file" During a pau_var_input or pau_fix_input function, characters are displayed in the clock as they are entered. Ctrl-H may be used to correct mistakes. Note that the variable name is used without the ${} when using it as an argument in a setting type function. If ${} were used, then the value of the variable would be used instead. Global and Local ---------------- In the 'Miscellaneous Features' window you may set certain parameters used by MachV when handling variables. If "Local/Global Vars" is selected then expanding a variable will first try a local variable and then a global variable. You could instead select either "Global Only Vars" or "Local Only Vars". Both Pau_Fix_Input and Pau_Var_Input functions and the Set_Variable can accept a third argument which is the hexidecimal representation of these flags. The values for these flags are: Local then global - 0 Global Only - 100 Local Only - 200 Save Var - 1000 Set_Variable"test,abcd,1100" This would set global variable "test" to "abcd" and also save it to ENVARC:. Only global variables may be saved. Pau_Var_Input"45,test,100" Waits for variable length input terminated with ESC (45) and then sets the global variable 'test' to that input. Also in the 'Miscellaneous Window', you may select "Save Vars". This will cause all global variables to be saved to ENVARC: when a Pau_ or Set_Variable function is used. From within text in a macro: "This is the contents of var is ${var}" "This is the username environment var ${username}" To use ${} without expanding it, you must escape the $ with a \. "This is the variable \${var}" Using variables lets you change a setting in just one place. For example, in your user-startup file you could set an overscan width variable: SetEnv OverScanW 680 And then use it in your NewShell command: exe_cmd"NewShell con:0/0/${OverScanW}/200/Shell" Or, SetEnv shell NewWShell exe_cmd"${Shell} con:0/0/${OverScanW}/200/${Shell}/CLOSE" Or for AUSH, SetEnv shell "NewAUSH WINDOW" exe_cmd"${Shell} con:0/0/${OverScanW}/200/Shell/CLOSE" ========================================================================= Clocks ------ The method used to select the screen that the clock can go on has been changed. Previously you would select one of "Workbnch", "Any Screen" or "Top Screen". Now you can enter an AmigaDos wild card pattern into a string gadget. This tells MachV what screens the clock can or can't go to. For example, #? will allow the clock to move to any screen. ~(Final Copy#?) will let the clock move to any screen except one titled "Final Copy...". You may specify a screen with no title by using two vertical bars ||. (#?||) will match any screen with or without a title. If there is no screen title, you may also match by the name of the program that owns a window on the screen. Preface the title with $. Example: $dh0:paint/dpaint The $ cannot be used inside patterns. It must be the first character in the string. Seconds ------- You select "Sec." in "Clock Features" to display seconds in the time. Gadgets ------- If you have more than one configuration, macros in the first configuration that are marked as 'Clock Gadget' and 'Global', and are not attached to a hotkey (they are 'NO KEY') will display the gadget in other configuration clocks. When an unkeyed macro is deleted, if there are gadgets in the clock the clock gadgets IDs will be updated. AppWindow --------- The clock is now (finally!) an AppWindow if opened on the Workbench. Icons dropped into this window will set the local environment variable "MachVar" to the fully qualified name of the icon. If multiple icons are dropped, the variable will contain all names separated by a space. e.g. dh0:src/app/main.c ram:readme This may be very useful when used with a macro (which may have a gadget) such as: Exe_Cmd"view80 ${MachVar}" You may want to delete this variable afterwards: Exe_Cmd"view80 ${MachVar}" Set_Variable"MachVar," Borders ------- In "Clock Features", you may select "Right Border", "Bottom Border" or "Borderless". These affect only clocks that have gadgets. Right Border - The size gadget uses the right border. Bottom Border - The size gadget uses the bottom border. Borderless - The clock has no border. ========================================================================= QEdit ----- 1. QEdit displays for null macros. 2. Auto executing macros do not get displayed in QEdit. 3. ARexx macros will not be kept in your configuration if you press while it is in the QEdit gadget. Previously you had the delete the macro before pressing . 4. When the QEdit window opens, it will display the last macro edited. ========================================================================= Mouse ----- You can set the middle mouse button to any qualifier or combination of qualifiers in the 'Miscellaneous Features' window. Simply select the desired check boxes. This replaces the function 'Set_Key' which has been removed. Note that you can still set the middle button to any other key by creating a macro for it. SunMouse, Click To Front, Window Cycle etc. ------------------------------------------- Most mouse options now also have a string gadget which lets you choose what windows to allow that particular option to operate on. A rather useful one is to set the SunMouse string to '~(MachV#?)'. This will prevent the SunMouse from activating the clock window. Using '$Workbench' will allow the option to operate only on windows owned by Workbench. ========================================================================= SetMachV 1. SetMachV uses a list requester when you want to select configurations. This is easier to use as it adjusts its height to the number of configurations. 2. Functions in the "Help" window are in lower case unless you hold while pressing or clicking on "Help". 3. Press to cycle backwards through the help. 4. SetMachV displays for null macros. 5. 'Print Macros' now is an external program that is run when you click on the gadget. This can also be run from the shell. SetMachV will look for it in the same directory as SetMachV is in. See the code PrintMacros.c for more details. 6. The volume for 'Key Click' and 'Beep' can be set in the 'Miscellaneous Features' window. Valid values range from 0-64. 7. The input handler priority can be set in the 'Miscellaneous Features' window. Valid priorities are 51 - 127. 55 is recommended, but if you have other programs with their own input handler, you may want to change this. Changes will not take effect until you save and run MachV again. Note that this is NOT the same thing as task priority. This is the priority of the handler that intercepts input before intuition has a chance to see it. It must be set above intuition which is 50. 8. Most buttons and check boxes have keyboard equivalents. Because of this, pressing of say, 'M' will open the 'Mouse Features' window, but pressing it again will not close it like in previous versions. 9. In order to avoid confusion, configurations will not change automatically when SetMachV is open and running. 10. New gadget added in 'Clock Features' to change clock borders. See above. 11. MachV will look first for SetMachV then it will try SetMachV.020. 12. Function name completion is now provided. When entering a function in the macro string gadget, pressing will complete the entry for you. If what you have entered is ambiguous, a window with possible completions is opened. You may then select the desired function by pressing the associated letter. You may also press or click on the close gadget to close the window. Text entered will be in the same case as you entered. If you typed: win_to_f win_to_front will be entered. If you entered: Msc_D Msc_Debug will be entered. If you entered: MSC_B MSC_BLANK_SCREEN will be entered. Functions that do not require the 3 letter prefix may also be completed using this method. z expands to: zoom_window 13. "Copy" now copies the flags as well as the macro and name. 14. SetMachV has a new gadget, "Select Title" in the configurations section (upper right corner). Clicking on it will bring up a list box with all available window titles, screen titles and program names. Selecting one of these will insert it into the configuration title string gadget. This replaces the programs AllTitles and AllTasks. =========================================================================