home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / filemanager / filebox_1 / Docs_ManualText < prev    next >
Encoding:
Text File  |  1997-09-03  |  53.0 KB  |  2,147 lines
  1. Kasoft Software
  2. File Box Module
  3. Reference Manual
  4.  
  5. (Format width is 76 characters)
  6.  
  7. -
  8.  
  9. Copyright © Kasoft Software 1997
  10.  
  11. Neither the whole nor any part of this manual, or the software described
  12. herein may be adapted or reproduced in any material form except with the
  13. prior written approval of the author.
  14.  
  15. The software described in this manual is subject to continuous development
  16. and improvement. All information of a technical nature and particulars of
  17. the software and its use (including the information and particulars in this
  18. manual) are given by Kasoft Software in good faith. However, Kasoft Software will not accept liability for any loss or damage arising from the use of the
  19. software or the documentation in this manual.
  20.  
  21. All correspondence should be addressed to the address given in the release
  22. note.
  23.  
  24. The relocatable module 'FileBox' was programmed by Kade Hansson. This module
  25. is suitable for use with all ARM-based computers running Acorn RISC OS
  26. version 3.10 or later.
  27.  
  28. This manual or the software it documents has no connection with Acorn
  29. Computers Limited, but necessary registration of the module title and
  30. allocation of a software interrupt chunk number has been carried out. Thus,
  31. the software should not interfere with other software which has taken
  32. similar precautions.
  33.  
  34. KASOFT and the Kasoft device are trademarks of Kasoft Software, and owned by
  35. Kade Hansson.
  36.  
  37. ACORN is a trademark of Acorn Computers Limited.
  38.  
  39. Edition 2 (ASCII text file version)
  40. Published September 1997; Issue 2
  41. Written by Kade Hansson
  42. Published by Kasoft Typesetting
  43. Code KM09602,02T
  44.  
  45. -
  46.  
  47. Contents
  48.  
  49. Introduction    Introduction to the File Box module
  50.                 The Load window
  51.                 The Save window
  52.                 Program information
  53.                 Interactive help
  54.  
  55. Overview        *Command protocol
  56.                 SWI protocol
  57.                 Controlling File Box
  58.  
  59. Technical Details
  60.                 *Command protocol
  61.                 Getting an input filename
  62.                 Getting an output filename
  63.                 Resetting File Box
  64.                 SWI protocol
  65.                 Getting an input filename
  66.                 Getting an output filename
  67.                 Controlling File Box
  68.                 File Box errors
  69.  
  70. SWI Calls       FileBox_InitiateLoadFromFiler (SWI &48240)
  71.                 FileBox_PollLoadFromFiler (SWI &48241)
  72.                 FileBox_InitiateSaveToFiler (SWI &48242)
  73.                 FileBox_PollSaveToFiler (SWI &48243)
  74.                 FileBox_AbortLoad (SWI &48244)
  75.                 FileBox_AbortSave (SWI &48245)
  76.                 FileBox_DoLoadFromFiler (SWI &48246)
  77.                 FileBox_DoSaveToFiler (SWI &48247)
  78.                 FileBox_Control (SWI &48248)
  79.                 FileBox_PollControl (SWI &48249)
  80.                 FileBox_AbortControl (SWI &4824A)
  81.                 FileBox_FiletypeExtendOp (SWI &4824B)
  82.  
  83. Service Calls   Service_FileBoxWorkspace (Service &48240)
  84.  
  85. *Commands       *Desktop_FileBox
  86.                 *Help FileBox
  87.                 *IOVarsOff
  88.                 *IOVarsOn
  89.                 *InputPrompt
  90.                 *InputReset
  91.                 *InputTitle
  92.                 *OutputReset
  93.                 *OutputTitle
  94.                 *OutputType
  95.                 *ResetFileBox
  96.  
  97. System Variables
  98.                 FileBox$GetInputFilename
  99.                 FileBox$GetOutputFilename
  100.  
  101. -
  102.  
  103. Introduction
  104.  
  105. The Kasoft File Box module provides loading and saving facilities for
  106. Desktop tasks. Any task, including one that is running in a task window, can
  107. use File Box as a simple means of implementing the standard file dragging
  108. procedures for the loading and saving of files. The technical intricacies of
  109. the RISC OS Desktop saving and loading protocols are hidden from tasks, with
  110. File Box acting as a useful intermediary.
  111.  
  112. This module was written by Kasoft Software and it is subject to
  113. continuous development and improvement. Updates to new versions and licences
  114. for distributing this module with commercial software are available. Feel
  115. free to contact us at the address given on the release note. Criticisms and
  116. suggestions for improvement will be appreciated. Please note that copyright
  117. subsists in this software, so you should familiarize yourself with the
  118. licence which accompanied it.
  119.  
  120. The Load window
  121.  
  122. The File Box Load window is displayed when a task requires an input file to
  123. be specified. If a task window requested this Load window, then its
  124. appearance is often accompanied by a message in that task window, giving the
  125. user more information on what is required. The Load window will usually open
  126. under the mouse pointer. There are several available responses to a Load
  127. window:
  128.  
  129. • To specify an input file, simply drag it onto the Load window. Do not drag
  130.   it to the parent task window.
  131.  
  132. • Alternatively, you can type the full pathname of the input file, and press
  133.   the Return key or click on OK.
  134.  
  135. • To abandon the operation either click on Cancel (or the close icon) or
  136.   press the Escape key.
  137.  
  138. The Save window
  139.  
  140. The File Box Save window is displayed when a task requires an output file to
  141. be specified. If a task window requested this Save window, then its
  142. appearance is often accompanied by a message in that task window, giving the
  143. user more information on what is required. The Save window will usually open
  144. under the mouse pointer. There are several available responses to a Save
  145. window:
  146.  
  147. • To specify an output file, type a leafname for the file (or use the name
  148.   supplied, if there is one) and drag the file icon to a directory viewer.
  149.   
  150. • Alternatively, you can type the full pathname of the output file, and
  151.   press the Return key or click on OK.
  152.   
  153. • To abandon the operation either click on Cancel (or the close icon) or
  154.   press the Escape key.
  155.  
  156. Program information
  157.  
  158. To obtain information on the version of the File Box module you are using,
  159. click Menu over a File Box window. Alternatively, you can type:
  160.  
  161. *Help FileBox
  162.  
  163. at the command line.
  164.  
  165. Interactive help
  166.  
  167. The File Box task supports interactive help (provided by the !Help
  168. application found in the Apps directory), so that moving the pointer over
  169. various elements of the Load and Save windows will cause helpful
  170. instructions and information to be displayed in the interactive help window.
  171.  
  172. -
  173.  
  174. Overview
  175.  
  176. There are two levels available to users of File Box facilities:
  177.  
  178. • The *Command level allows users to access the most simple File Box
  179.   facilities from the command line of a task window, within a TaskObey or
  180.   TaskExec file, within any Desktop task or within any language running in a
  181.   task window, such as BASIC.
  182.   
  183. • The preferred level of File Box operation is the SWI level, where File Box
  184.   facilities are accessed by programmers using the sophisticated SWI calls
  185.   provided by the File Box module.
  186.  
  187. *Command protocol
  188.  
  189. To specify a filename from the command line or within a program running in a
  190. task window often involves entering a long and complicated pathname. File
  191. Box avoids this by allowing filenames to be specified using the standard
  192. file dragging procedures.
  193.  
  194. To specify the full pathname of a file to be loaded or used for input in a
  195. task window, all that is necessary is to read the value of a system
  196. variable. *Commands are also provided to allow the title, prompt and default
  197. filename which appear in the Load window to be customized.
  198.  
  199. To specify the full pathname of a file to be saved or used for output in a
  200. task window, all that is necessary is to read the value of another system
  201. variable. *Commands are also provided to allow the title, file type and
  202. default filename which appear in the Save window to be customized.
  203.  
  204. SWI protocol
  205.  
  206. Several SWIs are provided to allow sophisticated control of all
  207. File Box facilities. One SWI initiates either a Load or Save operation,
  208. involving the opening a Load or Save window, which can have various aspects
  209. customized as required. Another SWI allows polling of the progress of the
  210. Load or Save operation, and will inform your task of the user's response
  211. when it occurs. A SWI is provided to perform an entire Load operation in one
  212. step, and there is a similar SWI for Save operations. These calls are
  213. simpler to use, but offer slightly less flexibility than the two step
  214. method.
  215.  
  216. Controlling File Box
  217.  
  218. A miscellaneous SWI allows the user to control and investigate other aspects
  219. of the File Box Desktop task, such as:
  220.  
  221. • Starting, quitting and restarting the File Box task.
  222.  
  223. • Reading the task handle of the File Box task.
  224.  
  225. • Specifying either 2D or 3D windows.
  226.  
  227. • Reading the type (2D or 3D) of windows currently used by the File Box
  228.   task.
  229.   
  230. • Opening and closing the program information window.
  231.  
  232. • Moving the Load and Save windows, or forcing them to the front of the
  233.   window stack.
  234.   
  235. • Enabling or disabling the File Box system variables.
  236.  
  237. • Reading and setting various attributes of the windows opened when using
  238.   the File Box system variables.
  239.  
  240. -
  241.  
  242. Technical Details
  243.  
  244. *Command protocol
  245.  
  246. Before you can use the *Command protocol, you must enable the File Box
  247. system variables using the command:
  248.  
  249. *IOVarsOn
  250.  
  251. If you are reading many system variables at a time, you must disable the
  252. File Box variables again, so that the operating system does not attempt to
  253. read their values. The following command disables the File Box system
  254. variables:
  255.  
  256. *IOVarsOff
  257.  
  258. If the operating system does read a File Box variable while the Desktop is
  259. suspended (during *Show from ShellCLI, for example), then the computer can
  260. crash. Even if the Desktop is active, it is inconvenient if you are
  261. presented with a spurious Load or Save window while reading many system
  262. variables at a time.
  263.  
  264. Getting an input filename
  265.  
  266. To specify an input filename via File Box facilities, it is simply a matter
  267. of referring to the system variable:
  268.  
  269. FileBox$GetInputFilename
  270.  
  271. For example, if you want to *Dump a file from a task window, using File Box
  272. to specify the input filename, you simply enter the command:
  273.  
  274. *Dump <FileBox$GetInputFilename>
  275.  
  276. If you are using the File Box variables to specify an input filename from
  277. within a program, you might like to customize various attributes of the Load
  278. window using the commands:
  279.  
  280. *InputTitle <title text>
  281. *InputPrompt <prompt text>
  282. *Set FileBox$GetInputFilename <default filename>
  283.  
  284. To reset the attributes of the Load window to their default values, simply
  285. use the command:
  286.  
  287. *InputReset
  288.  
  289. Getting an output filename
  290.  
  291. To specify an output filename via File Box facilities, it is simply a matter
  292. of referring to the system variable:
  293.  
  294. FileBox$GetOutputFilename
  295.  
  296. For example, if you want to save the system sprite area contents from a task
  297. window, using File Box to specify the output filename, you simply enter the
  298. command:
  299.  
  300. *SSave <FileBox$GetOutputFilename>
  301.  
  302. If you are using the File Box variables to specify an output filename from
  303. within a program, you might like to customize various attributes of the Save
  304. window using the commands:
  305.  
  306. *OutputTitle <title text>
  307. *OutputType <filetype>
  308. *Set FileBox$GetOutputFilename <default filename>
  309.  
  310. To reset the attributes of the Save window to their default values, simply
  311. use the command:
  312.  
  313. *OutputReset
  314.  
  315. Resetting File Box
  316.  
  317. If a task window exits before File Box receives a response via a Load or
  318. Save window opened by that task window, File Box will be stuck a busy state,
  319. even after that Load or Save window is closed. In order to reset File Box so
  320. that it is no longer busy, use the command:
  321.  
  322. *ResetFileBox
  323.  
  324. SWI protocol
  325.  
  326. The following SWIs are provided by the File Box module to allow tasks to
  327. make use of File Box input file facilities:
  328.  
  329. • FileBox_InitiateLoadFromFiler (SWI &48240)
  330. • FileBox_PollLoadFromFiler (SWI &48241)
  331. • FileBox_AbortLoad (SWI &48244)
  332. • FileBox_DoLoadFromFiler (SWI &48246)
  333.  
  334. The following SWIs are provided by the File Box module to allow tasks to
  335. make use of File Box output file facilities:
  336.  
  337. • FileBox_InitiateSaveToFiler (SWI &48242)
  338. • FileBox_PollSaveToFiler (SWI &48243)
  339. • FileBox_AbortSave (SWI &48245)
  340. • FileBox_DoSaveToFiler (SWI &48247)
  341.  
  342. Getting an input filename
  343.  
  344. To obtain a filename for input via File Box facilities, the first step is to
  345. call the SWI routine FileBox_InitiateLoadFromFiler (SWI &48240), passing
  346. details specifying various elements of the Load window, such as the title
  347. text, the prompt text and the default filename. A Load window will be
  348. opened, and you will be able to poll for the user's response using the SWI
  349. routine FileBox_PollLoadFromFiler (SWI &48241). To abort the operation
  350. before the user responds, simply call FileBox_AbortLoad (SWI &48244)
  351.  
  352. The SWI routine FileBox_DoLoadFromFiler (SWI &48246) condenses all of the
  353. steps outlined above into one simple call. However, by using this routine it
  354. is not possible to perform background processing while your task is waiting
  355. for the user's response, and it is also not possible to abort the operation
  356. before the user responds (after a certain period of time has elapsed, for
  357. example).
  358.  
  359. Getting an output filename
  360.  
  361. To obtain a filename for output via File Box facilities, the first step is
  362. to call the SWI routine FileBox_InitiateSaveToFiler (SWI &48242), passing
  363. details specifying various elements of the Save window, such as the title
  364. text, the sprite name of the file icon and the default filename. A Save
  365. window will be opened, and you will be able to poll for the user's response
  366. using the SWI routine FileBox_PollSaveToFiler (SWI &48243). To abort the
  367. operation before the user responds, simply call FileBox_AbortLoad (SWI
  368. &48245)
  369.  
  370. The SWI routine FileBox_DoSaveToFiler (SWI &48247) condenses all of the
  371. steps outlined above into one simple call. However, by using this routine it
  372. is not possible to perform background processing while your task is waiting
  373. for the user's response, and it is also not possible to abort the operation
  374. before the user responds.
  375.  
  376. Controlling File Box
  377.  
  378. The multi-purpose SWI routine FileBox_Control (SWI &48248) provides
  379. miscellaneous control functions. Its primary purpose is to control the File
  380. Box Desktop task, and many reason codes cause communications with the File
  381. Box task via a semaphore mechanism. Because communication with the File Box
  382. task via FileBox_Control is not instantaneous, two other calls allow you to
  383. wait for an operation to be completed or abandon the current operation.
  384. These SWI routines are FileBox_PollControl (SWI &48249) and
  385. FileBox_AbortControl (SWI &4824A).
  386.  
  387. The FileBox_Control SWI also provides direct access to and control over the
  388. *Command protocol. These calls are faster than their corresponding *Command
  389. and often provide more control. However, it is recommended that the
  390. preferred SWI protocol be used instead.
  391.  
  392. Support for FiletypeExtend
  393.  
  394. FileBox supports the Kasoft FiletypeExtend extension, and the routines it
  395. uses to allow this have been made publicly available through the SWI routine
  396. FileBox_FiletypeExtendOp (SWI &4824B).
  397.  
  398. File Box errors
  399.  
  400. The errors generated by the File Box module are described here. The SWI
  401. chunk number (&48240) should be added to the error numbers given here to get
  402. the full error number.
  403.  
  404. FileBox busy on Load
  405.  
  406. File Box error number 0. This error occurs when an attempt is made to open a
  407. Load window while a Load operation is still in progress, If this error
  408. occurs repeatedly, call the routine FileBox_AbortLoad (SWI &48244).
  409.  
  410. FileBox inactive on Load
  411.  
  412. File Box error number 1. This error occurs when an attempt is made to poll a
  413. Load operation when none is in progress. This may occur when another task
  414. calls FileBox_AbortLoad (SWI &48244) while your task is polling.
  415.  
  416. FileBox busy on Save
  417.  
  418. File Box error number 2. This error occurs when an attempt is made to open a
  419. Save window while a Save operation is still in progress, If this error
  420. occurs repeatedly, call the routine FileBox_AbortSave (SWI &48245).
  421.  
  422. FileBox inactive on Save
  423.  
  424. File Box error number 3. This error occurs when an attempt is made to poll a
  425. Save operation when none is in progress. This may occur when another task
  426. calls FileBox_AbortSave (SWI &48244) while your task is polling.
  427.  
  428. Bad FileBox_Control reason code
  429.  
  430. File Box error number 8. This error occurs if FileBox_Control (SWI &48248)
  431. is passed a reason code which has no defined purpose. Currently valid reason
  432. codes for FileBox_Control are in the range 0-32 (inclusive).
  433.  
  434. FileBox busy on Control
  435.  
  436. File Box error number 9. This error occurs when the user attempts to perform
  437. a control action when a previously specified action has not yet been
  438. completed. Your task must either wait until FileBox_PollControl (SWI &48249)
  439. returns 0, or abort the current operation, using the routine
  440. FileBox_AbortControl (SWI &4824A), before the new operation can be carried
  441. out.
  442.  
  443. File Box task is already active
  444.  
  445. File Box error number 62. This error occurs when an attempt is made to start
  446. the File Box Desktop task when it is already registered with the Wimp.
  447.  
  448. FileBox task is inactive
  449.  
  450. File Box error number 63. This error occurs when an operation which requires
  451. the presence of the File Box Desktop task is attempted. Use FileBox_Control
  452. 0 (SWI &48248) or *Desktop to start the File Box task.
  453.  
  454. -
  455.  
  456. SWI Calls
  457.  
  458. -
  459.  
  460. FileBox_InitiateLoadFromFiler
  461. (SWI &48240)
  462.  
  463. Initiates a File Box Load operation which only accepts files dragged from
  464. Filer windows
  465.  
  466. On entry:
  467.  
  468. R0 = pointer to title text (maximum 16 characters, including null)
  469. R1 = pointer to prompt text (maximum 16 characters, including null)
  470. R2 = pointer to default filename
  471.  
  472. On exit:
  473.  
  474. R0-R2 preserved
  475.  
  476. Interrupts:
  477.  
  478. Interrupt status is not defined
  479. Fast interrupts are enabled
  480.  
  481. Processor mode:
  482.  
  483. Processor is in SVC mode
  484.  
  485. Re-entrancy:
  486.  
  487. Not defined
  488.  
  489. Use:
  490.  
  491. If the File Box task is not registered with the Wimp, the error File Box
  492. task is inactive is returned. If you try to start the File Box task using
  493. *Desktop or FileBox_Control 0 (SWI &48248) after getting this error, you may
  494. find that repeating the call is successful.
  495.  
  496. If a Load window is not already open, then a window is opened on the Desktop
  497. ready to accept a file dragged to it from a Filer window, or a filename
  498. typed into its writable icon. The title text is used in the Load window's
  499. title bar and the prompt appears above the default filename.
  500.  
  501. If a Load window is already open, the error FileBox busy on Load is
  502. produced.
  503.  
  504. After making this call, it is expected that the caller will repeatedly poll
  505. for a response using FileBox_PollLoadFromFiler (SWI &48241).
  506.  
  507. Related SWIs:
  508.  
  509. FileBox_PollLoadFromFiler (SWI &48241), FileBox_AbortLoad (SWI &48244).
  510. FileBox_DoLoadFromFiler (SWI &48246)
  511.  
  512. Related vectors:
  513.  
  514. None
  515.  
  516. -
  517.  
  518. FileBox_PollLoadFromFiler
  519. (SWI &48241)
  520.  
  521. Reports on the progress of the current File Box Load operation (from a Filer
  522. window)
  523.  
  524. On entry:
  525.  
  526. R2 = pointer to filename buffer
  527.  
  528. On exit:
  529.  
  530. R0 = status indicator
  531. R1 = filetype if file dragged, otherwise preserved
  532. R2 = pointer to updated filename buffer if file specified, otherwise
  533.      preserved
  534.  
  535. Interrupts:
  536.  
  537. Interrupt status is not defined
  538. Fast interrupts are enabled
  539.  
  540. Processor mode:
  541.  
  542. Processor is in SVC mode
  543.  
  544. Re-entrancy:
  545.  
  546. Not defined
  547.  
  548. Use:
  549.  
  550. This call should only be made after FileBox_InitiateLoadFromFiler (SWI
  551. &48240) has been called.
  552.  
  553. If no Load operation is underway then the error FileBox inactive on Load is
  554. produced.
  555.  
  556. If the File Box Desktop task has been killed since the call to
  557. FileBox_InitiateLoadFromFiler then the error File Box task is inactive will
  558. be returned. In this case you can attempt to restart File Box using *Desktop
  559. or FileBox_Control 0 (SWI &48248). If this fails (as will be revealed by a
  560. subsequent call), you must call FileBox_AbortLoad (SWI &48244).
  561.  
  562. The status indicators returned in R0 are:
  563.  
  564. R0  Meaning
  565. -1  File Box is waiting for a user response. Continue to poll.
  566. 0   Load window was closed, and the Load operation abandoned.
  567. 1   A name was typed, and Return pressed or OK clicked upon. The buffer at
  568.     R2 is updated to contain the filename entered.
  569. 2   A file was dragged to the Load window. R1 is set to the filetype, and
  570.     the buffer at R2 is updated to contain the full pathname of the file.
  571.  
  572. When the user responds (R0 > -1), File Box automatically closes the Load
  573. window and becomes inactive in preparation for the next Load operation. If,
  574. for some reason, you do not want to continue polling (if *Desktop failed to
  575. restart the File Box Desktop task, for instance) you must call
  576. FileBox_AbortLoad, so that other callers may make use of the File Box
  577. loading facilities.
  578.  
  579. Related SWIs:
  580.  
  581. FileBox_InitiateLoadFromFiler (SWI &48240), FileBox_AbortLoad (SWI &48244).
  582. FileBox_DoLoadFromFiler (SWI &48246)
  583.  
  584. Related vectors:
  585.  
  586. None
  587.  
  588. -
  589.  
  590. FileBox_InitiateSaveToFiler
  591. (SWI &48242)
  592.  
  593. Initiates a File Box Save operation which only allows files to be dragged to
  594. Filer windows
  595.  
  596. On entry:
  597.  
  598. R0 = pointer to title text (maximum 16 characters, including null)
  599. R1 = pointer to file sprite name (maximum 16 characters, including null)
  600. R2 = pointer to default filename
  601. R3 = filetype
  602.  
  603. On exit:
  604.  
  605. R0-R3 preserved
  606.  
  607. Interrupts:
  608.  
  609. Interrupt status is not defined
  610. Fast interrupts are enabled
  611.  
  612. Processor mode:
  613.  
  614. Processor is in SVC mode
  615.  
  616. Re-entrancy:
  617.  
  618. Not defined
  619.  
  620. Use:
  621.  
  622. If the File Box task is not registered with the Wimp, the error File Box
  623. task is inactive is returned. If you try to start the File Box task using
  624. *Desktop or FileBox_Control 0 (SWI &48248) after getting this error, you may
  625. find that repeating the call is successful.
  626.  
  627. If a Save window is not already open, then a window is opened on the Desktop
  628. ready to have its file icon dragged to a Filer window or to have a name
  629. typed into its writable icon. The title text is used in the Save window's
  630. title bar and the default filename appears in the writable icon. If a Save
  631. window is already open, the error FileBox busy on Save is produced.
  632.  
  633. After making this call, it is expected that the caller will repeatedly poll
  634. for a response using FileBox_PollSaveToFiler (SWI &48242).
  635.  
  636. Related SWIs:
  637.  
  638. FileBox_PollSaveToFiler (SWI &48243), FileBox_AbortSave (SWI &48245),
  639. FileBox_DoSaveToFiler (SWI &48247)
  640.  
  641. Related vectors:
  642.  
  643. None
  644.  
  645. -
  646.  
  647. FileBox_PollSaveToFiler
  648. (SWI &48243)
  649.  
  650. Reports on the progress of the current File Box Save operation (to a Filer
  651. window)
  652.  
  653. On entry:
  654.  
  655. R2 = pointer to filename buffer
  656.  
  657. On exit:
  658.  
  659. R0 = status indicator
  660. R1 preserved
  661. R2 = pointer to updated filename buffer if file specified, otherwise
  662.      preserved
  663.  
  664. Interrupts:
  665.  
  666. Interrupt status is not defined
  667. Fast interrupts are enabled
  668.  
  669. Processor mode:
  670.  
  671. Processor is in SVC mode
  672.  
  673. Re-entrancy:
  674.  
  675. Not defined
  676.  
  677. Use:
  678.  
  679. This call should only be made after FileBox_InitiateSaveToFiler (SWI &48242)
  680. has been called.
  681.  
  682. If no Save operation is underway then the error FileBox inactive on Save is
  683. produced.
  684.  
  685. If the File Box Desktop task has been killed since the call to
  686. FileBox_InitiateSaveToFiler then the error File Box task is inactive will be
  687. returned. In this case you can attempt to restart File Box using *Desktop or
  688. FileBox_Control 0 (SWI &48248). If this fails (as will be revealed by a
  689. subsequent call), you must call FileBox_AbortSave (SWI &48245).
  690.  
  691. The status indicators returned in R0 are:
  692.  
  693. R0  Meaning
  694. -1  File Box is waiting for a user response. Continue to poll.
  695. 0   Save window was closed, and the Save operation abandoned.
  696. 1   A name was typed, and Return pressed or OK clicked upon. The buffer at
  697.     R2 is updated to contain the filename entered.
  698. 2   The file icon was dragged from the Save window into a Filer display. The 
  699.     buffer at R2 is updated to contain the full pathname of the drag
  700.     destination.
  701.  
  702. When the user responds (R0 > -1), FileBox automatically closes the Save
  703. window and becomes inactive in preparation for the next Save operation. If,
  704. for some reason, you do not want to continue polling (if *Desktop failed to
  705. restart the File Box Desktop task, for instance) you must call
  706. FileBox_AbortSave, so that other callers may make use of the File Box saving
  707. facilities.
  708.  
  709. Related SWIs:
  710.  
  711. FileBox_InitiateSaveToFiler (SWI &48242), FileBox_AbortSave (SWI &48245).
  712. FileBox_DoSaveToFiler (SWI &48247)
  713.  
  714. Related vectors:
  715.  
  716. None
  717.  
  718. -
  719.  
  720. FileBox_AbortLoad
  721. (SWI &48244)
  722.  
  723. Aborts the current File Box Load operation
  724.  
  725. On entry:
  726.  
  727. -
  728.  
  729. On exit:
  730.  
  731. -
  732.  
  733. Interrupts:
  734.  
  735. Interrupt status is not defined
  736. Fast interrupts are enabled
  737.  
  738. Processor mode:
  739.  
  740. Processor is in SVC mode
  741.  
  742. Re-entrancy:
  743.  
  744. Not defined
  745.  
  746. Use:
  747.  
  748. This call should only be made by the task currently calling
  749. FileBox_PollLoadFromFiler (SWI &48241) in order to abort the current Load
  750. operation and close the File Box loading window.
  751.  
  752. If no Load operation is underway, this SWI will return without signalling an
  753. error.
  754.  
  755. If a Load operation is pending (it has been initiated, but as yet the File
  756. Box task has not opened a Load window), this SWI call will force File Box
  757. into an inactive state.
  758.  
  759. If a Load operation is underway, the window will be closed and this SWI call
  760. will force File Box into an inactive state.
  761.  
  762. If a Load operation has been completed (and the window has been closed) but
  763. the result has not been returned through polling, this operation will force
  764. File Box into an inactive state.
  765.  
  766. Any task which continues to poll after this SWI has been called will receive
  767. the error FileBox inactive on Load.
  768.  
  769. Related SWIs:
  770.  
  771. FileBox_InitiateLoadFromFiler (SWI &48240),
  772. FileBox_PollLoadFromFiler (SWI &48241)
  773.  
  774. Related vectors:
  775.  
  776. None
  777.  
  778. -
  779.  
  780. FileBox_AbortSave
  781. (SWI &48245)
  782.  
  783. Aborts the current File Box Save operation
  784.  
  785. On entry:
  786.  
  787. -
  788.  
  789. On exit:
  790.  
  791. -
  792.  
  793. Interrupts:
  794.  
  795. Interrupt status is not defined
  796. Fast interrupts are enabled
  797.  
  798. Processor mode:
  799.  
  800. Processor is in SVC mode
  801.  
  802. Re-entrancy:
  803.  
  804. Not defined
  805.  
  806. Use:
  807.  
  808. This call should only be made by the task currently calling
  809. FileBox_PollSaveToFiler (SWI &48243) in order to abort the current Save
  810. operation and close the File Box saving window.
  811.  
  812. If no Save operation is underway, this SWI will return without signalling an
  813. error.
  814.  
  815. If a Save operation is pending (it has been initiated, but as yet the File
  816. Box task has not opened a Save window), this SWI call will force File Box
  817. into an inactive state.
  818.  
  819. If a Save operation is underway, the window will be closed and this SWI call
  820. will force File Box into an inactive state.
  821.  
  822. If a Save operation has been completed (and the window has been closed) but
  823. the result has not been returned through polling, this operation will force
  824. File Box into an inactive state.
  825.  
  826. Any task which continues to poll after this SWI has been called will receive
  827. the error FileBox inactive on Save.
  828.  
  829. Related SWIs:
  830.  
  831. FileBox_InitiateSaveToFiler (SWI &48242),
  832. FileBox_PollSaveToFiler (SWI &48243)
  833.  
  834. Related vectors:
  835.  
  836. None
  837.  
  838. -
  839.  
  840. FileBox_DoLoadFromFiler
  841. (SWI &48246)
  842.  
  843. Performs a complete File Box Load operation
  844.  
  845. On entry:
  846.  
  847. R0 = pointer to title text (maximum 16 characters, including null)
  848. R1 = pointer to prompt text (maximum 16 characters, including null)
  849. R2 = pointer to filename buffer (containing default filename)
  850.  
  851. On exit:
  852.  
  853. R0 = result indicator
  854. R1 = filetype if file dragged, otherwise preserved
  855. R2 = pointer to updated filename buffer if file specified, otherwise
  856.      preserved
  857.  
  858. Interrupts:
  859.  
  860. Interrupts are enabled
  861. Fast interrupts are enabled
  862.  
  863. Processor mode:
  864.  
  865. Processor is in SVC mode
  866.  
  867. Re-entrancy:
  868.  
  869. Not defined
  870.  
  871. Use:
  872.  
  873. If the File Box task is not registered with the Wimp, the error File Box
  874. task is inactive is returned. If you try to start the File Box task using
  875. *Desktop or FileBox_Control 0 (SWI &48248) after getting this error, you may
  876. find that repeating the call is successful.
  877.  
  878. If a Load window is not already open, then a window is opened on the Desktop
  879. ready to accept a file dragged to it from a Filer window, or a filename
  880. typed into its writable icon. The title text is used in the Load window's
  881. title bar and the prompt appears above the default filename.
  882.  
  883. If a Load window is already open, the error FileBox busy on Load is
  884. produced. After opening a Load window, this call will repeatedly poll until
  885. the user responds or the Escape key is pressed whilst the calling task has
  886. the input focus.
  887.  
  888. If the Escape key is pressed (and the calling task has the input focus) then
  889. the error Escape will be returned and the Load operation aborted (the Load
  890. window will be closed).
  891.  
  892. If the File Box Desktop task is killed during the polling process then the
  893. error File Box task is inactive will be returned. In this case you can
  894. attempt to restart File Box using *Desktop or FileBox_Control 0 (SWI
  895. &48248).
  896.  
  897. Upon getting a user response, one of the following result indicators is
  898. returned in R0:
  899.  
  900. R0  Meaning
  901. 0   Load window was closed, and the Load operation abandoned.
  902. 1   A name was typed, and Return pressed or OK clicked upon. The buffer at
  903.     R2 is updated to contain the filename entered.
  904. 2   A file was dragged to the Load window. R1 is set to the filetype, and
  905.     the buffer at R2 is updated to contain the full pathname of the file.
  906.  
  907. When the user responds, File Box automatically closes the Load window and
  908. becomes inactive in preparation for the next Load operation.
  909.  
  910. Related SWIs:
  911.  
  912. FileBox_InitiateLoadFromFiler (SWI &48240),
  913. FileBox_PollLoadFromFiler (SWI &48241)
  914.  
  915. Related vectors:
  916.  
  917. None
  918.  
  919. -
  920.  
  921. FileBox_DoSaveToFiler
  922. (SWI &48247)
  923.  
  924. Performs a complete File Box Save operation
  925.  
  926. On entry:
  927.  
  928. R0 = pointer to title text (maximum 16 characters, including null)
  929. R1 = pointer to file sprite name (maximum 16 characters, including null)
  930. R2 = pointer to filename buffer (containing default filename)
  931. R3 = filetype
  932.  
  933. On exit:
  934.  
  935. R0 = result indicator
  936. R2 = pointer to updated filename buffer if file specified, otherwise
  937.      preserved
  938.  
  939. Interrupts:
  940.  
  941. Interrupts are enabled
  942. Fast interrupts are enabled
  943.  
  944. Processor mode:
  945.  
  946. Processor is in SVC mode
  947.  
  948. Re-entrancy:
  949.  
  950. Not defined
  951.  
  952. Use:
  953.  
  954. If the File Box task is not registered with the Wimp, the error File Box
  955. task is inactive is returned. If you try to start the File Box task using
  956. *Desktop or FileBox_Control 0 (SWI &48248) after getting this error, you may
  957. find that repeating the call is successful.
  958.  
  959. If a Save window is not already open, then a window is opened on the Desktop
  960. ready to have its file icon dragged to a Filer window or to have a name
  961. typed into its writable icon. The title text is used in the Save window's
  962. title bar and the default filename appears in the writable icon.
  963.  
  964. If a Save window is already open, the error FileBox busy on Save is
  965. produced.
  966.  
  967. After opening a Save window, this call will repeatedly poll until the user
  968. responds or the Escape key is pressed whilst the calling task has the input
  969. focus.
  970.  
  971. If the Escape key is pressed (and the calling task has the input focus) then
  972. the error Escape will be returned and the Load operation aborted (the
  973. loading window will be closed).
  974.  
  975. If the File Box Desktop task is killed during the polling process then the
  976. error File Box task is inactive will be returned. In this case you can
  977. attempt to restart File Box using *Desktop or FileBox_Control 0 (SWI
  978. &48248).
  979.  
  980. Upon getting a user response, one of the following result indicators is
  981. returned in R0:
  982.  
  983. R0  Meaning
  984. 0   Save window was closed, and the Save operation abandoned.
  985. 1   A name was typed, and Return pressed or OK clicked upon. The buffer at
  986.     R2 is updated to contain the filename entered.
  987. 2   The file icon was dragged from the Save window into a Filer display. The 
  988.     buffer at R2 is updated to contain the full pathname of the drag
  989.     destination.
  990.  
  991. When the user responds, File Box automatically closes the Save window and
  992. becomes inactive in preparation for the next Save operation.
  993.  
  994. Related SWIs:
  995.  
  996. FileBox_InitiateSaveToFiler (SWI &48242),
  997. FileBox_PollSaveToFiler (SWI &48243)
  998.  
  999. Related vectors:
  1000.  
  1001. None
  1002.  
  1003. -
  1004.  
  1005. FileBox_Control
  1006. (SWI &48248)
  1007.  
  1008. Perform miscellaneous control actions
  1009.  
  1010. On entry:
  1011.  
  1012. R0 = reason code
  1013. Other registers depend on reason code
  1014.  
  1015. On exit:
  1016.  
  1017. R0 preserved
  1018. Other registers depend on reason code
  1019.  
  1020. Interrupts:
  1021.  
  1022. Interrupt status is not defined
  1023. Fast interrupts are enabled
  1024.  
  1025. Processor mode:
  1026.  
  1027. Processor is in SVC mode
  1028.  
  1029. Re-entrancy:
  1030.  
  1031. Not defined
  1032.  
  1033. Use:
  1034.  
  1035. The action carried out by FileBox_Control is determined by the reason code
  1036. in R0 as follows:
  1037.  
  1038. R0  Action
  1039. 0   Start File Box task
  1040. 1   Quit File Box task
  1041. 2   Restart File Box task
  1042. 3   Return task handle of File Box task
  1043. 4   Use 2D windows (effective from next start/restart)
  1044. 5   Use 3D windows (effective from next start/restart)
  1045. 6   Use appropriate windows, based on bit 0 of CMOS byte 140 (effective from 
  1046.     next start/restart)
  1047. 7   Read current window style (effective from next start/restart)
  1048. 8   Open program information dialogue box (or bring to front)
  1049. 9   Close program information dialogue box (or bring to front)
  1050. 10  Move Load window (or bring to front)
  1051. 11  Move Save window (or bring to front)
  1052. 12  Enable File Box system variables
  1053. 13  Disable File Box system variables
  1054. 14  Read input variable name
  1055. 15  Read window title for input variable
  1056. 16  Set window title for input variable
  1057. 17  Restore default window title for input variable
  1058. 18  Read prompt text for input variable
  1059. 19  Set prompt text for input variable
  1060. 20  Restore default prompt text for input variable
  1061. 21  Read default filename for input and output variable
  1062. 22  Set default filename for input and output variable
  1063. 23  Restore null string as default filename for input and output variables
  1064. 24  Restore default title, prompt and filename for input variable
  1065. 25  Read output variable name
  1066. 26  Read window title for output variable
  1067. 27  Set window title for output variable
  1068. 28  Restore default window title for output variable
  1069. 29  Read filetype for output variable
  1070. 30  Set filetype for output variable
  1071. 31  Restore default filetype for output variable
  1072. 32  Restore default title, filetype and filename for output variable
  1073.  
  1074. For details on each of these reason codes, see below.
  1075.  
  1076. Related SWIs:
  1077.  
  1078. FileBox_PollControl (SWI &48249), FileBox_AbortControl (SWI &4824A)
  1079.  
  1080. Related vectors:
  1081.  
  1082. None
  1083.  
  1084. -
  1085.  
  1086. FileBox_Control 0 to 2
  1087. (SWI &48248)
  1088.  
  1089. Starts, quits or restarts the File Box Desktop task
  1090.  
  1091. On entry:
  1092.  
  1093. R0 = 0, 1 or 2
  1094.  
  1095. On exit:
  1096.  
  1097. R0 preserved
  1098.  
  1099. Use:
  1100.  
  1101. FileBox_Control 0 attempts to start the File Box task immediately. If the
  1102. File Box task is already running then the error File Box task is already
  1103. active is generated.
  1104.  
  1105. FileBox_Control 1 attempts to cause the File Box task to exit. This action
  1106. is queued until File Box next returns from polling the Wimp.
  1107.  
  1108. FileBox_Control 2 attempts to cause the File Box task to exit and then be
  1109. restarted. This will ensure that the correct set of windows (2D or 3D) is in
  1110. use. This action is queued until File Box next returns from polling the
  1111. Wimp.
  1112.  
  1113. -
  1114.  
  1115. FileBox_Control 3
  1116. (SWI &48248)
  1117.  
  1118. Returns task handle of File Box Desktop task
  1119.  
  1120. On entry:
  1121.  
  1122. R0 = 3
  1123.  
  1124. On exit:
  1125.  
  1126. R0 preserved
  1127. R1 = task handle, or 0 or -1 if File Box task is inactive
  1128.  
  1129. Use:
  1130.  
  1131. If the File Box task is registered with the Wimp, this call returns the task
  1132. handle by which the Wimp refers to the task in R1. If the File Box task is
  1133. unregistered, R1 = 0 or -1 on exit.
  1134.  
  1135. -
  1136.  
  1137. FileBox_Control 4 to 6
  1138. (SWI &48248)
  1139.  
  1140. Sets the style of windows currently in use
  1141.  
  1142. On entry:
  1143.  
  1144. R0 = 4, 5 or 6
  1145.  
  1146. On exit:
  1147.  
  1148. R0 preserved
  1149.  
  1150. Use:
  1151.  
  1152. FileBox_Control 4 selects 2D-style windows.
  1153.  
  1154. FileBox_Control 5 selects 3D-style windows.
  1155.  
  1156. FileBox_Control 6 selects the appropriate window style based on the
  1157. computer's configuration. Specifically, it selects 3D-style windows only if
  1158. bit 0 of CMOS RAM byte number 140 is set, and 2D-style windows otherwise.
  1159. Window style selections only come into effect the next time the File Box
  1160. Desktop task is started or restarted, using FileBox_Control 0 or 2.
  1161.  
  1162. -
  1163.  
  1164. FileBox_Control 7
  1165. (SWI &48248)
  1166.  
  1167. Returns the style of windows currently in use
  1168.  
  1169. On entry:
  1170.  
  1171. R0 = 7
  1172.  
  1173. On exit:
  1174.  
  1175. R0 preserved
  1176. R1 = style number
  1177.  
  1178. Use:
  1179.  
  1180. The value of R0 on exit corresponds to the style of windows that will be
  1181. selected on the next start or restart of the File Box task:
  1182.  
  1183. R0  Meaning
  1184. 0   Window style will based on computer's configuration (bit 0 of CMOS RAM
  1185.     byte number 140).
  1186. 2   2D-style windows will be selected
  1187. 3   3D-style windows will be selected
  1188.  
  1189. -
  1190.  
  1191. FileBox_Control 8
  1192. (SWI &48248)
  1193.  
  1194. Open program information dialogue box
  1195.  
  1196. On entry:
  1197.  
  1198. R0 = 8
  1199. R1 = screen x-coordinate of top edge of window visible area (in OS units)
  1200. R2 = screen y-coordinate of left edge of window visible area (in OS units)
  1201.  
  1202. On exit:
  1203.  
  1204. R0-R2 preserved
  1205.  
  1206. Use:
  1207.  
  1208. This call opens the program information window at the given position on the
  1209. screen. If this window is already open, it is moved to the new position
  1210. specified. This action is queued until the File Box task next returns from
  1211. polling the Wimp.
  1212.  
  1213. -
  1214.  
  1215. FileBox_Control 9
  1216. (SWI &48248)
  1217.  
  1218. Close program information dialogue box
  1219.  
  1220. On entry:
  1221.  
  1222. R0 = 9
  1223.  
  1224. On exit:
  1225.  
  1226. R0 preserved
  1227.  
  1228. Use:
  1229.  
  1230. This call closes the program information window if it isn't already closed.
  1231. This action is queued until the File Box task next returns from polling the
  1232. Wimp.
  1233.  
  1234. -
  1235.  
  1236. FileBox_Control 10 and 11
  1237. (SWI &48248)
  1238.  
  1239. Move the Load or Save window (or bring it to the front of the window stack)
  1240.  
  1241. On entry:
  1242.  
  1243. R0 = 10 or 11
  1244. R1 = screen x-coordinate of top edge of window visible area (in OS units)
  1245. R2 = screen y-coordinate of left edge of window visible area (in OS units)
  1246.  
  1247. On exit:
  1248.  
  1249. R0-R2 preserved
  1250.  
  1251. Use:
  1252.  
  1253. FileBox_Control 10 moves the Load window (if it is open) to the position
  1254. specified.
  1255.  
  1256. FileBox_Control 11 moves the Save window (if it is open) to the position
  1257. specified.
  1258.  
  1259. If R1 = -1 on entry, the relevant window is not moved, but merely
  1260. brought to the front of the window stack in in its current position.
  1261.  
  1262. These actions are queued until the File Box task next returns from polling
  1263. the Wimp.
  1264.  
  1265. -
  1266.  
  1267. FileBox_Control 12 and 13
  1268. (SWI &48248)
  1269.  
  1270. Enables or disables the File Box system variables
  1271.  
  1272. On entry:
  1273.  
  1274. R0 = 12 or 13
  1275.  
  1276. On exit:
  1277.  
  1278. R0 preserved
  1279.  
  1280. Use:
  1281.  
  1282. FileBox_Control 12 enables the File Box system variables
  1283. FileBox$GetInputFilename and FileBox$GetOutputFilename.
  1284.  
  1285. FileBox_Control 13 disables these system variables.
  1286.  
  1287. -
  1288.  
  1289. FileBox_Control 14 and 25
  1290. (SWI &48248)
  1291.  
  1292. Read input or output system variable name
  1293.  
  1294. On entry:
  1295.  
  1296. R0 = 14 or 25
  1297. R1 = pointer to buffer to contain name of system variable (at least 32 bytes)
  1298.  
  1299. On exit:
  1300.  
  1301. R0 preserved
  1302. R1 = pointer to updated buffer containing name of requested system variable
  1303.      (null terminated)
  1304.  
  1305. Use:
  1306.  
  1307. These call returns a null terminated string in the specified buffer based on
  1308. the reason code:
  1309.  
  1310. R0  String returned
  1311. 14  FileBox$GetInputFilename
  1312. 25  FileBox$GetOutputFilename
  1313.  
  1314. -
  1315.  
  1316. FileBox_Control 15, 18, 21, 26 and 29
  1317. (SWI &48248)
  1318.  
  1319. Read attributes of Load and Save windows used by File Box system variables
  1320.  
  1321. On entry:
  1322.  
  1323. R0 = 15, 18, 21, 26 or 29
  1324. R1 = pointer to buffer to contain string (see below for minimum buffer size)
  1325.  
  1326. On exit:
  1327.  
  1328. R0 preserved
  1329. R1 = pointer to updated buffer containing null terminated string
  1330.  
  1331. Use:
  1332.  
  1333. These calls returns a null terminated string in the specified buffer based
  1334. on the reason code:
  1335.  
  1336. R0  String returned
  1337. 15  Window title used by input variable (up to 16 characters, including
  1338.     null)
  1339. 18  Prompt text used by input variable (up to 16 characters, including null)
  1340. 21  Default filename used by both input and output variables (up to 256
  1341.     characters, including null)
  1342. 26  Window title used by output variable (up to 16 characters, including
  1343.     null)
  1344. 29  Hexadecimal filetype number used by output variable (up to 4 characters
  1345.     including null) or xxx, indicating no filetype.
  1346.  
  1347. -
  1348.  
  1349. FileBox_Control 16, 19, 22, 27 and 30
  1350. (SWI &48248)
  1351.  
  1352. Set attributes of Load and Save windows used by File Box system variables
  1353.  
  1354. On entry:
  1355.  
  1356. R0 = 16, 19, 22, 27 or 30
  1357. R1 = pointer to buffer containing null terminated string
  1358.  
  1359. On exit:
  1360.  
  1361. R0,R1 preserved
  1362.  
  1363. Use:
  1364.  
  1365. These calls change an input or output variable Load/Save window attribute
  1366. string, depending on the reason code:
  1367.  
  1368. R0  Attribute written
  1369. 16  Window title used by input variable (up to 16 characters, including
  1370.     null)
  1371. 19  Prompt text used by input variable (up to 16 characters, including null)
  1372. 22  Default filename used by both input and output variables (up to 256
  1373.     characters, including null)
  1374. 27  Window title used by output variable (up to 16 characters, including
  1375.     null)
  1376. 30  Filetype used by output variable (up to 9 characters, including null).
  1377.     The string passed may be a hexadecimal filetype number, the filetype
  1378.     textual equivalent or xxx, indicating no filetype. A Bad file type 
  1379.     error will be generated if the filetype is not recognized.
  1380.  
  1381. -
  1382.  
  1383. FileBox_Control 17, 20, 23, 24, 28, 31 and 32
  1384. (SWI &48248)
  1385.  
  1386. Restore default attributes for Load and Save windows used by File Box system
  1387. variables
  1388.  
  1389. On entry:
  1390.  
  1391. R0 = 17, 20, 23, 24, 28, 31 or 32
  1392.  
  1393. On exit:
  1394.  
  1395. R0,R1 preserved
  1396.  
  1397. Use:
  1398.  
  1399. These restore default values for specific attributes, depending on the
  1400. reason code:
  1401.  
  1402. R0  Attribute written
  1403. 17  Window title used by input variable is set to Input from:
  1404. 20  Prompt text used by input variable is set to Filename:
  1405. 23  Default filename used by both input and output variables is set to an
  1406.     empty string
  1407. 24  All default input variable Load window attributes
  1408. 28  Window title used by output variable is set to Output to:
  1409. 31  Filetype used by output variable is set to none (xxx), represented by a
  1410.     white box icon.
  1411. 32  All default output variable Save window attributes
  1412.  
  1413. -
  1414.  
  1415. FileBox_PollControl
  1416. (SWI &48249)
  1417.  
  1418. Return the number of the control action currently in progress
  1419.  
  1420. On entry:
  1421.  
  1422. -
  1423.  
  1424. On exit:
  1425.  
  1426. R0 = reason code corresponding to current control action (0 means no action
  1427.      in progress)
  1428.  
  1429. Interrupts:
  1430.  
  1431. Interrupt status is not defined
  1432. Fast interrupts are enabled
  1433.  
  1434. Processor mode:
  1435.  
  1436. Processor is in SVC mode
  1437.  
  1438. Re-entrancy:
  1439.  
  1440. Not defined
  1441.  
  1442. Use:
  1443.  
  1444. This call returns the reason code corresponding to the currently queued
  1445. FileBox_Control action. If R0 = 0 on exit, then no action is waiting to be
  1446. carried out.
  1447.  
  1448. Related SWIs:
  1449.  
  1450. FileBox_Control (SWI &48248), FileBox_AbortControl (SWI &4824A)
  1451.  
  1452. Related vectors:
  1453.  
  1454. None
  1455.  
  1456. -
  1457.  
  1458. FileBox_AbortControl
  1459. (SWI &4824A)
  1460.  
  1461. Abort any control action currently in progress
  1462.  
  1463. On entry:
  1464.  
  1465. -
  1466.  
  1467. On exit:
  1468.  
  1469. R0 = reason code corresponding to previous control action state
  1470.  
  1471. Interrupts:
  1472.  
  1473. Interrupt status is not defined
  1474. Fast interrupts are enabled
  1475.  
  1476. Processor mode:
  1477.  
  1478. Processor is in SVC mode
  1479.  
  1480. Re-entrancy:
  1481.  
  1482. Not defined
  1483.  
  1484. Use:
  1485.  
  1486. This call returns the reason code corresponding to the previously queued
  1487. FileBox_Control action, which has since been removed from the queue by this
  1488. call. If R0 = 0 on exit, then no action is waiting to be carried out, and
  1489. this call has no effect.
  1490.  
  1491. Related SWIs:
  1492.  
  1493. FileBox_Control (SWI &48248), FileBox_PollControl (SWI &48249)
  1494.  
  1495. Related vectors:
  1496.  
  1497. None
  1498.  
  1499. -
  1500.  
  1501. FileBox_FiletypeExtendOp
  1502. (SWI &4824B)
  1503.  
  1504. Support routines for FiletypeExtend
  1505.  
  1506. On entry:
  1507.  
  1508. R0 = reason code
  1509. Other registers depend on reason code
  1510.  
  1511. On exit:
  1512.  
  1513. R0 preserved
  1514. Other registers depend on reason code
  1515.  
  1516. Interrupts:
  1517.  
  1518. Interrupt status is not defined
  1519. Fast interrupts are enabled
  1520.  
  1521. Processor mode:
  1522.  
  1523. Processor is in SVC mode
  1524.  
  1525. Re-entrancy:
  1526.  
  1527. Not defined
  1528.  
  1529. Use:
  1530.  
  1531. The action carried out by FileBox_FiletypeExtendOp is determined by the reason code in R0 as follows:
  1532.  
  1533. R0 Action
  1534. 0  Generate large icon name
  1535. 1  Generate small icon name
  1536. 2  Load address to raw filetype
  1537. 3  Map raw filetype
  1538.  
  1539. For details on each of these reason codes, see below.
  1540.  
  1541. Related SWIs:
  1542.  
  1543. None
  1544.  
  1545. Related vectors:
  1546.  
  1547. None
  1548.  
  1549. -
  1550.  
  1551. FileBox_FiletypeExtendOp 0 and 1
  1552. (SWI &4824B)
  1553.  
  1554. Generate large or small icon name
  1555.  
  1556. On entry:
  1557.  
  1558. R0 = 0 or 1
  1559. R1 = filetype number
  1560. R2 = buffer for sprite name
  1561.  
  1562. On exit:
  1563.  
  1564. R0-R2 preserved
  1565.  
  1566. Use:
  1567.  
  1568. The buffer is filled with the sprite name that should be used to represent a file having the given filetype number:
  1569.  
  1570. • If the filetype is -1, then file_xxx (R0 = 0) or small_xxx (R0 = 1) is
  1571.   generated.
  1572. • If the filetype is in the range &000-&FFF, then file_xxx (R0 = 0) or
  1573.   small_xxx (R0 = 1) is generated, where xxx is the 12-bit filetype in
  1574.   hexadecimal.
  1575. • If the filetype is outside this range, then file_xxxxx (R0 = 0) or
  1576.   small_xxxxx (R0 = 1) is generated, where xxx is the 20-bit filetype in
  1577.   hexadecimal.
  1578.  
  1579. -
  1580.  
  1581. FileBox_FiletypeExtendOp 2
  1582. (SWI &4824B)
  1583.  
  1584. Load address to raw filetype
  1585.  
  1586. On entry:
  1587.  
  1588. R0 = 2
  1589. R2 = load address
  1590.  
  1591. On exit:
  1592.  
  1593. R0,R2 preserved
  1594. R1 = raw filetype number
  1595.  
  1596. Use:
  1597.  
  1598. The filetype number is extracted from the load address in a manner compatible with FiletypeExtend. No other mapping is applied, so invisible files are returned with their full 20-bit type, and similarly no mapping is applied to squashed files.
  1599.  
  1600. -
  1601.  
  1602. FileBox_FiletypeExtendOp 3
  1603. (SWI &4824B)
  1604.  
  1605. Remap raw filetype
  1606.  
  1607. On entry:
  1608.  
  1609. R0 = 3
  1610. R1 = raw filetype number
  1611.  
  1612. On exit:
  1613.  
  1614. R0 preserved
  1615. R1 = mapped filetype number
  1616.  
  1617. Use:
  1618.  
  1619. If the raw filetype number is specified by one of the following mappings, it is remapped:
  1620.  
  1621. Raw     Mapped  Mapping description
  1622. &FFxxx  &xxx    Invisible files
  1623. &FExxx  &FCA    Squashed files
  1624.  
  1625. -
  1626.  
  1627. Service Calls
  1628.  
  1629. -
  1630.  
  1631. Service_FileBoxWorkspace
  1632. (Service Call &48240)
  1633.  
  1634. Request for address of FileBox module workspace
  1635.  
  1636. On entry:
  1637.  
  1638. R1 = &48240
  1639.  
  1640. On exit:
  1641.  
  1642. R1 = 0 to claim, else preserved to pass on
  1643. R2 = address of FileBox module workspace if claimed, preserved otherwise
  1644.  
  1645. Use
  1646.  
  1647. This call is for internal use only. It must not be claimed by any module
  1648. other than FileBox itself.
  1649.  
  1650. -
  1651.  
  1652. *Commands
  1653.  
  1654. -
  1655.  
  1656. *Desktop_FileBox
  1657.  
  1658. Command to initialize File Box Desktop task
  1659.  
  1660. Syntax:
  1661.  
  1662. *Desktop_FileBox
  1663.  
  1664. Parameters:
  1665.  
  1666. None 
  1667.  
  1668. Use:
  1669.  
  1670. This command is provided for the use of the Desktop, in order to start up
  1671. the File Box Desktop task automatically. Do not use *Desktop_FileBox, use
  1672. either *Desktop or FileBox_Control 0 (SWI &48248) instead.
  1673.  
  1674. Related commands:
  1675.  
  1676. *Desktop
  1677.  
  1678. Related SWIs:
  1679.  
  1680. FileBox_Control (SWI &48248), Wimp_StartTask (SWI &400DE)
  1681.  
  1682. Related vectors:
  1683.  
  1684. None
  1685.  
  1686. -
  1687.  
  1688. *Help FileBox
  1689.  
  1690. Displays information about the FileBox module
  1691.  
  1692. Syntax:
  1693.  
  1694. *Help FileBox
  1695.  
  1696. Parameters:
  1697.  
  1698. None
  1699.  
  1700. Use:
  1701.  
  1702. This command gives miscellaneous information about the version of the
  1703. FileBox module currently present in the system, including the version
  1704. number, date of assembly, a brief overview and a list of commands provided.
  1705.  
  1706. Examples:
  1707.  
  1708. *Help FileBox
  1709.  
  1710. ==> Help on keyword FileBox
  1711. Kasoft FileBox
  1712. Written by Kade Hansson
  1713. ©1996 Kasoft Software
  1714.  
  1715. FileBox provides SWIs which allow non-Wimp programs running
  1716. on the desktop to make use of the RISC OS desktop file
  1717. dragging conventions. In addition, FileBox provides system
  1718. variables which allow *-commands issued on the desktop to
  1719. obtain file names using FileBox facilities.
  1720. All rights reserved. No part of this software may be
  1721. reproduced, stored or publicly distributed without the
  1722. written permission of Kasoft Software.
  1723.  
  1724. ==> Help on keyword FileBox
  1725. Module is: File Box        0.50 (08 Sep 1996) © Kasoft
  1726.  
  1727. Commands provided:
  1728. IOVarsOn        IOVarsOff       InputPrompt     InputTitle      InputReset
  1729. OutputType      OutputTitle     OutputReset     ResetFileBox   
  1730. Desktop_FileBox
  1731.  
  1732. It has help on:
  1733. FileBox
  1734.  
  1735. Related commands:
  1736.  
  1737. *Help
  1738.  
  1739. Related SWIs:
  1740.  
  1741. None
  1742.  
  1743. Related vectors:
  1744.  
  1745. None
  1746.  
  1747. -
  1748.  
  1749. *IOVarsOff
  1750.  
  1751. Disables File Box input and output system variables
  1752.  
  1753. Syntax:
  1754.  
  1755. *IOVarsOff
  1756.  
  1757. Parameters:
  1758.  
  1759. None
  1760.  
  1761. Use:
  1762.  
  1763. The command *IOVarsOff disables the system variables
  1764. FileBox$GetInputFilename and FileBox$GetOutputFilename. This is essential if
  1765. the system variables are being enumerated (e.g. by *Show), as spurious save
  1766. and load windows can appear, or the system can crash. This command is
  1767. equivalent to FileBox_Control 13 (SWI &48248).
  1768.  
  1769. The File Box system variables are disabled by default. That is, they are
  1770. disabled whenever the File Box module is loaded, reloaded or reinitialized.
  1771.  
  1772. Related commands:
  1773.  
  1774. *IOVarsOn, *Show
  1775.  
  1776. Related SWIs:
  1777.  
  1778. FileBox_Control (SWI &48248)
  1779.  
  1780. -
  1781.  
  1782. *IOVarsOn
  1783.  
  1784. Enables File Box input and output system variables
  1785.  
  1786. Syntax:
  1787.  
  1788. *IOVarsOn
  1789.  
  1790. Parameters:
  1791.  
  1792. None
  1793.  
  1794. Use:
  1795.  
  1796. The command *IOVarsOn enables the system variables FileBox$GetInputFilename
  1797. and FileBox$GetOutputFilename. This command is equivalent to FileBox_Control
  1798. 14 (SWI &48248).
  1799.  
  1800. The File Box system variables are disabled by default. That is, they are
  1801. disabled whenever the File Box module is loaded, reloaded or reinitialized.
  1802. It is therefore necessary to ensure that the variables are enabled if you
  1803. plan to use them.
  1804.  
  1805. Related commands:
  1806.  
  1807. *IOVarsOff, *Show
  1808.  
  1809. Related SWIs:
  1810.  
  1811. FileBox_Control (SWI &48248)
  1812.  
  1813. -
  1814.  
  1815. *InputPrompt
  1816.  
  1817. Change or read the input variable prompt text
  1818.  
  1819. Syntax:
  1820.  
  1821. *InputPrompt [<prompt text>]
  1822.  
  1823. Parameters:
  1824.  
  1825. <prompt text>  the text to be used as the input prompt (maximum 15
  1826.                characters)
  1827.  
  1828. Use:
  1829.  
  1830. This command changes the prompt text which appears in the Load window when
  1831. the value of FileBox$GetInputFilename is requested. If the prompt text is
  1832. omitted, the current prompt text is displayed. It is equivalent to
  1833. FileBox_Control 18 and 19 (SWI &48248).
  1834.  
  1835. Example:
  1836.  
  1837. *InputPrompt Filename:
  1838.  
  1839. Related commands:
  1840.  
  1841. *InputTitle, *InputReset
  1842.  
  1843. Related SWIs:
  1844.  
  1845. FileBox_Control (SWI &48248)
  1846.  
  1847. -
  1848.  
  1849. *InputReset
  1850.  
  1851. Restore the default attributes to the input variable Load window
  1852.  
  1853. Syntax:
  1854.  
  1855. *InputReset
  1856.  
  1857. Parameters:
  1858.  
  1859. None
  1860.  
  1861. Use:
  1862.  
  1863. This command restores the default prompt text (Filename:), window title
  1864. (Input from:) and filename (null string) to the Load window which appears
  1865. when the value of the variable FileBox$GetInputFilename is requested. It is
  1866. equivalent to calling the routine FileBox_Control 24 (SWI &48248).
  1867.  
  1868. Related commands:
  1869.  
  1870. *InputPrompt, *InputTitle
  1871.  
  1872. Related SWIs:
  1873.  
  1874. FileBox_Control (SWI &48248)
  1875.  
  1876. -
  1877.  
  1878. *InputTitle
  1879.  
  1880. Change or read the input variable title bar text
  1881.  
  1882. Syntax:
  1883.  
  1884. *InputTitle [<title text>]
  1885.  
  1886. Parameters:
  1887.  
  1888. <title text>  the text to be used as the input title (maximum 15 characters)
  1889.  
  1890. Use:
  1891.  
  1892. This command changes the title bar text which appears in the Load window
  1893. when the value of FileBox$GetInputFilename is requested. If the title text
  1894. is omitted, the current title is displayed. It is equivalent to
  1895. FileBox_Control 15 and 16 (SWI &48248).
  1896.  
  1897. Example:
  1898.  
  1899. *InputTitle Input from:
  1900.  
  1901. Related commands:
  1902.  
  1903. *InputPrompt, *InputReset
  1904.  
  1905. Related SWIs:
  1906.  
  1907. FileBox_Control (SWI &48248)
  1908.  
  1909. -
  1910.  
  1911. *OutputReset
  1912.  
  1913. Restore the default attributes to the output variable Save window
  1914.  
  1915. Syntax:
  1916.  
  1917. *OutputReset
  1918.  
  1919. Parameters:
  1920.  
  1921. None
  1922.  
  1923. Use:
  1924.  
  1925. This command restores the default filetype (none, xxx), window title (Output
  1926. to:) and filename (null string) to the Save window which appears when the
  1927. value of the variable FileBox$GetOutputFilename is requested. It is
  1928. equivalent to calling the routine FileBox_Control 32 (SWI &48248).
  1929.  
  1930. Related commands:
  1931.  
  1932. *OutputType, *OutputTitle
  1933.  
  1934. Related SWIs:
  1935.  
  1936. FileBox_Control (SWI &48248)
  1937.  
  1938. -
  1939.  
  1940. *OutputTitle
  1941.  
  1942. Change or read the output variable title bar text
  1943.  
  1944. Syntax:
  1945.  
  1946. *OutputTitle [<title text>]
  1947.  
  1948. Parameters:
  1949.  
  1950. <title text>  the text to be used as the output title (maximum 15
  1951.               characters)
  1952.  
  1953. Use:
  1954.  
  1955. This command changes the title bar text which appears in the Save window
  1956. when the value of FileBox$GetOutputFilename is requested. If the title text
  1957. is omitted, the current title is displayed. It is equivalent to
  1958. FileBox_Control 26 and 27 (SWI &48248).
  1959.  
  1960. Example:
  1961.  
  1962. *OutputTitle Output to:
  1963.  
  1964. Related commands:
  1965.  
  1966. *OutputType, *OutputReset
  1967.  
  1968. Related SWIs:
  1969.  
  1970. FileBox_Control (SWI &48248)
  1971.  
  1972. -
  1973.  
  1974. *OutputType
  1975.  
  1976. Change or read the output variable filetype
  1977.  
  1978. Syntax:
  1979.  
  1980. *OutputType [<filetype> | xxx]
  1981.  
  1982. Parameters:
  1983.  
  1984. <filetype>  the filetype number or textual equivalent
  1985.  
  1986. Use:
  1987.  
  1988. This command changes the filetype icon which appears in the Save window when
  1989. the value of FileBox$GetOutputFilename is requested. The parameter can be a
  1990. hexadecimal filetype number, the textual equivalent or xxx, which indicates
  1991. no type (represented by a white box icon). If the parameter is omitted, the
  1992. current filetype is displayed. This command is equivalent to FileBox_Control
  1993. 29 and 30 (SWI &48248).
  1994.  
  1995. Examples:
  1996.  
  1997. *OutputType
  1998. No type     xxx
  1999. *OutputType Text
  2000. *OutputType
  2001. Text        FFF
  2002. *OutputType FFD
  2003. *OutputType
  2004. Data        FFD
  2005. *OutputType RMInfo
  2006. *OutputType
  2007. RMInfo      E0002
  2008. *OutputType E0001
  2009. *OutputType
  2010. DAInfo      E0001
  2011.  
  2012. Related commands:
  2013.  
  2014. *OutputTitle, *OutputReset
  2015.  
  2016. Related SWIs:
  2017.  
  2018. FileBox_Control (SWI &48248)
  2019.  
  2020. -
  2021.  
  2022. *ResetFileBox
  2023.  
  2024. Abort all Load and Save operations
  2025.  
  2026. Syntax:
  2027.  
  2028. *ResetFileBox
  2029.  
  2030. Parameters:
  2031.  
  2032. None
  2033.  
  2034. Use:
  2035.  
  2036. *ResetFileBox causes all File Box Load and Save operations to be abandoned
  2037. and the corresponding windows to be closed. All tasks using File Box
  2038. facilities which continue to poll will receive the error File Box inactive
  2039. on Load or File Box inactive on Save. This command should be used with
  2040. caution. It is equivalent to calls to each of the routines FileBox_AbortLoad
  2041. (SWI &48244) and FileBox_AbortSave (SWI &48245).
  2042.  
  2043. Related commands:
  2044.  
  2045. None
  2046.  
  2047. Related SWIs:
  2048.  
  2049. FileBox_AbortLoad (SWI &48244), FileBox_AbortSave (SWI &48245)
  2050.  
  2051. -
  2052.  
  2053. System Variables
  2054.  
  2055. - 
  2056.  
  2057. FileBox$GetInputFilename
  2058.  
  2059. Filename for data input or loading (must be enabled using *IOVarsOn or
  2060. similar)
  2061.  
  2062. Reading:
  2063.  
  2064. When the value of this variable is requested, a call is made to
  2065. FileBox_DoLoadFromFiler (SWI &48246) using the title text, prompt text and
  2066. default filename currently set up.
  2067.  
  2068. If the request is made from a task window, then a File Box Load window will
  2069. be opened on the Desktop. If the request is made from other environments the
  2070. system may crash (although the Escape key can sometimes be used).
  2071.  
  2072. If an error occurs, the Close icon is clicked on or the Escape key is
  2073. pressed then a null filename will be returned in response to the request.
  2074. Otherwise, the value of this variable will be the filename specified by the
  2075. user via dragging or typing.
  2076.  
  2077. Reading example:
  2078.  
  2079. *Echo <FileBox$GetInputFilename>
  2080.  
  2081. ADFS::KaModula2.$.InputFile
  2082.  
  2083. Writing:
  2084.  
  2085. Writing this variable sets the default filename used for the read action. It
  2086. is equivalent to a call to FileBox_Control 22 (SWI &48248).
  2087.  
  2088. Writing example:
  2089.  
  2090. *Set FileBox$GetInputFilename InputFile
  2091.  
  2092. Related commands:
  2093.  
  2094. *IOVarsOn, *IOVarsOff, *InputPrompt, *InputReset, *InputTitle
  2095.  
  2096. Related SWIs:
  2097.  
  2098. FileBox_DoLoadFromFiler (SWI &48246), FileBox_Control (SWI &48248)
  2099.  
  2100. -
  2101.  
  2102. FileBox$GetOutputFilename
  2103.  
  2104. Filename for data output or saving (must be enabled using *IOVarsOn or
  2105. similar)
  2106.  
  2107. Reading:
  2108.  
  2109. When the value of this variable is requested, a call is made to
  2110. FileBox_DoSaveToFiler (SWI &48247) using the title text, filetype and
  2111. default filename currently set up.
  2112.  
  2113. If the request is made from a task window, then a File Box Save window will
  2114. be opened on the Desktop. If the request is made from other environments the
  2115. system may crash (although the Escape key can sometimes be used).
  2116.  
  2117. If an error occurs, the Close icon is clicked on or the Escape key is
  2118. pressed then a null filename will be returned in response to the request.
  2119. Otherwise, the value of this variable will be the filename specified by the
  2120. user via dragging or typing.
  2121.  
  2122. Reading example:
  2123.  
  2124. *Echo <FileBox$GetOutputFilename>
  2125.  
  2126. ADFS::KaModula2.$.OutputFile
  2127.  
  2128. Writing:
  2129.  
  2130. Writing this variable sets the default filename used for the read action. It
  2131. is equivalent to a call to FileBox_Control 22 (SWI &48248).
  2132.  
  2133. Writing example:
  2134.  
  2135. *Set FileBox$GetOutputFilename OutputFile
  2136.  
  2137. Related commands:
  2138.  
  2139. *IOVarsOn, *IOVarsOff, *OutputType, *OutputReset, *OutputTitle
  2140.  
  2141. Related SWIs:
  2142.  
  2143. FileBox_DoSaveToFiler (SWI &48247), FileBox_Control (SWI &48248)
  2144.  
  2145. -
  2146.  
  2147.