home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / htmle96b.zip / HM-PROG.INF (.txt) < prev    next >
OS/2 Help File  |  1996-07-22  |  38KB  |  1,688 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. HTML-Ed REXX Functions ΓòÉΓòÉΓòÉ
  3.  
  4. The following functions are available for use in your REXX Macros: 
  5.  
  6.       hmChangeFilename 
  7.       hmCharFromLine 
  8.       hmCharsToTags 
  9.       hmClear 
  10.       hmCloseFile 
  11.       hmConvertSlashes 
  12.       hmCopy 
  13.       hmCurrentFile 
  14.       hmCut 
  15.       hmDelete 
  16.       hmDeselectAll 
  17.       hmDisableRefresh 
  18.       hmEnableRefresh 
  19.       hmExit 
  20.       hmFind 
  21.       hmGoToLine 
  22.       hmInsert 
  23.       hmInsertFile 
  24.       hmLineFromChar 
  25.       hmNew 
  26.       hmOpen 
  27.       hmOpenOutputWindow 
  28.       hmPaste 
  29.       hmQueryChanged 
  30.       hmQueryFilename 
  31.       hmQueryLineCount 
  32.       hmQueryLineLength 
  33.       hmQuerySel 
  34.       hmQuerySelText 
  35.       hmQueryTextLength 
  36.       hmQueryWrap 
  37.       hmRemoveTags 
  38.       hmResetUndo 
  39.       hmRingLeft 
  40.       hmRingFiles 
  41.       hmRingRight 
  42.       hmSaveAll 
  43.       hmSaveAs 
  44.       hmSaveASCII 
  45.       hmSaveCurrent 
  46.       hmSaveOptions 
  47.       hmSay 
  48.       hmSelectAll 
  49.       hmSetChanged 
  50.       hmSetSel 
  51.       hmSetWrap 
  52.       hmStatusSay 
  53.       hmSwitchTo 
  54.       hmTagsCase 
  55.       hmUndo 
  56.       hmVersion 
  57.       hmWrapAround 
  58.  
  59.  
  60. ΓòÉΓòÉΓòÉ <hidden> Introduction ΓòÉΓòÉΓòÉ
  61.  
  62. Welcome to the HTML-Ed Programmer's Reference! 
  63.  
  64. HTML-Ed extends the REXX language with 52 new functions.  These functions are 
  65. explained in this reference manual. 
  66.  
  67. If this is the first time you have used the .HM Macro functions, please read 
  68. over this entire document before proceeding.  Many of the functions have 
  69. important remarks that you should be aware of before using them. 
  70.  
  71. Things to remember: 
  72.  
  73.      Name your HTML-Ed macros with an .HM extension.  This is not strictly 
  74.       necessary, but it will help you to tell apart normal REXX .CMD files and 
  75.       REXX macros that use the HTML-Ed extended functions. 
  76.  
  77.      The .HM macro functions are very powerful - but power comes at a price. 
  78.       The functions are not crash proof and you can crash HTML-Ed if you are 
  79.       not careful.  Always check the return codes a function returns (unless 
  80.       there is only one possible return code) and take appropriate action.  For 
  81.       functions that require parameters, make sure you are passing it a correct 
  82.       value. 
  83.  
  84.      Take special care that you do not enter an infinite loop.  HTML-Ed will 
  85.       not be able to recover from a stuck macro. 
  86.  
  87.      Your macro runs on HTML-Ed's main thread!  (This will change in the 
  88.       future).  Therefore, while your macro is running you will not be able to 
  89.       interact with any windows (the message queue will be "hung").  If your 
  90.       macro is taking a long time to complete, or if it gets stuck in an 
  91.       infinite loop, pressing Ctrl+ESC a few times should bring up a dialog 
  92.       that will allow you to kill HTML-Ed (alternatively, you could use a 
  93.       process killer such as Watchcat to kill HTML-Ed).  It is a good idea to 
  94.       make sure your macros are short. 
  95.  
  96.      An insertion point is just a number.  "0" is the insertion point before 
  97.       the first character in the editor.  Take special care to ensure that any 
  98.       insertion points you are using are valid - any time you insert or remove 
  99.       any text the insertion points after the changed portion will be invalid. 
  100.       Take extreme care when writing looping search/replace macros as it is 
  101.       very easy to become stuck in an infinite loop. 
  102.  
  103.      Use hmSay instead of Say.  If more than 32kb of text is written to stdout 
  104.       HTML-Ed will appear to crash (in reality, HTML-Ed is waiting for the 
  105.       macro to finish and the macro is waiting for the unnamed pipe to be 
  106.       cleared - so nothing happens).  This will be addressed in a future 
  107.       version. 
  108.  
  109.  If you have problems: 
  110.  
  111.       Nothing appears to be happening! 
  112.  
  113.                          .HM macros simply stop execution when there is an 
  114.                           error.  When an error occurs, anything written to 
  115.                           stdout does not get copied to the output window (use 
  116.                           hmSay to overcome this problem).  If you have a 
  117.                           syntax error in your program and you have been using 
  118.                           say instead of hmSay it may appear as if nothing has 
  119.                           happened. 
  120.  
  121.                          You can use hmSay to help track down the problem. 
  122.  
  123.       One of the functions doesn't work as it should! 
  124.  
  125.                          First, make sure you read (and re-read) all the 
  126.                           appropriate information in this manual.  If the 
  127.                           problem persists, contact me. 
  128.  
  129.  Contacting the author: 
  130.  
  131.      HTML-Ed's author, Ian Prest, may be contacted in the following ways: 
  132.  
  133.       email:         ianprest@connect.reach.net (put "HTML-Ed" somewhere on the 
  134.                      subject line) 
  135.  
  136.       snail mail: 
  137.  
  138.                                           Ian Prest
  139.                                           R.R.#1
  140.                                           Shannonville, Ontario
  141.                                           K0K 3A0
  142.                                           re: HTML-Ed
  143.  
  144.      Visit the HTML-Ed Home Page on the internet! 
  145.       http://www.wp.com/ianprest/htmled.html 
  146.  
  147.  
  148. ΓòÉΓòÉΓòÉ 1.1. hmChangeFilename ΓòÉΓòÉΓòÉ
  149.  
  150.  Function:  hmChangeFilename 
  151.  
  152.  Purpose:   to change the filename of the current editor 
  153.  
  154.  Syntax:    rc = hmChangeFilename(file) 
  155.  
  156.            file           the new filename 
  157.  
  158.  Returns:  0 
  159.  
  160.  Remarks: 
  161.  
  162.            hmChangeFilename changes the name of the current file, but does not 
  163.            save anything with the new filename, and does not alter the file's 
  164.            "changed" flag. 
  165.  
  166.            hmChangeFilename is usually used after a call to hmSaveAs. 
  167.  
  168.  Example: 
  169.  
  170.  
  171.                       /* Save the file with a new filename */
  172.                       call hmSaveAs "newfile.htm"
  173.  
  174.                       /* Update the titlebar's filename to reflect the change */
  175.                       call hmChangeFilename "newfile.htm"
  176.  
  177.  
  178. ΓòÉΓòÉΓòÉ 1.2. hmCharFromLine ΓòÉΓòÉΓòÉ
  179.  
  180.  Function:  hmCharFromLine 
  181.  
  182.  Purpose:   to find the insertion point of the first character of a line 
  183.  
  184.  Syntax:    ipt = hmCharFromLine(line) 
  185.  
  186.            line           line number of interest 
  187.  
  188.  Returns:  insertion point of the first character of line 'line' 
  189.  
  190.  Remarks: 
  191.  
  192.            Use hmCharFromLine to determine where a line starts. 
  193.  
  194.  Example: 
  195.  
  196.  
  197.                       /* example to "home" the cursor */
  198.  
  199.                       /* get cursor position */
  200.                       ipt = hmQuerySel("cursor")
  201.  
  202.                       /* get current line */
  203.                       line = hmLineFromChar(ipt)
  204.  
  205.                       /* find start of current line */
  206.                       ipt = hmCharFromLine(line)
  207.  
  208.                       /* set cursor position */
  209.                       call hmSetSel ipt,ipt
  210.  
  211.  
  212. ΓòÉΓòÉΓòÉ 1.3. hmCharsToTags ΓòÉΓòÉΓòÉ
  213.  
  214.  Function:  hmCharsToTags 
  215.  
  216.  Purpose:   to convert characters to HTML character identities 
  217.  
  218.  Syntax:    rc = hmCharsToTags() 
  219.  
  220.  Returns: 
  221.  
  222.            0              No error 
  223.            1              No text was selected 
  224.  
  225.  Remarks: 
  226.  
  227.            hmCharsToTags works exactly as the "Convert characters to tags" menu 
  228.            function does, converting all the characters in the selected text to 
  229.            their HTML equivilants. 
  230.  
  231.  Example: 
  232.  
  233.  
  234.                       /* Convert all special characters to tags */
  235.                       call hmCharsToTags
  236.  
  237.  
  238. ΓòÉΓòÉΓòÉ 1.4. hmClear ΓòÉΓòÉΓòÉ
  239.  
  240.  Function:  hmClear 
  241.  
  242.  Purpose:   to delete the current selection 
  243.  
  244.  Syntax:    rc = hmClear() 
  245.  
  246.  Returns:  0 
  247.  
  248.  Remarks: 
  249.  
  250.  Example: 
  251.  
  252.  
  253.                       /* delete the current selection */
  254.                       call hmClear
  255.  
  256.  
  257. ΓòÉΓòÉΓòÉ 1.5. hmCloseFile ΓòÉΓòÉΓòÉ
  258.  
  259.  Function:  hmCloseFile 
  260.  
  261.  Purpose:   to close the current file 
  262.  
  263.  Syntax:    rc = hmCloseFile() 
  264.  
  265.  Returns: 
  266.  
  267.            0              No error 
  268.            1              Last file closed - HTML-Ed will now exit 
  269.  
  270.  Remarks: 
  271.  
  272.            The user is not prompted to save the current file (if it has not 
  273.            been saved) before it is closed.  It is up to the macro to ensure 
  274.            the file is saved if necessary. 
  275.  
  276.            If this function returns "1" then your macro should exit as soon as 
  277.            possible becuase HTML-Ed is trying to exit.  Any furthur actions 
  278.            performed on any (non-existant) files will probably crash HTML-Ed. 
  279.  
  280.  Example: 
  281.  
  282.  
  283.                       /* Close the current file */
  284.                       rc = hmCloseFile()
  285.  
  286.                       /* Exit macro if necessary */
  287.                       if rc=1 then exit
  288.  
  289.  
  290. ΓòÉΓòÉΓòÉ 1.6. hmConvertSlashes ΓòÉΓòÉΓòÉ
  291.  
  292.  Function:  hmConvertSlashes 
  293.  
  294.  Purpose:   to convert backslashes to forward slashes 
  295.  
  296.  Syntax:    rc = hmConvertSlashes() 
  297.  
  298.  Returns: 
  299.  
  300.            0              No error 
  301.            1              No text was selected 
  302.  
  303.  Remarks: 
  304.  
  305.            hmConvertSlashes works exactly as the "Convert \ to /" menu function 
  306.            does, converting all the backslashes in the selected text. 
  307.  
  308.  Example: 
  309.  
  310.  
  311.                       /* Convert all backslashes to forward slashes */
  312.                       call hmConvertSlashes
  313.  
  314.  
  315. ΓòÉΓòÉΓòÉ 1.7. hmCopy ΓòÉΓòÉΓòÉ
  316.  
  317.  Function:  hmCopy 
  318.  
  319.  Purpose:   to copy the current selection to the clipboard 
  320.  
  321.  Syntax:    rc = hmCopy() 
  322.  
  323.  Returns:  0 
  324.  
  325.  Remarks: 
  326.  
  327.  Example: 
  328.  
  329.  
  330.                       /* copy the current selection to the clipboard */
  331.                       call hmCopy
  332.  
  333.  
  334. ΓòÉΓòÉΓòÉ 1.8. hmCurrentFile ΓòÉΓòÉΓòÉ
  335.  
  336.  Function:  hmCurrentFile 
  337.  
  338.  Purpose:   to return the name of the current file 
  339.  
  340.  Syntax:    title = hmCurrentFile() 
  341.  
  342.  Returns:   window title of the current file 
  343.  
  344.  Remarks: 
  345.  
  346.            The title returned can be used to switch back to this file later. 
  347.  
  348.            If you desire the actual filename of the current file, follow this 
  349.            call with a call to hmQueryFilename. 
  350.  
  351.  Example: 
  352.  
  353.  
  354.                       /* Get current window title */
  355.                       file = hmCurrentFile()
  356.  
  357.                       /* Display it */
  358.                       call hmSay file
  359.  
  360.  
  361. ΓòÉΓòÉΓòÉ 1.9. hmCut ΓòÉΓòÉΓòÉ
  362.  
  363.  Function:  hmCut 
  364.  
  365.  Purpose:   to cut the current selection to the clipboard 
  366.  
  367.  Syntax:    rc = hmCut() 
  368.  
  369.  Returns:  0 
  370.  
  371.  Remarks: 
  372.  
  373.  Example: 
  374.  
  375.  
  376.                       /* cut the current selection */
  377.                       call hmCut
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 1.10. hmDelete ΓòÉΓòÉΓòÉ
  381.  
  382.  Function:  hmDelete 
  383.  
  384.  Purpose:   to delete text from a specified location 
  385.  
  386.  Syntax:    rc = hmDeselectAll(start,length) 
  387.  
  388.            start          insertion point to start deleting at 
  389.  
  390.            length         number of characters to delete 
  391.  
  392.  Returns:  number of characters deleted 
  393.  
  394.  Remarks: 
  395.  
  396.  Example: 
  397.  
  398.  
  399.                       /* Delete the first 15 characters */
  400.                       call hmDelete 0, 15
  401.  
  402.  
  403. ΓòÉΓòÉΓòÉ 1.11. hmDeselectAll ΓòÉΓòÉΓòÉ
  404.  
  405.  Function:  hmDeselectAll 
  406.  
  407.  Purpose:   to deselect all the text in the current file 
  408.  
  409.  Syntax:    rc = hmDeselectAll() 
  410.  
  411.  Returns:  0 
  412.  
  413.  Remarks: 
  414.  
  415.            hmDeselectAll works exactly as the "Deselect All" menu function 
  416.            does. 
  417.  
  418.  Example: 
  419.  
  420.  
  421.                       /* Deselect All Text */
  422.                       call hmDeselectAll
  423.  
  424.  
  425. ΓòÉΓòÉΓòÉ 1.12. hmDisableRefresh ΓòÉΓòÉΓòÉ
  426.  
  427.  Function:  hmDisableRefresh 
  428.  
  429.  Purpose:   to disable the editor when about to perform heavy editing 
  430.            operations 
  431.  
  432.  Syntax:    rc = hmDisableRefresh() 
  433.  
  434.  Returns:  0 
  435.  
  436.  Remarks: 
  437.  
  438.            Calls to hmDisableRefresh must have a corresponding call to 
  439.            hmEnableRefresh before your macro ends. 
  440.  
  441.            If you omit the hmEnableRefresh, you will not be able to use the 
  442.            file that was disabled - the mouse will turn into a clock cursor 
  443.            when over the editor, and the editor will not accept any keyboard 
  444.            input.  However, other files in the ring (if they weren't disabled) 
  445.            will not be affected and HTML-Ed will continue running so you can 
  446.            still save the file and exit. 
  447.  
  448.  Example: 
  449.  
  450.  
  451.                       /* Disable the editor */
  452.                       call hmDisableRefresh
  453.  
  454.                       /* do some editing */
  455.                         ...
  456.  
  457.                       /* Enable it again */
  458.                       call hmEnableRefresh
  459.  
  460.  
  461. ΓòÉΓòÉΓòÉ 1.13. hmEnableRefresh ΓòÉΓòÉΓòÉ
  462.  
  463.  Function:  hmEnableRefresh 
  464.  
  465.  Purpose:   to enable the editor after a call to hmDisableRefresh 
  466.  
  467.  Syntax:    rc = hmEnableRefresh() 
  468.  
  469.  Returns:  0 
  470.  
  471.  Remarks: 
  472.  
  473.            Calls to hmDisableRefresh must have a corresponding call to 
  474.            hmEnableRefresh before your macro ends.  See hmDisableRefresh for 
  475.            furthur information. 
  476.  
  477.  Example: 
  478.  
  479.  
  480.                       /* Disable the editor */
  481.                       call hmDisableRefresh
  482.  
  483.                       /* do some editing */
  484.                         ...
  485.  
  486.                       /* Enable it again */
  487.                       call hmEnableRefresh
  488.  
  489.  
  490. ΓòÉΓòÉΓòÉ 1.14. hmExit ΓòÉΓòÉΓòÉ
  491.  
  492.  Function:  hmExit 
  493.  
  494.  Purpose:   to exit HTML-Ed 
  495.  
  496.  Syntax:    rc = hmExit() 
  497.  
  498.  Returns:  0 
  499.  
  500.  Remarks: 
  501.  
  502.            The user is not prompted to save any of the files in the ring before 
  503.            they are closed.  It is up to the macro to ensure the files are 
  504.            saved. 
  505.  
  506.            If you use this function in your macro it should be the last 
  507.            instruction before the macro ends. 
  508.  
  509.  Example: 
  510.  
  511.  
  512.                       /* Exit HTML-Ed */
  513.                       call hmExit
  514.                       exit
  515.  
  516.  
  517. ΓòÉΓòÉΓòÉ 1.15. hmFind ΓòÉΓòÉΓòÉ
  518.  
  519.  Function:  hmFind 
  520.  
  521.  Purpose:   to find a text string in the current file 
  522.  
  523.  Syntax:    ipt = hmFind(text,[start],[stop],[cs]) 
  524.  
  525.            text           text string to search for 
  526.  
  527.            start          insertion point from which to start searching 
  528.  
  529.            stop           insertion point to stop searching at 
  530.  
  531.            cs=0           case insensitive (default) 
  532.            cs=1           case sensitive 
  533.  
  534.  Returns: 
  535.  
  536.            -1             Text not found 
  537.            other          Insertion point of the end of the text that was found 
  538.  
  539.  Remarks: 
  540.  
  541.            Specifying a start position of -1 starts the search from the cursor 
  542.            (the default if 'start' is omitted).  A stop position of -1 stops 
  543.            the search at the end of the text (the default if 'stop' is 
  544.            omitted). 
  545.  
  546.            If the text string is found the text string is selected.  The 
  547.            insertion point (ipt) of the cursor is then returned.  You can 
  548.            replace the text by simply calling hmInsert. 
  549.  
  550.            To search for the next ocurrance of the string, simply search again, 
  551.            starting from the cursor (if the cursor position hasn't changed) or 
  552.            from ipt (the return value from the last call to hmFind). 
  553.  
  554.            If you have replaced the text, search from "ipt - length(text) + 
  555.            length(replace_string)." 
  556.  
  557.  Example: 
  558.  
  559.  
  560.                       /* Search for a string */
  561.                       text = "Find Me!"
  562.  
  563.                       ipt = hmSearch(text,,,1)   /* Case sensitive!              */
  564.                       ipt = hmSearch(text)       /* Case insensitive!            */
  565.  
  566.                       ipt = hmSearch(text,0)     /* Start from beginning of file */
  567.                       ipt = hmSearch(text,ipt)   /* Search again                 */
  568.  
  569.  
  570. ΓòÉΓòÉΓòÉ 1.16. hmGoToLine ΓòÉΓòÉΓòÉ
  571.  
  572.  Function:  hmGoToLine 
  573.  
  574.  Purpose:   to move the cursor to a specified line 
  575.  
  576.  Syntax:    rc = hmGoToLine(line) 
  577.  
  578.            line           line number to move the cursor to 
  579.  
  580.  Returns:   0 
  581.  
  582.  Remarks: 
  583.  
  584.            hmGoToLine moves the cursor to the start of the specified line. If 
  585.            the line specified is greater than the last line in the file, the 
  586.            cursor will be moved to the start of the last line.  If zero is 
  587.            specified for the line, the cursor will be moved to the start of the 
  588.            current line. 
  589.  
  590.  Example: 
  591.  
  592.  
  593.                       /* Move to line 6 */
  594.                       call hmGoToLine 6
  595.  
  596.  
  597. ΓòÉΓòÉΓòÉ 1.17. hmInsert ΓòÉΓòÉΓòÉ
  598.  
  599.  Function:  hmInsert 
  600.  
  601.  Purpose:   to insert some text at the cursor 
  602.  
  603.  Syntax:    rc = hmInsert(text) 
  604.  
  605.            text           text string to insert at the cursor 
  606.  
  607.  Returns:   0 
  608.  
  609.  Remarks: 
  610.  
  611.            Any selected text at the time of the call to hmInsert will be 
  612.            replaced with the text string being inserted. 
  613.  
  614.  Example: 
  615.  
  616.  
  617.                       /* insert a text string */
  618.                       call hmInsert "This is some inserted text."
  619.  
  620.                       /* insert a text string with a newline character */
  621.                       call hmInsert "This is an inserted line!"d2c(10)
  622.  
  623.  
  624. ΓòÉΓòÉΓòÉ 1.18. hmInsertFile ΓòÉΓòÉΓòÉ
  625.  
  626.  Function:  hmInsertFile 
  627.  
  628.  Purpose:   to insert a text file into the current file at the cursor 
  629.  
  630.  Syntax:    rc = hmInsertFile(filename) 
  631.  
  632.            filename       the file to insert into the current file 
  633.  
  634.  Returns: 
  635.  
  636.            0              No Error 
  637.            1              Error opening file 
  638.  
  639.  Remarks: 
  640.  
  641.            hmInsertFile (like the other file manipulation functions) will not 
  642.            inform the user with a message box when there is a file error.  You 
  643.            must check the return code to ensure the file was inserted 
  644.            correctly. 
  645.  
  646.  Example: 
  647.  
  648.  
  649.                       /* Insert a text file at the cursor */
  650.                       rc = hmInsertFile("insert.txt")
  651.  
  652.                       /* Inform user on error */
  653.                       if rc<>0 then call hmStatusSay "Error loading file!",30
  654.                       else call hmStatusSay "Done.",30
  655.  
  656.  
  657. ΓòÉΓòÉΓòÉ 1.19. hmLineFromChar ΓòÉΓòÉΓòÉ
  658.  
  659.  Function:  hmLineFromChar 
  660.  
  661.  Purpose:   to query the line number of a specified insertion point 
  662.  
  663.  Syntax:    line = hmLineFromChar(ipt) 
  664.  
  665.            ipt            the insertion point of interest 
  666.  
  667.  Returns:  line number 
  668.  
  669.  Remarks: 
  670.  
  671.  Example: 
  672.  
  673.  
  674.                       /* find out what line the cursor is on */
  675.                       ipt = hmQuerySel("cursor")
  676.                       line = hmLineFromChar(ipt)
  677.  
  678.                       /* tell user */
  679.                       call hmStatusSay "We're on line #"line"!",30
  680.  
  681.  
  682. ΓòÉΓòÉΓòÉ 1.20. hmNew ΓòÉΓòÉΓòÉ
  683.  
  684.  Function:  hmNew 
  685.  
  686.  Purpose:   to open a new, untitled document, and switch to it 
  687.  
  688.  Syntax:    rc = hmNew() 
  689.  
  690.  Returns:   0 
  691.  
  692.  Remarks: 
  693.  
  694.            hmNew would be most useful for a macro that generates a complete 
  695.            HTML file from scratch.  hmNew switches to the new document after 
  696.            creating it. 
  697.  
  698.  Example: 
  699.  
  700.  
  701.                       /* Open a new document and create a (very simple) HTML skeleton */
  702.                       call hmNew
  703.                       call hmInsert "<HTML><HEAD></HEAD><BODY></BODY></HTML>"
  704.  
  705.  
  706. ΓòÉΓòÉΓòÉ 1.21. hmOpen ΓòÉΓòÉΓòÉ
  707.  
  708.  Function:  hmOpen 
  709.  
  710.  Purpose:   to open send one-line status updates to the user via the status 
  711.            line 
  712.  
  713.  Syntax:    rc = hmOpen(filename) 
  714.  
  715.            filename       name of the file to open 
  716.  
  717.  Returns: 
  718.  
  719.            0              No Error 
  720.            1              Error opening file. 
  721.  
  722.  Remarks: 
  723.  
  724.            hmOpen (like the other file manipulation functions) will not inform 
  725.            the user with a message box when there is a file error.  You must 
  726.            check the return code to ensure the file was opened correctly. 
  727.  
  728.            After the file is opened, it will become the current file in the 
  729.            ring. 
  730.  
  731.  Example: 
  732.  
  733.  
  734.                       /* Open a file */
  735.                       rc = hmOpen("myfile.htm")
  736.  
  737.                       /* Modify it */
  738.                       if rc = 0 then ...
  739.  
  740.                       /* Save the file */
  741.                       call hmSaveCurrent
  742.  
  743.  
  744. ΓòÉΓòÉΓòÉ 1.22. hmOpenOutputWindow ΓòÉΓòÉΓòÉ
  745.  
  746.  Function:  hmOpenOutputWindow 
  747.  
  748.  Purpose:   to open the Output Window 
  749.  
  750.  Syntax:    rc = hmOpenOutputWindow() 
  751.  
  752.  Returns:   0 
  753.  
  754.  Remarks: 
  755.  
  756.            hmOpenOutputWindow should be used before you display any important 
  757.            data to the Output Window.  If hmOpenOutputWindow isn't called, the 
  758.            user may never see what you write unless they open the Output Window 
  759.            manually, or have turned on the "Open Output Window when starting 
  760.            external process" option. 
  761.  
  762.  Example: 
  763.  
  764.  
  765.                       /* Open the Output Window and write some text to it */
  766.                       call hmOpenOutputWindow
  767.                       call hmSay "Hello World!"
  768.  
  769.  
  770. ΓòÉΓòÉΓòÉ 1.23. hmPaste ΓòÉΓòÉΓòÉ
  771.  
  772.  Function:  hmPaste 
  773.  
  774.  Purpose:   to paste the contents of the clipboard to the editor 
  775.  
  776.  Syntax:    rc = hmPaste() 
  777.  
  778.  Returns:  0 
  779.  
  780.  Remarks: 
  781.  
  782.  Example: 
  783.  
  784.  
  785.                       /* paste clipboard contents at cursor */
  786.                       call hmPaste
  787.  
  788.  
  789. ΓòÉΓòÉΓòÉ 1.24. hmQueryChanged ΓòÉΓòÉΓòÉ
  790.  
  791.  Function:  hmQueryChanged 
  792.  
  793.  Purpose:   to query the "changed" flag for the current file 
  794.  
  795.  Syntax:    rc = hmQueryChanged() 
  796.  
  797.  Returns: 
  798.  
  799.            0              file is unchanged since the last save 
  800.            1              file has been changed 
  801.  
  802.  Remarks: 
  803.  
  804.            You must check the changed flag before you close files (or exit 
  805.            HTML-Ed) if you want to make sure the file has been saved. 
  806.  
  807.  Example: 
  808.  
  809.  
  810.                       /* query changed status */
  811.                       wrap = hmQueryChanged()
  812.                       if wrap=1 then call hmSay "File has been modified!"
  813.                       else call hmSay "File is unchanged."
  814.  
  815.  
  816. ΓòÉΓòÉΓòÉ 1.25. hmQueryFilename ΓòÉΓòÉΓòÉ
  817.  
  818.  Function:  hmQueryFilename 
  819.  
  820.  Purpose:   to query the filename of a certain window title 
  821.  
  822.  Syntax:    file = hmQueryFilename(title) 
  823.  
  824.            title          window title of the desired file 
  825.  
  826.  Returns:  filename of the desired file 
  827.  
  828.  Remarks: 
  829.  
  830.            You must call hmQueryFilename to get the actual filename after a 
  831.            call to hmCurrentFile or hmRingFiles. 
  832.  
  833.            If a file is untitled, or if the file does not exist in the ring, an 
  834.            empty string ("") is returned. 
  835.  
  836.  Example: 
  837.  
  838.  
  839.                       /* display actual filename of current file */
  840.                       title = hmCurrentFile()
  841.                       filen = hmQueryFilename(title)
  842.                       call hmSay filen
  843.  
  844.  
  845. ΓòÉΓòÉΓòÉ 1.26. hmQueryLineCount ΓòÉΓòÉΓòÉ
  846.  
  847.  Function:  hmQueryLineCount 
  848.  
  849.  Purpose:   to query the line count for the current file 
  850.  
  851.  Syntax:    lines = hmQueryLineCount() 
  852.  
  853.  Returns:  number of lines in the current file 
  854.  
  855.  Remarks: 
  856.  
  857.  Example: 
  858.  
  859.  
  860.                       /* how many lines? */
  861.                       lines = hmQueryLineCount()
  862.                       call hmSay "There are "lines" lines in this file."
  863.  
  864.  
  865. ΓòÉΓòÉΓòÉ 1.27. hmQueryLineLength ΓòÉΓòÉΓòÉ
  866.  
  867.  Function:  hmQueryLineLength 
  868.  
  869.  Purpose:   to query the length from a specified insertion point to the end of 
  870.            the line 
  871.  
  872.  Syntax:    lines = hmQueryLineLength(ipt) 
  873.  
  874.            ipt            insertion point to start from 
  875.  
  876.  Returns:  length from ipt to the end of the line 
  877.  
  878.  Remarks: 
  879.  
  880.  Example: 
  881.  
  882.  
  883.                       /* delete to end of line */
  884.                       cur = hmQuerySel("cursor")
  885.                       len = hmQueryLineLength(cur)
  886.                       call hmDelete cur,len-1
  887.  
  888.  
  889. ΓòÉΓòÉΓòÉ 1.28. hmQuerySel ΓòÉΓòÉΓòÉ
  890.  
  891.  Function:  hmQuerySel 
  892.  
  893.  Purpose:   to query the cursor or anchor points 
  894.  
  895.  Syntax:    ipt = hmQuerySel(type) 
  896.  
  897.            type = 
  898.  
  899.                           "anchor"       request the anchor point 
  900.                           "cursor"       request the cursor position 
  901.                           "min"          request the minimum selection point 
  902.                                          (whether it is the cursor or anchor 
  903.                                          point) 
  904.                           "max"          request the maximum selection point 
  905.                                          (whether it is the cursor or anchor 
  906.                                          point) 
  907.  
  908.  Returns:  the requested insertion point 
  909.  
  910.  Remarks: 
  911.  
  912.            The cursor and anchor points are the endpoints of the current 
  913.            selection.  The cursor point is the endpoint that the cursor is at, 
  914.            and the anchor point is the other endpoint. 
  915.  
  916.            If there is no selected text, the cursor and anchor points (and, 
  917.            therefore, the min and max points) will be the same. 
  918.  
  919.  Example: 
  920.  
  921.  
  922.                       /* delete to end of line */
  923.                       cur = hmQuerySel("cursor")
  924.                       len = hmQueryLineLength(cur)
  925.                       call hmDelete cur,len-1
  926.  
  927.  
  928. ΓòÉΓòÉΓòÉ 1.29. hmQuerySelText ΓòÉΓòÉΓòÉ
  929.  
  930.  Function:  hmQuerySelText 
  931.  
  932.  Purpose:   to query the selected text 
  933.  
  934.  Syntax:    text = hmQuerySelText() 
  935.  
  936.  Returns:  the selected text 
  937.  
  938.  Remarks: 
  939.  
  940.            If there is no selected text, hmQuerySelText returns an empty string 
  941.            (""). 
  942.  
  943.  Example: 
  944.  
  945.  
  946.                       /* get 15 characters, starting at the cursor */
  947.                       cur = hmQuerySel("cursor")
  948.                       call hmSelSet cur+15,cur
  949.                       text = hmQuerySelText()
  950.                       call hmSelSet cur,cur
  951.  
  952.                       /* print it out */
  953.                       call hmSay text
  954.  
  955.  
  956. ΓòÉΓòÉΓòÉ 1.30. hmQueryTextLength ΓòÉΓòÉΓòÉ
  957.  
  958.  Function:  hmQueryTextLength 
  959.  
  960.  Purpose:   to query the length of the current document 
  961.  
  962.  Syntax:    len = hmQueryTextLength() 
  963.  
  964.  Returns:  length of the current document 
  965.  
  966.  Remarks: 
  967.  
  968.            A good use for hmQueryTextLength is to find the insertion point of 
  969.            the end of the document. 
  970.  
  971.  Example: 
  972.  
  973.  
  974.                       /* get length of file */
  975.                       len = hmQueryTextLength()
  976.  
  977.  
  978. ΓòÉΓòÉΓòÉ 1.31. hmQueryWrap ΓòÉΓòÉΓòÉ
  979.  
  980.  Function:  hmQueryWrap 
  981.  
  982.  Purpose:   to query the word wrap status of the current file 
  983.  
  984.  Syntax:    rc = hmQueryWrap() 
  985.  
  986.  Returns: 
  987.  
  988.            0              Word wrap off 
  989.            1              Word wrap on 
  990.  
  991.  Remarks: 
  992.  
  993.            The word wrap status applies only to the current file.  Another file 
  994.            may have a different word wrap status. 
  995.  
  996.  Example: 
  997.  
  998.  
  999.                       /* query wrap status */
  1000.                       wrap = hmQueryWrap()
  1001.                       if wrap=1 then call hmSay "Word wrap enabled!"
  1002.                       else call hmSay "Word wrap disabled."
  1003.  
  1004.  
  1005. ΓòÉΓòÉΓòÉ 1.32. hmRemoveTags ΓòÉΓòÉΓòÉ
  1006.  
  1007.  Function:  hmRemoveTags 
  1008.  
  1009.  Purpose:   to remove the HTML tags from the selected text 
  1010.  
  1011.  Syntax:    rc = hmRemoveTags() 
  1012.  
  1013.  Returns: 
  1014.  
  1015.            0              No error 
  1016.            1              No text was selected 
  1017.  
  1018.  Remarks: 
  1019.  
  1020.            hmRemoveTags works exactly as the "Remove Tags" menu function does, 
  1021.            removing all the tags from the selected text. 
  1022.  
  1023.  Example: 
  1024.  
  1025.  
  1026.                       /* Remove tags in the selected text */
  1027.                       call hmRemoveTags
  1028.  
  1029.  
  1030. ΓòÉΓòÉΓòÉ 1.33. hmResetUndo ΓòÉΓòÉΓòÉ
  1031.  
  1032.  Function:  hmResetUndo 
  1033.  
  1034.  Purpose:   to prevent the user from undoing something 
  1035.  
  1036.  Syntax:    rc = hmResetUndo() 
  1037.  
  1038.  Returns:   0 
  1039.  
  1040.  Remarks: 
  1041.  
  1042.            If you call hmResetUndo after you change the document, the user will 
  1043.            be prevented from undoing your change. 
  1044.  
  1045.  Example: 
  1046.  
  1047.  
  1048.                       /* Prevent an Undo */
  1049.                       call hmResetUndo
  1050.  
  1051.  
  1052. ΓòÉΓòÉΓòÉ 1.34. hmRingLeft ΓòÉΓòÉΓòÉ
  1053.  
  1054.  Function:  hmRingLeft 
  1055.  
  1056.  Purpose:   to move left in the file ring 
  1057.  
  1058.  Syntax:    rc = hmRingLeft() 
  1059.  
  1060.  Returns:   0 
  1061.  
  1062.  Remarks: 
  1063.  
  1064.  Example: 
  1065.  
  1066.  
  1067.                       /* Move left in the file ring */
  1068.                       call hmRingLeft
  1069.  
  1070.  
  1071. ΓòÉΓòÉΓòÉ 1.35. hmRingFiles ΓòÉΓòÉΓòÉ
  1072.  
  1073.  Function:  hmRingFiles 
  1074.  
  1075.  Purpose:   to return a list of all the files in the file ring 
  1076.  
  1077.  Syntax:    rc = hmRingFiles(stem[,options]) 
  1078.  
  1079.            stem           The name of the stem variable to return the titles 
  1080.                           in. 
  1081.  
  1082.            options        If the options string contains an 'F', hmRingFiles 
  1083.                           will only return those files that have been saved 
  1084.                           (not untitled), and only one instance of each file. 
  1085.  
  1086.  Returns:   0 
  1087.  
  1088.  Remarks: 
  1089.  
  1090.            The number of files will be returned in stem.0 and the actual 
  1091.            filenames are returned in stem.n where n is a number from 1 to 
  1092.            stem.0, much the same as SysFileTree returns a list of files. 
  1093.  
  1094.            Currently the "F" (Files only) option is the only available option. 
  1095.  
  1096.            Note that the values returned are not filenames - they are window 
  1097.            titles.  To find the filename of a certain window title, follow this 
  1098.            call with a call to hmQueryFilename. 
  1099.  
  1100.  Example: 
  1101.  
  1102.  
  1103.                       /* Get the file ring in the 'ring' stem variable */
  1104.                       call hmRingFiles "ring"
  1105.  
  1106.                       /* Display the file ring */
  1107.                       call hmOpenOutputWindow
  1108.                       do i=1 to ring.0
  1109.                          call hmSay ring.i
  1110.                       end
  1111.  
  1112.  
  1113. ΓòÉΓòÉΓòÉ 1.36. hmRingRight ΓòÉΓòÉΓòÉ
  1114.  
  1115.  Function:  hmRingRight 
  1116.  
  1117.  Purpose:   to move right in the file ring 
  1118.  
  1119.  Syntax:    rc = hmRingRight() 
  1120.  
  1121.  Returns:   0 
  1122.  
  1123.  Remarks: 
  1124.  
  1125.  Example: 
  1126.  
  1127.  
  1128.                       /* Move right in the file ring */
  1129.                       call hmRingRight
  1130.  
  1131.  
  1132. ΓòÉΓòÉΓòÉ 1.37. hmSaveAll ΓòÉΓòÉΓòÉ
  1133.  
  1134.  Function:  hmSaveAll 
  1135.  
  1136.  Purpose:   to save all named (not untitled) files in the ring 
  1137.  
  1138.  Syntax:    rc = hmSaveAll() 
  1139.  
  1140.  Returns: 
  1141.  
  1142.            0              No Error 
  1143.            1              Error opening file 
  1144.            2              Error writing to file 
  1145.  
  1146.  Remarks: 
  1147.  
  1148.            On error, hmSaveAll makes the file that caused the error the current 
  1149.            file in the ring. 
  1150.  
  1151.            Unlike hmSaveCurrent, unnamed files and files that haven't been 
  1152.            changed do not cause errors.  These files are not saved, however. 
  1153.  
  1154.            The "changed" flag is cleared for all saved files. 
  1155.  
  1156.  Example: 
  1157.  
  1158.  
  1159.                       /* Save all the files in the ring */
  1160.                       rc = hmSaveAll()
  1161.  
  1162.                       /* if there was an error, inform user */
  1163.                       if rc<>0 then call hmStatusSay "Error saving this file!",30
  1164.                       else call hmStatusSay "Done!",30
  1165.  
  1166.  
  1167. ΓòÉΓòÉΓòÉ 1.38. hmSaveAs ΓòÉΓòÉΓòÉ
  1168.  
  1169.  Function:  hmSaveAs 
  1170.  
  1171.  Purpose:   to save the current file with a given filename 
  1172.  
  1173.  Syntax:    rc = hmSaveAs(filename) 
  1174.  
  1175.            filename       the filename with which to save the current file 
  1176.  
  1177.  Returns: 
  1178.  
  1179.            0              No Error 
  1180.            1              Error opening file 
  1181.            2              Error writing to file 
  1182.  
  1183.  Remarks: 
  1184.  
  1185.            hmSaveAs (like the other file manipulation functions) will not 
  1186.            inform the user with a message box when there is a file error.  You 
  1187.            must check the return code to ensure the file was saved correctly. 
  1188.  
  1189.            hmSaveAs will also not warn you about an existing file - it will 
  1190.            overwrite the file automatically.  If you don't wish to overwrite an 
  1191.            existing file you must use standard REXX functions to determine if 
  1192.            the file already exists. 
  1193.  
  1194.            If an existing file is overwritten, the existing EA's are preserved. 
  1195.            It is up to the macro to remove the EA's if desired. 
  1196.  
  1197.            Note that unlike the "Save As..." menu option, the in-memory 
  1198.            filename (the one on the titlebar) for the current file is not 
  1199.            changed. You can use the hmChangeFilename function for that purpose. 
  1200.  
  1201.  Example: 
  1202.  
  1203.  
  1204.                       /* Modify the current file */
  1205.                       call hmInsert ...
  1206.  
  1207.                       /* Save it under a new filename */
  1208.                       call hmSaveAs "newfile.htm"
  1209.  
  1210.                       /* Undo the last change */
  1211.                       call hmUndo
  1212.  
  1213.  
  1214. ΓòÉΓòÉΓòÉ 1.39. hmSaveASCII ΓòÉΓòÉΓòÉ
  1215.  
  1216.  Function:  hmSaveASCII 
  1217.  
  1218.  Purpose:   to save an ASCII version of the current file with a given filename 
  1219.  
  1220.  Syntax:    rc = hmSaveASCII(filename) 
  1221.  
  1222.            filename       the filename with which to save the current file as 
  1223.                           ASCII 
  1224.  
  1225.  Returns: 
  1226.  
  1227.            0              No Error 
  1228.            1              Error opening file 
  1229.            2              Error writing to file 
  1230.  
  1231.  Remarks: 
  1232.  
  1233.            hmSaveASCII (like the other file manipulation functions) will not 
  1234.            inform the user with a message box when there is a file error.  You 
  1235.            must check the return code to ensure the file was saved correctly. 
  1236.  
  1237.            hmSaveASCII will also not warn you about an existing file - it will 
  1238.            overwrite the file automatically.  If you don't wish to overwrite an 
  1239.            existing file you must use standard REXX functions to determine if 
  1240.            the file already exists. 
  1241.  
  1242.            If an existing file is overwritten, the existing EA's are preserved. 
  1243.            It is up to the macro to remove the EA's if desired. 
  1244.  
  1245.  Example: 
  1246.  
  1247.  
  1248.                       /* Save an ascii version of the current file */
  1249.                       rc = hmSaveASCII("myfile.txt")
  1250.  
  1251.                       /* Inform user on error */
  1252.                       if rc<>0 then call hmStatusSay "Error saving as ASCII!",30
  1253.                       else call hmStatusSay "Saved!",30
  1254.  
  1255.  
  1256. ΓòÉΓòÉΓòÉ 1.40. hmSaveCurrent ΓòÉΓòÉΓòÉ
  1257.  
  1258.  Function:  hmSaveCurrent 
  1259.  
  1260.  Purpose:   to save the current file in the file ring 
  1261.  
  1262.  Syntax:    rc = hmSaveCurrent() 
  1263.  
  1264.  Returns: 
  1265.  
  1266.            0              No Error 
  1267.            1              Error opening file 
  1268.            2              Error writing to file 
  1269.            3              File was unchanged (save was unnecessary) 
  1270.            4              No filename (current file is untitled) 
  1271.  
  1272.  Remarks: 
  1273.  
  1274.            hmSaveCurrent (like the other file manipulation functions) will not 
  1275.            inform the user with a message box when there is a file error.  You 
  1276.            must check the return code to ensure the file was saved correctly. 
  1277.  
  1278.            The "changed" flag is cleared if the file is saved correctly. 
  1279.  
  1280.  Example: 
  1281.  
  1282.  
  1283.                       /* Open a file */
  1284.                       rc = hmOpen("myfile.htm")
  1285.  
  1286.                       /* Modify it */
  1287.                       if rc = 0 then ...
  1288.  
  1289.                       /* Save the file */
  1290.                       call hmSaveCurrent
  1291.  
  1292.  
  1293. ΓòÉΓòÉΓòÉ 1.41. hmSaveOptions ΓòÉΓòÉΓòÉ
  1294.  
  1295.  Function:  hmSaveOptions 
  1296.  
  1297.  Purpose:   to save the current options 
  1298.  
  1299.  Syntax:    rc = hmSaveOptions() 
  1300.  
  1301.  Returns:  0 
  1302.  
  1303.  Remarks: 
  1304.  
  1305.            hmSaveOptions works just like the "Save Options/Position" menu 
  1306.            function.  It causes all the options and window positions to be 
  1307.            saved. 
  1308.  
  1309.  Example: 
  1310.  
  1311.  
  1312.                       /* Save options */
  1313.                       call hmSaveOptions
  1314.  
  1315.  
  1316. ΓòÉΓòÉΓòÉ 1.42. hmSay ΓòÉΓòÉΓòÉ
  1317.  
  1318.  Function:  hmSay 
  1319.  
  1320.  Purpose:   to send textual information to the user via the Output Window 
  1321.  
  1322.  Syntax:    rc = hmSay(text) 
  1323.  
  1324.            text           a text string to be displayed in the Output Window 
  1325.  
  1326.  Returns:   0 
  1327.  
  1328.  Remarks: 
  1329.  
  1330.            If a .CMD or .HM REXX Macro sends more than 32kb of data to stdout, 
  1331.            HTML-Ed will crash (this limit does not exist for EXE's!).  This 
  1332.            limit should be more than enough for all your needs.  However, if 
  1333.            you need to display a significant amount of data, you should use 
  1334.            hmSay instead of say because hmSay does not suffer from this 
  1335.            limitation. 
  1336.  
  1337.            Note that if you mix calls to say and hmSay, you will not get the 
  1338.            results you expected.  The output from all calls to hmSay will be 
  1339.            displayed before the output from all calls to say.  Therefore, you 
  1340.            should avoid mixing calls to say and hmSay. 
  1341.  
  1342.  Example: 
  1343.  
  1344.  
  1345.                       /* Display text in Output Window */
  1346.                       call hmSay "Hello World!"
  1347.  
  1348.  
  1349. ΓòÉΓòÉΓòÉ 1.43. hmSelectAll ΓòÉΓòÉΓòÉ
  1350.  
  1351.  Function:  hmSelectAll 
  1352.  
  1353.  Purpose:   to select all the text in the current file 
  1354.  
  1355.  Syntax:    rc = hmSelectAll() 
  1356.  
  1357.  Returns:  0 
  1358.  
  1359.  Remarks: 
  1360.  
  1361.            hmSelectAll works exactly as the "Select All" menu function does. 
  1362.  
  1363.  Example: 
  1364.  
  1365.  
  1366.                       /* Select All Text */
  1367.                       call hmSelectAll
  1368.  
  1369.  
  1370. ΓòÉΓòÉΓòÉ 1.44. hmSetChanged ΓòÉΓòÉΓòÉ
  1371.  
  1372.  Function:  hmSetChanged 
  1373.  
  1374.  Purpose:   to set a document's "changed" flag 
  1375.  
  1376.  Syntax:    rc = hmSetChanged(changed) 
  1377.  
  1378.            changed=0      unchanged 
  1379.            changed=1      changed 
  1380.  
  1381.  Returns:   0 
  1382.  
  1383.  Remarks: 
  1384.  
  1385.  Example: 
  1386.  
  1387.  
  1388.                       /* turn off changed flag */
  1389.                       call hmSetChanged 0
  1390.  
  1391.  
  1392. ΓòÉΓòÉΓòÉ 1.45. hmSetSel ΓòÉΓòÉΓòÉ
  1393.  
  1394.  Function:  hmSetSel 
  1395.  
  1396.  Purpose:   to set the anchor and cursor points 
  1397.  
  1398.  Syntax:    rc = hmSetWrap(anchor, cursor) 
  1399.  
  1400.            anchor         insertion point of the anchor point 
  1401.  
  1402.            cursor         insertion point of the cursor 
  1403.  
  1404.  Returns:   0 
  1405.  
  1406.  Remarks: 
  1407.  
  1408.            If you simply wish to move the cursor, call hmSetSel with the same 
  1409.            value for the cursor and anchor. 
  1410.  
  1411.  Example: 
  1412.  
  1413.  
  1414.                       /* move the cursor to the beginning of the file */
  1415.                       call hmSetSel 0, 0
  1416.  
  1417.  
  1418. ΓòÉΓòÉΓòÉ 1.46. hmSetWrap ΓòÉΓòÉΓòÉ
  1419.  
  1420.  Function:  hmSetWrap 
  1421.  
  1422.  Purpose:   to set the word wrap status of the current file 
  1423.  
  1424.  Syntax:    rc = hmSetWrap(wrap) 
  1425.  
  1426.            wrap=0         word wrap off 
  1427.            wrap=1         word wrap on 
  1428.  
  1429.  Returns:   0 
  1430.  
  1431.  Remarks: 
  1432.  
  1433.            Note that the word wrap status will be changed for the current file 
  1434.            only - not all the files in the ring.  However, if you open or 
  1435.            create another file then the new file will inherit the word wrap 
  1436.            style from the current file at the time of its creation. 
  1437.  
  1438.  Example: 
  1439.  
  1440.  
  1441.                       /* turn on word wrap */
  1442.                       call hmSetWrap 1
  1443.  
  1444.  
  1445. ΓòÉΓòÉΓòÉ 1.47. hmStatusSay ΓòÉΓòÉΓòÉ
  1446.  
  1447.  Function:  hmStatusSay 
  1448.  
  1449.  Purpose:   to send one-line status updates to the user via the status line 
  1450.  
  1451.  Syntax:    rc = hmStatusSay(text[,time]) 
  1452.  
  1453.            text           a text string to be displayed on the status line 
  1454.  
  1455.            time           approximate time (in tenths of a second) that the 
  1456.                           text should be displayed before being cleared.  If 
  1457.                           zero, or if omitted, the text will be displayed until 
  1458.                           the next call to hmStatusSay, or until HTML-Ed writes 
  1459.                           to the status line itself (such as during Open and 
  1460.                           Save operations). 
  1461.  
  1462.  Returns:   0 
  1463.  
  1464.  Remarks: 
  1465.  
  1466.            hmStatusSay is very useful since it allows you to quickly inform the 
  1467.            user of your macro's status without requiring that the Output Window 
  1468.            be displayed. 
  1469.  
  1470.  Example: 
  1471.  
  1472.  
  1473.                       /* Display text on the status line for three seconds */
  1474.                       call hmStatusSay "Hello World!", 30
  1475.  
  1476.                       /* Display text on the status line indefinitely*/
  1477.                       call hmStatusSay "Hello Again!"
  1478.  
  1479.  
  1480. ΓòÉΓòÉΓòÉ 1.48. hmSwitchTo ΓòÉΓòÉΓòÉ
  1481.  
  1482.  Function:  hmSwitchTo 
  1483.  
  1484.  Purpose:   to switch to a specified file in the file ring 
  1485.  
  1486.  Syntax:    rc = hmSwitchTo(file) 
  1487.  
  1488.            file           The filename of the file to switch to 
  1489.  
  1490.  Returns: 
  1491.  
  1492.            0              No Error 
  1493.            1              Couldn't find file in ring 
  1494.  
  1495.  Remarks: 
  1496.  
  1497.            You should note that when switching to a file you must specify the 
  1498.            complete filename and path.  You may also switch to an untitled file 
  1499.            or a second instance of a file by specifying exactly what appears in 
  1500.            the title bar.  See the examples. 
  1501.  
  1502.            Note also that this is not case sensitive.  "E:\HOME.HTM" is treated 
  1503.            exactly the same as "e:\home.htm". 
  1504.  
  1505.  Example: 
  1506.  
  1507.  
  1508.                       /* Switch to a file */
  1509.                       call hmSwitchTo "F:\homepage\home.htm"
  1510.  
  1511.                       /* Switch to another instance of the same file */
  1512.                       call hmSwitchTo "F:\homepage\home.htm:1"
  1513.  
  1514.                       /* Switch to untitled file #2 */
  1515.                       call hmSwitchTo "Untitled #2"
  1516.  
  1517.  
  1518. ΓòÉΓòÉΓòÉ 1.49. hmTagsCase ΓòÉΓòÉΓòÉ
  1519.  
  1520.  Function:  hmTagsCase 
  1521.  
  1522.  Purpose:   to convert the case of HTML tags 
  1523.  
  1524.  Syntax:    rc = hmTagsCase([case]) 
  1525.  
  1526.            case = 0       lowercase 
  1527.            case = 1       uppercase (the default if parameter is omitted) 
  1528.  
  1529.  Returns: 
  1530.  
  1531.            0              No error 
  1532.            1              No text was selected 
  1533.  
  1534.  Remarks: 
  1535.  
  1536.            hmTagsCase works exactly as the "Convert tags" menu functions do, 
  1537.            converting the case of all the HTML tags in the selected text. 
  1538.  
  1539.  Example: 
  1540.  
  1541.  
  1542.                       /* Convert tags to uppercase */
  1543.                       call hmTagsCase
  1544.  
  1545.                       /* Convert tags to lowercase */
  1546.                       call hmTagsCase 0
  1547.  
  1548.  
  1549. ΓòÉΓòÉΓòÉ 1.50. hmUndo ΓòÉΓòÉΓòÉ
  1550.  
  1551.  Function:  hmUndo 
  1552.  
  1553.  Purpose:   to undo/redo the last operation 
  1554.  
  1555.  Syntax:    rc = hmUndo() 
  1556.  
  1557.  Returns: 
  1558.  
  1559.            0              No error 
  1560.            1              Undo was not performed (usually becuase there was 
  1561.                           nothing to undo) 
  1562.  
  1563.  Remarks: 
  1564.  
  1565.            Calling hmUndo twice in a row will redo the undone operation. 
  1566.  
  1567.  Example: 
  1568.  
  1569.  
  1570.                       /* undo something */
  1571.                       call hmUndo
  1572.  
  1573.  
  1574. ΓòÉΓòÉΓòÉ 1.51. hmVersion ΓòÉΓòÉΓòÉ
  1575.  
  1576.  Function:  hmVersion 
  1577.  
  1578.  Purpose:   to return the name and version number of the host program 
  1579.  
  1580.  Syntax:    version = hmVersion() 
  1581.  
  1582.  Returns:   version string (eg. "HTML-Ed v0.96b") 
  1583.  
  1584.  Remarks: 
  1585.  
  1586.            You should check the version of HTML-Ed that is being used before 
  1587.            you use functions introduced in future versions.  I will strive to 
  1588.            make the HM macro functions fully backward-compatible. 
  1589.  
  1590.            However, unless your macro is specific to HTML-Ed, do not enforce 
  1591.            the presence of the "HTML-Ed" text at the beginning of the string - 
  1592.            only check the version number.  I intend to use the HM macro 
  1593.            functions in a future project and most, if not all of the HM macro 
  1594.            functions will be the same (most likely only a few functions will be 
  1595.            missing - mainly ones specific to HTML like hmSaveASCII, 
  1596.            hmConvertSlashes, etc). 
  1597.  
  1598.  Example: 
  1599.  
  1600.  
  1601.                       /* Get version string */
  1602.                       version = hmVersion()
  1603.  
  1604.                       /* Display version */
  1605.                       call hmSay version
  1606.  
  1607.  
  1608. ΓòÉΓòÉΓòÉ 1.52. hmWrapAround ΓòÉΓòÉΓòÉ
  1609.  
  1610.  Function:  hmWrapAround 
  1611.  
  1612.  Purpose:   to wrap two text strings around the selected text 
  1613.  
  1614.  Syntax:    rc = hmWrapAround(open,close) 
  1615.  
  1616.            open           text string to insert before the selection 
  1617.  
  1618.            close          text string to insert after the selection 
  1619.  
  1620.  Returns:  0 
  1621.  
  1622.  Remarks: 
  1623.  
  1624.            This function is the same one used by many of HTML-Ed's tag 
  1625.            functions. 
  1626.  
  1627.  Example: 
  1628.  
  1629.  
  1630.                       /* simulate a "Styles/Bold" menu choice */
  1631.                       call hmWrapAround "<B>","</B>"
  1632.  
  1633.  
  1634. ΓòÉΓòÉΓòÉ 2. Examples ΓòÉΓòÉΓòÉ
  1635.  
  1636. The following examples are also available on disk: 
  1637.  
  1638.       AUTODATE.HM 
  1639.  
  1640.  
  1641. ΓòÉΓòÉΓòÉ <hidden> Examples Introduction ΓòÉΓòÉΓòÉ
  1642.  
  1643. These are some example .HM macros.  Visit the HTML-Ed Hope Page at 
  1644. http://www.wp.com/ianprest/htmled.html for new example macros submitted by 
  1645. users (please mail me any macros you write that you think others would find 
  1646. useful). 
  1647.  
  1648.  
  1649. ΓòÉΓòÉΓòÉ 2.1. AUTODATE.HM ΓòÉΓòÉΓòÉ
  1650.  
  1651. This macro replaces the text between the comment tags <!-- AUTODATE --> and 
  1652. <!-- /AUTODATE --> and replaces the text between them with the current date. 
  1653.  
  1654.  
  1655. /* .HM Macro to replace a date in the current file with a new date */
  1656.  
  1657. starttext = "<!-- AUTODATE -->"
  1658. stoptext = "<!-- /AUTODATE -->"
  1659.  
  1660. /* disable the editor */
  1661. call hmDisableRefresh
  1662.  
  1663. /* find the start and stop points for searching for the date */
  1664. /* these are so we don't accidentally modify the wrong text */
  1665. start = hmFind(starttext,0,,1)
  1666. if start=-1 then call notfound
  1667. stop = hmFind(stoptext,start,,1)
  1668. if stop=-1 then call notfound
  1669.  
  1670. /* select the text that will be replaced */
  1671. call hmSetSel start,stop-length(stoptext)
  1672.  
  1673. /* insert the new date */
  1674. call hmInsert date()
  1675.  
  1676. /* inform user of success */
  1677. call hmStatusSay "Updated AUTODATE!",40
  1678.  
  1679. /* exit the macro */
  1680. call hmEnableRefresh
  1681. exit
  1682.  
  1683. /* this procedure is called when one of the expected strings is not found */
  1684. notfound: procedure
  1685.     call hmStatusSay "Couldn't find AUTODATE!",40
  1686.     call hmEnableRefresh
  1687.     exit
  1688.