Text Mode User Interface Toolkit Reference Manual Release 1.02 Copyright (c) 1991 Trumphurst Ltd. Trumphurst Ltd. The Willows St. Martins Moor Oswestry Shropshire SY10 7BH England Tel: (+44) 0691-670318 Fax: (+44) 0691-670316 Mail: nikki@cix.compulink.co.uk nikki%cix@specialix.co.uk Contents ActionButton 3 ActiveButton 3 alert 3 AlignFlag 4 Application 4 ApplyEditButton 5 BorderFlag 6 Box 6 BoxChars 6 BoxType 6 Button 6 ButtonDefault 6 CancelButton 7 CEerrorCode 7 CenterText 7 CheckButton 8 CloseButton 9 CloseEditButton 9 Cluster 10 Collection 10 ColorSet 11 Colors 11 Command 11 CommandEvent 11 Complete 11 confirm 12 Control 12 ControlFlag 12 CriticalErrorEvent 12 CriticalErrorHandler 13 DateEdit 14 Dialog 14 DirectoryEdit 15 EditCluster 16 EditControl 16 EditControlList 16 EditFlags 16 Event 17 EventSource 17 EventQueue 17 FileAttribute 19 FileEdit 19 FileList 20 FixedText 20 FocusEvent 20 FoundFile 21 FunctionCommand 21 GCollection(type) 22 GCommand(type) 22 GIterator(type) 22 GQueue(type) 22 GStack(type) 23 Group 23 HCluster 24 HLine 24 Help 24 HelpKey 24 Inspector 25 InstantCheckButton 25 IntEdit 25 InterruptEvent 25 Iterator 25 KeyboardEvent 27 Keys 27 List 28 ListElement 28 LowerEdit 29 Menu 30 MenuBar 30 MenuButton 30 Message 30 ModalDialog 31 MouseButtons 31 MouseEvent 31 MouseInspect 32 MouseMovement 32 MultiLineText 33 NamedProtected 34 ObjectCollection 35 OCollection(type) 35 ObjectIterator 35 OIterator(type) 35 Option 36 Panel 37 PCommand(type,param) 37 Point 37 PopWindow 38 PositionEvent 38 Protected 39 RadioButton 40 RadioGroup 40 RadioHCluster 40 RadioVCluster 40 Rectangle 41 ResetEditButton 42 RightText 42 Screen 43 select 43 Space 44 StateFlag 44 SubWindow 44 Text 45 TextEdit 45 Time 47 TimeEdit 49 UnsignedEdit 50 UpperEdit 50 VCluster 51 VLine 51 VObject 51 Window 57 A ActionButton ----Button-----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "button.hpp" A Button which performs some function when clicked. The action is passed as a pointer to a Command. The Command will be executed whenever it is clicked, with the particular instance of Button passed as its doit parameter. This class is subclassed to provide the ActiveButton - such as is found in dialog boxes. ActionButton(Command *cmd = 0, const char *name = "ActionButton", Keys hotkey = Knone); The size of the ActionButton is just big enough to contain the name. ActionButton(coord width, coord height, Command *cmd = 0, const char *name = "ActionButton", Keys hotkey = Knone); The initial size of the ActionButton is specified in the constructor. ActiveButton ----ActionButton-----Button-----Control-----VObject- ----Rectangle +----NamedProtected--- - ---- Protected #include "button.hpp" An ActionButton which has a border round it. The border is normally a single box, but shows as a double box when the ActiveButton is the default (i.e. is selected by default when is pressed). ActiveButton(Command *cmd = 0, const char *n = "ActiveButton", Keys hotkey = Knone, ButtonDefault makedefault = notDefault); The size of the ActionButton is just big enough to contain the name. ActiveButton(const coord w, const coord h, Command *cmd = 0, const char *n = "ActiveButton", Keys hotkey = Knone, ButtonDefault makedefault = notDefault); The initial size of the ActionButton is specified in the constructor. void makedefault(ButtonDefault d = Default); This method can be called to turn default status on and off . alert extern void alert(const char *text,const ColorSet &c = alertColors); #include "alert.hpp" t the text (which may contain embedded newlines), and an "O.K." button. Control does not return to the caller until the user presses the button. The dialog is automatically removed from the screen. AlignFlag #include "vobject.hpp" This enum is used to specify how objects are laid out within a Cluster, and how to lay out objects on the screen. AFHcenter Place horizontally in center of rectangle AFHleft Place at left side of rectangle AFHright Place at right side of rectangle AFHexpand Expand horizontally to fit rectangle AFVcenter Place vertically in center of rectangle AFVtop Place at top of rectangle AFVbottom Place at bottom of rectangle AFVexpand Expand vertically to fit rectangle AFexpand Expand horizontally and vertically (AFVExpand | AFHExpand) AFcenter Center horizontally and vertically (AFHcenter|AFVcenter) AFtabstop Make this item a Tabstop item (see StateFlag) These flags are or-ed together. For portability, you should cast the or-ed flags to an AlignFlag, although Zortech C++ does not require this. Application ---[Group]----VObject-----Rectangle +----NamedProtected----Protected #include "applic.hpp" Every program that uses the toolkit must have one (and only one) Application declared in it. This is the only VObject that does not have to be created with new. In most programs, the Application is declared in the main module, and that is all there is to it. If you want to change the default behaviour of the application, you may sub-class Appliation, and override some virtual methods in it. Static methods A number of static methods are provided, for use either in VObject's or in your code. static void focusto(VObject *o); Move the keyboard focus to a VObject. Keyboard events will be passed to the specified VObject until another VObject takes the focus. static void mousefocusto(VObject *o,int repeat = 0); Move the mouse focus to a VObject. All mouse events will be passed to the VObject until it calls mousefocusoff. static void mousefocusoff(VObject *o); Mouse events will be passed to the topmost VObject containing the mouse cursor. static VObject *kbdfocus() { return kfocus; } static VObject *moufocus() { return mfocus; } Return the current value of the mouse and keyboard focus. static int openHelpFile(const char *filename, const char *progname = 0); Open the help file filename.HLP, and direct future help requests into this file. The table of contents and index at the beginning of the file are read into memory. Returns 0 if the file was not found, or was not a valid help file compiled with MAKEHELP.EXE. If progname is supplied, it should be the value of argv[0] (i.e. the program name), and the helpfile will be searched for on the program directory. In any case, if the help file is not found, all directories on the PATH are searched. static int help(const char *key); The string key is looked up in the table of contents of the current help file, and an appropriate page of help is displayed. On exit from help, the function returns 1. If the key is not found in the table of contents, no action is taken, and the function returns 0. ApplyEditButton ----ActiveButton-----ActionButton-----Button----- Control----- -----VObject-----Rectangle +----NamedProtected----Protected +-----------------[EditControlList]----EditControl #include "editctrl.hpp" An ActiveButton that calls the valid and write methods for all the EditControl's it is connected with. If any of the valid methods fail, then no writing is performed. ApplyEditButton's are usually used for the "Apply" button in a dialog, which will update the values being set by the dialog, but without closing the dialog box. ApplyEditButton(EditControl *e, const char *name = "Apply", Keys hotkey = Knone, Command *cmd = 0); An ApplyEditButton with only 1 EditControl connected with it. ApplyEditButton(EditControl **e, const char *name = "Apply",Keys hotkey = Knone, Command *cmd = 0); An ApplyEditButton with an array of EditControl's connected with it. B BorderFlag #include "vobject.hpp" This enum is used to indicate the type of border on (for example) Windows, Boxes, Clusters and Dialogs. BFnone No border BFsingle Single box border BFdouble Double box border BFbold Bold strip border BFstyle Mask the above only BFshowactive Double box if Button is "active". BFtitle Place name in title bar BFtabstop Set SFtabstop These flags are or-ed together. For portability, you should cast the or-ed flags to a BorderFlag, although Zortech C++ does not require this. Box ----Space-----VObject-----Rectangle +----NamedProtected----Protected #include "layout.hpp" An empty box VObject. The type of box border can be determined (default BFsingle), and the width and height. Box(coord width,coord height, BorderFlag b = BFsingle, const char *name = "Box"); BoxChars #include "hardware.hpp" An array of strings used to draw the various boxes and lines. This is included in screen.cpp so that the strings may be changed for other operating systems (e.g. Unix). BoxType #include "hardware.hpp" This enum is used internally to describe the various types of boxes. The values used in the DOS text mode version are BTnone, BTsingle, BTdouble, and BTbold. Button ----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "button.hpp" The Button is the basis for all the different kinds of button. ButtonDefault #include "button.hpp" This enum is used when creating ActiveButtons, to indicate whether they are to be the default button. notDefault Default C CancelButton ----ActiveButton-----ActionButton-----Button----- Control----- -----VObject-----Rectangle +----NamedProtected----Protected #include "button.hpp" An ActiveButton which will cancel the current Window if it is clicked. Cancelling a Window involves calling the Window cancelok method (which normally places a CloseEvent for itself in the event queue and returns 1). The CloseEvent will remove the Window from the Application and delete it (also any VObjects within it). CancelButton(const char *name = "Esc=Cancel", Keys hotkey = Kesc, Command *cmd = 0, ButtonDefault makedefault = notDefault); This constructor makes it easy to change the displayed name of the button, and its hot key. Notice that there is usually a hot key for this button (Esc). Notice also that the button is not the default button unless you provide a Default argument. CancelButton(Command *cmd, ButtonDefault makedefault = notDefault, const char *name = "Esc=Cancel"); This constructor makes it easy to add aditional processing to the CancelButton. The supplied Command will be executed when the button is pressed. Only if it returns != 0 will the cancel process proceed. Note that the hotkey (Esc) cannot be changed in this constructor. CEerrorCode #include "event.hpp" An enum describing the possible DOS critical errors. See CriticalErrorEvent. CEwriteProtected Write protect error CEnoSuchDrive Unknown unit CEnotReady Drive not ready CEbadCommand Unknown command CEdataError Data error CEbadRequest Bad request structure length CEseekError Seek error CEmedia Unknown media type CEsectorNotFound Sector not found CEpaperOut Printer out of paper CEwriteError Write fault CEreadError Read fault CEgeneralError General error CenterText ----Text-----VObject-----Rectangle +----NamedProtected----Protected #include "textedit.hpp" A Text string that centres itself. CenterText(const char *string,int length = -1); If length is not specified, the length of the string is used as the initial size of the CenterText. CheckButton ----Button-----Control-----VObject-----Rectangle +----NamedProtected----Protected +--------------EditControl #include "check.hpp" A checkable button, with two states - on and off. Clicking on it, or pressing the space bar, toggles it on or off. It can be used to set whole or part of an unsigned int to bit-values of all 1's, or all 0's. This is achieved with a bit mask (setbits below). In this way, you can use a series of CheckButtons to set each individual bit in a word. As this is also an EditControl, the initial value is read from the unsigned int on creation, and written back only when the write method is called. Normally, CheckButtons will be written back automatically with a CloseEditButton or an ApplyEditButton. CheckButton(const char *name, unsigned int &result, unsigned int setbits); If (result & setbits) == setbits the CheckButton will be on initially. int value() const; Returns setbits if the CheckButton is pressed, 0 if it is not pressed. Example : unsigned int chk = 0; // The integer to set // Now declare the Buttons CheckButton *cb1 = new CheckButton("Check 1",chk,BIT(0)), *cb2 = new CheckButton("Check 2",chk,BIT(1)), *cb3 = new CheckButton("Check 3",chk,BIT(2)); // Put pointers to them in an array of EditControls EditControl *a[] = { cb1, cb2, cb3, 0 }; // Use a Dialog to display them ModalDialog *d = new ModalDialog( new VCluster( // Organise one above the other cb1, cb2, cb3, new HCluster( // Then a horizontal group AlignFlag(AFHexpand|AFtabstop), // which is a Tabstop new CloseEditButton(a), new ApplyEditButton(a), new ResetEditButton(a), new CancelButton, EndList), EndList), "Test Check Buttons"); d->enter(); Bits 0-2 of chk will be set according to which buttons were checked by the user. CloseButton ----ActiveButton-----ActionButton-----Button----- Control----- -----VObject-----Rectangle +----NamedProtected----Protected #include "button.hpp" An ActiveButton which will close the current Window if it is clicked. Closing a Window involves calling the Window closeok method (which normally places a CloseEvent for itself in the event queue and returns 1). The CloseEvent will remove the Window from the Application and delete it (also any VObjects within it). CloseButton(const char *name = "O.K.", Keys hotkey = Knone, Command *cmd = 0, ButtonDefault makedefault = Default); This constructor makes it easy to change the displayed name of the button, and its hot key. Notice that the button is made the default button unless you provide a notDefault argument. CloseButton(Command *cmd, ButtonDefault makedefault = Default, const char *name = "O.K."); This constructor makes it easy to add aditional processing to the CloseButton. The supplied cmd Command will be executed when the button is pressed. Only if it returns != 0 will the close process proceed. CloseEditButton ----CloseButton-----ActiveButton-----ActionButton--- -- -----Button-----Control-----VObject----- Rectangle +----NamedProtected---- Protected +-----------------[EditControlList]----EditControl #include "editctrl.hpp" A CloseButton which will validate and write one or more EditControls before closing the containing Window. If any of the EditControls contains invalid data, the Window will not be closed. CloseEditButton(EditControl *e, const char *name = "O.K.",Keys hotkey = Knone, Command *cmd = 0, ButtonDefault makedefault = Default); CloseEditButton(EditControl *e, Command *cmd, ButtonDefault makedefault = Default, const char *name = "O.K."); These two constructors correspond to the two CloseButton constructors, but also take a pointer to the single EditControl to validate and write. CloseEditButton(EditControl **e, const char *name = "O.K.", Keys hotkey = Knone, Command *cmd = 0, ButtonDefault makedefault = Default); CloseEditButton(EditControl **e, Command *cmd, ButtonDefault makedefault = Default, const char *name = "O.K."); These two constructors duplicate those above, but take an array of EditControls to validate and write. Cluster ----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "cluster.hpp" The Cluster is the basis of the automatic layout of VObjects on the screen. This is the base class for the two types of Cluster you will actually use - the HCluster (for horizontal rows of VObjects), and the VCluster (for vertical columns of VObjects). It could be used to derive new types of Cluster - a TableCluster perhaps ? Collection #include "collect.hpp" This class library (like most others) provides a Collection class to hold lists of objects. This base Collection class will hold any object, as the implementation is a dynamic array of void pointers. The generic class macros are used to provide type-safe Collections of any particular kind of object, and also Stacks and Queues. A useful variety of methods are provided, together with a copy constructor and assignment operator, so you can assign Collections to one another without problems. Maintaining the Collection int add(const void *c); Add item. Returns place added, or -1 on error. void insert(const void *c); Add item to beginning of Collection. void append(const void *c); Add item to end of Collection. void appendvalist(va_list v); Add all items in (null-terminated) va_list to end of Collection. int remove(const void *c); Remove item from Collection. Returns 0 if the item was not found in the Collection. Access functions int size() const; Number of elements in the Collection. void *first() const; Return first item in the Collection. void *last() const; Return last item in the Collection. void *operator[](int i) const; Return an element from the Collection. int elementNo(const void *e) const; Return the element number of an item (or -1 if e is not in the Collection). Miscellaneous void *get(); Removes and returns a pointer to the first item in the Collection. void *getlast(); Removes and returns a pointer to the last item in the Collection. int error(); Returns non-zero if an operation (e.g. add) failed because of shortage of memory. Using generic Collection classes. To declare a Collection class to hold Widgets (say), all you need to do is ... declare(GCollection,Widget); This will create a Collection class, called GCollection(Widget). Note that all the functions are inline, so no further implementation is needed. Stacks and Queues are created in a similar way, but are provided with appropriate maintenance and access methods - see GQueue(type) and GStack(type). ColorSet #include "vobject.hpp" A structure containing the eight colors used to render a particular Window. The color used for any individual VObject are determined from the lowest 3 bits of its StateFlag (hence 8 colors). The 3 bits in question represent disabled, focussed, and highlighted. Each Window can have its own ColorSet. The library provides three sets - normal windows (defaultColors), alert boxes (alertColors), and help screens (helpColors), which automatically take account of current screen mode (mono or color). Colors #include "hardware.hpp" This enum defines the coilors available on the current platform. Under DOS, the colors are ... Black, Blue, Green, Cyan, Red, Magenta, Brown, White, Gray, LightBlue, LightGreen, LightCyan, LightRed, LightMagenta, Yellow, BrightWhite and Blinking (which may be ored with the others). Command ----Protected #include "command.hpp" This is the base class for a whole collection of classes (see GCommand below). It enables pointers to methods in classes to be passed around the system and through the EventQueue in a type-safe manner. virtual int v_doit(VObject *sender); The virtual method which is overridden in subclasses. The default implementation does nothing int doit(VObject *sender) { VALIDATE(this); return v_doit(sender); } Public method which calls v_doit after validating the Command (see Protected below). CommandEvent ----Event #include "command.hpp" CommandEvent(Command *command); Construct a CommandEvent which will execute command when it is despatched. Complete #include "textedit.hpp" This enum is returned from the complete virtual method of a TextEdit, to indicate what action is to be taken whenever the user has changed the Text, and wants to move the focus off the TextEdit. COK The text is valid, it should be left unchanged. Cchanged The text was not valid, but it has been changed to a valid value. Crestore The original text (before the focus arrived on it) will be restored. Cinvalid The text is invalid (prevents write() from updating the parameter). confirm extern int confirm(const char *text,const char *yestext = "Yes", const char *notext = "No", const ColorSet &c = alertColors); #include "alert.hpp" Place a Confirmation Dialog on the screen. The dialog contains the text (which may contain embedded newlines), and "Yes" and "No" buttons. Return value is 1 if the user pressed the "Yes" button, 0 for the "No" button. The dialog is automatically removed from the screen. Control ----VObject-----Rectangle +----NamedProtected----Protected #include "vobject.hpp" A VObject which will accept the keyboard focus. This is used as the base class of all interactive objects, such as Buttons and TextEdits. Protected constructor to place a Control in a perticular spot in a Window ... Control(const Rectangle &r,const char *name = "Control"); Public constructors Control(const char *n = "Control"); Placement will be carried out by a Cluster. Size will be determined by the return values of the minwidth, minheight, maxwidth and maxheight methods. Control(const coord left, const coord top, const coord right, const coord bottom, const char *name = "Control"); Exact placement. Control(const coord width, const coord height, const char *name = "Control"); Exact sizing. Placement will be carried out by a Cluster. ControlFlag #include "vobject.hpp" This enum is used to indicate the internal state of a VObject. It is not normally manipulated by user programs. CFNone No flags set. CFfocus Keyboard focus on object. CFsize Change in size of object. CFposition Object moved. CFdirty Needs painting. CFcontentsdirt Contents need updating. y CFpartdirty dirtyArea is valid. Part needs painting. CFclean Anything needs updating. CFupdate Any part needs painting. CFactive Interested in events. These flags are or-ed together. For portability, you should cast the or-ed flags to a ControlFlag, although Zortech C++ does not require this. CriticalErrorEvent ----Event #include "event.hpp" The Event generated when a DOS critical error occurrs while a CriticalErrorHandler is in existence. virtual int handle(VObject *o); Pass the Event to the VObject's criterr method. The important access methods int drive() const; The DOS drive letter which caused the error, or '?' if no drive applies. int ax() const; The value from the AX register when the DOS critical error handler was called. See your DOS programmers manual for details. CEerrorCode errcode() const; The error code. const char *description() const; A standard 2-line description of the error. Useful if you want to pop up an alert box describing the error to the user. CriticalErrorHandler #include "event.hpp" CriticalErr CriticalErrorHandler in the function or block. Critical errors will be trapped from the declaration to the end of the enclosing block. This is one of the few objects in the toolkit that is declared directly, rather than being allocated via new. D DateEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "timeedit.hpp" A TextEdit to allow the user to amend the date portion of a Time. It automatically aligns itself within an EditCluster, showing the prompt in the left-hand column, and the date itself in the right-hand column. As this is also an EditControl, the initial value is read from the Time on creation, and written back only when the write method is called. Normally, TimeEdits will be written back automatically with a CloseEditButton or an ApplyEditButton. DateEdit(Time &t,const char *prompt = ""); Example : Time t1; // The time is set to the system clock // Now declare the Edits EditCluster *e = new EditCluster( new DateEdit(t1,"System date"), new TimeEdit(t1,"System time"), EndList); ModalDialog *d = new ModalDialog( new VCluster( // Organise one above the other e, new HCluster( // Then a horizontal group AlignFlag(AFHexpand|AFtabstop), // which is a Tabstop new CloseEditButton(e), new ApplyEditButton(e), new ResetEditButton(e), new CancelButton, EndList), EndList), "Test Check Buttons"); d->enter(); The Time t1 will now be set according to the user's input. Dialog ----Window-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "dialog.hpp" The basic user-interaction dialog box. A Dialog has a box round it, with a title bar of name. The enter method for a basic Dialog returns immediately, before user interaction occurs. If you want to do some processing at the end of the Dialog, you can either attach functions to the CloseButton and the CancelButton, or you can use a ModalDialog (see below). Dialog(VObject *contents,const char *name); Create a Dialog containing the VObject contents. The Dialog will be positioned automatically in the centre of the screen. Dialog(const coord left, const coord top, const coord right, const coord bottom, VObject *contents, const char *name); Create a Dialog in a specific place on the screen. Manipulate Dialogs in Application void enter(); Display the Dialog on the screen, and make it the focus. This function returns immediately - the Dialog will be displayed, and user interaction will start, when control returns to the Application message loop. Note that all events will be passed to the Dialog until it is closed, which makes it a modal dialog. void show(); Place the Dialog on the screen, and make it the focus. This function returns immediately - the Dialog will be displayed, and user interaction will start, when control returns to the Application message loop. Note that the Dialog will be treated like any other Window, which makes it a non-modal dialog. void remove(); Remove the Dialog from the screen. DirectoryEdit ----FileEdit-----UpperEdit-----TextEdit-----Control- ---- -----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "fileedit.hpp" A TextEdit which allows the user to enter a DOS directory name. This class implements the browse method, allowing the user to pop down a browse window with a list containing the current directory, all the subdirectories of the current directory, the parent directory and all other disk drives. The user may select the current directory, or navigate around the directory tree by selecting subdirectories, the parent directory, or other disks. The directory name field is set to 30 characters in the current implementation. Future implementations will accept a length parameter. "" ""); E EditCluster ----HCluster-----Cluster-----Group-----VObject----- Rectangle +----NamedProtected---- Protected +--------------EditControl #include "editclus.hpp" This is an automatic layout tool for TextEdits. It arranges the TextEdits in a vertical column, with the prompts lined up on the left, and the fields on the right. The constructors all take a variable-length list of TextEdits (terminated by EndList). Multiple constructors are provided because the variable arguments must be last in the argument list, so the default argument mechanism cannot be used. EditCluster(TextEdit *e,...); EditCluster(AlignFlag a,TextEdit *e,...); EditCluster(const char *name, AlignFlag a, TextEdit *e,...); EditCluster(const char *name, AlignFlag a, BorderFlag f, TextEdit *e,...); The defaults for the shorter constructers are ... name "HCluste Not shown on screen unless r" BFtitle is used a AFexpand Expand to fit container f BFnone No border EditControl #include "editctrl.hpp" The basic class for all VObjects that allow the user to update a value (e.g. TextEdit, CheckButton). This class provides the following important virtual methods ... read Get the value from the variable valid Check the user input is valid write Validate the input and write it back to the variable writeback Just write back the current value (assumed valid) To create a new class based on EditControl, you only need to override the virtual methods read, valid and writeback. The main value of deriving classes from EditControl is that they can then all be connected to CloseEditButtons, ApplyEditButtons and ResetEditButtons, giving automatic control of a user dialog. EditControlList ----EditControl #include "editctrl.hpp" This is an internal class, used to keep track of EditControls in EditButtons. EditFlags #include "textedit.hpp" This is an internal enum, used to hold the internal state of a TextEdit. Event #include "event.hpp" An abstract class for the basic external event on the EventQueue. virtual int despatch(class Window *control) = 0; Decide which VObjects in the Application are to handle the event. Calls handle() for each one in turn until handle returns non-zero. May call handle with special value of 0, meaning send the event to the Application. This method will be overridden in derived classes - e.g. a KeyboardEvent despatches itself to the keyboard focus, a MouseEvent despatches itself to the mouse focus, or to the object in which the event happened. virtual int handle(VObject *o) = 0; Send the Event to the specified VObject. Return 0 if the VObject was not interested. May be called with a special value of o = 0, meaning send the Event to the Application. EventSource ----NamedProtected----Protected #include "event.hpp" An external source of Events - e.g. a mouse, or the keyboard. A derived class exists for each possible source of Events. You can easily add your own EventSources by deriving from this class. The toolkit already contains internal static EventSources for the mouse, keyboard and control-c handler. These sources are automatically added to the EventQueue when it is created. You can create your own event sources and add them to the queue if you wish. EventSource(const char *name); The constructor merely takes a name for debugging purposes. Event *poll(); virtual Event *v_poll() = 0; meth method is called. The v_poll virtual method will only be called when the EventSource is enabled. int enable(); virtual int v_enable(); This method should contain any setup code (e.g. hooking interrupts) for the EventSource. It will be called when the EventQueue is enabled (after the Screen object is initialised). It may also be called again (after a call to disable) - e.g. after shelling to DOS. Return 1 on success, 0 on failure. The v_enable virtual method will only be called if the EventSource is not currently enabled. void disable(); virtual void v_disable(); This method should contain any tidy up code (e.g. restoring interrupts) for the EventSource. It will be called when the EventQueue is disabled (before the Screen object is restored). It may also be called during the execution of the program, e.g. before shelling to DOS. The v_disable virtual method will only be called if the EventSource is currently enabled. protected: int enabled(); Indicates whether the EventQueue is to poll this EventSource. This flag is set and reset when enable and disable are called. EventQueue #include "event.hpp" The main event queue for the system. Only one EventQueue is created, called eventQueue. This must be created in your main program, before the Application. It is enabled when the Application starts up, and polled by the Application. You can add new EventSources to those polled by the queue. extern EventQueue eventQueue; Event *operator() (); Returns the next Event from the EventQueue. Returns 0 if no event is waiting. int add(EventSource *s); Add a new EventSource. The EventSource should normally be enabled when adding, but this is not necessary if you intend to enable it later. The enabled flag determines whether the EventSource is polled. Returns -1 on failure. int remove(EventSource *s); Remove an EventSource. returns 0 on failure. void enable(); Enable all EventSources (unless they are already enabled). Sets the enabled flag on each EventSource successfully enabled. void disable(); Disable all EventSources (unless they are already disabled). Clears the enabled flag on each EventSource disabled. F FileAttribute #include "flist.hpp" This enum is used for two purposes - to specify which FoundFiles will appear in a Filelist, and to indicate the type of a particular FoundFile. FAnone No attributes FAreadable Set if you want non-readable files/dirs excluded Used for files that are readable (all files in DOS) FAwriteable Set if you want non-writeable files/dirs excluded Used for files that are writeable FAfile Set if you want files included Used for files (not directories) FAdirectory Set if you want directories included Used for directories FAexcludedot Set if you DON'T want current dir included FAfixeddisk Set if you want hard disk letters including Used for hard disks FAremovedisk Set if you want floppy disk letters including Used for floppy disks FAdisk Set if you want both types of disk letters including FAdummy Used for any FoundFile created with the third (user-defined) constructor. These flags are or-ed together. For portability, you should cast the or-ed flags to a FileAttribute, although Zortech C++ does not require this. FileEdit ----UpperEdit-----TextEdit-----Control-----VObject-- ---Rectangle +----NamedProtected--- - ---- Protected +------------EditControl #include "fileedit.hpp" A TextEdit which allows the user to enter a DOS file name. This class implements the browse method, allowing the user to pop down a browse window with a list containing all the files in the current directory, all the subdirectories of the current directory, the parent directory and all other disk drives. The user may select a file from the current directory, or navigate around the directory tree by selecting subdirectories, the parent directory, or other disks. The file name field is set to 30 characters in the current implementation. Future implementations will accept a length parameter. FileEdit(char *fileName, const char *prompt = "", int allowCreate = 0, FileAttribute a = FAfile); If allowCreate is non-zero, any valid DOS filename which includes a valid path (or no path at all) will be accepted as valid. If it is zero, only existing DOS files are allowed. Changing the value of FileAttribute determines the type of file that may be accepted - e.g. a value of FAwriteable will not allow the selection of an existing read-only file. FileList ----List-----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "flist.hpp" This is a list of FoundFiles, which can be displayed on the screen. It is used to show the pop-down file/directory browse lists associated with FileEdits and DirectoryEdits. It may also be used to present a scrollable list of files in your own code. FileList(coord height, const char *fname = "*.*", FileAttribute a = FileAttribute(FAfile|FAdirectory), const char *name = "FileList", const BorderFlag b = BorderFlag(BFsingle|BFtabstop)) ; Fix the height. Include file matching fname, with attributes a. The default border is a single box, and the FileList is a tabstop. FileList(const char *fname = "*.*", FileAttribute a = FileAttribute(FAfile|FAdirectory), const char *name = "FileList", const BorderFlag b = BorderFlag(BFsingle|BFtabstop)) ; As above, but the height will be set by a containing Cluster. int addfiles(const char *fname = "*.*", FileAttribute a = FileAttribute(FAfile|FAdirectory)) ; Add files matching fname with attributes a to the FileList. int addFile(FoundFile *f); Add a single file to the list. You can use this method to add your own user-defined FoundFile objects to the list. const FoundFile *selected() const; Return the FoundFile from the list that the user selected. Returns 0 if no file is selected. void sort(int (*compare)(const FoundFile *,const FoundFile *)); Sort the FileList. The list will be maintained in order when new items are added to it. Suggested functions for compare are sortname, sortext, sorttime and sortsize. int count() const; Return the number of FoundFiles in the list. If you are deriving a subclass to enable the user to pick a file or directory from a list, you will probably want to override the pick and escape virtual methods. They are called when the user selects an item (by pressing or by double clicking on it), and when the user presses Escape (or right-clicks on the list) respectively. FixedText ----VObject-----Rectangle +----NamedProtected----Protected #include "text.hpp" This is the "cheapest" way of getting fixed, static text displayed on the screen. No memory is allocated to hold a copy of the text string supplied, so it had better be a constant string. FixedText(const char *string); FocusEvent -----Event #include "event.hpp" An abstract Event which is despatched to the keyboard focus. virtual int despatch(Window *control); Tries to pass the Event to the keyboard focus of the Application, or its containing VObjects. virtual int handle(VObject *o) = 0; FoundFile ----ListElement-----VObject-----Rectangle +----NamedProtected----Protected #include "flist.hpp" This class is used in FileLists, to hold information about a file, directory or disk. FoundFile(struct FIND *f); Construct from structure returned by findfirst (see dos.h). FoundFile(char disk,int fixed); Construct a disk name FoundFile. FoundFile(const char *name, FileAttribute a = FAdummy, const Time &time = Time::zero, unsigned long size = 0); Construct a user-defined FoundFile. The FAdummy attribute will always be set. const char *fname() const; Return the file name. Skips the first character of disk ([) and directory (\) names. FileAttribute attribute(FileAttribute a = ~FAnone) const; Test to see if this FoundFile has any particular attributes. The default parameter returns all the attribute flags. const Time &time() const; Return the file time (zero for disk name entries). unsigned long size() const; Return the file size (0 for disk name entries). FunctionCommand ----Command----Protected #include "command.hpp" FunctionCommand(int (*function)(VObject *)); The FunctionCommand is constructed with a pointer to a standard function. The function will be called whenever the Command is executed. The function will be passed a pointer to the sending VObject passed to Command::doit(). virtual int v_doit(VObject *sender); The virtual execution method which calls the function. G GCollection(type) ----Collection #include "collect.hpp" A generic Collection to hold items of a particulart type. See Collection for method details. To declare a Collection class to hold Widgets (say), all you need to do is ... declare(GCollection,Widget); This will create a Collection class, called GCollection(Widget). Note that all the functions are inline, so no further implementation is needed. GCommand(type) ----Command----Protected #include "command.hpp" A Generic Command which calls a method for objects of type type. The method is passed a pointer to the sending VObject passed to GCommand(type)::doit(). GCommands may be associated with Options, Buttons etc. To make an ActionButton which calls the select(VObject *) method of your class MyList, you first need a GCommand class which can send messages to a MyList. All you need to do is declare(GCommand,MyList); in your header (mylist.hpp) file. This will provide the definition of a GCommand class, called GCommand(MyList), including all the inline functions. Then, in your mylist.cpp file, do implement(GCommand,MyList) (Note lack of semicolon), which will implement the non- inline functions. Now, assuming you have created a MyList object called aMyList, you can create the ActionButton ... ActionButton *button = new ActionButton(new GCommand(MyList)(MyList::select,aMyList), "Select"); Constructor GCommand(type)(int (type::*function)(VObject *), type *destination); The method to be called and the object to which to send the message are specified in the constructor. GIterator(type) ----Iterator #include "collect.hpp" An Iterator which iterates over a generic Collection - GCollection(type). To declare an Iterator class for a GCollection(Widget) (say), all you need to do is ... declare(GIterator,Widget); This will create an Iterator class, called GIterator(Widget). Note that all the functions are inline, so no further implementation is needed. GQueue(type) ----Collection #include "collect.hpp" A generic queue to hold items of a particulart type. For constructors, see Collection. To declare a Queue class to hold Widgets (say), all you need to do is ... declare(GQueue,Widget); Note that all the functions are inline, so no further implementation is needed. The methods for queues are ... void put(const Widget *item); Place an item on the end of the queue. Widget *peek() const; Return the item at the front of the queue, without removing it. Returns 0 if there is nothing in the queue. Widget *last() const; Return the item at the back of the queue, without removing it. Returns 0 if there is nothing in the queue. Widget *get(); Remove and return the item at the front of the queue. Returns 0 if there is nothing in the queue. GStack(type) ----Collection #include "collect.hpp" A generic stack to hold items of a particulart type. For constructors, see Collection. To declare a Stack class to hold Widgets (say), all you need to do is ... declare(GStack,Widget); Note that all the functions are inline, so no further implementation is needed. The methods for stacks are ... void push(const Widget *item); Push an item onto the top of the stack. Widget *peek() const; Return the item on the top of the stack, without removing it. Returns 0 if there are no items on the stack. Widget *pop() const; Remove and return the item on the top of the stack. Returns 0 if there are no items on the stack. Group ----VObject-----Rectangle +----NamedProtected----Protected #include "group.hpp" The basic VObject containing a group of other VObjects. This is subclassed for Window, Cluster, List, Menu etc. etc. It takes care of painting all its contents, passing events between them, determining its own dimensions from the dimensions of its contents and so on. H HCluster ----Cluster-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "cluster.hpp" A Cluster of VObjects automatically laid out in a horizontal row. The VObjects to be laid out are passed as a variable argument list to the constructor (terminated with EndList). Multiple constructors are provided, as the default argument mechanism cannot be used with variable arguments. HCluster(VObject *v,...); HCluster(AlignFlag a,VObject *v,...); HCluster(const char *name,AlignFlag a,VObject *v,...); HCluster(const char *name,AlignFlag a,BorderFlag f,VObject *v,...); HCluster(const char *name = "VCluster", AlignFlag a = AFexpand, BorderFlag f = BFnone); This last constructor is used to create an empty HCluster, which will later be filled by calls to the add method, and it indicates the defaults for missing arguments to the previous constructors. HLine ----Box-----Space-----VObject-----Rectangle +----NamedProtected----Protected #include "layout.hpp" A simple horizontal line. The line type is specified as a BorderFlag. HLine(coord width = 1,BorderFlag b = BFsingle,const char *n = "HLine"); Help #include "help.hpp" This class (together with the related classes below) provides the functionality of the context-sensitive, hyper-text help system. It contains the help index for a particular help file, and has methods to look up help pages etc. Help files are created using any text editor, and "compiled" using MAKEHELP.EXE. HelpKey ----ListElement-----VObject-----Rectangle +----NamedProtected----Protected #include "help.hpp" Part of the help system, this class holds details of a key in the help index. I Inspector ----Window-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "inspect.hpp" The Inspector class implements the inspect facility. Clicking on any VObject while the Alt key is held down will pop up an Inspector for that VObject. This feature is disabled if the libraries are compiled with #define NINSPECT. InstantCheckButton ----CheckButton-----Button-----Control-----VObject-- --- +----NamedProtected--- - ---- Protected -----Rectangle +---------------EditControl #include "check.hpp" A CheckButton that updates its parameter immediately it is checked (or unchecked), rather than waiting for a write call. InstantCheckButton(const char *name,unsigned int &result, unsigned int setbits); IntEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "textedit.hpp" A TextEdit for integers. IntEdit(int &i,const char *prompt = "",int low = INT_MIN,int high = INT_MAX); The range of permissible values is specified with low and high. InterruptEvent ----Event #include "event.hpp" The event generated whenever an interrupt signal occurs (Ctrl-Break under DOS). The default Application traps this event, and puts up a confirmation box before exiting the program. virtual int handle(VObject *o); The Event is passed to the VObject's interruptevent method. Iterator #include "collect.hpp" This class provides an iterator to step over the elements of a Collection one at a time. The class allows traversal in either direction, and maintains a default direction set up in the constructor. The Iterator can even be started at a particular element in the Collection, rather than at the beginning (or end if traversal is backwards). Iterator(const Collection& l, int backwards = 0); Iterator(const Collection& l, const void *startAt, int backwards = 0); Move pointer about list void start(); void end(); void reset(); To start/end depending on default direction int set(const void* s); To a particular member of list Normal traversal of list void *next(); void *previous(); void *operator() (); Access next element in default direction K KeyboardEvent ----FocusEvent----Event #include "event.hpp" virtual int despatch(Window *control); Each character of keyboard input is passed to the FocusEvent despatch method, which tries to pass it to the keyboard focus of the Application, or its containing VObjects. If none of these are interested, the various hotkey methods are tried in turn. virtual int handle(VObject *o); Pass the event to the VObject kbdevent method. The important access methods are ... unsigned value() const; Return the ASCII value of the key pressed, or one of the values from the Keys enum. unsigned shifts() const; Return the shift state (as returned by the BIOS). This state might be meaninless under Unix. Keys #include "hardware.hpp" This enum gives special named values for each special key on the keyboard (such as Alt keys, function keys, etc.). There is also a special value Kauto used as a hot key in Menu Option constructors, indicating that Alt+ the quick key should be used (or some other combination under Unix). Programmers wishing to produce portable applications should not rely on more than 10 function keys, and should not rely on Alt keys if they intend to port to Unix. L List ----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "list.hpp" This class provides the basic scrollable list. It is used for pop-down lists, lists of Menu Options etc. List(ObjectCollection &c,const char *name = "List", const BorderFlag b = BFsingle); The size is calculated from the contents. List(ObjectCollection &c, coord width, coord height, const char *name = "List", const BorderFlag b = BFsingle); The size is specified in the constructor. Methods provided are ... int line() The currently selected item no (or -1) int size() The number of items in the list virtual int select(const int s); Select an item in the list. Returns 1 if s was a valid item number. virtual void deselect(); Deselect the current item (if any). virtual int pick(); This virtual method is called whenever an item is selected with or click. It may be overridden in subclasses - the default behaviour is to ignore the event. virtual int escape(); This virtual method is called when the user presses Esc or clicks the right mouse button over the list. Again, the default behaviour is to ignore the event. int topitem(); Return the item number currently shown at the top of the list. void deleteall(); Delete all the items in the ObjectCollection. void changeCollection(); Inform list of a change to the ObjectCollection. int remove(int itemno); Remove item from ObjectCollection. int add(VObject *o); Add item to ObjectCollection. For type safety, this should be overridden in derived Lists. void resize(int changeheight = 0); Make the list the right size for the ObjectCollection. The width of the List will be the size of the widest VObject in it (plus the border), and the size of the list will be reduced so there are no empty slots visible. If changeheight is non-zero, the height will be increased if the collection can't all be seen. void makeVisible(int item); Ensure the specified item is visible on the screen (scrolling the list if necessary). ListElement ----VObject-----Rectangle +----NamedProtected----Protected #include "list.hpp" A typical element of a List. This class is provided as a building block, to be subclassed for special kinds of VObject that need to be displayed in a List. When it is painted, it merely shows its name. The default width is the length of the name string. LowerEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "textedit.hpp" A TextEdit which automatically translates all input to lower case. LowerEdit(char *string,int length, const char *prompt = ""); M Menu ----List-----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "menu.hpp" A pop-down menu. Menus are normally attached to MenuButtons, and are invoked automatically when the button is pressed. Menu(const char *name,const ColorSet &c = defaultColors); Options will be added later, using addOption and addvalist. Menu(const char *name,const ColorSet &c,Option *o,...); Options included in constructor. Menu(const char *name,Option *o,...); As above, using the default ColorSet. void addOption(Option *o); Add an Option to the menu. void addvalist(Option *o,va_list args); Add a va_list of Options to the menu. MenuBar ----HCluster-----Cluster-----Group-----VObject----- Rectangle +----NamedProtected---- Protected #include "menu.hpp" A menu bar, consisting of MenuButtons, each with its own Menu. A MenuBar is created automatically when you create a Panel. MenuBar(Keys hotkey,MenuButton *b,...); SAA convention says the hotkey should be KF10. MenuButton ----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "menu.hpp" A Button which pops down a Menu when it is pushed. MenuButton(const char *name,Menu *m,Keys hotkey = Kauto); Constructor taking a Menu. The name may contain one tilde (~) character just before a letter or digit. This will be used as the quick key - pressing this key while the MenuBar containing this MenuButton is in focus will select the button, and pop down the Menu. The default value of hotkey will cause this same key to be used with the Alt key as the hotkey for this MenuButton. Pressing Alt+this key will immediately pop down the Menu, from anywhere in the Application. MenuButton(const char *n,Keys hotkey,Option *o,...); Shorthand constructor which makes its own Menu and places the supplied Options on it. Message #include "alert.hpp" A Window containing a message to the user is popped up on the screen. The window will be removed next time control returns to the Application message loop. Message(const char *text,int width = -1, AlignFlag alignment = AFcenter, BorderFlag border = BFdouble, const ColorSet &c = defaultColors); The constructor gives full control over the size, relative position, color and border of the Message, but the default values are for the size to be the length of the string, the single box to be centered on the screen, and for the default color to be used. ModalDialog ----Dialog-----Window-----Group-----VObject----- Rectangle +----NamedProtected---- Protected #include "dialog.hpp" The classic modal dialog. A ModalDialog has a box round it, with a title bar of name. The enter method for a ModalDialog shows the dialog, and interacts with the user immediately. It does not return until the user closes the dialog. ModalDialog(VObject *contents,const char *name); Create a ModalDialog containing the VObject contents. The ModalDialog will be positioned automatically in the centre of the screen. ModalDialog(const coord left, const coord top, const coord right, const coord bottom, VObject *contents, const char *name); Create a ModalDialog in a specific place on the screen. Manipulate ModalDialogs in Application ... void enter(); Display the Dialog on the screen, and make it the focus. This function displays the Dialog, and completes user interaction before returning. Note that all events will be passed to the ModalDialog until it is closed, which makes it a modal dialog. void show(); Place the ModalDialog on the screen, and make it the focus. This function returns immediately - the ModalDialog will be displayed, and user interaction will start, when control returns to the Application message loop. Note that the ModalDialog will be treated like any other Window, which makes it a non-modal dialog ! void remove(); Remove the ModalDialog from the screen. MouseButtons #include "event.hpp" This enum contains bit flags indicating which mouse buttons are pressed. MBnone 0 MBleft BIT(0) MBright BIT(1) MBmiddle BIT(2) MBinspect BIT(3) MouseEvent ----PositionEvent----Event #include "event.hpp" A MouseEvent is placed in the event queue whenever the mouse is moved, ot a button is depressed or released. typedef int (VObject::*mouseEventFunc)(MouseEvent &); MouseEvent(mouseEventFunc handler = 0, const char *name = "", const Point &here = origin, MouseButtons buttons = MBnone); The constructor is passed a pointer to a VObject method which will be called whenever the MouseEvents handle method is called. The important access methods are ... MouseButtons buttons(); Which buttons are pressed. See MouseButtons above const Point& at(); Position where event happened. Other methods virtual int handle(VObject *o); Pass the MouseEvent to the Vobjects handle method. This method may call the MouseEvent's callHandler method to re- despatch the MouseEvent to the intended VObject method. The default handle method first calls the mouseenter or mouseexit methods if necessary, then, if they do not return 1, it calls back the callHandler method as described. int callHandler(VObject *o) { return (func ? (o->*func)(*this) : 0); } Pass the Event to the VObject method pointer given in the constructor. const char *name() const { return namestring; } The name of the event (for debugging). static int doubleClickTime; This is set to the time (in hundredths of a second) which must elapse between two clicks for them not to be treated as a double click. The default value is 50 (half a second). MouseInspect -----MouseEvent-----PositionEvent-----Event #include "event.hpp" A MouseInspect Event is placed in the EventQueue whenever the left mouse button is pressed while the Alt key is held down. This facility is disabled if the library is compiled with NINSPECT defined. MouseInspect(const Point &here = origin); virtual int handle(VObject *o); Pass the Event to the VObjects inspectclick method. MouseMovement -----MouseEvent-----PositionEvent-----Event #include "event.hpp" MouseMovement(const Point &here); Create a MouseMovement at the specified position. MouseMovement(); Create a MouseMovement at the same position as the last MouseEvent. virtual int handle(VObject *o); Pass the Event to the VObject's mousemove method. MultiLineText ----Text-----VObject-----Rectangle +----NamedProtected----Protected #include "text.hpp" A Text containing a string with embedded newlines. Tab characters are not expanded. MultiLineText(const char *string = "",int length = -1); The string is printed in a rectangle large enough to hold it. The default length is the length of the string - shorter lengths will only print part of the string. Longer lengths might be necessary if you intend to change the string later. MultiLineText(coord width,coord height, const char *string = "",int length = -1); The rectangle is specified explicitly. void setString(const char *string); Replace the original string with a new one. Strings longer than the length specified (or implied) in the constructor will be truncated. const char *string(); Return the current string. int maxlen(); Return the maximum length (as specified or implied in the constructor). N NamedProtected ----Protected #include "protect.hpp" A subclass of Protected which stores its name, and prints the name when debugging information is requested. NamedProtected(const char *name); Constructor takes the name pointer. This had better point to a static string, or area of memory which will remian valid for the life of the object. You can change the name by overwriting this area of memory with the new name. const char *name() const; Return the name string. O ObjectCollection ----Collection #include "collect.hpp" Collection containing only VObjects. This is a separate class, so that it can be used as the base for a further generic class - OCollection(type). It also has additional methods ... void deleteall(); This deletes the contents of the collection. As the destructor for VObject is virtual, all the objects on the list will be deleted correctly. void sort(int (*compare)(const VObject *,const VObject *)); This sorts the VObjects in the Collection. Further additions (using add) will be added in correctly sorted position. OCollection(type) ----ObjectCollection-----Collection #include "collect.hpp" A generic ObjectCollection to hold items of a particulart type. See ObjectCollection for method details. Note that the sort method will now require a function which takes two pointers to items of your type, rather than VObjects. To declare an ObjectCollection class to hold Widgets (say), all you need to do is declare(OCollection,Widget); in your header (.hpp) file. This will provide the definition of an ObjectCollection class, called OCollection(Widget), including all the inline functions. Then, in your .cpp file, do ... implement(OCollection,Widget) (Note lack of semicolon), which will implement the non- inline functions. ObjectIterator ----Iterator #include "collect.hpp" This class provides an Iterator to step over the elements of an ObjectCollection one at a time. For details, see Iterator. OIterator(type) ----ObjectIterator-----Iterator #include "collect.hpp" An ObjectIterator which iterates over a generic ObjectCollection - OCollection(type). To declare an ObjectIterator class for a OCollection(Widget) (say), all you need to do is ... declare(OIterator,Widget); This will create an ObjectIterator class, called OIterator(Widget). Note that all the functions are inline, so no further implementation is needed. Option ----VObject-----Rectangle +----NamedProtected----Protected #include "menu.hpp" A Menu option. Option(const char *text,Command *cmd = 0,Keys hotkey = Knone); pre pressed while the containing Menu has the focus. The hotkey causes the Option to be selected immediately, from anywhere in the Application. A special hotkey value, Kauto makes the hotkey Alt+the quick key. The Command will be executed whenever the Option is selected. void on(int switchon = 1); void off(); Enable and disable the Option. The option appears grayed when it is disabled. P Panel ----Window-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "panel.hpp" An SAA standard interaction Panel. Has a menu bar, and a client area. Most applications will have a Panel, usually created at the start of the application, and staying on the screen the whole time. Panel(MenuBar *menu, VObject *v = 0, const char *name = 0, const ColorSet &c = defaultColors, AlignFlag a = AlignFlag(AFHexpand|AFVexpand)); Normal constructor. By default the Panel will take the whole screen. The VObject is the client area. Panel(const coord left, const coord top, const coord right, const coord bottom, MenuBar *menu, VObject *v = 0, const char *name = 0, const ColorSet &c = defaultColors); Special constructor allowing full size control. The VObject is the client area. PCommand(type,param) ----Command----Protected #include "command.hpp" A Generic Command which calls a method for objects of type type, passing a parameter of type param. The method is also passed a pointer to the sending VObject passed to GCommand(type)::doit(). PCommands may be associated with Options, Buttons etc. To make an ActionButton which calls the select(VObject *,int) method of your class MyList, you first need a PCommand class which can send messages to a MyList. All you need to do is declare(PCommand,MyList,int); in your header (mylist.hpp) file. This will provide the definition of a GCommand class, called PCommand(MyList,int), including all the inline functions. Then, in your mylist.cpp file, do implement(PCommand,MyList,int) (Note lack of semicolon), which will implement the non- inline functions. aMyL aMyList, you can create the ActionButton ... ActionButton *button = new ActionButton(new PCommand(MyList,int)(MyList::select, aMyList,2), "Select"); Constructor PCommand(type)(int (type::*function)(VObject *,param), type *destination, param parm); The method to be called, the object to which to send the message, and the parameter to pass are all specified in the constructor. Point #include "rect.hpp" Basis of coordinate system. The Point is a structure with lots of useful inline operators. coord x, y; The coordinates, based on 0,0 at the top left of the screen. Assignment operators Point& operator=(const Point &p); Assign one Point to another. Point& operator+=(const Point &p); Add two Points. (1,2) + (3,4) = (4,6). Point& operator+=(const coord i); Add a coordinate to a Point. (1,2) + 3 = (4,5). Point& operator-=(const Point &p); Subtract two Points. (3,4) - (1,2) = (2,2). Point& operator-=(const coord i); Subtract a coordinate from a Point. (3,4) - 2 = (1,2). Boolean operators int operator== (const Point &p) const; Test if two Points are equal. Both coordinates must match for equality. int operator!= (const Point &p) const; Reverse of ==. int operator< (const Point &p) const; Test if both coordinates of one Point are less than another. (1,1) < (2,2), but (1,3) is NOT < (2,2). int operator<= (const Point &p) const; Test if both coordinates of one Point are less than or equal to another. int operator> (const Point &p) const; Test if both coordinates of one Point are greater than another. int operator>= (const Point &p) const; Test if both coordinates of one Point are greater than or equal to another. PopWindow ----SubWindow-----Window-----Group-----VObject----- Rectangle +----NamedProtected--- - ---- Protected #include "popwin.hpp" A pop-up Window. Used (for example) in TextEdits for the pop-down browse list. A PopWindow automatically removes itself if the user presses Escape or clicks with the right mouse button, or if the PopWindow loses the focus. PopWindow(VObject *v, const ColorSet &c = defaultColors, AlignFlag a = AlignFlag(AFVtop|AFHleft), const char *name = "PopWindow"); A PopWindow containing the VObject. void popin(coord x,coord y); Pop the PopWindow onto the screen near the specified coordinates. void popin(const Point &p); Pop the PopWindow onto the screen near the specified coordinates. void popin(VObject *v); Pop the PopWindow onto the screen near the specified VObject. void popout(); Remove the PopWindow from the screen. PositionEvent ----Event #include "event.hpp" An Event with a position, which is despatched to the top Window which contains the position. PositionEvent(const Point &here = origin); const Point &at() const { return p; } The position where the Event happened. virtual int despatch(Window *control); Send the Event to the VObject at the Point p, and its containers. virtual int handle(VObject *o) = 0; Protected #include "protect.hpp" This class forms the basis for the built-in object validity checking system and debugging tool. All the overhead of using protection can be turned off by recompiling the library with NOPROTECT defined. In the checking implementation, any object of a class derived from Protected can be validated by calling its valid method. An assertion that an object is valid can be placed in the code using the VALIDATE macro. Protected(); Constructor sets the internal checking data. ~Protected(); Destructor invalidates the internal checking data. int valid() const ; Checks if the internal data is valid. Returns TRUE (1) or FALSE (0). int isnew() const; This method is only implemented if protection is on. It determines if the object was constructed with new. Returns TRUE (1) if so, FALSE (0) if the object is static or automatic. void dump(FILE *f) const; Dump debugging information about the current object to the specified FILE. void *operator new(size_t); Operator new is overridden so that a Protected object can determine whether it was created with new. Static debugging methods and variables static void dumpstack(FILE *f = 0); static void dumpheap(FILE *f = 0); static void dumpall(FILE *f = 0) { dumpstack(f); dumpheap(f); } These methods dump debugging data about all currently live objects to the specified file (default is to Protected::dumpfile). static const char on; // If protection is on static const char off; // If protection is off This static constant is used to ensure modules compiled with a mixture of protection on and off cannot be linked together by mistake. This is taken care of automatically whenever protect.hpp is included - each module that includes it will contain a static constructor with a reference to either Protect::on or Protect::off, depending whether protection was on or off. This facility can be turned off by defining LIBRARY_MODULE. This is most useful when you have a single source file which is compiled to give multiple object files (like the library source files), so you cannot have static constructors in all the object files. static FILE *dumpfile; The default file to contain debugging dump information. If this is not set up, output will go to stderr. R RadioButton ----Button-----Control-----VObject-----Rectangle +----NamedProtected----Protected #include "radio.hpp" Basic radio button. These are usually created automatically in a RadioHCluster or RadioVCluster. RadioButton(const char *name,int &result,int value); Create a RadioButton with text specified by name. Store value in result if the button is selected. int value() const { return val; } Return the current value. RadioGroup ----EditControl #include "radio.hpp" A Group of RadioButtons. Used internally by RadioHCluster and RadioVCluster. RadioHCluster ----HCluster-----Cluster-----Group-----VObject----- Rectangle +----NamedProtected---- Protected +----------------RadioGroup-----EditControl #include "radio.hpp" A group of RadioButtons, arranged horizontally (one beside the other). RadioHCluster(int &result,const char *b,...); The RadioButtons have text specified by b and subsequent const char * parameters. They have values starting from 0, and ascending sequentially. Only one button in the group is selected. When write is called, the result is updated with the value of the currently selected button. RadioHCluster(const char *name,BorderFlag f,int &result, const char *b,...); The RadioButtons have text specified by b and subsequent const char * parameters. They have values starting from 0, and ascending sequentially. Only one button in the group is selected. When write is called, the result is updated with the value of the currently selected button. The extra parameters allow you to specify a border round the group, and an optional title (shown if f contains BFtitle). RadioVCluster ----VCluster-----Cluster-----Group-----VObject----- Rectangle +----NamedProtected---- Protected +----------------RadioGroup-----EditControl #include "radio.hpp" th the other). RadioVCluster(int &result,const char *b,...); The RadioButtons have text specified by b and subsequent const char * parameters. They have values starting from 0, and ascending sequentially. Only one button in the group is selected. When write is called, the result is updated with the value of the currently selected button. RadioVCluster(const char *name,BorderFlag f,int &result, const char *b,...); The RadioButtons have text specified by b and subsequent const char * parameters. They have values starting from 0, and ascending sequentially. Only one button in the group is selected. When write is called, the result is updated with the value of the currently selected button. The extra parameters allow you to specify a border round the group, and an optional title (shown if f contains BFtitle). Rectangle #include "rect.hpp" The basic Rectangle, used to size VObjects. Constructors Rectangle(); Default constructor. All coordinates initialised to zero. Rectangle(const coord left,const coord top, const coord right,const coord bottom); Full constructor. All coordinates specified. Rectangle(const Point& topl,const Point& botr); Full constructor. Top left and bottom right Points specified. Rectangle(const Point& topl,const coord width,const coord height); Full constructor. Top left Point, width and height specified. Rectangle(const coord width,const coord height); Partial constructor. Only width and height specified. Top left will be at (0,0). Rectangle(const Rectangle &r); Copy constructor. Access methods. coord left() const; coord right() const; coord top() const; coord bottom() const; The various coordinates. coord width() const; coord height() const; The width and height. Note that the default Rectangle will have a width and height of 1. const Point& topleft() const; const Point& botright() const; The top left and bottom right corners. Changing the Rectangle. void position(coord x,coord y); void position(const Point &p); Position the top left corner of the Rectangle to the specified coordinates or Point. The size of the Rectangle is unchanged. void move(coord x,coord y); void move(const Point& p); Move the Rectangle by the specified distance. Move(1,1) will shift the Rectangle one character right, and one character down. The width and height remain unchanged. void setwidth(const coord w); void setheight(const coord h); Change the width and height. void setsize(coord x,coord y); void setsize(const Point &p); Change the width and height simultaneously. Rectangle& operator=(const Rectangle& r); Assign one Rectangle to another. The destination becomes the same size and position as the source. Boolean methods. int encloses(const coord x,const coord y) const; int encloses(const Point& p) const; Determine if the specified Point is inside the Rectangle. Points on the boundary count as inside. int encloses(const Rectangle& r) const; Determine if one Rectangle wholly encloses another. int inside(const Rectangle& r) const; Determine if one Rectangle is wholly enclosed by another. int intersects(const Rectangle &r) const; Determine if two Rectangles overlap. Intersection and Union Rectangle& operator&=(const Rectangle &r); Intersection of two rectangles. This operation is only valid if the two Rectangles intersect. Rectangle& operator|=(const Rectangle &r); Union of two rectangles (smallest rectangle which encloses both) ResetEditButton ----ActiveButton-----ActionButton-----Button----- Control----- -----VObject-----Rectangle +----NamedProtected----Protected +-----------------[EditControlList]----EditControl #include "editctrl.hpp" An ActiveButton that calls the read methods for all the EditControl's it is connected with. ResetEditButton's are usually used for the "Undo" button in a dialog, which will restore the original values, discarding any edits, but without closing the dialog box. ResetEditButton(EditControl *e, const char *name = "Reset", Keys hotkey = Knone, Command *cmd = 0); A ResetEditButton with only 1 EditControl connected with it. ResetEditButton(EditControl **e, const char *name = "Reset", Keys hotkey = Knone, Command *cmd = 0); A ResetEditButton with an array of EditControl's connected with it. RightText ----Text-----VObject-----Rectangle +----NamedProtected----Protected #include "text.hpp" A Text which right-justifies its string. RightText(const char *string,int length = -1); S Screen ---[Rectangle] #include "screen.hpp" This class is used as the interface to the screen hardware. Most of its methods are private (Window is a friend, so can call them). You would only override this class if you wanted to implement the toolkit on different hardware, or improve the interface. A screen pointer variable is provided to access the hardware screen (e.g. to obtain its size). coord width() const { return Rectangle::width(); } coord height() const { return Rectangle::height(); } const Rectangle& rectangle() const { return *this; } void emergencyMessage(const char *s); This method is provided to allow an emergence close-down message to be written to the screen without any memory allocation or DOS functions being called. It is provided so that a new_handler can exit cleanly if the system runs out of memory. select extern void select(const char *text, Command *cmd, const char *option,...); Place a Selection Dialog on the screen. The dialog contains the text (which may contain embedded newlines), and buttons for each option. If an option button is pressed, the corresponding Command is executed. Additional options and Commands are supplied in sequence (command, option, command, option, ...). Control returns to the caller immediately. The dialog is automatically removed from the screen after the user presses one of the buttons. Space ----VObject-----Rectangle +----NamedProtected----Protected #include "layout.hpp" Spacing used in Clusters to neaten appearance. Placing a Space in a Cluster ensures there is at least the specified amount of space between the adjacent items. Space(coord width = 1,coord height = 1, const char *name = "Space"); StateFlag #include "vobject.hpp" Indicates the state and default appearance of a VObject. SFalloff No flags SFnormal Draw in normal colour SFdisabled Disabled (gray out) SFfocus Show in focus color (if SFshowfocus) SFnormonly (SFdisabled|SFfocus) Mask highlight SFhighlight Highlighted SFcolor (SFnormonly|SFhighlight) Color index SFshowfocus Change color if in focus SFselected Selected or pressed SFactfocus This VObject gets unwanted keyboard input SFtabstop Tab key will move the focus to this VObject SFmousein The mouse pointer is inside this VObject SFleftdown Left button down started event SFrightdown Right button down started event SFmiddledown Middle button down started event SFmoved Mouse moved while button down SFbuttondown (SFleftdown|SFrightdown|SFmiddledown) Any button SFmouseflags (SFmousein|SFleftdown|SFrightdown|SFmiddled own|SFmoved) These flags are or-ed together. For portability, you should cast the or-ed flags to a StateFlag, although Zortech C++ does not require this. SubWindow ----Window-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "popwin.hpp" A Window which pops in near a Point or VObject on the screen. SubWindow(VObject *contents, const ColorSet &c = defaultColors, AlignFlag a = AlignFlag(AFVtop|AFHleft), const char *name = "SubWindow"); A SubWindow containing the VObject. void popin(coord x,coord y); Pop the SubWindow onto the screen near the specified coordinates. void popin(const Point &p); Pop the SubWindow onto the screen near the specified coordinates. void popin(VObject *v); Pop the SubWindow onto the screen near the specified VObject. void popout(); Remove the SubWindow from the screen. T Text ----VObject-----Rectangle +----NamedProtected----Protected #include "text.hpp" A simple displayed string. Text(const char *string = "",int length = -1); The default length is the length of the string. void setString(const char *string); Change the string. The original length will be used (the string will be truncated to fit if necessary). const char *string() const; int maxlen() const; Return the current text string, and the maximum length. TextEdit ----Control-----VObject-----Rectangle +----NamedProtected----Protected +-----------EditControl #include "textedit.hpp" An editable text string. The usual range of editing keys is provided - insert / overtype mode, delete, move by character, word and field etc. This is also an EditControl, so it has read(), valid() and write() methods. Note that the write() method overwrites the original string, which is normally a static or allocated field. TextEdit(char *string,int length,const char *prompt = ""); void setString(const char *string); const char *string() const { return text; } Set and return the current string contents. int maxlen() const { return textlen; } Return the maximum length. int insmode() const; True if the TextEdit is in insert mode. int canBrowse() const; True if the user can press cursor down to browse a list of possible values (combo box). int isValid() const; True if the current user input is a valid value for the TextEdit. int hasChanged() const; True if the string has been changed since the input focus last arrived on the TextEdit. virtual char filter(char inchar); Filter is called for each character input before placing it in the TextEdit. Should return the translated character, or 0 if not valid. The default filter ignores control characters. virtual int validate(); Called after each single key change to the string. The string before the change is found in string(). The string after the change is in edittext. If it returns 0, the change is not allowed, and the TextEdit remains unchanged. pos is also reset to it's original value. If it returns 1, the TextEdit is automatically updated from edittext. If required, validate may change edittext (e.g. insert filler characters, convert to upper case, etc.) before returning. The functions inschars() and delchars() assist with this. validate may also change pos, if required. enum Complete { COK, Cchanged, Crestore, Cinvalid }; virtual Complete complete(); Complete is called whenever the user has changed the TextEdit, and wants to move the focus off the TextEdit. If edittext is valid, it should be left unchanged, and completed should return COK. If edittext is not valid, it may be changed to a valid value, and completed should return Cchanged. The TextEdit will then be updated with the new string. Alternatively, completed can return Crestore, and the original text (before the focus arrived on it) will be restored into the TextEdit. Finally, complete may return Cinvalid, and the EditControl will be marked invalid (preventing write() from updating the parameter). static int defaultMode; 1 = insert, 0 = overtype. Can be set by your application if you like insert mode to be the default. Standard EditControl methods int valid(); calls validate() and complete() if necessary. Highlights the field if it is not valid, and returns 1 if the string is valid, 0 if it is not. virtual void read(); Re-read value from argument string. virtual int writeback(); Write value to argument string. Protected methods used by subclasses. void toggleInsert(); void insertOn(); void insertOff(); Change insert / overtype mode. int pos; Current cursor position in the string. char *edittext; New string after single key edit. Helper functions if you want to modify the user's input "on the fly" - e.g. to insert filler characters. const char *original() const; Returns the value which was in the string when the focus arrived on the TextEdit. int inschars(int posn,int nchars = 1); Shift edittext up the specified number of characters (default 1) to make a space at the specified position. int delchars(int posn,int nchars = 1); Delete some characters at the specified position from edittext. void updateString(); Update the string from edittext. Methods to enable browsing (a combo box). void setBrowsable(); void resetBrowsable(); Indicate whether browsing is enabled. A subclass that wishes to allow browsing will normally call setBrowsable() in its constructor. virtual VObject *browse(); Called when the browse key (cursor down) is hit, or the user clicks on the down arrow at the end of the TextEdit. browse should return some kind of List object. The TextEdit will take care of placing it in a PopWindow, displaying it, etc. void endBrowse(const char *chosen = 0); The List should also remember its TextEdit, and call endBrowse() when the user has finished with the List. Set chosen to a string containing the user's selection, or leave it at the default value of 0 if the user decided not to select anything. This is usually done by overriding the List's pick() and escape() methods. Time #include "time.hpp" Holds a date and time, to the nearest second. Uses the C library time functions. Constructors Time(long daysSinceJan1_1970); As returned by the C library function time(). Time(); System clock date & time. Time(unsigned dosdate, unsigned dostime); Conversion from DOS file date & time. Time(const char *filename); The time and date of the specified file (zero if file not found). Set Time void set(long secsSinceJan1_1970); int setdate(unsigned int day, unsigned int month, unsigned int year); Returns 0 if the date was invalid. int setdate(const char *string); Convert the string into a date (returns 0 if an invalid date). void setdate(unsigned daysSinceJan1_1970); int settime(unsigned int hour, unsigned int minute, unsigned int second = 0); Change the time without changing the date. int settime(long secsSinceMidnight); Change the time without changing the date. int settime(const char *string); Convert the string into a time (returns 0 if the time was invalid). void systemtime(); Set time to system clock. int setdostime(unsigned date,unsigned time); Convert from DOS directory date & time. int filetime(const char *filename); Set to file date & time - return 0 if file not found. Get parts of Time. long time() const; unsigned int dayno() const; Days since Jan 1 1970. long secsSinceMidnight() const; unsigned dostime() const; unsigned dosdate() const; Convert to DOS directory time and date. unsigned hour() const; 0-23 unsigned minute() const; 0-59 unsigned second() const; 0-59 unsigned year() const; In full e.g. 1990 unsigned month() const; 1-12 unsigned day() const; 1-31 const char *formattime(const char *format); Use the time package strftime() function to format the time. Returns a string returned by form(), so it won't last for ever. const char *strdate() { return formattime("%d/%m/%y"); } const char *strtime() { return formattime("%H:%M:%S"); } const char *strdatetime() { return formattime("%d/%m/%y %H:%M:%S"); } The following comparison operators are provided. They do the expected things. Return type Left argument Operator Right argument int const Time == const Time & int const Time != const Time & int const Time < const Time & int const Time > const Time & int const Time <= const Time & int const Time >= const TIme & The other operators are. Time & Time = const Time & Time & Time = long (numberOfSeco nds) Time & Time += long (numberOfSeco nds) Time & Time -= long (numberOfSeco nds) long const Time - const Time & (number of seconds between two Times). static Time &zero; The zero point from which time is measured. TimeEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "timeedit.hpp" A TextEdit to allow the user to amend the time portion of a Time. It automatically aligns itself within an EditCluster, showing the prompt in the left-hand column, and the time itself in the right-hand column. As this is also an EditControl, the initial value is read from the Time on creation, and written back only when the write method is called. Normally, TimeEdits will be written back automatically with a CloseEditButton or an ApplyEditButton. TimeEdit(Time &t,const char *prompt = ""); Example : Time t1; // The time is set to the system clock // Now declare the Edits EditCluster *e = new EditCluster( new DateEdit(t1,"System date"), new TimeEdit(t1,"System time"), EndList); ModalDialog *d = new ModalDialog( new VCluster( // Organise one above the other e, new HCluster( // Then a horizontal group AlignFlag(AFHexpand|AFtabstop), // which is a Tabstop new CloseEditButton(e), new ApplyEditButton(e), new ResetEditButton(e), new CancelButton, EndList), EndList), "Test Check Buttons"); d->enter(); U UnsignedEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "textedit.hpp" A TextEdit for unsigned integers. UnsignedEdit(unsigned &i,const char *prompt = "", unsigned low = 0, unsigned high = UINT_MAX); The range of permissible values is specified with low and high. UpperEdit ----TextEdit-----Control-----VObject-----Rectangle +----NamedProtected----Protected +------------EditControl #include "textedit.hpp" A TextEdit which automatically translates all input to upper case. UpperEdit(char *string,int length, const char *prompt = ""); V VCluster ----Cluster-----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "cluster.hpp" A Cluster of VObjects automatically laid out in a vertical column. The VObjects to be laid out are passed as a variable argument list to the constructor (terminated with EndList). Multiple constructors are provided, as the default argument mechanism cannot be used with variable arguments. VCluster(VObject *v,...); VCluster(AlignFlag a,VObject *v,...); VCluster(const char *name,AlignFlag a,VObject *v,...); VCluster(const char *name,AlignFlag a,BorderFlag f,VObject *v,...); VCluster(const char *name = "VCluster",AlignFlag a = AFexpand, BorderFlag f = BFnone); This last constructor is used to create an empty VCluster, which will later be filled by calls to the add method, and it indicates the defaults for missing arguments to the previous constructors. VLine ----Box-----Space-----VObject-----Rectangle +----NamedProtected----Protected #include "layout.hpp" A simple vertical line. The line type is specified as a BorderFlag. VLine(coord width = 1,BorderFlag b = BFsingle, const char *n = "VLine"); VObject ----Rectangle #include "vobject.hpp" This is the base class for all objects that appear on the screen. It has many virtual methods which may be overridden in subclasses to determine their behaviour. VObject(const Rectangle &r,const char *name = "VObject"); A protected constructor for derived classes that have already calculated their size and position. VObject(const char *name = "VObject"); VObject(const coord left,const coord top, const coord right, const coord bottom, const char *name = "VObject"); VObject(const coord width,const coord height, const char *name = "VObject"); Constructors to cover a variety of ways of specifying the size and position of an object. virtual ~VObject(); The destructor is virtual, so any subclass destructor will always be called correctly. const char *name() const; Return the name of the VObject as specified in the constructor. State Flag manipulation. StateFlag testFlag(StateFlag f) const; Test if certain state flags for the VObject are set. Used in inline methods below ... void disable() { setFlag(SFdisabled); dirty(); } void enable() { clearFlag(SFdisabled); dirty(); } The SFdisabled flag usually determines what color the VObject is painted. It is also used to disable selection of this VObject. void highlight() { setFlag(SFhighlight); dirty(); } void unhighlight() { clearFlag(SFhighlight); dirty(); } The SFhighlight flag usually determines what color the VObject is painted. Control Flag manipulation ControlFlag testcFlag(ControlFlag f) const; Test if certain control flags for the VObject are set. void ignoreEvents() { clearcFlag(CFactive); } void recogniseEvents() { setcFlag(CFactive); } The VObject will not receive Events unless CFactive is set. void clean() { clearcFlag(CFclean); } This is called whenever the VObject has been freshly painted on the screen. void dirty() { setcFlag(CFdirty); } This is called whenever something happens which means the whole VObject needs to be repainted - e.g. after highlighting it. void dirty(const Rectangle &r); This is called when some part of the VObject needs to be redrawn - e.g. after an obscuring Window is removed. Methods called by objects inside this one if their Control flags has changed. virtual void contentsSet(VObject* o,ControlFlag f); virtual void contentsCleared(VObject* o,ControlFlag f); o is the VObject whose Control flags have changed, and f is the flags that have changed. Method called by objects inside this one if they are deleted virtual void contentsDeleted(VObject* v); Get color index - these are indices into the ColorSet of the Window used for the colors of this VObject when drawing it. int getcolor() const; The main color. int getnormal() const; Ignore highlight attribute int gethighlight() const; Force highlight on Container - the VObject that contains this one. void setcontainer(VObject *v); VObject *getcontainer(); Window - the Window containing this VObject, into which it is drawn. virtual void setwindow(Window *w); Window *getwindow() const; Moving or resizing the Object virtual void move(coord x,coord y); These alternative inline methods all call the main move method, which is the only one which needs to be overridden in subclasses. void position(coord x,coord y) { move(x - left(),y - top()); } void position(const Point &p) { position(p.x,p.y); } void move(const Point& p) { move(p.x,p.y); } virtual void setwidth(const coord w); virtual void setheight(const coord h); These alternative inline methods all call the main set methods, which are the only ones which need to be overridden in subclasses. void setsize(coord x,coord y) { setwidth(x); setheight(y); } void setsize(const Point &p) { setsize(p.x,p.y); } void placeInside(const Rectangle& r); Place the VObject inside the Rectangle. First, if the VObject is too large to fit, is is reduced in size. Then it is moved the minimum distance to ensure it is wholly contained in the Rectangle. virtual void align(AlignFlag a,const Rectangle& r); The VObject is lined up inside the Rectangle according to the AlignFlag. Finding the minimum and maximum size of an object virtual coord minwidth() const; virtual coord minheight() const; These methods return the minimum size required to display the VObject. They are used by Clusters to lay out objects in Windows. virtual coord maxwidth() const; virtual coord maxheight() const; These methods return the "ideal" size required to display the VObject. The default is to return the same value as the "min" methods, but subclasses sometimes override this default - e.g. a DOS directory entry might have a minimum length just large enough to display the file name, and a maximum width long enough to display the file size and date, as well. Drawing the VObject virtual void paint(Rectangle r); This is the method called to display the VObject in its Window. This method will be overridden in all VObjects which will actually show on the screen. The Rectangle is a clipping area - you need not paint any part of the VObject outside this area, as either the area is not visible on the screen, or it is already shown correctly. If you do paint outside this area, the Window will take care of any clipping which needs to be done to prevent your output "bleeding" through an overlapping Window. void draw() { paint(*this); clean(); } Force the whole object to be drawn virtual void update(); Draw any parts which are dirty Set & reset keyboard focus virtual int setfocus(int tabstop = 1); Return 1 if this VObject will accept focus, 0 otherwise. If tabstop is zero, the VObject should only accept focus if it is not a tabstop - i.e. !testFlag(SFtabstop). It is normal for derived classes that wish to override this method to call the base class method, so that the correct flags etc. are set. virtual void resetfocus(); Called whenever the VObject loses focus. Again, it is normal for derived objects to call the base class method so that the correct flags are set. virtual void clearfocus(VObject *v = 0); A special method called when a whole nest of VObjects must lose the focus - e.g. an Option in a Menu in a MeneButton in a MenuBar. Calling clearfocus for the Option will also clear the focus from the containers. The container calls will have v set to the contained VObject each time. Increment and decrement keyboard focus. virtual int incfocus(int tabstop = 1,int decrement = 0); A virtual method for VObjects which contain other VObjects. Moves the focus to the next contained VObject which will accept it. The tabstop parameter is passed on to setfocus for the contained VObjects. The basic VObject always returns 0, as it doesn't have any contents. int decfocus(int tabstop = 1) { return incfocus(tabstop,1); } Trivial inline - decrement focus. virtual int nextTabstop(int decrement = 0,int wrap = 0); Move the focus to the next tabstopped item. The basic VObject accepts the focus if it is a tabstop, and it hasn't got the focus already. A Group will pass the focus on to the next tabstop inside it. If the last tabstop already has focus, the Group will wrap round to the first, or return zero, depending of the value of wrap. Set & reset mouse focus and repeat. void setmoufocus(int repeat = 0); void resetmoufocus(); Grab and release mouse focus. While a VObject has the mouse focus, it gets all MouseEvents. If repeat is non- zero, the VObject will receive repeated mouse movement events, even when the user does not move the mouse. This is useful e.g. for continuous scrolling while a mouse button is down in a list. Determine the topmost (smallest) object containing a point virtual VObject *containingObject(const Point &p); This is used by the MouseEvent despatch method to determine which VObject the mouse is over. If the current VObject does not contain the Point, it returns 0. If it does contain the Point, it determines if any VObject inside this one also contains the Point, and returns that VObject or itself. virtual int help(); Try to display help for this object. The base VObject class passes its name to the Application help handler. This is usually sufficient for most things. MouseEvent handling methods virtual int handle(MouseEvent& e); This method takes a MouseEvent and farms it out to the different methods below. It is not often overridden, except to monitor all mouse events and pass them on to the base class handle method. Virtual methods called for each type of event. It should only be necessary to override some of these to deal with those types of event in which a derived class is interested. If a VObject is not interested in a particular Event, the method should pass it on to the base class method. If it is interested, it should process the Event, and return 1. This will prevent the Event being passed on to containing VObjects. The default VObject version of most methods returns 0 (not interested). virtual int mousemove(MouseEvent& e); All movement events. virtual int mouseenter(MouseEvent& e); virtual int mouseexit(MouseEvent& e); Called whenever the mouse enters or leaves the VObject's bounding rectangle. virtual int leftdown(MouseEvent& e); virtual int middledown(MouseEvent& e); virtual int rightdown(MouseEvent& e); Called when the particular button is pressed. Do not design your user interface so it can not be used with a one-button mouse ! One-button mice only have a left button. virtual int leftup(MouseEvent& e); virtual int middleup(MouseEvent& e); virtual int rightup(MouseEvent& e); Called when a particular button is released. virtual int leftclick(MouseEvent& e); virtual int middleclick(MouseEvent& e); virtual int rightclick(MouseEvent& e); Called when the mouse is clicked without moving, after down and up messages have been processed virtual int inspectclick(MouseEvent& e); If inspecting is on (library compiled without NINSPECT defined), this method will be called when the user does a left click while holding down the Alt key. The VObject will pop an Inspector up on the screen, showing the internal details of the VObject. virtual char *inspectinfo(char *buffer = 0,const char *s = 0) const; Get a textual description of what this object looks like inside, for the Inspector. Other Event handling methods. virtual int kbdevent(KeyboardEvent& e); KeyboardEvents are only received while the VObject has the focus. virtual int dohotkey(KeyboardEvent& e); If the focus VObject and its containers are not interested in a KeyboardEvent the despatcher tries all the dohotkey methods. virtual int interruptevent(InterruptEvent& e); Called when the user presses Ctrl-Break. virtual int criterr(CriticalErrorEvent& e); Called when a DOS critical error has occurred, and a CriticalErrorHandler exists. Debugging stuff. static FILE *debug; virtual char *debuginfo(char *buffer = 0) const; If debug tracing is enabled (library compiled without NDEBUG defined), you can set VObject::debug to a C FILE opened with fopen. Copious tracing information will be written to the file. Remember to set VObject::debug to zero if you close the file ! The trace function obtains its description of the VObject being traced by calling debuginfo. You may override this method to provide your own description (showing extra internal information) if you wish. The method uses an existing string buffer, or allocates a new one if buffer is zero. It returns the buffer used (or allocated). This makes it easy to add information to the base class information - call the base class debuginfo and strcat the extra information on the end. Protected methods and variables. VObject *container; The VObject that contains this one. Window *window; The Window that contains the VObject. Rectangle dirtyArea; The area to be painted on next draw if only part of the VObject is dirty. This only contains valid information if testcFlag(CFpartdirty) is non-zero. void moveDirtyArea(coord x,coord y); Move dirty area during scroll. This method is called when the VObject is scrolled, so that the dirty area is moved along with the scrolled information. State Flag manipulation void setFlag(StateFlag f); void clearFlag(StateFlag f); void toggleFlag(StateFlag f); Control Flag manipulation void setcFlag(ControlFlag f); void clearcFlag(ControlFlag f); These methods will pass flag information up through containing VObjects via the contentsSet and contentsCleared methods. void newname(const char *name); Change the name of a VObject. W Window ----Group-----VObject-----Rectangle +----NamedProtected----Protected #include "window.hpp" Protected constructor Window(const char *n,const ColorSet &c = defaultColors); Constructors Window(VObject *contents = 0, AlignFlag a = AlignFlag(AFHexpand|AFVexpand), const ColorSet &c = defaultColors, const char *name = "Window"); The AlignFlag is used to align the Window on the Screen automatically. VObject *conte VObject *contents = 0, const ColorSet &c = defaultColors, const char *name = "Window"); The Window is constructed in exactly the place specified. Change colors void setcolors(const ColorSet &c); Method called by VObjects inside the Window if they are deleted virtual void contentsDeleted(VObject* v); Manipulate Windows in the Application. void enter(); Pops the Window up as the top Window in the Application. Events will not be passed to other Windows underneath this one, until this Window is removed (a modal window). void show(); Adds the Window to the Application (a non-modal window). void remove(); Remove the Window from the Application. Set which VObject gets unwanted keyboard input void setactive(VObject *v); void clearactive(VObject *v); The currently active object will be passed all keyboard input that is not wanted by the focussed object. This is used for default buttons (see CloseButton). Can we close this window ? virtual int closeok(); virtual int cancelok(); Attempt to close or cancel this Window. If close or cancel is not permitted (e.g. if something is not filled in correctly), this method should return 0. Otherwise it should call the Window method, which creates a new CloseEvent for the Window. Scroll part of the Window void scroll(Rectangle r,int color,int nlines = 1); Set nlines = 0 to clear. Set nlines < 0 to scroll down instead of up. If part of the area is not visible, this will merely dirty the rectangle. Print a string void printstring(Point at,const Rectangle &clip, int color,const char *string,int length = -1); Print a string, clipping it to the supplied Rectangle. The color is used as an offset into the ColorSet for the Window. The default length (-1) indicates the whole string is to be printed (up to the C null terminator). void printstring(const Point &at, int color, const char *string, int length = -1); The clipping Rectangle is the whole Screen. void printstring(const Point &at, const char *string, int length = -1) { printstring(at,getcolor(),s,length); } Uses the appropriate color for the current state of the Window. Fill a Rectangle with a character void fillrect(Rectangle r,int color,const char x); Again, color is used as an offset into the ColorSet for the Window. void fillrect(const Rectangle& r,const char x = ' ') { fillrect(r,getcolor(),x); } Use the appropriate color for the current state of the Window. Clear the whole window to a particular character. void clear(int color,const char x = ' '); void clear(const char x = ' ') { clear(getcolor(),x); } Draw a box void drawbox(const Rectangle& r, const Rectangle &clip, int color, const BorderFlag s, const char *title = ""); Draw a box, clipping it to the supplied Rectangle. The color is used as an offset into the ColorSet for the Window. The BorderFlag determines the style of the box. void drawbox(const Rectangle& r, int color, const BorderFlag s, const char *title = "") { drawbox(r,r,color,s,title); } The clipping Rectangle is the box itself. void drawbox(const Rectangle& r,const BorderFlag s = BFsingle) { drawbox(r,r,getcolor(),s); } Uses the appropriate color for the current state of the Window. Move text cursor to a point. void cursor(coord x,coord y); void cursor(const Point& p) { cursor(p.x,p.y); } Show and hide text cursor. void showcursor(int block = 0); Set block non-sero to get a block (insert) cursor (the default is an underline cursor). void hidecursor(); Move whole window virtual void move(coord x,coord y); Draw the Window virtual void paint(Rectangle r); Translate Window coordinates to Screen coordinates void screenCoords(Point &p) const { p += topleft(); } void screenCoords(Rectangle &r) const { r.move(topleft()); } and vice versa. void windowCoords(Point &p) const { p -= topleft(); } void windowCoords(Rectangle &r) const { r.move(-topleft().x,-topleft().y); } Virtual methods for events. virtual int kbdevent(KeyboardEvent& e); The Window deals with passing unwanted input to the active VObject (if any), and enabling the Tab and BackTab keys to pass the focus between tabstop items.