Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / ENHMEN.ZIP / ENHMENUS.DOC < prev next >

Wrap

Text File | 1991-03-29 | 32.6 KB | 698 lines

EnhMenus ver 1.0 An Enhanced Menu System for TurboVision Copyright 1991 Software Applications of Wichita OVERVIEW -------- EnhMenus is a menu system designed to replace the MENUS.TPU included with TurboVision. EnhMenus provides the same functionality as the standard Menus unit and is fully compatible with it. However, EnhMenus extends past Menus in many important respects by being completely object-oriented. All data structures (MenuItem, MenuBar, MenuBox, etc) have been changed to objects instead of records. Because of this, EnhMenus can be changed in any way you like without extensive recoding, unlike the standard Menus unit. Furthermore, EnhMenus provides exactly the same procedures and functions that Menus does, thus you're existing code should not require any modification. In addition to extending it, EnhMenus also corrects some bugs in the Menus unit. For example, select the the File menu in the IDE, press F1 for help, and then close the Help window using the close icon and the mouse. The menu disappears! SHAREWARE --------- Please note that EnhMenus is not free software. It is distributed under the ShareWare concept of marketing. This allows to see and use the software before buying. If you decide to use EnhMenus for your own purposes, you must register it. Registration involves sending in the accompanying order form (in the file Order.Frm) along with the payment of $15.00. Upon registration you will receive the non- shareware version of EnhMenus and its source code. Registration entitles you to link EnhMenus to any end product you like so long as the source code, nor the TPU file is redistributed. FILES INCLUDED -------------- This ZIP includes the following files: EnhMenus.Tpu - This unit contains the menu routines and objects EnhMenus.Doc - This file. Demo.Exe - Demo program for EnhMenus. Demo.Pas - Source code for Demo.Exe Demo.Doc - Please read this file while looking at the Demo, it highlights features of EnhMenus to look for. Order.Frm - An order form to receive the non-shareware version of EnhMenus and its source code. Read.Me - Introductory text file. INSTALLATION AND USE -------------------- To use EnhMenus, the Uses clause in the App unit must be changed to use EnhMenus instead of Menus. So, instead of uses Objects, Drivers, Memory, HistList, Views, Menus; It will read: uses Objects, Drivers, Memory, HistList, Views, EnhMenus; ______________________________________________________________________ Turbo Pascal, TurboVision are trademarks or registered trademarks of Borland International, Inc. Portions of this documentation are taken from TurboVision Guide and are copyrighted by Borland International. The App unit must then be recompiled and any units that use the App must similarly be recompiled. Don't forget to keep a backup of the original App.Pas and App.Tpu files! SIMILARITIES AND DIFFERENCES ---------------------------- As far as strict TurboVision programming is concerned, there is no difference between the EnhMenus and Menus units. Status line and menu functions, NewItem \ NewLine \______ Menu routines NewSubMenu / NewMenu / DisposeMenu / NewStatusDef \_________ Status line routines NewStatusKey / all work exactly the same in EnhMenus as they do in Menus. This ensures that your source units will not require any change if you access the status line and menus with these routines. However, if you deal directly with the various menu and status line data structures, some modification of the code will be required. NOTE: Although EnhMenus uses the same registration codes for the menus and status line objects as Menus, they are NOT compatible! An attempt to read Menus objects from a stream by EnhMenus will result in an error. EnhMenus also defines three new constants, sfPulled, sfUpdate, and ofPull. These are used as flags in the State and Options fields of the View object. They are defined so they don't interfere with use of other flags included in TurboVision. The flags are described in detail below. The only other major difference between EnhMenus and Menus is the fully object nature of EnhMenus which is described below. ENHMENUS OBJECTS ---------------- TMenuItem - Descended from TObject This object is only instantiated for a divider line. More often, the objects TMenuCommand and TMenuSubMenu will be used. FIELDS ------ Next : PMenuItem READ ONLY Points to the next item in the menu. It is nil if here is no next item. Name : PString READ ONLY Points to the name of the menu item. It is nil if the item is a divider line. Param : PString READ ONLY Points to the paramater list of the item. Displayed only in a MenuBox and as right-justified. - 2 - View : PView READ ONLY Points to the view that the item generates. For example a sub-menu's View field will point to the sub-menu view. KeyCode : Word READ/WRITE Stores the scan code for item's associated hotkey. KeyCode is zero if no hotkey exists. HelpCtx : Word READ/WRITE Contains the menu item's help context number. METHODS ------- Constructor Init(aName, aParam:TMenuStr; aHelpCtx:Word; aNext:PMenuItem); Calls TObject.Init and then initializes the Name, Param, HelpCtx, and Next fields. Constructor Load(var S:TStream); Creates a TMenuItem object and loads it from the stream. Destructor Done; virtual; Override: Sometimes Disposes of Name and Param and sets them to nil. Function Command:Word; virtual; Override: Sometimes The default Command method returns cmValid. If Command returns anything other than cmValid, when the item is activated, that command will be placed into the event queue and the menu aborted. If cmValid is returned, no command is placed into the event queue and the menu is not aborted. In this way, it is possible for the menu structure to perform other functions by overriding the Execute method. Function Execute(ParentMenu:PMenuMetaView:Word); virtual; Override: Sometimes Returns the command constant associated with the menu item by calling Command. By overriding this method, it is possible for an item to perform many different purposes such as issuing a Message. Procedure HotKey(aKeyCode:Word):PMenuItem; virtual; Override: Often The default HotKey method returns nil. Procedure Pull(ParentMenu:PMenuMetaView; On:Boolean); virtual; Override: Sometimes The default Pull method does nothing. This method is called whenever the use pulls down a menu from the menubar. Procedure Store(var S:TStream); virtual; Override: Sometimes Saves the menu item on the stream. TMenuCommand - Descended from TMenuItem Used for menu items that return a command to the application. Most often TMenuCommand objects are created using the NewItem function. METHODS ------- Constructor Init(aName, aParam:TMenuStr; aKeyCode, aCommand, aHelpCtx:Word; aNext:PMenuItem); - 3 - Calls TMenuItem.Init to initialize Name, Param, HelpCtx, and Next. Then KeyCode and Command are initialized to their respective values. Constructor Load(var S:TStream); Creates a TMenuCommand object by reading its information from the stream. Function Command:Word; virtual; Override: Seldom Returns the command associated with this item. Procedure Store(var S:TStream); virtual; Override: Seldom Stores information about the menu command on the stream. TMenuSubMenu - Descnded from TMenuItem TMenuSubMenu is used for menu items that create a submenu when selected, or pulled from the parent menu. Normally, TMenuSubMenu objects are created using the NewSubMenu function. FIELDS ------ SubMenu : PMenu READ ONLY Points to the list structure of menu items contained in the submenu. METHODS ------- Constructor Init(aName, aParam:TMenuStr; aHelpCtx:Word; aSubMenu:PMenu; aNext:PMenuItem); Calls TMenuItem to initialize Name, Param, HelpCtx, and Next. Then SubMenu is set to aSubMenu. Constructor Load(var S:TStream); Creates a TMenuSubMenu object from the information on the stream. Destructor Done; virtual; Override: Seldom Disposes of SubMenu and then calls TMenuItem.Done. Function Execute(ParentMenu:PMenuMetaView):Word; virtual; Override: Seldom If not already pulled, the submenu is pulled by calling Pull(ParentMenu, True). ParentMenu^.Owner^.ExecView is called with the submenu's associated view. Finally, if the menu had to be pulled it is put back, Pull(ParentMenu, False). Procedure HotKey(aKeyCode:Word):PMenuItem; virtual; Override: Seldom Calls SubMenu^.HotKey to search the associated menu for aKeyCode. Procedure Pull(ParentMenu:PMenuMetaView; On:Boolean); Override: Seldom Pull is used to create the submenu's view which is stored in the inherited field, View. If On is true, coordinates are calculated and View is inserted into ParentMenu^.Owner. If On is false, View is deleted from ParentMenu^.Owner, View is then disposed of and set to nil. Procedure Store(var S:TStream); virtual; Override: Seldom Stores the submenu item onto the stream. - 4 - TMenu - Descended from TObject This contains the items in the menu along with the default menu item. It is most often created by NewMenu. FIELDS ------ Items : PMenuItem READ ONLY A linked list of all the items in the menu. Default : PMenuItem READ ONLY Points to the default item in the menu. METHODS ------- Constructor Init(aItems:PMenuItem); Assigns both Items and Default to aItems. Constructor Load(var S:TStream); Creates a TMenu object and then loads its menu items from the stream. Destructor Done; virtual; Override: Seldom Disposes of every item in the menu. Function HotKey(aKeyCode:Word):PMenuItem; virtual; Override: Seldom Cycles through the items in the menu until it finds an item with the aKeyCode as its hotkey. Procedure Store(var S:TStream); virtual; Override: Seldom Stores each of the items in the menu on the stream. TStatusDef - Descended from TMenu TStatusDef is a stores the menu of items available on a status line given a range of help contexts. It is normally instantiated using the NewStatusDef function. FIELDS ------ Min : Word READ ONLY The minimum help context to which this particular status definition applies. Max : Word READ ONLY The maximum help context to which this particular status definition applies. Next : PStatusDef READ ONLY Points to the next status definition, nil if this definition is the last. METHODS ------- Constructor Init(aMin, aMax:Word; aItems:PMenuItem; aNext:PStatusDef); Calls TMenu.Init to initialize Items. Min, Max, and Next are then set to their respective values. Constructor Load(var S:TStream); Creates a TStatusDef object and initializes it from the information stored on the stream. Procedure Store(var S:TStream); - 5 - Stores the status definition onto the stream. TMenuMetaView - Descended from TView TMenuMetaView is the backbone of the EnhMenus units; all menu views are descended from this object. Normally this object is not instantiated. FIELDS ------ Current : PMenuItem READ ONLY While the menu is in a modal state, Current points to the highlighted item. Otherwise, Current is nil. ParentMenu : PMenuMetaView READ ONLY ParentMenu points to the TMenuMetaView that owns this menu. METHODS ------- Constructor Init(var Bounds:TRect); Calls TView.Init to set Bounds and sets EventMask to include evBroadcast. Constructor Load(var S:TStream); Creates a TMenuMetaView object and initializes its fields from the stream. Procedure Activate(Item:PMenuItem); virtual; Override: Seldom The Item^.Execute called with a pointer to Self given as the ParentMenu. If cmCancel is returned and the ParentMenu is nil, then the menu structure is aborted with cmCancel. If cmValid is returned, no operation is performed. If any command other than cmCancel or cmValid is returned, EndModal is called with the result. Procedure ChangeCurrent(Item:PMenuItem); virtual; Override: Seldom Changes Current to Item and displays a submenu if the sfPulled flag is set. Procedure EndModal(Command:Word); virtual; Override: Never EndModal ends the current modal state and returns Command as result of the caller's ExecView. Function Execute:Word; virtual; Override: Never Executes a menu until the user selects a menu item or cancels the menu. Returns the command assigned to the menu item or cmCancel if the menu was cancelled. Function FindItem(Ch:Char):PMenuItem; Returns a pointer to the menu item that has Ch as its shortcut key the highlighted character). Returns nil if no such menu item is found or if the menu item is disabled. Note that Ch is case-insensitive. Function GetHelpCtx:Word; virtual; Override: Sometimes This method returns the help context of the current menu selection. If this is hcNoContext, the parent menu's current context is checked. If there is no parent menu, GetHelpCtx returns hcNoContext. Procedure GetItemRect(Item:PMenuItem; var R:TRect); virtual; Override: Always - 6 - This method returns the rectangle occupied by the given menu item in R. Descendants of TMenuView must override this method in order to produce the correct rectangle in R. Procedure HandleEvent(var Event:TEvent); virtual; Override: Often Handle keyboard, mouse, and broadcast events for the menu. Keyboard events are handled by position the highlighted bar on the menu item with that highlighted character, then the item is activated. Mouse events are handled by tracking the mouse cursor while the left mouse button is pressed by the MouseEvent function. Broadcast events with the cmCommandSetChanged command causes the menu to redraw itself. Any object that overrides HandleEvent MUST chain back to this method. Function HotKey(aKeyCode:Word):PMenuItem; virtual; Override: Seldom This method checks the current menu for the hotkey, no such item is found, it checks the ParentMenu. Function ItemAt(P:TPoint):PMenuItem; virtual; Override: Always This method returns the item located at point P, or nil if no item exists there. Descendants of TMenuView must override ItemAt in order to produce the correct result. Function Menu:PMenu; virtual; Override: Always This is an abstract method that must be overriden. Function MouseInMenus(Where:TPoint):Boolean; Returns if the point in Where is located somewhere in the currently displayed menu chain. TMenuView - Descended from TMenuMetaView TMenuBar and TMenuBox are descended from this object. It is not intended to be instantiated. FIELDS ------ TrapKeys : Byte READ/WRITE TrapKeys contains the keyboard shift mask that the menu should respond to. By default, only TMenuBar uses this and sets it to kbAltShift. METHODS ------- Constructor Init(var Bounds:TRect; aMenu:PMenu; aParentMenu:PMenuMetaView); Calls TMenuMetaView to initialize the bounds parameter, then initializes Menu and ParentMenu to their respective parameters. TrapKeys is set to zero. Constructor Load(var S:TStream); Creates a TMenuView object and initializes it to the information read from the stream. Destructor Done; virtual; Override: Seldom Calls TMenuMetaView.Done and disposes of Menu if ParentMenu is nil. - 7 - Function GetPalette:PPalette; virtual; Override: Sometimes Returns a pointer to the defualt CMenuView palette. Procedure HandleEvent(var Event:TEvent); virtual; Override: Often Handles keyboard and command events. Keyboard events with the shift state included in the TrapKeys mask cause the menu to focus on that menu item. Command events with the command cmMenu toggle the menu between a modal and non-modal state. Any object that overrides HandleEvent MUST chain back to this method. Function Menu:PMenu; virtual; Override: Sometimes Returns the list structure of the menu that the view is currently using. Procedure Store(var S:TStream); virtual; Override: Seldom Stores the object onto the stream. TMenuBar - Descended from TMenuView TMenuBar draws itself as a list of horizontal menu items. METHODS ------- Constructor Init(var Bounds:TRect; aMenu:PMenu); Calls TMenuView.Init with Bounds and aMenu and nil as the ParentMenu. GrowMode is set to gfGrowHiX and Options is set to include ofPull and ofPreProcess. TrapKeys defaults to kbAltShift to respond to alternate quick-keys. Procedure Draw; virtual; Override: Seldom Uses the palette to draw the menu bar horizontally across the screen. The focused menu item is highlighted again using the default palette. Procedure GetItemRect(Item:PMenuItem; var R:TRect); virtual; Override: Seldom Returns the rectangle containing Item. Procedure HandleEvent(var Event:TEvent); virtual; Override: Seldom If the menubar is in a modal state, it will respond to right arrow, left arrow, end, and home keys. A down key will cause the current menu item to be 'pulled' down if not already pulled. Any object that overrides HandleEvent MUST chain back to this method. TMenuBox - Descended from TMenuView TMenuBox is a rectangle that is automatically sized to include its menu items. It can be used as submenus for a menu bar, as a standalone menu, or as a pop-up menu. METHODS ------- Constructor Init(var Bounds:TRect; aMenu:PMenu; aParentMenu:PMenuMetaView); Calls TMenuView.Init with the Bounds, aMenu, aParentMenu. The State is set to include a shadow and options is set to - 8 - include ofPreProcess. Bounds is altered to adjust for the width and length of the menu. Procedure Draw; virtual; Override: Seldom Draws a box containing the menu items using the default palette. The focused menu item is highlighted. Procedure GetItemRect(Item:PMenuItem; var R:TRect); virtual; Override: Seldom Returns the rectangle containing Item in R. Procedure HandleEvent(var Event:TEvent); virtual; Override: Seldom HandleEvent responds to the down arrow, up arrow, page-down, and page-up keys as expected. Any object which overrides HandleEvent MUST chain back to this method. TStatusLine - Descended from TMenuMetaView The status line is essentially a linked list of menus, one of which is displayed depending on the current help context. As a menu itself, the status line can contain TMenuCommands and TMenuSubMenus. Also, because TMenuMetaView is TStatusLine's ancestor, TStatusLine can become focused and modal just like any other menu. FIELDS ------ Defs : PStatusDef READ ONLY Defs is the start of the linked list of menus. Defs is normally initialized through a series of calls to NewStatusDef. CurrentDef : PStatusDef READ ONLY Returns the status definition current being displayed according to the current help context. METHODS ------- Constructor Init(var Bounds:TRect; aDefs:PStatusDef); Calls TMenuMetaView.Init with the Bounds parameter. Options is set to include ofPreProcess and GrowMode is set to gfGrowLoY+gfGrowHiX+gfGrowHiY. Defs is set to aDefs and CurrentDef is also set to Defs. Constructor Load(var S:TStream); Reads the status line and all associated status line definitions from the stream. Destructor Done; virtual; Override: Seldom Calls TMenuMetaView.Done and then disposes of all of the status line definitions. Procedure Activate(Item:PMenuItem); virtual; Override: Seldom The Item^.Execute called with a pointer to Self given as the ParentMenu. If cmCancel is returned and the ParentMenu is nil, then the menu structure is aborted with cmCancel. If cmValid is returned, no operation is performed. If any command other than cmCancel or cmValid is returned, EndModal is called with the result. Differs from TMenuMetaView.Activate in that a disabled item (an item with - 9 - an associated command which has been disabled) won't remain highlighted. Procedure Draw; virtual; Override: Seldom Draws the status line as a horizontal bar containing the current definitions using the status line palette. The focused item is highlighted, also using the palette. Procedure GetItemRect(Item:PMenuItem; var R:TRect); virtual; Override: Seldom Returns the rectangle occupied by Item in R. Function GetPalette:PPalette; virtual; Override: Sometimes Returns the default CStatusLine palette. Procedure Hint(aHelpCtx:Word):String; virtual; Override: Often Returns a hint string for the current help context. This string is displayed at the end of the status line after a vertical divider bar. The current Hint returns an empty string and must be overriden to provide any useful information. Function Menu:PMenu; virtual; Override: Seldom Returns the current status definition contained in CurrentDef. Procedure Store(var S:TStream); Writes the status line and all of its status line definitions to the stream. Procedure Update; virtual; Override: Seldom Updates the status line to display the definition for the current help context. Normally never called except by the TApp.Idle method. OBJECT HIERARCHY ---------------- Linked list objects and storage objects: TObject____TMenuItem_____TMenuCommand \ \ \ \________TMenuSubMenu \ \___TMenu________TStatusDef Menu view objects: TView______TMenuMetaView_TMenuView \ \ \ \______TMenuBar \ \ \ \____TMenuBox \ \____TStatusLine OTHER TYPES ----------- TMenuStr = String[31] PMenu = ^TMenu PMenuMetaView = ^TMenuMetaView PMenuItem = ^TMenuItem PMenuCommand = ^TMenuCommand PMenuSubMenu = ^TMenuSubMenu - 10 - PStatusDef = ^TStatusDef PMenuView = ^TMenuView PMenuBar = ^TMenuBar PMenuBox = ^TMenuBox PStatusLine = ^TStatusLine OTHER ROUTINES -------------- Procedure DisposeMenu(Menu:PMenu) Reclaims the memory used by Menu's items and any submenus that exist in Menu. Function NewItem(Name, Param:TMenuStr; KeyCode:Word; Command:Word; aHelpCtx:Word; Next:PMenuItem):PMenuItem Creates and returns a pointer to a new PMenuCommand object initialized with the proper parameters. Function NewLine(Next:PmenuItem):PMenuItem Creates and returns a pointer to a new PMenuItem object. The PMenuItem object has its Name and Param fields initialized to an empty string and HelpCtx is set to hcNoContext. Function NewMenu(Items:PMenuItem):PMenu Creates and returns a pointer to a TMenu object which contains Items. Items is normally created by nesting calls to NewItem, NewSubMenu, and NewLine. Function NewStatusDef(aMin, aMax:Word; aItems:PMenuItem; aNext:PStatusDef):PStatusDef Creates and returns a pointer to a new TStatusDef object initialized with the proper parameters. Normally, aItems is a set of nested calls to NewStatusKey, NewItem, or NewSubMenu. Function NewStatusKey(aText:String; aKeyCode:Word; aCommand:Word; aNext:PMenuItem):PMenuItem Creates and returns a pointer to a new TStatusKey object initialized with the proper parameters. Function NewStatusMenu(aText:String; aHelpCtx, aKeyCode:Word; SubMenu:PMenu; aNext:PMenuItem):PMenuItem Creates a submenu specifically for the status line. Notice that a status line submenu also takes on a KeyCode value so that it can be activated from the keyboard. Function NewSubMenu(Name:TMenuStr; aHelpCtx:Word; SubMenu:PMenu; Next:PMenuItem) Creates and returns a pointer to a new TMenuSubMenu object initialized to the proper parameters. CONSTANTS --------- CMenuView = #2#3#4#5#6#7 CStatusLine = #2#4#4#5#6#7 ofPull = $0400 When the ofPull bit is set in a menu's Options field, the menu's items will automatically pull their submenus when selected. An example of such a menu would be the menu bar. sfPulled = $1000 - 11 - If this state bit is set, the one of the items in the menu currently has its submenu pulled. Note that the setting of this bit is not necessarily related to the ofPull bit. sfUpdate = $2000 Used only on the TStatusLine object when the status line needs to be updated. SUPPORT ------- Registered users can receive free support for EnhMenus via CompuServe account number 71441,2402. Any questions or comments should also be directed through CompuServe at the same account number. Thanks for using EnhMenus! - 12 -