Stars of Shareware: Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Stars of Shareware: Programmierung / SOURCE.mdf / programm / msdos / pascal / rehack / text / window.txt < prev

Wrap

Text File | 1993-06-27 | 11.2 KB | 294 lines

File: WINDOW.TXT Path: ...\REHACK\TEXT\WINDOW.TXT Version: 0.01 Author: Pat Reilly CIS Id: 71333,2764 Created On: 6/23/93 Modified On: 6/27/93 Description: Doc file for WINDOW.HPP. Tabs: 4 Hierarchy of classes: Visible ──┬── Window ──┬── Game (See GAME.HPP and GAME.TXT) │ │ │ ├── ButtonsWindow (not yet implemented) │ │ │ ├── CharacterWindow (not yet implemented) │ │ │ └── MessageWindow (not yet implemented) │ ├── CloseUp (not yet implemented) │ ├── Automap (not yet implemented) │ ├── Button (not yet implemented) . . . This hierarchy of classes forms an event-driven framework for REHACK's CRPG program. Game is a generic game class which has a close-up window, an automap window, a buttons window, a character window, and a message window. See GAME.TXT for more information on the Game class. NOTE: Right now, the Windows classes have no automatic drawing (or painting) functionality. This will need to be added in future revisions in order to put more common functionality in the Visible and Window class (saving on duplicating the code in all higher classes). Class Visible ============= This class is the base class for the Windows hierarchy. It encapsulates a rectangular object which can respond to events. By default (ctor), a Visible is both visible and can be focused. Right now being visible is meaningless, since no paint related functionality is in place. Being focused relates to which events Visible will receive from its owning Window (see Window class below). Also by default, Visible's are masked from receiving Broadcast events (see EVENT.TXT). Methods ------- Visible() constructor Creates a default object which is visible and focusable and can receive all events except Broadcasts. ~Visible() virtual destructor If the object is currently in a Window, removes it before destructing. void get(Event& event) virtual By default, just calls owner->get(event), or clears the event if owner == 0. See Window::get() Game::get() (GAME.TXT) for more info. void handle(Event& event) virtual By default, just handles a left button click in the object's area by focusing the object (if flags allow); if PassFirstClick flag is set, does not clear the event. Rect getLocalBounds() const Returns the bounding rectangle for this object in this object's coordinate system. This means that the returned Rect's topLeft member will always be the Point (0,0). Rect getOwnerBounds() const Returns the bounding rectangle for this object in its OWNER'S coordinate system. This is the same as the bounds member. Point makePointLocal(const Point& pt) const Converts pt from global coordinates to local coordinates. Point makePointGlobal(const Point& pt) const Converts pt from local coordinates to global coordinates. void setFlag(dword bits, bool enable) virtual The bits argument should only have one bit (flag) set. If this flag is currently clear, setFlags() sets it. When paint-related methods are added, this method will be modified to paint the object when necessary (if, for example, bits == Visible). Currently, Only bits 0..6 are used, but bits 0..15 are reserved for system use. Bits 16..31 are available for user flags, with the first available bit defined by vfFirstUserFlag. bool getFlag(dword b) const Returns true if all the bits that are set in b are also set in flags, otherwise false. Can be used to check if multiple flags are set by having b be the logical OR of more than one flag. bool grabFocus() Forces the object to try and take the focus. If the currently focused object refuses to give up the focus, or this object is disabled, not visible, or is not focusable, returns false and the object is not focused. Otherwise the object is focused and returns true. bool canLoseFocus() virtual By default, returns true. If an object requires doing validation (such as an editline), this function can be overridden so that it refuses to lose the focus until the correct input is received. Visible* nextObject() Returns a pointer to the next object in z-order, or null. Visible* prevObject() Returns a pointer to the previous object in z-order, or null. word run() virtual By default, just returns IdCancel. void stopRunning(word id) If this object is currently run()ning, stops it by setting modalReturnValue to id. Note that it won't stop running if id is idNull. If this object isn't running, calls its owner's stopRunning(id). Members ------- Rect bounds Objects bounding rectangle in its owner's coordinate system. dword flags Object's state flags. Window* owner Pointer to this object's owner (parent). Visible* next Visible forms a circular singly-linked list; next points to the next object in the list. Only valid if owner != 0. word modalReturnValue Value returned by run(). State flags ----------- vfVisible Indicates if the object is visible (set) or hidden (clear). vfFocused Indicates if the object is currently it's owner's focused object (set) or not (clear). Focused objects receive certain events that non-focused objects do not. See Window::handle() for more details. When painting the object, certain objects might want to paint it differently when its focused than when its not; an example would be Buttons. vfDisabled Indicates if the object is currently disabled (set) or not (clear). Disabled objects will not receive any events. When painting the object, a different look might be wanted when the object is disabled versus when its not; "grayed" controls are an example. vfModal Indicates if the object (normally a Window) is modal or not. This bit is used internally by the windows classes. vfFocusable Indicates whether this object can be made the focus (set) or not. vfPassFirstClick If set, the object is not focused, and it receives a left pos device button click, the event is not cleared. This allows focusable objects to both gain the focus AND respond all to the same mouse click. vfFirstUserFlag Indicates the first of 16 user-defined flags that can be used with getFlag() and setFlag(). Since these are bit flags, the first available user flag would be vfFirstUserFlag; the second would be vfFirstUserFlag*2, etc. Class Window - derived from Visible ============ The Window class encapsulates a linked list of Visibles. It is meant to be more of a container than a pure screen object. But it still has a rectangular region its responsible for; when painting functionality is added, a Window will ensure that any of its sub-objects (whether Visibles or Windows) do not paint outside its bounding rectangle. Windows can have a focused sub-object; it will be pointed to by the member currentObject if so. Windows also maintain their linked list of sub-objects in "Z-order"; whenever a new object is inserted into the Window it is inserted at the end (furthest from bottomObject) of the list. Because of this, the objects in a Window can be traversed from bottom to top by starting at the bottomObject pointer and traversing. Since Window is derived from Visible, any non-overridden function from Visible apply to it. One method that Window overrides is the handle(Event&) function. If the event is positional (pos device), it is passed to the upper-most object (in z-order) which is visible and contains the position of the event. If the event is a focused event, it passed only to currentObject (if not null). Broadcast events are passed to all the sub-objects. Methods ------- Window(const Rect&) constructor Initializes its base class Visible by passing it the bounding rectangle, then initializes its linked list for an empty list and no focused object. ~Window() destructor Deletes each object in its linked list. void handle(Event& event) virtual If event.isPositional() returns true, the lastObjectThat() iterator is called to find the top-most object which contains this point and is visible. If one is found, the event is passed to it, otherwise the event is ignored. If event.isFocused() returns true, passes the event to currentObject if its not null, else ignores it. If event.isBroadcast() returns true, the forEachObject() iterator is called to pass the event to each object in the list. void insert(Visible* obj) If obj is already in another window (its owner member is not null), it is removed from its current owner. Then obj is inserted into the end of the linked list and obj->grabFocus() is called to make the object focused (which might fail, leaving the focus where it is). void remove(Visible* obj) Removes the object if its contained in the Window, and sets its owner member to null to indicate that no Window owns the object. bool moveFocusTo(Visible* obj) Attempts to change the focus from the current object to obj. If obj is not a sub-object of the Window, returns false. If obj already has the focus, returns true. If currentObject is null, or currentObject->canLoseFocus() returns true, then the focus is moved to obj; but only if obj can accept the focus (obj->getFlag(vfFocusable) return true). void forEachObject(void (*fn)(Visible*, void*), void* args) const For each sub-object in the window, fn(obj, args) is called. This acts as an iterator function for all sub-objects. The form of fn is: void foo(Visible* obj, void* args); Visible* firstObjectThat(bool (*fn)(Visible*, void*), void* args) const Iterates through each sub-object in the window, starting at the bottom-most (bottomObject) and working up to the top-most; the first object for which fn returns true is returned, or null if none do. The form of fn is: bool foo(Visible* obj, void* args); Visible* lastObjectThat(bool (*fn)(Visible*, void*), void* args) const Same as firstObjectThat(), but instead of iterating from the bottom object to the top, it starts at the top object and iterates down to the bottom. word run() virtual Overridden to provide making a Window modal. When called, run() will set modalReturnValue to IdNull, then run a loop which calls get() to retrieve an event and then (if the event is not null) passes it to handle(). This will continue as long as modalReturnValue is IdNull. Any object in the Window's chain of sub-objects can stop this loop by calling stopRunning() and passing it the value that run() should return. Members ======= Visible* bottomObject This is the 'head' of the linked list of sub-objects. It points to the sub-object which is lowest in z-order (furthest from the screen). The sub-objects for a circular linked list, which means that if the list is followed node to node, you will eventually return to bottomObject again. Visible* currentObject This points the the currently focused object, or is null. See handle() for the implications of the currently focused object. Friends ======= void makeInc() This global function is used in the ASMINC module/program. See ASMINC.CPP and ASMINC.TXT for more information.