=============================================================================== === === === === === Documentation for Con.library V2.00 === === === === === =============================================================================== Con.library is developed by Bjørn Reese. --- Con.library --------------------------------------------------------------- Con.library is a run time reentrant library, developed with the purpose to ease the living for application programmers. It contains functions to format and display texts, accept keys/messages, strings or numbers and to handle the cursor and screen controls, amongst other things. The library must be places in LIBS: to be used. This is version 2.00. --- Disclaimer ---------------------------------------------------------------- Con.library is tested to run as smoothly and bugfree as possible, but the author renounces any responsibility for faulty use of, or damages caused by, Con.library and all that goes with it. --- Distribution -------------------------------------------------------------- Con.library may be distributed freely with, and only with, the documentation, source and include files and if no charge is being made, except for a nominal media fee. Otherwise you need the written approval of the author. --- Commercial use ------------------------------------------------------------ Con.library may be used in commercial [ and non-commercial ] products without paying any royalties to the author. But I would be really happy to be mentioned. The documentation, source, includes and examples may be distributed along with the product without the written approval of the author. --- Public Domain ------------------------------------------------------------- The Con.library, the source, the includes and the examples is made Public Domain for two reasons: 1) I am too busy to make any updates in the near future. 2) To support the wonderful idea of Public Domain and Shareware. Please look in the "ConLib.readme" file to see exactly what Con.library should consist of. =============================================================================== Why Con.library? =============================================================================== Well, I have always wondered why Commodore had to make the Operating System so hard to get along with. As an assembler programmer I have always cursed the lack of an easy and comprehensive way to handle inputs and outputs to/from the screen [ like Basic's INPUT and PRINT ]. In Con.library I have combined the features of intuition windows and console.device, which gives the possibillity to use menues, gadgets etc. and also an easy control of cursor and text. =============================================================================== Overview =============================================================================== Some of the names of variable, constants, structures etc. may vary a little from language to language. Please refere to the includes for you language for the correct name. --- Window -------------------------------------------------------------------- Before using the main functions of Con.library you must open a ConWindow, using the OpenCon function. Closing the ConWindow is done by CloseCon. A "ConWindow" is just a normal Intuition Window connected with Console.device. So when you open the ConWindow it is done exactly the same way as OpenWindow() in Intuition. --- Functions ----------------------------------------------------------------- The main functions of Con.library are DoFormat, Convert, Display, Accept and AcceptString. - DoFormat converts a string and a list of arguments into a string in a sprintf() or Exec.RawDoFmt() style. - Convert converts a string into a numeric value. - Display shows a text on the screen [ in a specific ConWindow ]. The text is formatted before use, using DoFormat. For more information read the description of Display. - The Accept functions are designed to work just as you want it to, through the use of numerous flags. o Accept is used to check if the user has pressed a defined key. You can choose to wait until a key was pressed or just continue, echo the pressed key or not, read both key presses and releases or just one of them, and more. Accept can also be used to wait for messages [ like MENUPICK or CLOSEWINDOW etc. ], except for RAWKEY and VANILLAKEY as they are masked out by Accept. o AcceptString works in many way just like Basic's INPUT or a more like a String Gadget. It's main purpose is to get a text string from the keyboard. There are a couple of editing features like cursor movement, clear line, clear to end of line, restore original buffer and so on. o You may accept a numerical value by using AcceptString and Convert. Before using the Accept functions you must define which characters you will allow as ValidChars and as ExitChars [ see below ]. This is done with DefineChars. For a detailed information read the descriptions of the Accept functions and of DefineChars. If a message is encountered in AcceptString one of the there different actions will be taken. o Ignore, if message is not defined in the Accept Structure [ acc_ExitFlags ] o Exit, if a Message Handler is not defined in the ConHandle Structure [ cnh_MsgHandler = 0 ] o Jump to Message Handler, if it is defined [ cnh_MsgHandler containing a pointer to a procedure ]. More information about this feature in the description of SetMsgHandler. Besides from the functions mentioned above, there are a number of other functions, mainly to handle cursor and graphics control. --- Characters ---------------------------------------------------------------- There are three types of characters: - ValidChars are the characters which are accepted as input characters and added to a possible input string. - ExitChars are the characters which will terminate Accept/AcceptString [ for instance or ]. NB: Accept will also terminate on a ValidChar, but with a different value in *Success*. - EchoChars are the characters which may be echoed in the window. This only works for the Accept functions [ it is not always smart to echo a or likewise ]. EchoChars are treated independent from ValidChars and ExitChars. --- Types --------------------------------------------------------------------- In this documentation I have used the types, which is specified in the - exec/types.i - exec/types.h includes from Commodore, to describe the functions and the structures. The descriptions in the "Short Description of Structures" section are only descriptive, and the actual include files may vary from language to language, so please look in the specific include(s) made for your language. =============================================================================== Quick list of functions =============================================================================== OpenCon.........Opens a new ConWindow. CloseCon........Closes a specific ConWindow. DoFormat........Formats a text string [ like sprintf() ]. UserNotes.......Defines a specific user text [ to be used by DoFormat ] DefineChars.....Defines Valid or Exit Chars used by Accept and AcceptString. DisplayRaw......Prints an unformatted text in ConWindow. Display.........Prints a formatted text in ConWindow. Accept..........Gets an input [ key/message ] from console. AcceptString....Gets a string from console. SetMsgHandler...Set a new User Message Handler GetInfo.........Get information about a specific ConWindow. SetGfx..........Set Text Styles, Foreground and Background Colors. GotoXY..........Places Cursor at a specific position. Cursor..........Turns Cursor On or Off. Scroll..........Scrolls the text in the ConWindow a specific amount of lines. Convert.........Converts an ASCII string into a number [ DEC/HEX/OCT/BIN ] =============================================================================== Description of functions =============================================================================== Following is an in-depth description of the functions in Con.library. It consists of four/five parts: SYNTAX - a formal description of the function and its arguments. It is represented in the following fashion: Result = Function (Arguments) D0 An/Dn TYPE Arguments If the function does not return a result it will be omitted from the syntax description. The An/Dn are only of interrest to assembler programmers as they state the registers used for a specific argument. TYPE defines the type of the subsequent argument. ARGUMENTS - a short description of the arguments used by the function. RESULT - a short description of the result of the function. DESCRIPTION - a verbal description of the function and what it does. EXAMPLES - some examples of the usage. --- OpenCon ------------------------------------------------------------------- SYNTAX ~~~~~~ ConHandle = OpenCon (ConWindow,CursorMode) D0 A0 D0 APTR ConWindow UWORD CursorMode APTR ConHandle ARGUMENTS ~~~~~~~~~ ConWindow A pointer to a normal Intuition NewWindow Structure, which is also used by OpenWindow() in Intuition. CursorMode The cursor settings [ see Cursor ]. RESULT ~~~~~~ ConHandle A pointer to a specific ConWindow Structure as defined in the includes. DESCRIPTION ~~~~~~~~~~~ - OpenCon opens a ConWindow, which is a normal Intuition Window connected with Console.device. Use this function instead of OpenWindow() in Intuition. --- CloseCon ------------------------------------------------------------------ SYNTAX ~~~~~~ CloseCon (ConHandle) A0 APTR ConHandle ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] DESCRIPTION ~~~~~~~~~~~ - CloseCon closes the ConWindow which is specified by *ConHandle*. --- DoFormat ------------------------------------------------------------------ SYNTAX ~~~~~~ TextBuffer = DoFormat (ConHandle,String,FormatArgs,TextBuffer,BufferSize) D0 A0 A1 A2 A3 D0 APTR ConHandle APTR String APTR FormatArgs APTR TextBuffer ULONG BufferSize ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] String A pointer to the unformatted String [ NULL-terminated ]. FormatArgs A pointer to the arguments for formatting the string. TextBuffer A pointer to where the result must be delivered. BufferSize The maximum size of the formatted string. RESULT ~~~~~~ TextBuffer A pointer to the formatted string. DESCRIPTION ~~~~~~~~~~~ - DoFormat works like the RawDoFmt() function in Exec.library or like the formatting part of sprintf() in C, but it has been improved over both. It formats a string, using an unformatted string and some formatting arguments. The unformatted string can contain two different types of formatting characters: - The Control Codes [ Represented by the "\" charackter (BackSlash) ] - The Merging Codes [ - - - "%" - (Percent) ] The Control Codes determines the appearance of the string. The following Control Codes are the same as those in sprintf(): \b = BackSpace [ ASCII 8 ] \t = Tabulator [ ASCII 9 ] \n = LineFeed [ ASCII 10 ] \v = Vertical Tabulator [ ASCII 11 ] \f = FormFeed [ ASCII 12 ] \r = Carriage Return [ ASCII 13 ] \\ = The Character "\" itself The following Control Codes are unique for Con.library: \[ = Escape [ ASCII 27 ] \{ = CSI [ ASCII 155 ] \xxx = Binary Value xxx [ ASCII 0-255 ] \* = Binary Value (16 bits) from *FormatArgs* \#x = User Notes x [ 1-8 ] \@ = Plain Style \B = Bold Style \I = Italic Style \U = Underlined Style \Cx = Foreground Color [ 0-9 ] \Zx = Background Color [ 0-9 ] \C and \Z does no error checking (as there can be more than 4 colors to choose from if WorkBench has been set to fx. 8 colors). Be sure that the values are correct as the are passed unchanged to "console.device". Only one digit is allowed! The Merging Codes is represented by the "%" character followed by a character which determines what the argument shall be treated as. This character may be one of the following: s = String c = Character d = Signed Decimal Number u = Unsigned Decimal Number x = Hexadecimal Number o = Octal Number b = Binary Number % = The Character "%" itself Please note that the argument for a string [ %s ] must be a pointer to a NULL- terminated string. In the Merging Codes [ between the "%" and the character ] we may add some attributes, so that the Merging Codes can be represented by the following general syntax [ any of the attributes may be omitted ]: -0xxx.yyyl ,where - Left Justifies the output [ otherwise Right Justified ] 0 For Numbers: Output leading zeroes instead of spaces For Chars: Output leading user defined char [ default '.' ] ¹ xxx Minimal field width .yyy Maximal field width l Specify a 32 bits [ long ] argument [ otherwise 16 bits ] ² ¹) Please note that the leading zeroes and spaces can be changed in the ConHandle structure, BUT in the Merging Codes it is still represented by a "0" character. ²) This does not apply for %s and %c. The %ls and %lc will cause an error. *FormatArgs* must be a succesive list of arguments. When a Merging Code is recognised in the text, the next value will be fetched from *FormatArgs*. The "\*" Control Code also fetches the next value from *FormatArgs*. *TextBuffer* must be a pointer to an idle buffer in which the result is returned. Please note that the size of the *TextBuffer* must be bigger than the size of the *String* [ as the formatted string almost always is bigger than the unformatted string ] if *BufferSize* is not specified (ie. set to IGNOREVALUE). The argument *TextBuffer* and the result *TextBuffer* is the same, but for future compatibillity please use the result *TextBuffer* [ ie. D0 ] If an error is detected in the syntax of either Control Codes or Merging Codes, the interpretation of the specific code is terminated and is being outputted as a normal text. EXAMPLES ~~~~~~~~ Control Codes: In the following examples we assume that User Note #3 is set to "Aliens". Unformatted string: Formatted string: ---------------------------------------------------------- "Hello World\n" "Hello World",10 "Ascii \65\\" "Ascii A\" "\{1;1H" 155,"1;1H" "\fListen \#3\n" 12,"Listen Aliens",10 Merging Codes: %8d = A Decimal Number of minumum 8 Characters %-8d = As %8d but Left Justified %08d = As %8d but with Leading Zeros %.40s = A String of maximun 40 Characters --- UserNotes ----------------------------------------------------------------- SYNTAX ~~~~~~ UserNotes (ConHandle,UserText,NoteNumber) A0 A1 D0 APTR ConHandle APTR UserText UWORD NoteNumber ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] UserText A pointer to a NULL-terminating text NoteNumber A number between 1 and 8 [ both included ] DESCRIPTION ~~~~~~~~~~~ - UserNotes defines a specific user text [ used by \#x - see DoFormat ]. --- DefineChars --------------------------------------------------------------- SYNTAX ~~~~~~ DefineChars (Mode,BitTable,ArrayOfChars) D0 A1 A2 ULONG Mode APTR BitTable APTR ArrayOfChars ARGUMENTS ~~~~~~~~~ Mode A value telling how DefineChars should operate BitTable A pointer to a BitTable ArrayOfChars A pointer to a NULL-terminating string of ASCII characters DESCRIPTION ~~~~~~~~~~~ - DefineChars creates a table of allowed characters for Accept and AcceptString. *Mode* indicates how you want to use DefineChars: DEFMODE_ALL = Choose all keys DEFMODE_NEW = Start a new table DEFMODE_ADD = Add to table DEFMODE_REM = Remove from table DEFMODE_GET = Get a pre-defined table The pre-defined tables are currently: DEFALL = All possible values DEFNONE = No values at all DEFALFANUM = Alfanumeric values DEFALFA = Alfabetic values DEFNUMERIC = Numeric values DEFDECIMAL = Decimal values DEFHEX = Hexadecimal values DEFOCTAL = Octal values DEFBINARY = Binary values DEFFLOAT = Floating Point values The Valid and Exit Tables are contained in the AcceptStructure. *ArrayOfChars* points to a NULL-terminating array of ASCII characters. If you want to use any special keys [ like the F-keys ] when use the AKEY_ which is specified in the includes. EXAMPLES ~~~~~~~~ Define a new *BitTable*: Mode = DEFMODE_NEW Define *BitTable* as all numeric values: Mode = DEFMODE_GET+DEFNUMERIC --- DisplayRaw ---------------------------------------------------------------- SYNTAX ~~~~~~ DisplayRaw (ConHandle,String,MaxLength) A0 A1 D0 APTR ConHandle APTR String ULONG MaxLength ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] String A pointer to a NULL-terminated text MaxLength A max. length of the text DESCRIPTION: - DisplayRaw prints an unformatted [ raw ] text on the ConWindow pointed to by *ConHandle*. This function is provided as a stripped and hence faster method to get a text on screen. If *MaxLength* is set to IGNOREVALUE then the text will terminate at NULL (not before). --- Display ------------------------------------------------------------------- SYNTAX ~~~~~~ Display (ConHandle,String,FormatArgs,MaxLength) A0 A1 A2 D0 APTR ConHandle APTR String APTR FormatArgs ULONG MaxLength ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] String A pointer to a NULL-terminated text FormatArgs A pointer to the arguments for formatting the string. MaxLength A max. length of the text DESCRIPTION ~~~~~~~~~~~ - Display prints a formatted text [ see DoFormat ] on the ConWindow pointed to by *ConHandle*. Display calculates the length of the string and adds the value in cnh_ExLength [ default 256 ] to it. The value of cnh_ExLength can be changed at any given time, and if your format arguments requires more space, you must do so. No checking is performed. --- Accept -------------------------------------------------------------------- SYNTAX ~~~~~~ Success = Accept (ConHandle,AcceptStructure,Flags) D0 A0 A1 D0 APTR ConHandle APTR AcceptStructure ULONG Flags LONG Success ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] AcceptStructure A pointer to the normal AcceptStructure as defined in the includes. Flags Determines how Accept shall execute RESULT ~~~~~~ Success Everything OK, an Error, an ExitFlag, an ExitChar or an user defined value DESCRIPTION ~~~~~~~~~~~ - Accept basically gets a key from the console, though it may function in other ways as well. *Flags* [ ACCF_ ] determines the way Accept works. *Success* tells how successful Accept was. Success = -1 => Error [ NULL in acc_Char ] Success = 0 => OK [ Character in acc_Char ] Success = 1 => ExitFlag [ Message information in AcceptStructure ] Success = 2 => ExitChar [ Character in acc_Char ] *Success* may also be an user defined value. More on this in the description of SetMsgHandler. These are the flags for Accept: o ACCF_ERASE: Clear the Message Stack before reading. Caution! this also ignores messages like CLOSEWINDOW. o ACCF_RAWKEY: Return RawKeys, otherwise return VanillaKeys. o ACCF_DUALKEY: Report both key presses and releases, otherwise only one of them [ which will be dependent on ACCF_UPKEY ]. o ACCF_UPKEY: Report only when a key is released, otherwise only when a key is pressed. If ACCF_DUALKEY is selected, this flag will be ignored. o ACCF_ECHO: Echo the key on the ConWindow, otherwise nothing appears. If ACCF_RAWKEY is selected, this flag will be ignored. Which keys will be echoed is determined by cnh_EchoTable in the ConHandle, which default is DEFALFANUM. o ACCF_WAIT: Waits for reaction from the keyboard, otherwise do not wait. If a keypress [ or keyrelease dependent on ACCF_UPKEY ] was reported or found in the keyboard buffer, Accept will return with a OK, otherwise it will return with an Error. Accept may be terminated by an ExitFlag [ specified by acc_ExitFlags in the AcceptStructure ]. These ExitFlags are equvalent to the IDCMP flags from Intuition. This allows you to terminate Accept if fx. CLOSEWINDOW was chosen, or indeed use Accept to specifically wait for a message like CLOSEWINDOW. When calling Accept you can amongst others specify its starting position on the screen and its styles and colors by setting the proper values in the AcceptStructure. Also read the "Short Description of Structures" for further informations. --- AcceptString -------------------------------------------------------------- SYNTAX ~~~~~~ Success = AcceptString (ConHandle,AcceptStructure,Flags) D0 A0 A1 D0 APTR ConHandle APTR AcceptStructure ULONG Flags LONG Success ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] AcceptStructure A pointer to an extended AcceptStructure as defined in the includes Flags Determines how AcceptString shall execute RESULT ~~~~~~ Success Everything OK, an Error, an ExitFlag or an user defined value DESCRIPTION ~~~~~~~~~~~ - AcceptString get a string. *Flags* determines the way AcceptString works. accs_MaxLength in *AcceptStructure* contains the maximum length of the string. It is very important to note that *AcceptStructure* must point to an extended Accept Structure, which contains further information needed for accepting a string [ the accs_ fields ]. When editing you can optionally use following keyboard combinations: = Delete input text. = Restore original input text. = Delete input text from cursor until end of field. = Toggle between insert and overwrite. = Delete previous character = Delete current character = Moves cursor one position left = - - - - right = Moves cursor to end of field = Moves cursor to start of field If *InputBuffer* exceeds a line [ ie. acc_XStart + acc_Length > cin_XSize ] it will be cut in length to fit the line, because an input field which continues onto a new line looks messy and is regarded as an error. *Success* [ D0.L ] tells how successful AcceptString was. Success = -1 => Error Success = 0 => OK [ String in accs_InputBuffer, and the length in accs_Length ] Success = 1 => ExitFlag [ Message information in AcceptStructure ] *Success* may also be an user defined value. More on this in the description of SetMsgHandler. These are the specific AcceptString flags: o ACCF_ERASE: Clear the Message Stack before reading. Caution! this also ignores messages like CLOSEWINDOW. o ACCF_JUSTIFIED: Text will be rigth justified in the accept field, otherwise left justified. o ACCF_CONTINUE: Continue editing the input, otherwise restart input. This is especially useful if Accept was terminated by an ExitFlag [ like MENUPICK or DISKREMOVED ]. Continuation is determined by acc_Position. This field is mostly internal, but can be used for setting a start position within the range of acc_Length. o ACCF_OVERWRITE: Overwrite text, otherwise insert. o ACCF_LASTEXIT: Exit the input if the input buffer is full [ accs_Length = accs_MaxLength ], otherwise allow continuing editing. o ACCF_FULLSTOP: Stop inserting further characters if the input buffer is full. If ACCF_OVERWRITE is selected this flag will be ignored. o ACCF_NOAMIGA: All combinations are disabled o ACCF_NOSTDAMIGA: All non-standard combinations [ and ] are disabled. o ACCF_NOSCROLL: Disable scrolling within input field. If accs_MaxLength bigger than accs_FieldLen it is cut in size. For handling other messages sent duing an AcceptString you have two choices. Firstly you can let AcceptString terminate, handle the message and call AcceptString again with the ACCF_CONTINUE flag set. Secondly you can use the SetMsgHandler function for handling the message. This metode does not terminate AcceptString. For more information please read the description of SetMsgHandler. Also read the "Short Description of Structures" for further informations. --- SetMsgHandler ------------------------------------------------------------- SYNTAX ~~~~~~ OldMsgHandler = SetMsgHandler(ConHandle,NewMsgHandler) D0 A0 A1 APTR ConHandle APTR NewMsgHandler APTR OldMsgHandler ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] NewHandler A pointer to your routine which handle messages RESULT ~~~~~~ OldHandler A pointer to the previous handler DESCRIPTION ~~~~~~~~~~~ - It is possible to set your own Message Handler. This is activated if an Intuition Message occurs while performing Accept or AcceptString, but only if the flag is define in ExitFlags [ all others are ignored ]. Your handler should consist of what it normally does, for instance a Menu or Gadget Handler. A pointer to the message is delivered in both D0 and A0 to your handler. To get back to Accept/AcceptString simply return using RTS. If you want the Accept/AcceptString to continue set D0 to NULL. Any other value in D0 will terminate with the original value in D0 to let you determine what went wrong. Please do not terminate your program immediately if you detect, say CLOSEWINDOW, because there is a lot of heap on the stack, which will only cause your program to crash if you try to exit it. The correct way to exit, is to set D0 to a certain value [ other than NULL and preferably other than -1 which means Error and 1 which means ExitFlag ] and return to Accept/AcceptString, and then catch the special error after the call of Accept/AcceptString. To remove a handler simply set *NewMsgHandler* = NULL and call this function. --- GetInfo ------------------------------------------------------------------- SYNTAX ~~~~~~ ConInfo = GetInfo (ConHandle,ConInfo) D0 A0 A1 APTR ConHandle APTR ConInfo ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] ConInfo A pointer to a ConInfo structure RESULT ~~~~~~ ConInfo - A pointer to an initialized ConInfo structure DESCRIPTION ~~~~~~~~~~~ - GetInfo gets the current cursor and window settings as specified in the *ConInfo* structure. --- SetGfx -------------------------------------------------------------------- SYNTAX ~~~~~~ SetGfx (ConHandle,Styles,FgCol,BgCol) A0 D0 D1 D2 APTR ConHandle UWORD Styles UWORD FgCol UWORD BgCol ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] Styles Text Styling FgCol Foreground Color BgCol Background Color DESCRIPTION ~~~~~~~~~~~ - SetGfx sets the text styles, foreground and background colors. The text *Styles* are defined in the includes. Currently the following flags are supported: SGFF_PLAIN SGFF_BOLD SGFF_ITALIC SGFF_UNDERLINE The colors must be specified as 30 - 3x and 40 - 4x, meaning 30 will set foreground to color 0 and 41 will set background to color 1. --- GotoXY -------------------------------------------------------------------- SYNTAX ~~~~~~ GotoXY (ConHandle, X, Y) A0 D0 D1 APTR ConHandle UWORD X UWORD Y ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] X Coloumn Y Row DESCRIPTION ~~~~~~~~~~~ - GotoXY places the cursor at a given position specified by (X,Y). The Top-Left corner is (1,1). --- Cursor -------------------------------------------------------------------- SYNTAX ~~~~~~ Cursor (ConHandle,Mode) A0 D0 APTR ConHandle UWORD Mode ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] Mode Cursor settings [ currently ON/OFF ] DESCRIPTION ~~~~~~~~~~~ - Cursor handles the looks of the cursor. Currently two modes are supported: CURSOROFF - Turns the cursor off. CURSORON - Turns the cursor on. --- Scroll -------------------------------------------------------------------- SYNTAX ~~~~~~ Scroll (ConHandle,Step) A0 D0 APTR ConHandle WORD Step ARGUMENTS ~~~~~~~~~ ConHandle [ See OpenCon ] Step Lines to scroll DESCRIPTION ~~~~~~~~~~~ - Scroll scrolls the text in the window the number of lines determined by *Step*. If it is positive the text will scroll down, and if it is negative the text will scroll up [ ie. if you want to scroll the text 2 lines up, you must set *Step* = -2 ]. --- Convert ------------------------------------------------------------------- SYNTAX ~~~~~~ Result = Convert (String,ResultBuffer,Flags,MaxLength) D0 A1 A2 D0 D1 APTR String APTR ResultBuffer ULONG Flags UWORD MaxLength APTR Result ARGUMENTS ~~~~~~~~~ String NULL-terminating ASCII string containing the number to be converted. ResultBuffer A pointer to an empty 32 bits location. Flags Tells what number system to convert to [ DEC/HEX/OCT/BIN ] and some other attributes. MaxLength The maximum length of the number to be converted. RESULT ~~~~~~ Result A pointer to the converted number OR NULL if any error occured. DESCRIPTION ~~~~~~~~~~~ - Convert converts an ASCII string to a binary value. The 'ResultBuffer' must point to a longword. Please note that only the convertion ASCII->OCT have not been implemented so far. The actual length of *String* is calculated and used, except if *MaxLength* specifies a smaller value. You can set *MaxLength* to IGNOREVALUE to ignore it. =============================================================================== Short Description of Structures =============================================================================== --- AcceptStructure ----------------------------------------------------------- acc_XStart, acc_YStart, acc_Styles, acc_FgCol and acc_BgCol can be set to any defined value to get an action. If any these field are set to IGNOREVALUE then the according field will be ignored [ = remain unchanged ]. If any of the Accept functions terminates because of an ExitFlag, the relevant values from the message can be found in the AcceptStructure. If ACC_RAWKEY was chosen the result will NOT be in acc_Char but in acc_Code. =============================================================================== About the Source =============================================================================== The source is made for the exellent "AsmOne" assembler, but it should work with "Devpac 2" - I think - if minor changes are made, like converting the square brackets [] with the normal brackets (). Originally the source was not intended to be released, but in the last minute I changed my mind for reasons stated elsewhere in this documentation, therefore the source is not very well documented (Sorry!). =============================================================================== Ideas =============================================================================== In my brainstorming list there are still some unused ideas: o Implementation of Floats [ in DoFormat and Convert ] o A group seperator in DoFormat [ fx. "%1001.0111" instead of "%10010111" and "19.443.422" instead of "19443422" ]. This would give us -0xxx.yyy.zzzl as the general syntax for DoFormat, where .zzz is the width of the groups [ 4 in the first and 3 in the second example ]. =============================================================================== History =============================================================================== Version 1.00a: - Lots of thinking, designing and programming. - First unofficially released version [ alfa version ]. Version 1.00b: - cnh_CursStatus renamed to cnh_CursorStatus. - *Success* was not reported in Accept/AcceptString, but it is now. - cnh_EchoTable determines which chars may be echoed and which may not. Version 1.01: - DoFormat totally rewritten. I was previously using RawDoFmt() in Exec, but it leaves a lot to be desired, so I wrote my own routines. As far as I can tell, DoFormat acts like RawDoFmt() but it adds a lot of features, and removed a minor bug in RawDoFmt(). - AcceptString added as a seperate function. Accept is now that previously known as AcceptKey. - AcceptString rewritten. It now scrolls back and forth if the accept field is smaller than the actual maximum input size. - AcceptStructure rewritten [ several times ]. - UserNotes added. - Lots of alternate padding characters [ like Decimal point, Leading zeroes ]. - cnh_MsgHandler added. - Documentation rewritten to fit the new features. Version 1.02: - ReplyMsg() added. OS2.0 seemed to bug with the omission of this. - The important parts of the Intuition Message are copied to AcceptStructure. - Some of the special keys [ like the F-keys ] was not working. They are now. - Convert added. Version 2.00: - First public release. =============================================================================== KNOWN BUGS AND OMISSIONS =============================================================================== - Octal values [ CNV_OCTAL ] are not implemented in Convert [ Does anybody use them anyway? ] - Attributes [ CNV_SIGNED and CNV_LEADSPACE ] are not implemented in Convert. - Long Unsigned in DoFormat [ %lu ] bugs if value >= $80000000. =============================================================================== Thank you's =============================================================================== I would like to express my gratitude to following: Jesper B. Krogholt: o For his major support and suggestions during development. o For making the Modula-2 interface. Michael Berg: o For making the C interface. =============================================================================== Any comments, suggestions, bugreports, gifts etc. can be directed to the author on this address: Bjørn Reese Stammen 55, -2 DK-5220 Odense SØ Denmark