PortHandle 2.0 Oberon-2 Class Library for AmigaOberon 3.0 Ports/Port _________/ | \_____________ / | \\ Ports/PublicPort IDCMPort/IDCMPort AppPort/AppPort | | \\ RexxHost/RexxHost | GTIDCMPort/GTIDCMPort | | \\ SimpleWinHandle/SimpleWinHandle | SimpleGTWinHandle/SimpleGTWinHandle | FindChange | ReqTest PortHandle 2.0 Oberon-2 Class Library for AmigaOberon 3.0 Copyright © 1992,1993 by hartmut Goebel * This program is FREEWARE, which means you may spread this library freely and use it for all kinds of public domain and freeware software, as long as the following restrictions are followed: - All files are copied in an unmodified state. If additional information is needed, place it in a separate file. - When using the PortHandle Class Library (or parts of it) you must put a note into the programs documentation and/or on-line info about that together with a Copyright note. E.g.: "This program was written using the PortHandle Class Library which is copyrighted © 1992,1993 by hartmut Goebel" - The copying is done on a non-commercial and non-profit basis only. A copy fee to replace media costs, postage etc. may be charged, and mustn't exceed DM 5,00 (about 3.- US$). - The distributor is not claiming the Copyright © of this program. - According to the Amiga Oberon licence you must not use any part of this library directly or indirectly for military concerns. * Using PortHandle Class Library in Shareware or commercial products If you want to use this library in a shareware or commercial product, please contact the author for special conditions. See Author. This will ensure me a small benefit for my work. * No Warranty THE MODULES AND PROGRAMS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF ANY MODULE IS ASSUMED BY YOU. Should a module prove defective, you (and not Commodore or its dealers or the author of AmigaOberon or PortHandle) assume the entire cost of all necessary servicing, repair, or correction. Further, neither Commodore nor the author of PortHAndle warrants, guarentees, or makes any representations regarding the use of, or the results of the use of, the modules in terms of corrections, accuracy, reliability, currentness, or otherwise; and you rely on the program and results solely at your own risk. * Limitation of liability THE AUTHOR OF PORTHANDLE LIABILITY IS LIMITED SOLELY TO THE REPAIR OR REPLACEMENT OF THE DEFECTIVE PRODUCT, IN ITS SOLE DISCRETION, AND SHALL NOT IN ANY EVENT INCLUDE DAMAGES FOR LOSS OF USE OR LOSS OF ANTICIPATED PROFITS OR BENEFITS OR OTHER INCIDENTAL OR CONSEQUENTIAL COSTS, EXPENSES OR DAMAGES, INCLUDING WITHOUT LIMITATION ANY DATA OR INFORMATION WHICH MAY BE LOST OR RENDERED INACCURATE, EVEN IF THE AUTHOR OF PORTHANDLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Some states do now allow a limitation on how long an implied warranty lasts, or limitation of incidental or consequential damages, so the above limitations or exclusions may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state. * Miscellaneous This agreement represents the entire understanding regarding the programs and related documentation, and supersedes any prior purchase order, communications or representations. If any provision of the agreement shall be deemed unlawful, void, or for any reason, unenforceable it shall be deemed everable from, and shall in no way effect the validity and enforceability of the remaining provisions of the agreement. The License Agreement shall inure to the benefit of the author of PortHandle. Overview ******** PortHandle 2.0 Oberon-2 Class Library for AmigaOberon 3.0 Port _________/ | \_____________ / | \\ PublicPort IDCMPort AppPort | | \\ RexxHost | GTIDCMPort | | \\ SimpleWinHandle | SimpleGTWinHandle | FindChange | ReqTest Port is the root class of this library. It is a generic port type, which's main purpose is to define some (most times abstract) methods for it's sub classes. PublicPort is a generic type for all kinds of public ports. Supports name unifying, uppercase names, priority etc. RexxHost defines some useful methods for handling ARexx ports very similar to the functions provided by SimpleRexx. It also ensures the correct naming and other things recommended by StyleGuide. AppPort handles the three kinds of Workbench Application objects: AppMenuItems, AppIcons ans AppWindows. IDCMPort generic type for all kinds of IDCMP ports. Offers esp. a mighty message dispatcher for all IDCMP classes, which handles all messages pending at the port. Includes a complete event main loop (see RKM Libraries p. 251f) for programs only communicating with one window. GTIDCMPort equivalent to IDCMPort, but for windows using GadTools.library. When switching to/from GadTools, just replace IDCMPort by GTIDCMPort in the IMPORT list (or the other way round). SimpleWinHandle offers an even easier way to handle single windows. FindChange, ReqChange a class and a module demonstrating the usage of IDCMPort (and WinHandle). FindChange is a simple Find/Change requester-like window. Needs another module ReqTestGUI (generated by GadToolsBox, should be contented in the distribution package) for compiling. General Design ============== For easy using the PortHandle Class Library it's good to know some general design ideas. For every class there is a function to initialize all needed fields and needed resources (esp. the message port) of an object. This function is called Init() and contained in the module with the same name as the class. Init() will return TRUE if all needed resources could be allocated. (1) After a Port has been initialized it is 'valid' and can be used (2). You MUST NOT use an invaild port as reciever! To free all resources used for an object just call the method Uninit(). After calling this method, the port is no longer 'valid'. Uninit() will also reply all pending messages, if any. The method Handle() receives all pending messages from the port and dispathes to one of the abstract handle methods (see the dokumentation -abstract_handle_methods- of each class). Most of these abstract methods will terminate the programm if not overwritten by a concrete subclass. Runtime checks -------------- For reasons of efficiency most parameters will not be checked by the library. Thus you have to ensure all the conditions mentioned in the documentation. This concerns esp. port and parameter validity. REMEMBER: You must not use a invalid port as reciever. Resource Tracking ----------------- The PortHandle Class Library does no resource tracking. That means, if you forget do call Uninit() when neccessary, the used resources will NOT BE FREED automaticly when the programm terminates. This is since in most cases the classes client will track this resources anyhow, what would only lead useless redundancy. ---------- Footnotes ---------- (1) Else it will return FALSE and return all interim used resources. (2) A Port can also become 'vaild' by using Ports/ShanghaiPort() System Requirements =================== The PortHandle Class Library needs AmigaOS 2.0 (V36) or higher and may be compiled with AmigaOberon Version 3.0, written by Fridtjof Siebert. For reasons of efficiency no OS version check is build in the library. But this should be no problem, since most programs will check this by itself in any case. Other Required Modules ====================== For compiling the PortHandler Class Library there are some other modules needed, which are not distributed in this set: MoreStrings - Copyright © 1992,1993 by hartmut Goebel current version: 1.1 SpecialStrings - Copyright © 1992 by hartmut Goebel current version: 1.0 Printf - by Volker Rudolph, hartmut Goebel, public domain needed version at least 1.3 This module can be found on the FD disks of AMOK Stuttgart and on many FTP servers. The author's addresses ********************** SnailMail hartmut Goebel Aufseßplatz 5 D-90459 Nürnberg*Germany E-Mail UseNet (prevered) hartmut@oberon.nbg.sub.org Z-Netz hartmut@asn.zer Fido hartmut Goebel of 2:246/81.1 Internet Relay Chat (IRC) nick Essich Credits ******* Fridtjof Siebert for his implementation of Oberon-2 for AmigaOS Oliver 'olk' Knorr for showing me some design defizits Hanspeter Mössenböck, Martin Reiser, Niklaus Wirth for the languages Oberon and Oberon-2 the guys from AMOK Stuttgart and AMOK Nürnberg for being good fellows :-) History ******* V 2.0 - 27 Aug 1993 Renamed most types to be homogenious and conventional - please check you modules! Redesigned IDCMPort due to a major design fault, thereby the module WinHandle has been joint into IDCMPort. Read the documentation of the modules IDCMPort and SimpleWinHandle, when using IDCMPort or any of its subclasses. V 1.4 - 4 Apr 1993 added new anstract Method RexxHost.HandleResult which is called every time a sent message comes back V 1.3 - 9 Jan 1992 splitted module Ports into Ports and PublicPorts V 1.2 - 7 Jan 1992 WinHandle no longer inherits IDCMPort since a window HAS a port V 1.1 - 6 Jan 1992 - changed receivers to VAR record for more flexibility - removed useless methods from AppPort V1.0 - 26 Dec 1992 first release Index *****