COMMENT @----------------------------------------------------------------------

	Copyright (c) GeoWorks 1988 -- All Rights Reserved

PROJECT:	PC GEOS
FILE:		ui.def

AUTHOR:		Tony Requist

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	Tony	2/89		Initial version
	Doug	7/7/92		Changed to no longer be a generated file

DESCRIPTION:
	This file contains the definitions for the UI library.  It is included
both by the library and by users of the library.  When included by the library,
the symbol "_DECLARER_" must be true.

	$Id: ui.def,v 1.2 98/03/18 00:36:25 joon Exp $

------------------------------------------------------------------------------@

SetDef	__UI

StartLibrary	ui

;
; Files that need to be included for ui.def to function.
;
include	file.def
include	vm.def
include	text.def
include	win.def
include input.def			; for KeyboardShortcuts
include localize.def
include Objects/processC.def
include gcnlist.def			; for FileChangeNotificationFrame
					;	(TEMPORARY)
UseLib	Objects/Text/tCommon.def

UI_STACK_SPACE_REQUIREMENT_FOR_RECURSE_ITERATION	= 600
; 
; Common value passed to ThreadBorrowStackSpace within the UI before doing
; the next of any recursive operation.

UI_MAXIMUM_THREAD_BORROW_STACK_SPACE_AMOUNT		= 1200
;
; Maximum value that should be pass to ThreadBorrowStackSpace within gui
; or spui code.  (Designed to to be small enough to not cause crashing
; when used with INTERFACE_THREAD_MINIMUM_STACK_SIZE)
; 

INTERFACE_THREAD_MINIMUM_STACK_SIZE			= 1500
;
; Smallest support stack size for threads running UI objects.  Most apps
; will want to use the default amount, which is currently set inside the
; UI to 2000.  Use values down to this amount only for apps having the most
; minimal of UI needs (such as a shell that takes login in only, then exits)

INTERFACE_THREAD_DEF_STACK_SIZE				= 2000
;
; Default stack size for ui threads as set by the UI.
;
; NOTE:  If you change the constant here, be sure to update the same constant
; INTERFACE_THREAD_DEF_STACK_SIZE in /staff/pcgeos/Tools/include/geode.h
; so that glue will correctly set the stack size for single-threaded apps
; not specifying a stack size.

;------------------------------------------------------------------------------
;	User Interface .ini constants
;------------------------------------------------------------------------------

;
; This constant represents the level of interface desired by the user, & 
; is the value stored in for the [ui] .ini category key of "userLevel".
; Lengthy descriptions are included here so that app designers can
; appropriately tune the default behavior of their applications for each
; given level.				-- Doug
;
UIInterfaceLevel	etype	word
	UIIL_INTRODUCTORY			enum	UIInterfaceLevel
	; This level is designed for the first-time user, or those who just
	; use computers infrequently.  Complex models & all but the most basic
	; features are shunned in favor of metaphors & functionality that is
	; easy to grasp.  Ease of learning and the absence of anything that
	; isn't immediately obvious are the most important considerations
	; of interfaces presented at this level, with a focus towards
	; providing a pleasant experience.  Ease of quick results is very
	; important, however prefabricated & limited in scope (remember
	; PrintShop?).
	;
	; Default behavior:
	; In this mode, the UI protects the user from the concepts of
	; "running" applications & "open" documents by letting them just
	; switch to whatever application & document they wish to use.  The
	; UI takes care of managing the running status of applications &
	; open status of documents transparently, in the background.
	; Apps generally come up maximized, and have no window controls
	; whatsoever (the exception here is desk accessories, which float
	; on top and may be moved & dismissed by the user).  Only one 
	; document at a time may be worked on, & it generally appears in
	; a display which is perminantly maximized.  Applications where
	; the user typically uses only one data file (Address book) won't
	; have a "File" menu at all.  Applications designed for creation of
	; new files will have only "New..." & "Switch to..." options, & will
	; automatically fetch & place files in a single directory.  Kbd
	; shorcuts & mnemonic navigation are turned off (excepting kbd only
	; systems) Application menu structures in general are kept to a minimum,
	; & advanced features are kept completely hidden, not even accessible
	; through the "Options" menu.

	UIIL_BEGINNING	enum	UIInterfaceLevel
	; This level is designed for those who feel comfortable with the
	; basic operation of their computer, how it works, what modules
	; exist within it, etc. & wish to gain access to more of its 
	; capability, or need to solve a particular problem or need for
	; something other than a canned solution.  This level adds in a number
	; of useful features to UI-provided menus, & results in applications
	; offering "options" to turn on all but the most advanced or short-cut
	; oriented capabilities within them. Ease of Learning remains the most
	; important aspect of the interface, & probability of successful
	; usage the most important goal.  We're trying to get the user to be
	; able to actually *accomplish* things here, all on their own, with
	; a low risk of failure.  Time to task completion is not an issue so
	; long as the user is able to figure out what the model is, how to use
	; it, & is able to actually complete whatever it is they're trying to
	; do.  This may be accomplished via more verbose, or scripted dialogs,
	; as opposed to the "set everything at once" type of dialogs seen
	; at higher levels.  The computer should detect abnormal or
	; dangerous situations & help the user to avoid costly mistakes.
	; Dangerous actions should be undoable.  Options that trade
	; performance against safety or recoverability will be tilted
	; towards recoverability.
	;
	; Default behavior:
	; In this mode, the document control adds "New..", "Switch to...", 
	; "Quick Backup", & variety of other capabilities.  Applications
	; offer a way to access most of their features.  The app launch &
	; document models remain "transparent".  Apps continue to run
	; full-screen.  Files created by the user remain in one directory.
	;

	UIIL_INTERMEDIATE	enum	UIInterfaceLevel
	; This level is designed for people familiar with the capabilities
	; of the software, & who are now willing to learn a few things that
	; might not otherwise be obvious in order to speed up their ability
	; to get things done.
	;
	; Default behavior:
	; Here we introduce the user to the concepts of "running apps" &
	; "open documents", & adds in easy to understand "power" features
	; that makes it easier to get things done.  The user must open &
	; close apps & docs to manage accessibility & performance.  App
	; windows start out overlapping (except on machines w/small screens)
	; Adds window min/max/restore capability, pinned menus.  Systems
	; with both mice & keyboards get kbd accelerators & mnemonic
	; navigation.  The system allows only one instance of any given
	; app to be running, but allows multiple documents to be open within
	; that app.

	UIIL_ADVANCED			enum	UIInterfaceLevel
	; This level is designed for the people who use their computer day in,
	; day out, and know PC/GEOS like the back of their hand.  All the
	; bells & whistles available are offered here, though still organized 
	; intelligently with the degree of accessibility set by the user --
	; a technical writer may live in his Word Processor, for instance, but
	; venture into other applications only infrequently -- they shouldn't
	; all look like the cockpits of 727's.  A reduction in the number
	; of steps necessary to complete common tasks, & the speed in which
	; this can be done becomes very important.  The key phrases here
	; are "powerful", "well designed", and "intelligent".
	;
	; Default behavior:
	; The UI offers the possibility of multiple instances of a given app,
	; dialog-clarified.  The notion of hierarchical storage of document
	; files is introduced.
	; 

	UIIL_GURU			enum	UIInterfaceLevel
	; Same as "UIIL_ADVANCED" level, but minus protective warning dialogs
	; that might be annoying to someone who never makes mistakes. :)
	; Options that trade performance against safety or recoverability are
	; tilted towards performance.

;
; This record is returned by UserGetInterfaceOptions
;
UIInterfaceOptions	record
    UIIO_OPTIONS_MENU:1			;TRUE if the options menu should exist
    UIIO_DISABLE_POPOUTS:1		;TRUE to not allow GIV_POPOUT
					;	GenInteractions to pop in and
					;	out.  FALSE to allow pop in
					;	and pop out behavior.

					; TRUE to allow specifying initally-
					; popped-out and hidden menu bars
    UIIO_ALLOW_INITIALLY_HIDDEN_MENU_BARS:1
					; TRUE to use "modal mask" if
					; support by SPUI
    UIIO_MODAL_MASK:1
    :12

UIInterfaceOptions	end

;
; This is the integer value stored in for the [uiOptions] .ini category key of
; "launchMode"
;
UILaunchModel	etype	word			; PARTIALLY IMPLEMENTED
	UILM_TRANSPARENT	enum UILaunchModel
	;
	; "Transparent" application launch mode is one in which the user
	; doesn't have to understand the concepts of a "running app", as
	; the system takes care of launching & shutting down apps in the
	; background to manage memory effectively.
	;
        ;       -> Express menu is really just a "startup" or "switch to" menu
	;	-> applications are shut down in background, & reloaded when
	;	   switched to
        ;       -> Single instance limit on any given app
        ;       -> App windows are full screen (except for those marked as
        ;           Desk Accessories, which float on top, & would not be 
	;	   managed transparently, i.e. would have to stay in memory
	;	   until exited))
	;	-> Minimize/Maximize/Restore/Close features of full-screen
	;	   main Primary windows removed
	;	-> "Exit" item is eliminated from File menu
	;	-> Default mode for UIIL_INTRODUCTORY, UIIL_BEGINNING

	;-------

        ; The following levels are all user-controlled, meaning that the
	; user has to understand the concept of a running app, & must manage
	; how many apps are running themselves.
	;
        ;	-> Express menu allows switching between currently running apps
       	;	-> By default, app windows are not maximized on launch, and are
	;	   movable & resizable.  This could be "fine tuned" by using
	;	   window options above, however.

	UILM_SINGLE_INSTANCE	enum UILaunchModel
	;
        ; This mode allows only a single instance of any one given app to
	; be running at a time.
	;
        ;	-> Single instance limit on given app
        ;	-> If app or document is double-clicked on, and an
	;	   instance of the app is already running, that
	;	   instance would be brought to the top (& any
	;	   document opened/switched to within it, depending
	;	   on the doc model)
	;	-> Default mode for UIIL_INTERMEDIATE

	UILM_MULTIPLE_INSTANCES	enum UILaunchModel
        ;	-> If app or document double-clicked on, and an
	;	   instance of the app is already running, a dialog
	;	   would come up asking if one of the already running
	;	   apps should be used, or whether a new instance
	;	   should be created.
	;	-> Default mode for UIIL_ADVANCED

	UILM_GURU		enum UILaunchModel
        ;	-> Like PC/GEOS V1.2 -- the system does nothing to protect
	;	   the user, so double-clicking on an app just launches
	;	   another instance.
	;	-> Default mode for UIIL_GURU

;
; This record is returned by UserGetLaunchOptions
;
UILaunchOptions	record
    UILO_DESK_ACCESSORIES:1		;TRUE if the desk accessory mode is
					;	supported (default = TRUE)
    UILO_CLOSABLE_APPS:1		;Set if all apps should be closable.
    					; This allows the user to close apps
					; even when in transparent mode.
    :14
UILaunchOptions	end

;
; This is the integer value stored in for the [uiOptions] .ini category key of
; "expressOptions"

UIExpressPositions	etype	word
UIEP_NONE		enum	UIExpressPositions
UIEP_TOP_PRIMARY	enum	UIExpressPositions
UIEP_LOWER_LEFT		enum	UIExpressPositions
;
UIExpressOptions record
    :3
    UIEO_DOCUMENTS_LIST:1
    ; Set for list of documents
    UIEO_RETURN_TO_DEFAULT_LAUNCHER:1
    ; Set to have a "Return to <default launcher>" button in the Express
    ; Menu
    UIEO_GEOS_TASKS_LIST:1
    ; Set for list of currently running GEOS applications
    UIEO_DESK_ACCESSORY_LIST:1
    ; Set for list of desk accessories (applications in World/Desk Accessories
    ; directory)
    UIEO_MAIN_APPS_LIST:1
    ; Set for list of applications in World directory
    UIEO_OTHER_APPS_LIST:1
    ; Set for hierarichal list of applications in subdirectories below World
    ; directory.
    UIEO_CONTROL_PANEL:1
    ; Set for control panel area.
    UIEO_DOS_TASKS_LIST:1
    ; Set for list of available DOS tasks.
    UIEO_UTILITIES_PANEL:1
    ; Set for utilities panel area.
    UIEO_EXIT_TO_DOS:1
    ; Set for Exit to DOS trigger.
    UIEO_POSITION	UIExpressPositions:3
    ; Position of Express menu.
UIExpressOptions end

;
; UIWindowOptions -- window options stored above.
; The interpretation of these options is left to each specific UI.
;
UIWindowOptions	record
	UIWO_MAXIMIZE_ON_STARTUP:1
	; If true, applications by default would come up maximized.  (Apps
	; marked as desk accessories would override this behavior)
	;
	; Default interpretation under Motif:  TRUE if
	; running on a small screen (less than 512 pixels in X, or 320 pixels
	; in Y), or if on keyboard-only machine, or if
	; InterfaceLevel < UIIL_INTERMEDIATE, or if
	; LaunchMode = UILM_TRANSPARENT.
	;

	UIWO_COMBINE_HEADER_AND_MENU_IN_MAXIMIZED_WINDOWS:1
	; This is a scren space saving measre -- if true, the header & menu
	; areas of maximized windows is combined, such that only the window
	; gadgetry, window menu & menus are left, i.e. the title string is
	; eliminated.
	;
	; Default interpretation under Motif:  TRUE if running on a small
	; screen (less than 512 pixels in X, or 320 pixels in Y).

	UIWO_PRIMARY_MIN_MAX_RESTORE_CONTROLS:1
	; If false, window gadgetry & menu items for minimizing, maximizing,
	; & restoring would disappear from primary windows.
	;
	; Default interpretation under Motif:  Always FALSE if
	; LaunchMode = UILM_TRANSPARENT, else TRUE if 
	; InterfaceLevel >= UIIL_INTERMEDIATE.

	UIWO_WINDOW_MENU:1
	; If true, a window menu for keyboard control of
	; min/max/restore/move/resize features will be provided.   If false,
	; only a "close" icon will appear in this space.
	;
	; Default interpretation:  TRUE if keyboardOnly = TRUE

	UIWO_PINNABLE_MENUS:1
	; True to allow "pinnable" menus.
	;
	; Default interpretation under Motif:  TRUE if
	; InterfaceLevel >= UIIL_INTERMEDIATE

	UIWO_KBD_NAVIGATION:1
	; True to allow keyboard accelerators, keyboard navigation
	;
	; Default interpretation under Motif:  TRUE if keyboard-only machine or
	; InterfaceLevel >= UIIL_INTERMEDIATE

	UIWO_POPOUT_MENU_BAR:1
	; True to allow menu bar to pop-out into a dialog box.  This should
	; only be allowed in very specific situations, because the specific UI
	; will not always provide gadgetry to restore the menu bar if the
	; dialog is closed.
	;
	; Default interpretation under Motif:  TRUE if running on a small
	; screen (less than 512 pixels in X, or 320 pixels in Y).

UIWindowOptions	end

UIWindowOptionsInteger	record
	UIWOI_MASK	UIWindowOptions:8
	; Mask of which UIWindowOptions in UIWOI_value have meaning.  (If 0,
	; user has made no preference for that specific option, & the default
	; behavior should be used)

	UIWOI_OPTIONS	UIWindowOptions:8
	; Actual UIWindowOptions to use (if mask bit above is 1 for any
	; given bit)
UIWindowOptionsInteger	end

;
; Options for how help works and is displayed
;
UIHelpOptions	record
	:15
	UIHO_HIDE_HELP_BUTTONS:1
	; TRUE: do not add help buttons to various dialog boxes.  Usually
	; used on small screen devices where screen space is at a premium,
	; or on a device that has a dedicated help button already.
	;
	; Default interpretation: FALSE (ie. help buttons appear)
	;
UIHelpOptions	end

;------------------------------------------------------------------------------
;	Imported methods
;------------------------------------------------------------------------------

; clipbrd.def

MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_FEEDBACK	method	MetaUIMessages
;
;	This method is sent to the source of a quick transfer item when a
;	potential destination provides feedback to the user indicating whether
;	a move, a copy or no operation will occur.  The default behavior is
;	determined by the destination, but the user may be able to override
;	with the <MOVE> or <COPY> override keys.
;
;	Context:	Notification message sent by quick-transfer mechanism
;	Source:		Sent by quick-transfer mechanism
;	Destination:	Sent to optr passed to UserStartQuickTransfer.
;			Handled if the quick-transfer source needs to know
;			what quick-transfer operation a potential destination
;			will perform.  Handler need not call superclass.
;	Interception:	Message sent directly to destination, no need to
;			intercept.
;
;	Pass:	bp - QuickTransferCursor action specified by source
;			(see UserSetQuickTransferCursor)
;	Return:	nothing
;

MSG_META_CLIPBOARD_NOTIFY_QUICK_TRANSFER_CONCLUDED	method	MetaUIMessages
;
;	This method is sent to the source of a quick transfer item when the
;	operation is completed.  The QuickNotifyFlags are set by any
;	MSG_META_END_MOVE_COPY handler.  This is only sent out if the source
;	requests notification with the QTF_NOTIFICATION flag passed to
;	UserStartQuickTransfer.
;
;	Context:	Notification message sent by quick-transfer mechanism
;	Source:		Sent by quick-transfer mechanism
;	Destination:	Sent to optr passed to UserStartQuickTransfer.
;			Handled if the quick-transfer source needs to know
;			when the quick-transfer destination has processed
;			the quick-transfer item.  Handler need not call
;			superclass.
;	Interception:	Message sent directly to destination, no need to
;			intercept.
;
;	Pass:	bp - QuickNotifyFlags
;	Return:	nothing
;

MetaUIMessages = MetaUIMessages + 1
MSG_META_CLIPBOARD_CUT					method	MetaUIMessages
MSG_META_CLIPBOARD_COPY					method	MetaUIMessages
MSG_META_CLIPBOARD_PASTE				method	MetaUIMessages
;
;	Sent to an obejct which is supposed to be the destination of a
;	clipboard operation.  MSG_META_CLIPBOARD_COPY should be handled by
;	registering the current selection with UI as the new clipboard item.
;	MSG_META_CLIPBOARD_CUT should do the same, but also delete the current
;	selection.  MSG_META_CLIPBOARD_PASTE should replace the current
;	selection with the current clipboard item, which can be obtained from
;	the UI.
;
;	Context:	High-level application clipboard function message
;	Source:		Sent by anyone to perform clipboard operation
;	Destination:	Handled by anyone who wishes to support clipboard
;			operations.
;	Interception:	May be intercepted to add clipboard support to
;			existing object that doesn't currently have
;			clipboard support or to enhance or replace
;			functionality of object that does have clipboard
;			support.  If replacing functionality, don't call
;			superclass, if enhancing functionality, call
;			superclass.
;
;	Pass:	nothing
;	Return:	nothing
;

; gProcC.def

MSG_META_UNDO						method	MetaUIMessages
;	
;	This message is sent out by the undo mechanism to play back an undo
;	action.
;
;	Context: Undo mechanism
;	Source: GenProcessClass
;	Interceptions: Intercepted by objects to handle their own undo data
;	Pass: ss:bp - UndoActionStruct
;	Return: nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_UNDO_FREEING_ACTION				method	MetaUIMessages
;
;	This message is sent out by the undo mechanism when freeing an action
;	created with the "NOTIFY_BEFORE_FREEING" message.
;
;	Context: Undo mechanism
;	Source: GenProcessClass
;	Interceptions: Intercepted by objects to handle their own undo data
;	Pass: ss:bp - AddUndoActionStruct
;	Return: nothing
;		ax, cx, dx, bp - destroyed
;

; clipbrd.def

MSG_META_SELECT_ALL					method	MetaUIMessages
MSG_META_DELETE						method	MetaUIMessages

MSG_META_CLIPBOARD_NOTIFY_TRANSFER_ITEM_FREED		method	MetaUIMessages
;
;	Sent to all ODs in TransferNotifyList to help maintain integrity
;	of transfer items from VM files other than the UI's transfer VM file.
;	Only sent if VM file handle of transfer item that is being freed
;	is different from UI's tranfser VM file handle.  If a transfer item
;	from a VM file other than the UI's transfer VM file is registered,
;	the VM blocks in that transfer item cannot be freed and the VM
;	file cannot be closed until notification is sent saying that the
;	transfer item has been freed.  Register'ers of such transfer items
;	should keep track of the VM file handle and VM block handle of the
;	item to check against the info sent by this method.
;
;	Context:	Notification message sent by clipboard mechanism
;	Source:		Sent by clipboard mechanism
;	Destination:	Sent to optrs on transfer notification list, added
;			with UserAddTransferNotify.  Handled if clipboard
;			changes need to be monitored.
;	Interception:	Message sent directly to destination, no need to
;			intercept.
;
;	Pass:	cx:dx - (VM file handle):(VM block handle) of transfer
;				item freed
;	Return:	nothing
;

MSG_META_CLIPBOARD_NOTIFY_NORMAL_TRANSFER_ITEM_CHANGED	method	MetaUIMessages
;
;	Sent to all ODs in TransferNotifyList to help with updating of
;	Cut/Copy/Paste button states.  Recipients can UserQueryTransfer
;	to check if the new normal transfer item contains formats that
;	the recipient supports.  If not, Paste button can be disabled.
;
;	Context:	Notification message sent by clipboard mechanism
;	Source:		Sent by clipboard mechanism, relayed by
;			GenEditControlClass
;	Destination:	Sent to optrs on transfer notification list, added
;			with UserAddTransferNotify.  Handled if clipboard
;			changes need to be monitored.
;	Interception:	Message sent directly to destination, no need to
;			intercept.
;
;	Pass:	nothing
;	Return:	nothing	
;

; gViewC.def

MSG_META_CONTENT_SET_VIEW				method	MetaUIMessages
;
; Sends view's output descriptor to the content before as the content is being
; made ready to appear onscreen.  A VisContent object will handle this
; message and save a pointer to the view.
;
; Context:	This will be the first thing sent to a content as it is being
;		prepared to appear onscreen.  It will be sent: a) as a view
;		is being made visible, or b) as a view is switching contents.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A process may want to intercept this and save away the view's
;		pointer, although usually an application will already have this
;		information.
;
; Pass:  	^lcx:dx -- view
; Return:	nothing
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_OPENING				method	MetaUIMessages
;
; Indicates that the view is opening, & that objects inside the view should
; prepare themselves visually.  This method will be sent BEFORE the initial
; MSG_META_CONTENT_VIEW_WIN_OPENED's, and BEFORE the first MSG_META_EXPOSED's.
; The companion to this message is MSG_META_CONTENT_VIEW_CLOSING.  
;
; Context:	This will be the last thing sent to a content as it is being
;		prepared to appear onscreen.  It will be sent: a) as a view
;		is being made visible, or b) as a view is switching contents.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A process can intercept this and do preparations similar
;		to MSG_VIS_OPEN in the visible world, if any such preparations
;		are necessary.
;
; Pass:  	^lcx:dx -- view
; Return:	nothing
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_CLOSING				method	MetaUIMessages
;
; Indicates that subviews are about to be closed, is used for objects to
; make themselves not visible.  This message will be sent BEFORE any
; MSG_META_CONTENT_VIEW_WIN_CLOSED's.  Note that it is NOT guaranteed to
; come before that last MSG_META_EXPOSED's arrive at the content.   The
; companion to this message is MSG_META_CONTENT_VIEW_OPENING.
;
; Context:	This will be the first thing sent to a content as it is being
;		removed from the screen.  It will be sent: a) as a view
;		is being made not visible, or b) as view is switching contents.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A process may want to intercept this and do preparations 
;		similar to MSG_VIS_CLOSEs in the visual world, if any such
;		preparations are necessary.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_META_CONTENT_VIEW_WIN_OPENED			method	MetaUIMessages
;
; This method is sent whenever a new view has been created, or when a new
; content is attached to a view.  This allows an application to keep
; track of all the open views.  This event will be received BEFORE the
; first MSG_META_EXPOSED is sent out, but the view window may or may
; not be mapped, so drawing should not be done in response to this event.
; Only applciations that keep a record of active view windows need to
; respond to this event.  The companion to this message is
; MSG_META_CONTENT_VIEW_WIN_CLOSED.  This message is sent AFTER MSG_META_-
; CONTENT_VIEW_OPENING when the view is coming up for the first time.
;
; Context:	This will be sent to a content as it is being
;		prepared to appear onscreen.  It will be sent: a) as a view
;		is being made visible, or b) as a view is switching contents.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A process may want to intercept this and save away the window
;		handle passed.
;
; Pass:		cx - width of view, in document coords
;		dx - height of view, in document coords
;		bp - handle of view window created
; Return:	none
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_WIN_CLOSED			method	MetaUIMessages
;
; This method is sent immediately after a view's window has been closed, or
; when a content is removed from a view, to let the content know that it
; should no longer maintain any references to this window.  The message is
; guaranteed to be sent to the content AFTER the last MSG_META_EXPOSED for
; that window is sent to the content.  If the content is keeping a
; window handle at this time, it should zero it now.  (The VisContent and
; VisContent objects do this.)  Note that while the Window may be "closed", it
; may not yet be freed, as this does not happen until all window-related
; messages have been flushed through the input queues (such as
; MSG_META_IMPLIED_WIN_CHANGE, MSG_META_RAW_UNIV_ENTER,
; MSG_META_RAW_UNIV_LEAVE).  The companion to this message is
; MSG_META_CONTENT_VIEW_WIN_OPENED.
;
; Context:	This will be sent to a content as it is being removed
;		from the screen.  It will be sent: a) as a view is being
;		made not visible, or b) as a view is switching contents.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A process may want to intercept this and remove references
;		to the view window handle.
;
; Pass:		bp -- handle of view window that is going away
; Return:	nothing
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_ORIGIN_CHANGED			method	MetaUIMessages
;
; This method is sent to indicate the current origin of the view window.
; It will be sent when a content is being used for the first time so it gets 
; the initial value, and on any subsequent changes of that value.
;
; Context:	This will be sent to a content immediately following a 
;		MSG_META_CONTENT_SET_VIEW as the content is being
;		prepared to appear onscreen.  It will be sent: a) as a view
;		is being made visible, or b) as a view is switching contents.
;		It is also sent on any subsequent changes of the origin.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A content may wish to subclass this and keep track of the 
;		current view origin, or for complicated documents, to ensure 
;		that everything now currently visible in the view window can 
;		be drawn correctly.
;
; Pass:		ss:bp -- {OriginChangedParams} new origin
;		dx    -- size OriginChangedParams
; Return:	none
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_SCALE_FACTOR_CHANGED		method	MetaUIMessages
;
; This method is sent whenever a view window has changed scale factors.
; Also when a content is being used for the first time so it gets the initial
; value.  The content need not do anything with this method if it doesn't
; want to.  This message will precede any MSG_META_EXPOSED message resulting
; from the scale factor changing, but the actual scale factor in the window
; will be indeterminate at time this message arrives.
;
; Context:	This will be sent to a content immediately following a 
;		MSG_META_CONTENT_SET_VIEW as the content is being
;		prepared to appear onscreen.  It will be sent: a) as a view
;		is being made visible, or b) as a view is switching contents.
;		It is also sent on any subsequent changes of the origin.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A content may wish to subclass this and keep track of the 
;		current scale factor, or for complicated documents, to ensure 
;		that everything now currently visible in the view window can 
;		be drawn correctly.
;
; Pass:		ss:bp -- {ScaleChangedParams} new origin
;		dx    -- size ScaleChangedParams
; Return:	none
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_SIZE_CHANGED			method	MetaUIMessages
;
; This method is sent whenever the size of the visible document area changes, 
; notifying the content of the new size.    This message will precede any
; MSG_META_EXPOSED resulting from the size change.  The window will have been
; sized (via a WinResize) by the time this message is handled, so you can
; call WinGetWinScreenBounds to get the real window size, for instance.
;
; Context:	This will be sent out on any change in size of the view window
;		in document coordinates, either from a resize of the view or
;		a change in the view's scale factor.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A content may wish to subclass this and keep track of the 
;		current view size, or for complicated documents, to ensure 
;		that everything now currently visible in the view window can 
;		be drawn correctly.  Also useful for contents who change their
;		document size based on the size of the visible area (e.g.
;		the notepad, where the height of the document is dependent
;		on the width.)
;
; Pass:		bp - handle of pane window
;		cx - new window width, in document coords (you will have to
;		     call WinGetWinScreenBounds to get the true size of the 
;		     window area in screen coordinates, for doing things like
;		     scale to fit.)
;		dx - new window height, in document coords
; Return:	none
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_TRACK_SCROLLING			method	MetaUIMessages
;
; Allows the content to track any scrolling that occurs in the view, and
; optionally changing the scroll amount that is passed.  See the above
; discussion on MSG_META_CONTENT_TRACK_SCROLLING for more info.  Note:  this
; message MUST be handled if GVA_TRACK_SCROLLING is set in the view's 
; attributes!
;
; Context:	Sent out by the view, if GVA_TRACK_SCROLLING is set in the 
;		view's attributes, on initial setting of the view's origin
;		and before any subsquent scroll of the view window is made.
; Source:	the content's GenView object
; Destination:  a content object, either a process, or a VisContent or subclass
; Interception: A content may wish to subclass this and keep track of the 
;		current view origin, or for complicated documents, to ensure 
;		that everything now currently visible in the view window can 
;		be drawn correctly.  It may also wish to change the scroll
;		values to scroll entire objects onscreen, for instance.
;		See MSG_META_CONTENT_TRACK_SCROLLING for more info,
;
; Pass:		ss:bp - TrackScrollingParams
;		dx - size TrackScrollingParams
; Return:	nothing
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_VIEW_LOST_GADGET_EXCL			method	MetaUIMessages
;
; Notification to output descriptor of view that a subview has lost the
; gadget exclusive, presumably because some other gadget has taken it away
; from the view, or because the subview is closing.  VisContentClass processes
; this method by sending itself a MSG_VIS_TAKE_GADGET_EXCL w/NULL data
;
; Context:	Sent when the view loses the gadget exclusive.
; Source:	A GenView object
; Destination:  The content of the view
; Interception: Only if you want to something else when the view loses the
;		gadget exclusive.
;  
; Pass:		bp - handle of view window
; Return:	Nothing
; 		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_NAVIGATION_QUERY			method  MetaUIMessages
;
; Sent from the view when the content is expected to do navigation.  Only
; if GVA_IS_NAVIGABLE is set (not yet created)...
;
;       Pass:	^lcx:dx	= object which originated this query
;		bp	= NavigateFlags 
;	Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_CONTENT_APPLY_DEFAULT_FOCUS			method  MetaUIMessages
;
; Sent from the view when it has HINT_DEFAULT_FOCUS, to search for an object
; under the content to award the default focus to.  
;
;	Pass:	nothing
;	Return:	nothing
;		ax, cx, dx, bp - destroyed
;
;
;

MSG_META_CONTENT_ENTER					method	MetaUIMessages
MSG_META_CONTENT_LEAVE					method	MetaUIMessages


; gDocC.def

MSG_META_DOC_OUTPUT_INITIALIZE_DOCUMENT_FILE		method	MetaUIMessages
;
;	Sent when the application should set the document file to the
;	empty document state.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_CREATE_UI_FOR_DOCUMENT		method	MetaUIMessages
;
;	Notification that a file has been opened.  Sent when the
;	application should construct (or enable) the UI components
;	used to	display the document.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_DESTROY_UI_FOR_DOCUMENT		method	MetaUIMessages
;
;	Notification that a file is about to be closed.  Sent when the
;	application should destroy (or disable) the UI components used
;	to display the document.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_ATTACH_UI_TO_DOCUMENT		method	MetaUIMessages
;
;	Notification that a document has been opened and UI has been
;	created for it and that it needs to be displayed.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_DETACH_UI_FROM_DOCUMENT		method	MetaUIMessages
;
;	Notification that a document is about to be closed and that
;	the UI used to display the file must be detached from the file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_READ_CACHED_DATA_FROM_FILE		method	MetaUIMessages
;
;	Notification that the application must update its cached
;	information from the file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_WRITE_CACHED_DATA_TO_FILE		method	MetaUIMessages
;
;	Notification that the document file needs to be up to date for
;	an action that is about to take place.  This message is not
;	sent to documents that are not modified (clean).
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_DOCUMENT_HAS_CHANGED		method	MetaUIMessages
;
;	Notification that the document has changed.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_PHYSICAL_SAVE			method	MetaUIMessages
;
;	Really save the file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_PHYSICAL_UPDATE			method	MetaUIMessages
;
;	Update chagnes to the file.  This is called on auto-save (if
;	the document control is set up to support auto-save) and on
;	detach to save changes to the file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_PHYSICAL_SAVE_AS_FILE_HANDLE	method	MetaUIMessages
;
;	This message is sent by the default
;	handler after opening the new DOS file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_PHYSICAL_REVERT			method	MetaUIMessages
;
;	Really revert the file.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_UPDATE_EARLIER_COMPATIBLE_DOCUMENT	method	MetaUIMessages
;
;	Handle updating of an earlier protocol file that is compatible with
;	the protocol of the document control (since the file is compatible
;	applications will often not handle this)
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_UPDATE_EARLIER_INCOMPATIBLE_DOCUMENT method MetaUIMessages
;
;	Handle updating of an earlier protocol file that is not compatible with
;	the protocol of the document control.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error) or 0 if no error
;	cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_SAVE_AS_COMPLETED			method	MetaUIMessages
;
;	Notification that a "Save As" has been completed for the
;	document.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_ATTACH_FAILED			method	MetaUIMessages
;
;	Notification that upon restarting from a state file the
;	document file could not be re-opened.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_PHYSICAL_REVERT_TO_AUTO_SAVE	method	MetaUIMessages
;
;	Really revert the file to its last auto-saved version.
;
; Pass:
;	cx:dx - GenDocument object
;	bp - file handle
; Return:
;	carry - set if error
;	ax - error code (if error)
;	cx, dx, bp - destroyed
;

MSG_META_UNUSED_META_UI_11				method	MetaUIMessages
MSG_META_UNUSED_META_UI_12				method	MetaUIMessages
MSG_META_UNUSED_META_UI_13				method	MetaUIMessages
MSG_META_UNUSED_META_UI_14				method	MetaUIMessages
MSG_META_UNUSED_META_UI_15				method	MetaUIMessages
MSG_META_UNUSED_META_UI_16				method	MetaUIMessages
MSG_META_UNUSED_META_UI_17				method	MetaUIMessages
MSG_META_UNUSED_META_UI_18				method	MetaUIMessages
MSG_META_UNUSED_META_UI_19				method	MetaUIMessages
MSG_META_UNUSED_META_UI_20				method	MetaUIMessages

; gCtrlC.def

MSG_META_UI_FORCE_CONTROLLER_UPDATE			method MetaUIMessages
;
; (NOTE:  Actual declaration of this & all MetaUIMessages is in ui.def)
; Force an object to update one or all of the notification lists that it
; talks to.
;
; Context:	Part of the UI controller API
; Source: 	Usually sent by a controller to its output
; Destination: 	Any object
; Interception: Objects that send notification for controllers should
;		respond to this
; Pass:		cx.dx - manufacturer ID, NotifyStandardNotificationTypes to
;		update or 0xffff.0xffff to update all or 0xffff.0xfffe to
;		generate the standard notifications
; Return: 	nothing (ax, cx, dx, bp destroyed)
;

; genC.def

MSG_META_GEN_PATH_RESTORE_DISK_PROMPT			method MetaUIMessages
;
; Prompts the user to insert a particular disk into a particular drive when
; restoring a disk handle for an object's path.
;
; Context:	sent by the callback passed to DiskRestore when a disk handle
;		saved in an object's path is being restored after a shutdown.
; Source:	one of the utility routines given below.
; Destination:	object possessing a path
; Interception:	may be intercepted if the object has more information to provide
;		the user than just the drive and disk name, or if it doesn't
;		wish to prompt the user. If it is intercepted, it should not
;		call the superclass.
;
; Pass:		ss:bp	= GenPathDiskRestoreArgs
; 		dx	= size GenPathDiskRestoreArgs
; Return:	carry set if message handled:
;			ax	= error code to return to DiskRestore (usually
;			  	  DRE_USER_CANCELED_RESTORE if user canceled, or
;			  	  DRE_DISK_IN_DRIVE if user claims the disk is
;				  there)
;		carry clear if message not handled
;		bp	= unchanged
;		cx, dx	= destroyed
; Notes:	the passed pointers are valid only so long as the handler
; 		doesn't cause the chunk with the object in it to shift. If
; 		they are needed after the chunk may have shifted, they should
; 		have the offset of the appropriate vardata that holds the
;		saved disk handle subtracted from them to find their offset
;		from the start of the buffer used by DiskSave/DiskRestore.
;		You can add that offset back into the new beginning of the
;		vardata after the chunk has shifted.
;

; gPageCC.def

MSG_META_PAGED_OBJECT_GOTO_PAGE				method MetaUIMessages
;
; Go to the given page
;
; Pass:
;	cx - page
;

MSG_META_PAGED_OBJECT_NEXT_PAGE				method MetaUIMessages
;
; Go to the next page
;
; Pass:
;	none
;

MSG_META_PAGED_OBJECT_PREVIOUS_PAGE			method MetaUIMessages
;
; Go to the previous page
;
; Pass:
;	none
;


MSG_META_NOTIFY_TASK_SELECTED				method MetaUIMessages

; uiInputC.def

MSG_META_GAINED_MOUSE_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_LOST_MOUSE_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_GAINED_KBD_EXCL				method MetaUIMessages
;
; This method is imported from the meta methods, so that ALL objects
; can receive it.  It is sent out when the kbd exclusive is given to an object.
; This is generally sent on through port windows to the application, to let
; it know that the port has the keyboard focus.
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_LOST_KBD_EXCL					method MetaUIMessages
;
; This method is imported from the meta methods, so that ALL objects
; can receive it.  
; It is sent out when the keyboard grab is taken away from the current
; owner, to the current owner to let them know they no longer have the
; keyboard grab.
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_GAINED_PRESSURE_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_LOST_PRESSURE_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_GAINED_DIRECTION_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_LOST_DIRECTION_EXCL				method MetaUIMessages
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_GRAB_FOCUS_EXCL				method MetaUIMessages
;
; May be passed to any visible or generic object to cause it to become
; the active focus within the focus level that is is in.
; The leaf object in the hierarchy which gains the focus exclusive will
; automatically be given the keyboard exclusive, & will thereby receive
; MSG_META_KBD_CHAR's that follow.
; 
; Commonly sent to text objects & other gadgets to switch which is the
; current focus. May also be passed to GenPrimarys, GenDisplays, independantly
; realizable GenInteractions, GenDisplayControl, GenViews, etc (windowed things)
; to cause them to become the active focus window within their level of the
; focus hierarchy, if possible (Specific UI's having real-estate focus, for
; instance, would ignore this request)
;
; NOTE that the object will not actually gain the focus exclusive until ALL
; other nodes above it in the hierarchy also have the focus excl within
; their levels.
; 
; This is the method equivalent of HINT_DEFAULT_FOCUS on generic objects.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_RELEASE_FOCUS_EXCL				method MetaUIMessages
;
; Opposite of MSG_META_GRAB_FOCUS_EXCL.  If the object does not currently
; have the exclusive, nothing will be done.
;
; Pass:         nothing
; Return:       nothing
;               ax, cx, dx, bp - destroyed
;

MSG_META_GET_FOCUS_EXCL					method MetaUIMessages
;
; May be sent to any visible or generic object which is a focus node,
; to get current focus object directly below the node, if any,
; regardless of whether current node is active (has the exclusive itself).
; WARNING:  This is a bad way to go about sending a message to currently
; active objects.  For example, if you call from the app thread to the UI
; thread to find out which is the current focus gadget, & then send a message
; to it, it is possible for the active gadget to change between the two
; calls.  Use MSG_META_SEND_CLASSED_EVENT for this type of operation if at
; all possible.
;
; Focus nodes in Generic UI library:	GenSystem
;					GenField
;					GenApplication
;					GenPrimary
;					GenDisplayControl
;					GenDisplay
;					GenView
;					GenInteraction (Indep. displayable only)
;					GenSummons
;
; Focus nodes in Visible UI library:	VisContent
;
; Pass:		nothing
; Return:	^lcx:dx	- focus object below this object
;		carry	- set to indicate message responded to (will be
;			  clear if message was sent to an object which is
;			  not a focus node)

MSG_META_GRAB_TARGET_EXCL				method MetaUIMessages
;
; May be passed to any visible or generic object to cause it to become
; the active target within the target level that is is in.  The active target
; hierarchy is the path for the transmission of messages via "TO_TARGET"
; request of MSG_META_SEND_CLASSED_EVENT.
; 
; Commonly sent to text objects & views to switch which is the current
; target. May also be passed to GenPrimarys, GenDisplays, independantly
; realizable GenInteractions, GenDisplayControl, GenViews, etc (windowed things)
; to cause them to become the active target window within their level of the
; target hierarchy.
; 
; The specific UI will automatically grab the Target exclusive for an object
; on any mouse press within the object if it is marked as "GA_TARGETABLE".
;
; NOTE that the object will not actually gain the target exclusive until ALL
; other nodes above it in the hierarchy also have the target excl within
; their levels.
; 
; This is the method equivalent of HINT_DEFAULT_TARGET
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_RELEASE_TARGET_EXCL				method MetaUIMessages
;
; Opposite of MSG_META_GRAB_TARGET_EXCL.  If the object does not currently
; have the exclusive, nothing will be done.
;
; Pass:         nothing
; Return:       nothing
;               ax, cx, dx, bp - destroyed
;

MSG_META_GET_TARGET_EXCL				method MetaUIMessages
;
; May be sent to any visible or generic object which is a target node,
; to get current target object directly below the node, if any,
; regardless of whether current node is active (has the exclusive itself).
; WARNING:  This is a bad way to go about sending a message to currently
; active objects.  For example, if you call from the app thread to the UI
; thread to find out which is the current target display, & then send a message
; to it, it is possible for the active display to change between the two
; calls.  Use MSG_META_SEND_CLASSED_EVENT for this type of operation if at
; all possible.
;
; Target nodes in Generic UI library:	GenSystem
;					GenField
;					GenApplication
;					GenPrimary
;					GenDisplayControl
;					GenDisplay
;					GenView
;					GenInteraction (Indep. displayable only)
;					GenSummons
;
; Target nodes in Visible UI library:	VisContent
;
;
; Pass:		nothing
; Return:	^lcx:dx	- target object below this object
;		carry	- set to indicate message responded to (will be
;			  clear if message was sent to an object which is
;			  not a target node)
;

MSG_META_GRAB_MODEL_EXCL				method MetaUIMessages
;
; May be passed to any visible or generic object to cause it to become
; the active model within the model level that is is in.  The active model
; hierarchy is the override path for the transmission of messages via
; "TO_MODEL" of MSG_META_SEND_CLASSED_EVENT.  (If no model hierarchy exists,
; the messages will be sent down the Target hierarchy)
; 
; NOTE that the object will not actually gain the model exclusive until ALL
; other nodes above it in the hierarchy also have the model excl within
; their levels.
; 
; This is the method equivalent of HINT_DEFAULT_MODEL
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_RELEASE_MODEL_EXCL				method MetaUIMessages
;
; Opposite of MSG_META_GRAB_MODEL_EXCL.  If the object does not currently
; have the exclusive, nothing will be done.
;
; Pass:         nothing
; Return:       nothing
;               ax, cx, dx, bp - destroyed
;

MSG_META_GET_MODEL_EXCL					method MetaUIMessages
;
; May be sent to any visible or generic object which is a model node,
; to get current model object directly below the node, if any,
; regardless of whether current node is active (has the exclusive itself).
; WARNING:  This is a bad way to go about sending a message to currently
; active objects.  For example, if you call from the app thread to the UI
; thread to find out which is the current model display, & then send a message
; to it, it is possible for the active display to change between the two
; calls.  Use MSG_META_SEND_CLASSED_EVENT for this type of operation if at
; all possible.
;
; Model nodes in Generic UI library:	GenSystem
;					GenApplication
;					GenUIDocumentControl
;					GenAppDocumentControl
;
; Pass:		nothing
; Return:	^lcx:dx	- model object below this object
;		carry	- set to indicate message responded to (will be
;			  clear if message was sent to an object which is
;			  not a model node)
;

MSG_META_RELEASE_FT_EXCL				method MetaUIMessages
;
; Releases Focus & Target for object at the same time.
;
; Pass:         nothing
; Return:       nothing
;               ax, cx, dx, bp - destroyed
;

MSG_META_MUP_ALTER_FTVMC_EXCL				method MetaUIMessages
;
; Allows an object to grab or release one or more of Focus, Target,
; or Model exclusives from the node that it is below.
; Internal message used to implement MSG_META_GRAB/RELEASE_FOCUS/etc._EXCL
; NOTE that this message is not deliverd to all visible objects, rather only
; those marked as VTF_WIN_GROUP or VTF_IS_INPUT_NODE. If you are implementing
; a new F/T/V/M/C node, & need this message, & are not a WinGroup, you will
; need to set the VTF_IS_INPUT_NODE bit in your init routine.
;
; Pass:		^lcx:dx	- object wishing to grab/release exlusive(s)
;		bp	- MetaAlterFTVMCExclFlags
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_GAINED_FOCUS_EXCL				method MetaUIMessages
MSG_META_LOST_FOCUS_EXCL				method MetaUIMessages
MSG_META_GAINED_SYS_FOCUS_EXCL			method MetaUIMessages
MSG_META_LOST_SYS_FOCUS_EXCL				method MetaUIMessages
.assert (MSG_META_GAINED_FOCUS_EXCL eq MSG_META_LOST_FOCUS_EXCL-1)


MSG_META_GAINED_TARGET_EXCL				method MetaUIMessages
MSG_META_LOST_TARGET_EXCL				method MetaUIMessages
MSG_META_GAINED_SYS_TARGET_EXCL			method MetaUIMessages
MSG_META_LOST_SYS_TARGET_EXCL			method MetaUIMessages
.assert (MSG_META_GAINED_TARGET_EXCL eq MSG_META_LOST_TARGET_EXCL-1)

MSG_META_GAINED_MODEL_EXCL				method MetaUIMessages
MSG_META_LOST_MODEL_EXCL				method MetaUIMessages
MSG_META_GAINED_SYS_MODEL_EXCL			method MetaUIMessages
MSG_META_LOST_SYS_MODEL_EXCL				method MetaUIMessages
.assert (MSG_META_GAINED_MODEL_EXCL eq MSG_META_LOST_MODEL_EXCL-1)

;
; These paired GAIN/LOSS messages for the Focus, Target, & Model
; hierarchies are sent, always in the order GAINED, then at some 
; point LOST, to objects on the hierarchy.  The GAINED_(APP) message is sent
; only when the object in question, AND all nodes in the hierarchy above
; that object, have gained the exclusive from the node above them, all the
; way up to the application object.  Just grabbing the exclusive from the
; next node up doesn't always guarantee you'll get a GAINED_(APP) message;  the
; node you're grabbing from must have itself received a GAINED_(APP) message but
; not yet the LOST_(APP) message.  Your object will receive the LOST_APP
; message if it has either released the exclusive, or the node from which
; you grabbed the exclusive itself received a LOST_(APP) message.  Now, if
; that weren't confusing enought, there is additionally the GAINED_SYS &
; LOST_SYS messages, which work just like the APP messages, but are more 
; restrictive in that you only gain the SYS_EXCL if your object & all nodes
; above it all the way to the system have the grab from the next node up.
; You will never receive GAINED_SYS_EXCL if you haven't already received the
; APP_EXCL, & you will always lose the SYS_EXCL before the APP_EXCL, if you
; have it.
;
; Context:	Part of the Focus/Target//Model hierarchy & mechanisms.
; Source:	Do NOT send these messages to objects yourself, unless you
;		are implementing or extending the above mechanism.
;		These messages should be sent only by the node object which 
;		is above the object receiving the message. 
;		They are normally generated in the MSG_META_GAINED_XXX_EXCL or
;		MSG_VIS_VUP_ALTER_FTVWC_EXCL handler for the node itself,
;		eminating from the call to FlowGainedExcl or
;		FlowAlterHierarchicalGrab, respectively
; Destination:	Any MetaClass object which has grabbed and not yet released
;		the focus exclusive
; Interception: Generic UI objects, VisTextClass, and all node objects
;		provide default behavior for processing this message.  The
;		messages may be intercepted, but this must done with care,
;		as there are critical code sections in which the hierarchy is
;		mid-transition, i.e. in what would normally be considered 
;		an illegal state.  These periods are from the start of a
;		GAINED method handler to the point where the superclass is
;		called, and from the point that the superclass is called to
;		the end of a LOST method handler.  (The reason for this is
;		simple:  Standard behavior is for the calling node to update
;		its instance data before sending a GAINED message, but
;		after calling a LOST message.)  Anything that may possible
;		result in a change request on the hierarchy involved may *not*
;		be performed during these critical code sections, or a fatal
;		error will result.  If in doubt, call the superclass at the
;		*start* of a GAINED method, & at the *end* of a LOST method
;		handler.  This will ensure that there is no section of code
;		in which hierarchy tampering is off-limits.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

;
; More input-related messages follow the 2 internal messages below.
;

;------------------------------------------------------------------------------
;	Redwood-specific GCN messages
;------------------------------------------------------------------------------

MSG_META_QUERY_SAVE_DOCUMENTS				method MetaUIMessages
; Private Message, currently used in Redwood only.
; This is sent out when a new document is started up.    If the old
; document has any open files, it will save them, with a dialog box for
; the user.
;
; Context:	Redwood only.
; Source:	Internally only.  Applications should not send this.
; Destination:	GenApplicationClass, GenDocumentControlClass, GenDocumentClass
; Interception:	Not generally intercepted.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
; 

MSG_META_BROADCAST_RETURNING_TO_WELCOME			method MetaUIMessages
; Private message, currently used in Redwood only.
; Broadcasts to all applications that we are returning to welcome.
;
; Context:	Redwood only.
; Source:	Internally only.  Applications should not send this.
; Destination:	GenApplicationClass
; Interception:	Applications can intercept this to do something special.  In
;		Redwood, GeoWrite uses this to bring itself to the front.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
; 
;------------------------------------------------------------



MSG_META_GAINED_DEFAULT_EXCL				method MetaUIMessages
;
; Sent out in response to this object receiving MSG_VIS_VUP_QUERY with
; SVQT_TAKE_DEFAULT_EXCLUSIVE, to notify a GenTrigger that it has gained
; the default exclusive.
;
; 	Pass:	- nothing
; 	Return:	- nothing
;

MSG_META_LOST_DEFAULT_EXCL				method MetaUIMessages
;
; Sent out in response to this object receiving MSG_VIS_VUP_QUERY with
; SVQT_RELEASE_DEFAULT_EXCLUSIVE, to notify a GenTrigger that it has lost
; the default exclusive.
;
; 	Pass:	- nothing
; 	Return:	- nothing
;
.assert (MSG_META_GAINED_DEFAULT_EXCL eq MSG_META_LOST_DEFAULT_EXCL-1)


MSG_META_MOUSE_BUMP_NOTIFICATION			method MetaUIMessages
;
;	MSG_META_MOUSE_BUMP_NOTIFICATION is an event that the IM places in
; the input queue to notify the UI that it has bumped the mouse position
; past this point in the queue.  This method is sent only when IMBumpMouse
; is called.
;
;	Pass:	cx	- x relative bump
;		dx	- y relative bump

MSG_META_FUP_KBD_CHAR					method MetaUIMessages
;
; When a leaf object in the FOCUS hierarchy gets a MSG_META_KBD_CHAR,
; and does not care about the character, it sends this method up the
; focus hierarchy to see if a parent object wants to handle it.
;
;	Pass:	SAME AS MSG_META_KBD_CHAR:
;		cx = character value
;		dl = CharFlags
;		dh = ShiftState
;		bp low = ToggleState
;		bp high = scan code
;	Return:	carry set if character was handled by someone (and should
;		not be used elsewhere).
;

MSG_META_PRE_PASSIVE_KBD_CHAR				method MetaUIMessages
MSG_META_POST_PASSIVE_KBD_CHAR				method MetaUIMessages
;
; Pass: 	SAME AS MSG_META_KBD_CHAR:
;		cx	- CharValue 	(See VC_ equates in keyboard.def)
;		dl	- CharFlags	(See CharFlags in keyboard.def)
;		dh 	- ShiftState	(See ShiftState in keyboard.def)
;		bp low 	- ToggleState	(See ToggleState in keyboard.def)
;		bp high - Raw PC Scan Code
;
;
; Return:
;		ax	- KbdReturnFlags (Defined below)
;			  mask KRF_PREVENT_PASS_THROUGH	- for PRE_PASSIVE,
;					blocks method from passing to grab.
;

MSG_META_QUERY_IF_PRESS_IS_INK				method MetaUIMessages
;
; Return whether or not a START_SELECT on this object should be passed on to
; the object, or whether it should be interecepted and turned into ink.
;
; Context: Part of the ink support mechanism.
;
; Source: Sent by any object (usually VisComp) to determine if one of its
;	  children wants ink.
;
; Destination: Any object in the Vis linkage that may be clicked on with the
;	       mouse.
;
; Interception: The default handler returns IRV_NO_INK. Objects that want
;		presses to be turned into ink need to return IRV_DESIRES_INK.
;		Some objects that need to do work on another thread (such as
;		a GenView) to determine whether the press should be ink or
;		not can return IRV_WAIT, which holds up the START_SELECT until
;		a MSG_GEN_APPLICATION_INK_QUERY_REPLY is sent to the application
;		object.
;
;		By default, clicks on VisComp-derived objects will *not* be
;		ink. To change this, set VisCompMakePressesInk as the message
;		handler for this method:
;
;			message VisCompMakePressesInk, MyVisCompClass,
;						MSG_META_QUERY_IF_PRESS_IS_INK
;
;
; Pass:		CX, DX - position of START_SELECT
;
; Return:	AX - InkReturnValue
;
;		if AX = IRV_DESIRES_INK or IRV_INK_WITH_STANDARD_OVERRIDE,
;				BP - handle of block with InkDestinationInfo
;					- or -
;				BP - 0
;

MSG_META_LARGE_QUERY_IF_PRESS_IS_INK			method MetaUIMessages
;
; Return whether or not a START_SELECT on this object should be passed on to
; the object, or whether it should be interecepted and turned into ink.
;
; Context: Part of the ink support mechanism.
;
; Source: Sent by any object (usually VisComp) to determine if one of its
;	  children wants ink.
;
; Destination: Any object in the Vis linkage that may be clicked on with the
;	       mouse.
;
; Interception: The default handler returns IRV_NO_INK. Objects that want ink
;		need to return IRV_DESIRES_INK. Some objects that need to do
;		work on another thread (such as the VisIsoContent) to determine
;		whether the press should be ink or not can return
;		IRV_WAIT, which holds up the START_SELECT until a
;		MSG_GEN_APPLICATION_INK_QUERY_REPLY is sent to the application
;		object.
;
; Pass:		dx - size of LargeMouseData
;  		ss:bp - ptr to LargeMouseData structure on the stack
;
; Return:	AX - InkReturnValue
;
;		if AX = IRV_DESIRES_INK or IRV_INK_WITH_STANDARD_OVERRIDE
;				BP - handle of block with InkDestinationInfo
;

;
;	Generic button events
;
; IMPORTANT NOTE:  Code in flow object & elsewhere depends on START/END pairs
; being sequential methods, as well as the order of SELECT, ADJUST, etc.
; in order, followed by the DRAG methods.  BE CAREFUL WHEN CHANGING!
;
; Specific ASSUMPTIONS which are currently made:
;
;	MSG_META_START_XXX +1 = MSG_META_END_XXX
;
;	MSG_XXXXXX + (MSG_XXX_PASSIVE_START_SELECT - MSG_META_START_SELECT)
;			= passive method #
;
;	MSG_META_START_XXX + (MSG_META_DRAG_SELECT - MSG_META_START_SELECT)
;			= DRAG method #
;
;
;MSG_META_PTR	- same data as below, but declared in Objects/inputC.def
MSG_META_START_SELECT					method MetaUIMessages
MSG_META_END_SELECT					method MetaUIMessages
MSG_META_START_MOVE_COPY				method MetaUIMessages
MSG_META_END_MOVE_COPY					method MetaUIMessages
MSG_META_START_FEATURES					method MetaUIMessages
MSG_META_END_FEATURES					method MetaUIMessages
MSG_META_START_OTHER					method MetaUIMessages
MSG_META_END_OTHER					method MetaUIMessages
MSG_META_DRAG_SELECT					method MetaUIMessages
MSG_META_DRAG_MOVE_COPY					method MetaUIMessages
MSG_META_DRAG_FEATURES					method MetaUIMessages
MSG_META_DRAG_OTHER					method MetaUIMessages
;
; The above methods are the standard button functions generated by the UI
; upon receiving MSG_META_MOUSE_BUTTON/MSG_META_MOUSE_PTR/
; MSG_META_MOUSE_DRAG events from the Input Manager.  These methods are sent
; out to whatever object has the implied grab (whichever window the mouse is
; over), until the mouse is "grabbed" by an object, after which the messages
; go there until the mouse is released (ungrabbed). See file Spec/User/
; button.doc for more details.
;
; Pass:
;		cx	- X position of mouse, in document coordinates of
;			  receiving object
;		dx	- X position of mouse, in document coordinates of
;			  receiving object
;
;		bp low  - ButtonInfo		(In input.def)
;			  mask BI_PRESS		- set if press
;			  mask BI_DOUBLE_PRESS	- set if double-press
;			  mask BI_B3_DOWN	- state of button 3
;			  mask BI_B2_DOWN	- state of button 2
;			  mask BI_B1_DOWN	- state of button 1
;			  mask BI_B0_DOWN	- state of button 0
;			  mask BI_BUTTON	- for non-PTR events, is
;						  physical button which has
;						  caused this event to be
;						  generated.
;
;		bp high - UIFunctionsActive	(In Objects/uiInputC.def)
;
; Return:
;		ax	- MouseReturnFlags	(In Objects/uiInputC.def)
; 			  mask MRF_PROCESSED - if event processed by gadget.
;					       See def. below.
;
; 			  mask MRF_REPLAY    - causes a replay of the button
;					       to the modified implied/active
;					       grab.   See def. below.
;
;			  mask MRF_SET_POINTER_IMAGE - sets the PIL_GADGET
;			  level cursor based on the value of cx:dx:
;			  cx:dx	- optr to PointerDef in sharable memory block,
;			  OR cx = 0, and dx = PtrImageValue (Internal/im.def)
;
;			  mask MRF_CLEAR_POINTER_IMAGE - Causes the PIL_GADGET
;						level cursor to be cleared
;

MSG_META_PRE_PASSIVE_BUTTON				method MetaUIMessages
MSG_META_POST_PASSIVE_BUTTON				method MetaUIMessages
;
;	MSG_META_PRE_PASSIVE_BUTTON and MSG_META_POST_PASSIVE_BUTTON pass the
; same parameters as MSG_META_BUTTON.  If the more detailed parameters
; are needed, use FlowTranslatePassiveButton.
;
; Pass:
;		cx	- X position of mouse, in document coordinates of
;			  receiving object
;		dx	- X position of mouse, in document coordinates of
;			  receiving object
;		bp low - ButtonInfo
;			  mask BI_PRESS		- set if press
;			  mask BI_DOUBLE_PRESS	- set if double-press
;			  mask BI_B3_DOWN	- state of button 3
;			  mask BI_B2_DOWN	- state of button 2
;			  mask BI_B1_DOWN	- state of button 1
;			  mask BI_B0_DOWN	- state of button 0
;			  mask BI_BUTTON	- for non-PTR events, is
;						  physical button which has
;						  caused this event to be
;						  generated.
;		bp high	- ShiftState
; 			  mask SS__LALT		- Set if left ALT modifier
; 			  mask SS__RALT		- Set if right ALT modifier
; 			  mask SS__LCTRL	- Set if left CTRL modifier
; 			  mask SS__RCTRL	- Set if right CTRL modifier
; 			  mask SS__LSHIFT	- Set if left SHIFT  modifier
; 			  mask SS__RSHIFT	- Set if right SHIFT modifier
; 			  mask SS__SYSREQ	- Set if SYSREQ modifier
;
; Return:
;		ax	- MouseReturnFlags	(In this file)
; 			  mask MRF_PROCESSED - if event process (mouse in
;					       gadget)   See def. below.
;
;			  mask MRF_PREVENT_PASS_THROUGH - for PRE_PASSIVE
;					       messages, allows blocking of
;					       message from being set to
;					       implied/active grab
; 			  mask MRF_REPLAY    - causes a replay of the button
;					       to the modified pre/post passive
;					       grab list. See def. below.
;

MSG_META_PRE_PASSIVE_START_SELECT			method MetaUIMessages
MSG_META_PRE_PASSIVE_END_SELECT				method MetaUIMessages
MSG_META_PRE_PASSIVE_START_MOVE_COPY			method MetaUIMessages
MSG_META_PRE_PASSIVE_END_MOVE_COPY			method MetaUIMessages
MSG_META_PRE_PASSIVE_START_FEATURES			method MetaUIMessages
MSG_META_PRE_PASSIVE_END_FEATURES			method MetaUIMessages
MSG_META_PRE_PASSIVE_START_OTHER			method MetaUIMessages
MSG_META_PRE_PASSIVE_END_OTHER				method MetaUIMessages
MSG_META_POST_PASSIVE_START_SELECT			method MetaUIMessages
MSG_META_POST_PASSIVE_END_SELECT			method MetaUIMessages
MSG_META_POST_PASSIVE_START_MOVE_COPY			method MetaUIMessages
MSG_META_POST_PASSIVE_END_MOVE_COPY			method MetaUIMessages
MSG_META_POST_PASSIVE_START_FEATURES			method MetaUIMessages
MSG_META_POST_PASSIVE_END_FEATURES			method MetaUIMessages
MSG_META_POST_PASSIVE_START_OTHER			method MetaUIMessages
MSG_META_POST_PASSIVE_END_OTHER				method MetaUIMessages
;
;	Passive button methods.  These are sent ONLY to objects which
; have requested a passive grab.  The "POST" methods go to those that have
; set up a "POST" passive grab, the "PRE" to the "PRE". 
; See file Spec/User/button.doc for more details.
;
; Pass:
;		cx	- X position of mouse, in document coordinates of
;			  receiving object
;		dx	- X position of mouse, in document coordinates of
;			  receiving object
;
;		bp low  - ButtonInfo		(In Include/mouse.def)
;			  mask BI_PRESS		- set if press
;			  mask BI_DOUBLE_PRESS	- set if double-press
;			  mask BI_B3_DOWN	- state of button 3
;			  mask BI_B2_DOWN	- state of button 2
;			  mask BI_B1_DOWN	- state of button 1
;			  mask BI_B0_DOWN	- state of button 0
;			  mask BI_BUTTON	- for non-PTR events, is
;						  physical button which has
;						  caused this event to be
;						  generated.
;
;		bp high - UIFunctionsActive	(In this file)
;
; Return:
;		ax	- MouseReturnFlags	(In this file)
; 			  mask MRF_PROCESSED - if event process (mouse in
;					       gadget)   See def. below.
;
;			  mask MRF_PREVENT_PASS_THROUGH - for PRE_PASSIVE
;					       messages, allows blocking of
;					       message from being set to
;					       implied/active grab
; 			  mask MRF_REPLAY    - causes a replay of the button
;					       to the modified implied/active
;					       grab.   See def. below.
;
;

MSG_META_LARGE_PTR					method MetaUIMessages
MSG_META_LARGE_START_SELECT				method MetaUIMessages
MSG_META_LARGE_END_SELECT				method MetaUIMessages
MSG_META_LARGE_START_MOVE_COPY				method MetaUIMessages
MSG_META_LARGE_END_MOVE_COPY				method MetaUIMessages
MSG_META_LARGE_START_FEATURES				method MetaUIMessages
MSG_META_LARGE_END_FEATURES				method MetaUIMessages
MSG_META_LARGE_START_OTHER				method MetaUIMessages
MSG_META_LARGE_END_OTHER				method MetaUIMessages
MSG_META_LARGE_DRAG_SELECT				method MetaUIMessages
MSG_META_LARGE_DRAG_MOVE_COPY				method MetaUIMessages
MSG_META_LARGE_DRAG_FEATURES				method MetaUIMessages
MSG_META_LARGE_DRAG_OTHER				method MetaUIMessages
;
; The above methods are the equivalent of the non "LARGE" methods, but
; pass higher resolution mouse data.  Note that there is no default
; visible object library behavior for passing these on down to children.
; Objects requesting these events will have to decide what behavior to
; implement on their reception.
;
; Pass:
;		dx	- size of LargeMouseData
;		ss:bp	- ptr to LargeMouseData structure on stack
;
; Return:
;		ax	- MouseReturnFlags	(In this file)
; 			  mask MRF_PROCESSED - if event processed by gadget.
;					       See def. below.
;
; 			  mask MRF_REPLAY    - causes a replay of the button
;					       to the modified implied/active
;					       grab.   See def. below.
;
;			  mask MRF_SET_POINTER_IMAGE - sets the PIL_GADGET
;			  level cursor based on the value of cx:dx:
;			  cx:dx	- optr to PointerDef in sharable memory block,
;			  OR cx = 0, and dx = PtrImageValue (Internal/im.def)
;
;			  mask MRF_CLEAR_POINTER_IMAGE - Causes the PIL_GADGET
;						level cursor to be cleared
;
;

MSG_META_ENSURE_MOUSE_NOT_ACTIVELY_TRESPASSING		method MetaUIMessages
;
;	Sent to the passive, active/implied mouse grab chain whenever
; modality status changes within the system -- any object receiving this
; message which has a window grabbed should make sure that it has a legitimate
; right to have the window grab active -- if not, it should be released
; (Along with the mouse).  In particular, menus in stay-up mode should
; come down, any interaction between the mouse & primary, display, menu,
; or view windows should be terminated.  You will find useful the message
; MSG_GEN_APPLICATION_TEST_WIN_INTERACTIBILITY, which will test any passed OD
; against the list of window(s) which the mouse is allowed to interact with
; (Generally, top most sytem modal window, else top most app modal window,
; else all windows), & return a flag indicating the result.
;
;	Pass:	Nothing
;	Return:	ax	- 0	(MouseReturnFlags, which aren't used, but
;				 permit us to use existing code to process
;				 this method)

MSG_META_ENSURE_NO_MENUS_IN_STAY_UP_MODE		method MetaUIMessages
;
;	Sent to the passive, active/implied mouse grab chain whenever we
; want to make sure all of an application's menus are closed. Sent directly
; to the Flow object from the global-shortcut code, and from the keyboard
; activation code in OLButtonClass. Any menus receiving this method which
; are in stay-up mode should dismiss themselves.   When cx is non-zero,
; can also be used to merely count the number of outstanding menus.
;
;	Pass:	cx:dx - zero if we're to release the menus;
;			else pointer to EnsureNoMenusInStayUpModeParams
;	Return:	ax	- 0	(MouseReturnFlags, which aren't used, but
;				 permit us to use existing code to process
;				 this method)
;		cx, dx, bp  - destroyed
;
EnsureNoMenusInStayUpModeParams	struc
	ENMISUMP_menuCount	word	;Number of menus released so far
EnsureNoMenusInStayUpModeParams	ends

MSG_META_ENSURE_ACTIVE_FT				method MetaUIMessages
;
; Checks to make sure that some object with the Focus/Target node to which
; this message may be sent has the Focus & Target exclusives.  Called from
; within the UI, usually when windowed objects below the node have
; closed, or moved to the back, to give the Focus and/or Target to the most
; suitable window.
; 
; Source:	Most always internally from the UI, though is unrestricted
; Destination:	Focus/Target node, specifically:
;		GenSystem, GenField, or GenApplication object
; Interception:	No reason to intercept.  Default behavior is provided by
;		above objects.  Could possibly be replaced, but as default
;		behavior various by specific UI, results could be 
;		unpredictable.
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_META_NOTIFY_NO_FOCUS_WITHIN_NODE			method MetaUIMessages
;
; Notification from Focus node MSG_META_ENSURE_ACTIVE_FT handler that it
; was unable to keep/find an object below it suitable for being the focus.
; The most likely cause is that the last focusable geode/object running
; below this point has been shut down/closed.
;
; Source:	Focus node, MSG_META_ENSURE_ACTIVE_FT handler
; Destination:	Self
; Interception:	Intercepted to find something safe to do for the user, such
;		as push this field/app to the back, or mark this object as
;		no longer "focusable" & call MSG_META_ENSURE_ACTIVE_FT on
;		the node above this one, in an attempt to find something for
;		the user to access.  If there's nothing left at all in the
;		system, the last focusable application has exited, so it's
;		time to shut down.
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed


;##############################################################################
;# To be moved the correct place later
;##############################################################################

MSG_META_DOC_OUTPUT_IMPORT_FILE				method	MetaUIMessages
;
;	Notification that the user has imported a file.
;
; Pass:
;	ss:bp - GenTranslationParams
; Return:
;	carry - set if error
;	ax, cx, dx, bp - destroyed
;

MSG_META_DOC_OUTPUT_EXPORT_FILE				method	MetaUIMessages
;
;	Export the current document
;
; Pass:
;	ss:bp - GenTranslationParams
; Return:
;	none
;

MSG_META_GRAB_KBD					method MetaUIMessages
; 
; This message can be used to grab the keyboard for an object.
; In assembly language, you can also call the library routine
; VisGrabKbd.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_META_FORCE_GRAB_KBD					method MetaUIMessages
; 
; This message can be used to forcefully grab the keyboard for an object,
; taking the grab away from another object that has it if necessary.
; MSG_META_RELEASE_KBD can be used to release the grab.
; In assembly language, you can also call the library routine
; VisForceGrabKbd.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_META_RELEASE_KBD					method	MetaUIMessages
; 
; This message can be used to release the keyboard grab for an object.
; In assembly language, you can also call the library routine
; VisReleaseKbd.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;


ViewCommandType	etype	word
	VCT_ZOOM_IN	enum ViewCommandType	;no other data
	VCT_ZOOM_OUT	enum ViewCommandType	;no other data
	VCT_SET_SCALE	enum ViewCommandType	;data is scale %

MSG_META_VIEW_COMMAND_CHANGE_SCALE	method MetaUIMessages
;
;	Command the GenViewController to change the scale factor in the
;	view or view(s) depending the controllers mode.
;
; Source:	Unrestricted
; Destination:	GenViewController via GWNT_VIEW_STATE_CHANGE
; Interception:	Unlikely

; Pass:		
;		cx - ViewCommandType
;		dx - data dependent on ViewCommandType
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;
;
;

MSG_META_FIELD_NOTIFY_DETACH				method	MetaUIMessages
;
; Notification from GenField that it has detached.
;
; Context:	GenField notification message.
; Source:	GenField
; Destination:	notificationDestination of GenField
; Interception:	Handle as desired.  Notification only, don't call superclass.
; 
; Pass:
;		^lcx:dx = GenField sending notification
;		bp = non-zero if detaching because of shutdown
;		   = zero if just field is detaching
; Return:
;		nothing
;

MSG_META_FIELD_NOTIFY_NO_FOCUS				method	MetaUIMessages
;
; Notification from GenField that it no longer has any focus apps.
;
; Context:	GenField notification message.
; Source:	GenField
; Destination:	notificationDestination of GenField
; Interception:	Handle as desired.  Notification only, don't call superclass.
; 
; Pass:
;		^lcx:dx = GenField sending notification
;		bp = non-zero if field has no focus because of shutdown
;		   = zero otherwise
; Return:
;		nothing
;

MSG_META_FIELD_NOTIFY_START_LAUNCHER_ERROR		method	MetaUIMessages
;
; Notification from GenField that an error occured while trying to run
; the launcher for this GenField.
;
; Context:	GenField notification message.
; Source:	GenField
; Destination:	notificationDestination of GenField
; Interception:	Handle as desired.  Notification only, don't call superclass.
; 
; Pass:
;		^lcx:dx = GenField sending notification
; Return:
;		nothing
;

MSG_META_DELETE_RANGE_OF_CHARS		method		MetaUIMessages
;
; Delete the passed range of characters
;
; Source: GenPenInputControl
; Destination: any focused object
; Interception: any object
; Pass: ss:bp - VisTextRange (range of chars to delete)
; Return: nothing
; Destroyed: ax, cx, dx, bp	
;

MSG_META_TEST_WIN_INTERACTIBILITY	method		MetaUIMessages
;
; Returns carry set if the mouse can interact with the passed window.
; This is to exclude input from non-modal windows, or to exclude input
; when the application ignoreInput.
; 
; Pass: 	^lcx:dx	- InputOD of an windowed object to check
;		^hbp	- Window to check
; Return: 	carry	- set if mouse is allowed to interact with window
;		  	  clear if mouse may NOT interact with window -- any
;			  active window grab or mouse grab should be terminated.
; 		ax, cx, dx, bp - destroyed

MSG_META_CHECK_IF_INTERACTABLE_OBJECT	method		MetaUIMessages
;
; This message is sent to objects on the GAGCNLT_ALWAYS_INTERACTABLE_WINDOWS
; GCN list. Handlers should check to see if this is a child object of the
; object (or another object that should get messages while UserDoDialogs are
; on screen, and if so, return carry set.
;
; Source: GenApplication object
; Destination: objects on the GAGCNLT_ALWAYS_INTERACTABLE_WINDOWS GCN list
; Interception: any object
; Pass: cx:dx - object to check if is interactable
; Return: carry set if interactable
; Destroyed: ax, cx, dx, bp
;

MSG_META_GAINED_FULL_SCREEN_EXCL			method MetaUIMessages
MSG_META_LOST_FULL_SCREEN_EXCL				method MetaUIMessages
.assert (MSG_META_GAINED_FULL_SCREEN_EXCL eq MSG_META_LOST_FULL_SCREEN_EXCL-1)

;
; Methods sent out to GenFields, GenApplication on gain/loss of the
; "Full screen" exclusive, meaning the object has become/is no longer the
; top screen-dominating object at its level.  Generally useful in
; transparent-mode operation for non-detachable apps to know when the
; user can no longer see the app's Primary window.
;
; 	Pass:	- nothing
; 	Return:	- nothing

;------------------------------------------------------------------------------
;	Misc equates
;------------------------------------------------------------------------------



COMMENT @----------------------------------------------------------------------

FUNCTION:	AllocNavID
		DefineNavID
		NavToID
		NavToNearID

DESCRIPTION:	This macros are used in application (or specific UI)
		.UI files to define and make use of ID numbers during
		navigation of a window. See the hint definitions in
		Gen/genClass.asm for more info.

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	Eric	2/90		initial version

------------------------------------------------------------------------------@

;this macro allocates a unique ID number for a UI object, taking into
;consideration if the object is part of a specific UI or an application.

AllocNavID	macro	name
ifdef _SpecificUI
	&name	enum	SpecUINavigationID
	if &name ge NAVIGATION_ID_APP_START
		ErrMessage <ERROR: too many specific UI Navigation IDs>
	endif
else
	&name	enum	AppNavigationID
	if &name ge NAVIGATION_ID_APP_END
		ErrMessage <ERROR: too many application Navigation IDs>
	endif
endif
endm

;this macro allocates a unique ID number for a UI object, and places
;it into a define-word directive. THIS SHOULD ONLY BE USED WITH A HINT DEF!

DefineNavID	macro	name
	;make sure this is in a .rdef file!
	AllocNavID	&name
	dw	&name
endm

;this macro performs error checking on ID values used for navigating between
;UI objects.

NavErrorCheckID	macro	idvalue
ifdef _SpecificUI
	if &name ge NAVIGATION_ID_APP_START
		ErrMessage <ERROR: UI object cannot specify navigation ID in application range.>
	endif
else
	if &name lt NAVIGATION_ID_APP_START
		PrintMessage <WARNING: Navigation ID &idvalue may be a UI object.>
	endif
	if &name ge NAVIGATION_ID_APP_END
		ErrMessage <ERROR: Navigation ID &idvalue is too large.>
	endif
endif
endm

;this macro is used as an argument to a HINT_NAVIGATION_NEXT_ID in a .UI file.
;It means "jump to this ID".

NavToID	macro	idvalue
	NavErrorCheckID	&idvalue
	dw	&idvalue
endm

;this macro is used as an argument to a HINT_NAVIGATION_NEXT_ID in a .UI file.
;It means "jump to object which has ID that is closest to this value and
;is greater than or equal to it."

NavToNearID	macro	idvalue
	NavErrorCheckID	&idvalue
	dw	&idvalue or NAVIGATION_ID_START_OF_RANGE
endm

;------------------------------------------------------------------------------
;       Utility routines (in User/userUtils.asm)
;------------------------------------------------------------------------------

global UserCallFlow:far			; Calls the flow object
global UserMessageIM:far		; Sends message to the IM object
global UserLoadApplication:far		; To launch a geode of type APPLICATION
global UserCheckAcceleratorChar:far 	; Check char to see if type shortcut
global UserCheckInsertableCtrlChar:far	; Check if keypad char needs conversion
global UserGetDisplayType:far		; Get system's DisplayType
global UserSetDefaultMonikerFont:far	; Set Font/size to use for UI monikers
global UserGetDefaultMonikerFont:far	; Get Font/size to use for UI monikers
global USERGETHWRLIBRARYHANDLE:far	; Get the handle of the HWR library
UserGetHWRLibraryHandle	equ	USERGETHWRLIBRARYHANDLE

global UserRegisterForTextContext:far	;
global UserUnregisterForTextContext:far	;
;	
;	Registers/unregisters the passed object to receive context data from
;	focused text objects.
;
;	Pass: cx:dx - object to get context info
;

global USERREGISTERFORTEXTCONTEXT:far	;
global USERUNREGISTERFORTEXTCONTEXT:far	;

global USERCHECKIFCONTEXTUPDATEDESIRED:far
UserCheckIfContextUpdateDesired	equ	USERCHECKIFCONTEXTUPDATEDESIRED
;
;	Returns ax non-zero if context updates are desired
;

global UserCreateInkDestinationInfo:far	; Create an InkDestinationInfo struct

global USERGETDEFAULTUILEVEL:far
UserGetDefaultUILevel		equ	USERGETDEFAULTUILEVEL
global USERGETDEFAULTLAUNCHLEVEL:far
UserGetDefaultLaunchLevel	equ	USERGETDEFAULTLAUNCHLEVEL
global USERGETINTERFACEOPTIONS:far
UserGetInterfaceOptions		equ	USERGETINTERFACEOPTIONS
global USERGETLAUNCHMODEL:far
UserGetLaunchModel		equ	USERGETLAUNCHMODEL
global USERGETLAUNCHOPTIONS:far
UserGetLaunchOptions		equ	USERGETLAUNCHOPTIONS

; Object utilities

global UserCallApplication:far
global UserSendToApplicationViaProcess:far       
global CheckForDamagedES:far	; See if ES is a valid object block
global ECCheckUILMemOD:far	; See if bx:si is a UI-run object
global ECCheckODCXDX:far	; See if cx:dx is valid OD
global ECCheckLMemODCXDX:far	; See if cx:dx is valid non-process OD
global ECCheckUILMemODCXDX:far	; See if cx:dx is valid UI-run object
       
; Misc

global UserLoadExtendedDriver:far		; FOR LIMITED USE
global UserGetOverstrikeMode:far
global UserSetOverstrikeMode:far

global UserGetKbdAcceleratorMode:far		; FOR SPUI USE

global UserAddAutoExec:far, UserRemoveAutoExec:far
global USERADDAUTOEXEC:far, USERREMOVEAUTOEXEC:far

; Combine icon and text moniker into a new combination moniker

global UserCreateIconTextMoniker:far

CreateIconTextMonikerFlags	record
    CITMF_POSITION_ICON_ABOVE_TEXT:1	; place icon above text
    CITMF_TEXT_IS_FPTR:1	; CITMP_textMoniker is fptr to text
    CITMF_CREATE_CHUNK:1	; create new moniker chunk in destination block
				;  else new moniker will replace iconMoniker
    CITMF_SWAP_ICON_TEXT:1	; swap icon text locations
    :12
CreateIconTextMonikerFlags	end

CreateIconTextMonikerParams	struct
    CITMP_flags		CreateIconTextMonikerFlags	<>
    CITMP_spacing	word	; spacing between icon and text
    CITMP_destination	hptr	; destination block for new moniker if
				;  CITMF_CREATE_CHUNK is set
    CITMP_iconMoniker	optr	; source icon moniker (is also destination if
				;  CITMF_CREATE_CHUNK is not set)
    CITMP_textMoniker	dword	; source text moniker (optr or fptr)
CreateIconTextMonikerParams	ends


; From userScreen.asm

global UserScreenRegister:far	; to register a new screen in system.

; Standard interface to the sound driver

global UserStandardSound:far
global _UserStandardSound:far
global UserStopStandardSound:far
global USERSTOPSTANDARDSOUND:far

;
; NOTE: If you add values to StandardSoundType, you should add a flag to
; the StandardSoundFlag record below.
;

StandardSoundType	etype	word
	SST_ERROR	enum	StandardSoundType
	; Sound produced when an Error box comes up.

	SST_WARNING	enum	StandardSoundType
	; General warning beep sound

	SST_NOTIFY	enum	StandardSoundType
	; General notify beep

	SST_NO_INPUT	enum	StandardSoundType
	; Sound produced when the users keystrokes/mouse presses are not going
	; anywhere (if he clicks off a modal dialog box, or clicks on the 
	; field or something)

	SST_KEY_CLICK	enum	StandardSoundType
	; Sound produced when the keyboard is pressed, or when the
	; user clicks on a floating keyboard

	SST_ALARM	enum	StandardSoundType
	; A standard alarm sound.  (ask Palm...)

	SST_NO_HELP	enum	StandardSoundType
	; Sound produced when no help is available.

	SST_CUSTOM_SOUND	equ	0xfffd
	; Allows applications to play a custom sound handle and does all
	; the checking for sound being off, etc.  This is not a part of the
	; enumerated type to simplify error checking later.

	SST_CUSTOM_BUFFER	equ	0xfffe	
	; Allows applications to play a custom sound buffer and does all the
	; checking for sound being off, etc. This is not a part of the
	; enumerated type to simplify error checking later.

		; NOTE:  When using SST_CUSTOM_BUFFER in systems where the
		; sound library has a protocol number of 4.0 or earlier, it
		; is necessary for the calling thread to worry about 
		; synchronisation issues.  The calling thread must allocate 
		; a semaphre via ThreadAllocSem, and add sound events at the 
		; end of the buffers being played via SST_CUSTOM_BUFFER that 
		; V() this semaphore.  In the CLOSE_APPLICATION handler for 
		; the app, the app must P() this semaphore the same number 
		; of times it used SST_CUSTOM_BUFFER.  This will ensure that 
		; the app does not exit until all buffers played by 
		; SST_CUSTOM_BUFFER are completed.  Failure to do so 
		; introduces a race condition which can cause the system to 
		; crash.  You have been warned.
		;
		; If your app depends upon having sound library v4.1 or
		; newer, this is no longer a consideration.
		;				-- todd 12/29/93

	SST_CUSTOM_NOTE		equ	0xffff
	; Allows applications to play a custom note and does all the checking
	; for sound being off, etc. This is not a part of the enumerated type
	; to simplify error checking later.

	;
	; Default settings for sounds are as follows:
	;	TEMPO = 8 msec per 128th note (~ 240 beats a second)
	;	PRIORITY = SYSTEM_IMMEDIATE
	;

SST_IGNORE_SOUND_OFF	equ	0x8000
;
; if SST_????? is OR'd with SST_IGNORE_SOUND_OFF, the sound will be
; played regardless of [ui]sound or soundMask. Note that this doesn't
; work with SST_CUSTOM_???
;
; This feature supported in 3.0 or later.
;

;
; StandardSoundFlags
;
;   These flags are used in the [ui]:soundMask = <integer> INI key
; to turn individual StandardSoundTypes on and off.
; A StandardSoundType will be played by UserStandardSound if the
; corresponding bit is set in the soundMask key.  Note that the
; SST_CUSTOM_xxx "standard" sounds are not supported by this
; mechanism.
;

StandardSoundFlags	record

	:10
	SSF_ALARM:1
	SSF_KEY_CLICK:1
	SSF_NO_INPUT:1
	SSF_NOTIFY:1
	SSF_WARNING:1
	SSF_ERROR:1

StandardSoundFlags	end

SOUND_MASK_ALL		equ	0xffff


; Misc

				; Get required SPUI protocol number
global UserGetSpecUIProtocolRequirement:far
global UserGetInitFileCategory:far

;------------------------------------------------------------------------------
;       Utility routines (in User/userMain.asm)
;------------------------------------------------------------------------------

global UserAllocObjBlock:far
global UserCopyChunkOut:far
global UserHaveProcessCopyChunkIn:far
global UserHaveProcessCopyChunkOut:far
global UserHaveProcessCopyChunkOver:far

global UserCreateListEntry:far
global UserAddEntryToList:far
global UserCreateItem:far
global UserAddItemToGroup:far

global UserStoreDocFileName:far

global UserDiskRestore:far
;	Desc:	Front-end for DiskRestore to actually prompt the user for
;		the disk, if it's not present.
;	Pass:	ds:si	= data saved by DiskSave
;	Return:	carry set if couldn't restore disk handle:
;			ax	= DiskRestoreError
;		carry clear if disk properly restored
;			ax	= disk handle

global USERDISKRESTORE:far

ContinueLibrary	ui		; All remaining files are for the UI itself

include	iacp.def

PASSWORD_ENCRYPTED_SIZE = 8
if DBCS_PCGEOS
MAX_PASSWORD_SOURCE_LENGTH = 32
MAX_PASSWORD_SOURCE_SIZE = 32*(size wchar)
else
MAX_PASSWORD_SOURCE_LENGTH = 32
MAX_PASSWORD_SOURCE_SIZE = 32
endif

global UserEncryptPassword:far
global USERENCRYPTPASSWORD:far

global USERGETSYSTEMSHUTDOWNSTATUS:far
UserGetSystemShutdownStatus	equ	USERGETSYSTEMSHUTDOWNSTATUS

;
;	In Gen/genApplication.asm
;
global UserGetFloatingKbdEnabledStatus:far
global UserGetKeyboardDisplayStatus:far

;------------------------------------------------------------------------------
;       Field change confirmation routine and types (User/userUtility.asm)
;------------------------------------------------------------------------------

ConfirmFieldChangeType	etype	word

CFCT_BEGIN_FIELD_CHANGE		enum ConfirmFieldChangeType
; Call UserConfirmFieldChange with this type to kick off the field change
; process.  A response will be sent indicating whether the field change
; should proceed or not.
;
; Pass:		ax = CFCT_BEGIN_FIELD_CHANGE
;		dx:cx = optr to send response message to when all
;			replies are complete
;		bx    = msg to send to optr in dx:cx
;
; Return:	carry:	set: if someone else is already requesting a 
;				field change or parm err.  NO MSG WILL
;				BE SENT.
;			clear: if every is OK.  Msg will be sent when
;				all responses are in.
;
; Reply message has the following parameters:
;		cx	= TRUE to go ahead with field change
;			  FALSE to abort field change.
;

CFCT_CONFIRM_START		enum ConfirmFieldChangeType
; All who receive the GWNT_CONFIRM_FIELD_CHANGE notification are required
; to call UserConfirmFieldChange with CFCT_CONFIRM_START.  Once this is
; done, the receiver is free to pop up a dialog to query the user if this
; is what s/he wants to do.  Exclusivity is granted to the caller of
; CONFIRM_START so that the user doesn't see 5 dialogs all at once.
; Once the caller knows whether to allow or deny the field change,
; CONFIRM_COMPLETE MUST be called.
;	
; Note that if carry is set when this is called, someone else has already
; denied the field change so NOTHING SHOULD BE DONE BY THE RECEIVER in this
; case (CONFIRM_COMPLETE should not be called either).
;
; Pass:		nothing
; Return:	carry:	clear: caller has the exclusive right to query
;				the user for confirmation.  It is required
;				that the caller call CONFIRM_COMPLETE
;				when this is done.
;			set:   Change has already been aborted, forget
;				the notification ever happened.
; Side effects:	May block waiting for others to confirm.
;

CFCT_CONFIRM_COMPLETE		enum ConfirmFieldChangeType
; All who receive notification and called CONFIRM_START and got a carry
; clear return value MUST call this function.  Callers can thus indicate
; whether to allow or deny the field change at this point.
;
; Pass:		cx	= TRUE: allow the field change.
;			  FALSE: deny the field change.
;
; Return:	nothing

global UserConfirmFieldChange:far
;
; Description:	Used to initiate notification of a field change and to
;		respond positively or negatively to that change.  Since
;		all apps are detached when a field change occurs, those
;		on the GSNSLT_FIELD_CHANGE_NOTIFICATIONS gcn list can
;		chose to abort the field change if they desire.
;
; Pass:		ax	= ConfirmFieldChangeType
;		other regs depend on type in ax.  See details above.
;
; Return:	depends on change type passed in ax.
;
; Destroyed:	Nothing 

;------------------------------------------------------------------------------
;       Input Flow
;------------------------------------------------------------------------------

ContinueLibrary	ui

include Objects/uiInputC.def

;------------------------------------------------------------------------------
;	Visible Classes
;------------------------------------------------------------------------------

include	Objects/visC.def
include	Objects/vCompC.def
include	Objects/vCntC.def
include Internal/vUtils.def		; For SPUI assembly optimization only

;------------------------------------------------------------------------------
;	GenClass itself
;------------------------------------------------------------------------------

include Objects/genC.def

;------------------------------------------------------------------------------
;       Utility routines split out into seperate .def files
;------------------------------------------------------------------------------

include uDialog.def
include token.def

;------------------------------------------------------------------------------
;       Clipboard control
;------------------------------------------------------------------------------

include Objects/clipbrd.def

;------------------------------------------------------------------------------
;	All other Generic Classes
;------------------------------------------------------------------------------

;include Objects/genC.def
include Objects/gSysC.def
include Objects/gProcC.def
include Objects/gFieldC.def
include Objects/gScreenC.def
include Objects/gFSelC.def
include Objects/gViewC.def
include Objects/gContC.def
include Objects/gInterC.def
include Objects/gCtrlC.def
include Objects/gDocC.def
include Objects/gDocCtrl.def
include Objects/gDocGrpC.def
include Objects/gEditCC.def
include Objects/gViewCC.def
include Objects/gToolCC.def
include Objects/gPageCC.def
include Objects/gPenICC.def
include Objects/gGlyphC.def
include Objects/gTrigC.def
include Objects/gBoolGC.def
include Objects/gItemGC.def
include Objects/gDListC.def
include Objects/gItemC.def
include Objects/gBoolC.def
include Objects/gDispC.def
include Objects/gDCtrlC.def
include Objects/gPrimC.def
include Objects/gAppC.def
include Objects/gTextC.def
include Objects/gGadgetC.def
include Objects/gValueC.def
include Objects/gToolGC.def
include Internal/gUtils.def		; For SPUI assembly optimization only

include Objects/helpCC.def

include	Objects/eMenuC.def		; Express menu class

include Objects/emomC.def		; EMObjectManager class

include Objects/emTrigC.def		; EMTrigger Class
;------------------------------------------------------------------------------
;	Internal UI classes
;------------------------------------------------------------------------------

include Internal/uProcC.def		; UI's own process class

;##############################################################################
;# To be moved the correct place later
;##############################################################################


EndLibrary	ui
