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

	Copyright (c) GeoWorks 1991 -- All Rights Reserved

PROJECT:	PC GEOS
MODULE:		Include/Objects
FILE:		visC.def

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	Chris	7/91		Initial version

DESCRIPTION:
	Object definitions for VisClass.   

	$Id: visC.def,v 1.1 97/04/04 14:18:11 newdeal Exp $

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

SetDef __VISC

StartLibrary	ui
include win.def

VisEmptyClass	class	MetaClass, master
VisEmptyClass   endc

;------

VisClass	class	MetaClass, master

global VisInitialize:far
global VisObjectHandlesInkReply:far
	uses	GenClass		; Need this hear so that SpecBuild
					; routines can access generic 
					; instance data.

	uses	VisCompClass		; Needed so we can test IS_COMPOSITE
					; flag & then operate on Vis comp

	
;------------------------------------------------------------------------------
; VisClass Messages
;------------------------------------------------------------------------------


;
; Export MESSAGE space so that the Specific UI can add  messages
; to VisClass
;
VisSpecMessages	export DEFAULT_EXPORTED_MESSAGES

;
; Export MESSAGE space so that the Application can add messages to VisClass
;
VisAppMessages	export DEFAULT_EXPORTED_MESSAGES



;------------------------------------------------------------------------------
;	Drawing
;------------------------------------------------------------------------------

MSG_VIS_DRAW				message
;
;	MSG_VIS_DRAW is called to make an object draw itself.  A gstate is
; passed, which contains the handle of the window being drawn to.  This gstate
; should be passed in di to any graphics drawing routines called.  This message
; may be received as a result of a MSG_META_EXPOSED event going to the object's
; win-group, which in turns sends MSG_VIS_DRAW to all of its descendants, or
; the object can create its own gstate and sent a MSG_VIS_DRAW to itself to
; get itself redrawn if it wants to change its appearance.
;
; Context:	Sent through a visible tree as a result of a MSG_META_EXPOSED
;		on the win group object in the tree.  
; Source:	The object's visible parent (unless it is the win group
;		group itself, in which case it is sent to itself by its own
;		MSG_META_EXPOSED handler).
; Destination:  Any VisClass object
; Interception: All non-composite objects will want to intercept this if they
;		wish to draw anything.  Composite objects will want to 
;		intercept this if they need to draw anything besides their
;		visual children.  It shouldn't matter whether a composite draws
;		its special stuff before or after calling its superclass to 
;		draw its children.  Composites should NOT draw within the bounds
;		of its children.
;
; Pass:
;	cl	- DrawFlags:  DF_EXPOSED set if GState is set to update window
;	^hbp	- GState to draw through.
;		  This will be in the default state except for:
;
;			pen position, colors -- undefined
;
;		  Specific UI & GenGadget objects only:
;			font, size -- set to default for UI
;			private data -- set to DisplayScheme to use
;
;		  Non-UI objects:
;			font, size -- set to system default
;
;			
; Return:
;	GState	- The graphics state must be returned unchanged except for:
;			pen position, colors -- can be destroyed
;	ax, cx, dx, bp - destroyed
;
;
; DrawFlags - not stored in instance data, but passed in cl in MSG_VIS_DRAW
;
DrawFlags	record	
    DF_EXPOSED:1			;set if draw is the result of a MSG_META_EXPOSED
				;being processed, & therefore we are inbetween
				;calls made to the window system of
				;GrBeginUpdate & GrEndUpdate.
    ;
    ; This next bit is used for different stuff in different places. Please
    ; document all uses here.
    ;		Thanks.
    ;
    DF_OBJECT_SPECIFIC:1
    ; <<Scrolling list object>>
    ; Set if a composite which controls the drawing of its own children
    ; (such as the OLScrollingList) should NOT draw its children, i.e. just
    ; the composite itself.
    ;
    ; <<Text object>>
    ; This bit is also used by the text object to get it to draw all its
    ; lines, not just the ones which aren't masked out. This is used by
    ; 'draw' to get rotated text up on the screen.
    ;
    DF_PRINT:1			;set if draw is a result of a
				;MSG_META_EXPOSED_FOR_PRINT.  If this bit is set
				;then DF_EXPOSED will be set also
    DF_DONT_DRAW_CHILDREN:1	;set if composites should not be drawing their
    				;children
    DF_DISPLAY_TYPE DisplayClass:4	;set to DisplayClass (NOT DisplayType)
DrawFlags	end
		
;
;
; Writing a MSG_VIS_DRAW:
;
; Your object's instance data should be set up so that you know both the
; current drawn state of the object & the desired state.
;
;	If updating (DF_EXPOSED is set), then draw the
; entire object based on the desired state.  Even thought the window system
; will fill in the background color, you SHOULD NOT assume this, as this
; background filling can sometimes happen under a different thread at the
; same time as the object may be drawing itself, leaving a partially drawn
; image instead of a bacground fill.  In general, you should ALWAYS redo the
; background wash when drawing an DF_EXPOSED, unless your draw message can
; tolerate the existance of a partial image of the object already on the 
; screen (If you use XOR draw mode, then your message is NOT tolerant).  To
; be safe, just redraw the background.
;
; 	If you are not updating (DF_EXPOSED is not set)
; it is presumably because the desired state is different than the drawn state,
; and someone has send you a MSG_VIS_DRAW so that you will update the visual
; image to be correct.  In this case, you may be able to take shortcuts to
; get the correct image on the screen, since your "drawn" state will tell
; you what it currently looks like.  For instance, in a simple button which
; just inverts when pressed, you might be able to simply invert the rectangle,
; instead of redrawing the whole thing.
;
; < see also Spec/User/visual.doc >
;

MSG_VIS_REDRAW_ENTIRE_OBJECT		message	
;
; Redraws an object entirely, creating a temporary gstate and sending a 
; MSG_VIS_DRAW to itself.  Will not do anything if the object is currently
; not drawable.
;
; Context:	Usually called as a result of a state change in an object,
;		rather than during the update mechanism.
; Source:	any VisClass object, usually sent to itself
; Destination:  any VisClass object, usually sent to itself
; Interception: generally not intercepted.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
;
	
MSG_VIS_VUP_CREATE_GSTATE		message
;
; MSG_VIS_VUP_CREATE_GSTATE travels up the visible tree until it hits a
; WIN GROUP.  The message at that point will create a graphics state
; for the window associated with the view.  If no window exists,
; a GState will be created anyway, without a window association.
;
; Specific UI's often choose to subclass this message in their composite
; objects, in order to change the default GState settings, & to store a 
; DisplayScheme in the private data area of the GState.
;
; This message may also be subclassed by large (32-bit) composites & layers,
; in order to apply a 32-bit translation offset to the GState before returning
; it to the calling child object.
;
; In the case that the visible object is free-floating, i.e. neither a
; WIN_GROUP nor specific UI composite handler can be found for this message,
; then the default VisClass handler will create a GState without a window
; association.
;
; Context:	Usually done when drawing is needed at a time other than
;		the update mechanism, where a gstate needs to be created in
;		order to draw.
; Source:	Any VisClass object
; Destination:  A VisClass object that answers the query (nearly all VisComp
;		objects can answer)
; Interception: One might have an object intercept this in order to set up
;		a certain initial graphics state after creating the gstate.
;		Or, less likely, create a gstate using a window other than the
;		window the object currently resides.
;
; Pass:		nothing
; Returns:	carry	- set indicating message handler found.  Since the
;			  visible object library itself provides a default
;			  handler, this will always be the case, unless 
;			  the object has been subclassed, & that subclass
;			  provides a handler which returns carry clear.
;
; 		^hbp 	- GState, which references window that
;			  object is realized under, if any, otherwise
;			  references a NULL window.  Note that in all cases
;		 	  a GState is created, & therefore will have to be
;			  destroyed by the caller (Using GrDestroyState).
;		ax,cx,dx- destroyed
;
;		  The GState will be in the default state except for:
;
;		     All objects:
;			pen position, colors -- undefined
;
;		     Objects in a 32-bit visible tree:
;			transformation matrix -- offset in 32-bit space by
;						 large composites/layer objects
;						 above this object.
;
;		     Non-Specific UI objects:
;			font, size -- set to system default
;
;		     Specific UI objects only:
;			font, size -- set to default for UI
;			private data -- set to DisplayScheme to use
;			lineEndJoin -- set to SQUARECAPS, which simplifies
;				the drawing of UI objects.
;			NOTE:  This data will not get set in the case of
;			       a non-composite visible object without a
;			       visible parent.
;


;-------------------------------------------------
;	MSG_VIS_VUP_QUERY
;-------------------------------------------------

MSG_VIS_VUP_QUERY		message
;	MSG_VIS_VUP_QUERY is used to query up the visible composite tree.
; Other MSG_VIS_VUP_QUERY* messages do this same action, but are
; only available within the generic UI itself.  MSG_VIS_VUP_QUERY is
; extensible, in that the specific UI may add new types of data to be queried
; for.  Anybody who subclasses this message MUST call their superclass if they
; don't handle the query so the default Vis handler can pass the message 
; upwards and return nulls if the message is not answered.
;
;	*** WARNING ***
;	This message is a low level message primarily used within the UI.
;	Applications should use MSG_VIS_VUP_CALL_OBJECT_OF_CLASS.  Various
;	handlers for this message use ThreadBorrowStack space, so data cannot
;	be passed or returned on the stack.
;
; Context:	Getting various information by looking up the visible tree
; Source:	Any VisClass object
; Destination:  Any VisClass object that answers the query
; Interception: Any VisClass object may want to intercept a certain query
;		specially, for various reasons.  It would be unusual for
;		current query types (VUQ_DISPLAY_SCHEME, VUQ_VIDEO_DRIVER).
;
; Pass:
;	cx	- VisUpwardQueryType, or SpecVisUpwardQueryType,
; Returns:
;	carry	- set if query has been responded to
;	ax, cx, dx, bp	- response data (depends on query type)
;			  or null if query not responded to.
;

VisUpwardQueryType 	etype word

SPEC_VIS_QUERY_START	equ	2000	; offset to first specific UI query type
APP_VIS_QUERY_START	equ	4000	; offset to first app UI query type

VUQ_DISPLAY_SCHEME 	enum VisUpwardQueryType
;
; Context:	May be used when drawing part of a visible tree
; Source:	Any VisClass object
; Destination:  Typically handled by the field object
; Interception: It would be unusual to intercept this, as long as there is
;		a single video mode per field.
;
; Pass:	cx	- VUQ_DISPLAY_SCHEME
; Return:
;	carry	- set if VUP message found routine to process request
;	ax, cx, dx, bp - display scheme
;

VUQ_VIDEO_DRIVER 	enum VisUpwardQueryType
;
; Used to fetch the handle of the video driver which is in
; use for this location in the visible tree.
;
; Context:	Might be used when drawing part of a visible tree
; Source:	Any VisClass object
; Destination:  Typically handled by the field object
; Interception: It would be unusual to intercept this, as long as there is
;		a single video mode per field.
;
; Pass:	cx	- VUQ_VIDEO_DRIVER
; Return:
;	carry	- set if VUP message found routine to process request
;	ax	- handle of video driver
;	cx, dx, bp - destroyed
;

MSG_VIS_VUP_FIND_OBJECT_OF_CLASS			message
;
;	Searches up the visible tree, looking for an object belonging to the
; specified class.
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  Any VisClass object belonging to the class passed.
; Interception: An object would only intercept this if it was trying to 
;		masquerade as another object, a dubious idea to be sure.
;
; Pass:		cx:dx	- class of object we're looking for
; Return:	^lcx:dx	- object, if found, else returns null
;		carry	- set if found, clear if no object of class found.
;		ax, bp	- destroyed


;-------------------------------------------
;	Messages dealing with ClassedEvents
;-------------------------------------------


;MSG_META_SEND_CLASSED_EVENT	message	MetaUIMessages
;
; This method is defined in MetaClass, & augmented by any class that wishes
; to do so, by the addition of new TravelOption types.  MetaClass provides
; TO_NULL & TO_SELF.
;
; VisClass extends TargeObject options to include a way to send a method
; up the visible tree to an object of a certain class.
;
; Pass:		^hcx	- ClassedEvent
;		dx	- TravelOption
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

TO_VIS_PARENT			enum TravelOption, first VisMessages
; Object is first visible parent of the class specified.



MSG_VIS_VUP_CALL_OBJECT_OF_CLASS		message
;
; Call up the visual tree until an object of the class specified in the event
; is found, & call it with the event passed.
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The first object found of the class specified
; Interception: Any object trying to intercept certain messages to another
;		class of object might want to wait and take certain messages
;		itself.
;
; Pass:		^hcx	- ClassedEvent
; Return:	carry, ax, cx, dx, bp - return values from call
;
;Sample Code/Programming Tips
;----------------------------
; The following example code, if passed a visual object in ^lbx:si,
; will get the size of the field that the object resides in (of course, this
; code assumes that the GenField currently has a visual counterpart, which you
; you can only count on for a GenField object.)
;
; GetFieldSize	proc	near
;	push	bx
;	push	si
;	mov	ax, MSG_VIS_GET_SIZE
;				; Deliver to GenField
;	mov	bx, segment GenFieldClass
;	mov	si, offset GenFieldClass
;	mov	di, mask MF_RECORD 
;	call	ObjMessage
;	mov	cx, di		; Get handle to ClassedEvent in cx
;	pop	si		; Get object below primary to be iconified
;	pop	bx
;	clr	di
;	mov	ax, MSG_VIS_VUP_CALL_OBJECT_OF_CLASS
;	call	ObjMessage
;	ret
;	
; GetFieldSize	endp



MSG_VIS_VUP_SEND_TO_OBJECT_OF_CLASS		message
;
; Sends event up the visual tree until an object of the class
; specified in the event is found, at which point the event is
; delivered to that object.  (Like MSG_VIS_VUP_CALL_OBJECT_OF_CLASS,
; but sends instead of calls, meaning no return parameters)
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The first object found of the class specified
; Interception: Any object trying to intercept certain messages to another
;		class of object might want to wait and take certain messages
;		itself.
;
; Pass:		^hcx	- ClassedEvent
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_VUP_TEST_FOR_OBJECT_OF_CLASS		message
;
; Probes up the visual tree to see if an object of the specified
; class exists.  Useful if there is question as to whether a 
; MSG_VIS_VUP_CALL/SEND_OBJECT_OF_CLASS can be handled.
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The first object found of the class specified
; Interception: Any object trying to intercept certain messages to another
;		class of object might want return a positive result here.
;
; Pass:		cx:dx - class 
; Return:	carry set if object of class found
;		carry clear if object of class not found
;		ax, cx, dx, bp - destroyed
;
			
MSG_VIS_VUP_CALL_WIN_GROUP		message
;
; Call up the visual tree until a win group is found, & call it with the event 
; passed.
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The win group object
; Interception: Any object trying to intercept certain messages to the win group
;		might want to wait and take certain messages itself.
;
; Pass:		^hcx	- ClassedEvent 
; Return:	carry, ax, cx, dx, bp - return values from call
;
;Sample Code/Programming Tips
;----------------------------
; The following example code, if passed a visual object in ^lbx:si,
; will get the size of the win group that the object resides in:
;
; IconifyPrimaryThatObjectIsIn	proc	near
;	push	bx
;	push	si
;	mov	ax, MSG_VIS_GET_SIZE
;	mov	bx, segment VisClass	;set to the base class that can handle 
;	mov	si, offset VisClass	;  the message in ax
;	mov	di, mask MF_RECORD 
;	call	ObjMessage
;	mov	cx, di		; Get handle to ClassedEvent in cx
;	pop	si		; Get object 
;	pop	bx
;	clr	di
;	mov	ax, MSG_VIS_VUP_CALL_WIN_GROUP
;	call	ObjMessage
;	ret
;	
; IconifyPrimaryThatObjectIsIn	endp



MSG_VIS_VUP_SEND_TO_WIN_GROUP		message
;
; Sends event up the visual tree until a win group vis object
; is found, at which point the event is delivered to that object.  (Like MSG_
; VIS_VUP_CALL_WIN_GROUP, but sends instead of calls, meaning no return 
; parameters)
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The win group object
; Interception: Any object trying to intercept certain messages to the win group
;		might want to wait and take certain messages itself.
;
; Pass:		^hcx	- ClassedEvent
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

;-------------------------------------------------
;	Setting/getting attributes
;-------------------------------------------------

MSG_VIS_SET_ATTRS			message
;
;	MSG_VIS_SET_ATTRS may be called change the visible attributes of
; a vis object.
;
; VA_VISIBLE
; ----------
;	Only visible trees topped by a visible object marked as a WIN_GROUP
; may be brought on-screen or off screen (known as realizing, unrealizing).
; To realize, or make visual, a WIN_GROUP, the VA_VISIBLE bit must be
; set, & then a visual update must be performed on the branch.  To bring
; a visible tree off screen, the VA_VISIBLE bit is cleared, & the tree
; is visually updated. Both may be done with the MSG_VIS_SET_ATTRS.  Please
; note that this assumes a visual tree, which has been attached to the visual
; object that it is to appear in/under.
;
;	Visible branches may contain nested WIN_GROUP's, but realizing
; one WIN_GROUP will not realize any below it.  All lower WIN_GROUP
; must be unrealized before those above it may be unrealized.  CONTENT
; objects are considered, & must be marked as, WIN_GROUP's.
;
; NOTE TO SPECIFIC UI & GenGadget Users:
;
;	The flag VA_VISIBLE is now reserved for the VISIBLE world & should
; not be used directly by Specific UI code.  Instead,  you should
; manipulate the bits GS_USABLE, SA_ATTACHED, & SA_REALIZABLE via the
; messages MSG_GEN_SET_USABLE, MSG_GEN_SET_NOT_USABLE, & 
; MSG_SPEC_SET_ATTRS.
;
; VA_MANAGED
; ----------
;	Set if this object is included in its parent's geometry manager 
; calculations.  Any composite RecalcSize handler should position children 
; that have this bit set.  Sizing and positioning of the object must be done 
; to this object manually.   MSG_VIS_UPDATE_GEOMETRY will be sent to any object 
; that is marked invalid, whether this bit is set or not.
;
; VA_DRAWABLE
; -----------
;	Any visible object which is not marked as VA_DRAWABLE will not
; appear visually - basically, it will not receive MSG_VIS_DRAW's, at least
; not from the routine VisCompDraw.  Other routines which send MSG_VIS_DRAW's
; should be careful not to send the message if this bit is not set.  This
; flag DOES NOT affect geometry, which may still reserve visual space for
; the object.
;
; VA_DETECTABLE
; -------------
;	If this bit is set, all button-related events will be sent to the
; object.
;
; VA_FULLY_ENABLED
; ----------------
;	If this bit is clear, the object is considered disabled, and various
; things like mouse events, drawing, etc. will be handled differently by the
; object.  This bit is set or cleared during vis builds of generic objects,
;
; < see also Spec/User/visual.doc >
;
; Usage
; -----
; 
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:	cl	- VisAttrs bits to be set
;	ch	- VisAttrs bits to be cleared
;
;	Bits that may be changed are:
;
;	VA_VISIBLE		- set if should be visible, if parent
;				  is.
;	VA_MANAGED		- set if geometrically managed
;	VA_DRAWABLE		- set if drawable (invisible)
;	VA_DETECTABLE		- set if hit detectable w/mouse
;	VA_FULLY_ENABLED	- set if enabled
;
;	dl 	- VisUpdateMode	   (how update, if any should be done)
;
; Return:	nothing
;		cx, dx, bp - preserved
;		ax - destroyed
;

MSG_VIS_SET_GEO_ATTRS			message
;
; Sets non-composite geometry attributes for a visual object.  Changing
; VGA_DONT_CENTER or VGA_HAS_SIZE_HINTS requires the object's geometry
; to be invalidated.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		cl -- VisGeoAttrs to set
;		ch -- VisGeoAttrs to clear
;		dl -- VisUpdateMode
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
  
MSG_VIS_GET_GEO_ATTRS			message
;
; Returns the current non-composite geometry attibutes.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	cl -- VisGeoAttrs
;		ax, ch, dx, bp -- destroyed
;
	
MSG_VIS_GET_OPT_FLAGS			message
;
; Returns current invalid flags for this object.  
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	cl -- VisOptFlags
;		ax, ch, dx, bp -- destroyed
;
	
MSG_VIS_SET_TYPE_FLAGS			message
; 
; Sets type flags for an object.  An object MUST not be realized when it
; receives this message.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		cl -- VisTypeFlags to set
;		ch -- VisTypeFlags to clear
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
  
MSG_VIS_GET_TYPE_FLAGS			message
;
; Returns current type flags for this object.
;
; Pass:		nothing
; Return:	cl -- VisTypeFlags
;		ax, ch, dx, bp -- destroyed
;
  
MSG_VIS_GET_ATTRS			message					
;
; Returns visible attributes for an object.
; 
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	cl -- VisAttrs
;		ax, ch, dx, bp -- destroyed
;

	
	
;-------------------------------------------------
;		Geometry messages
;-------------------------------------------------

MSG_VIS_GET_POSITION				message
;
; Returns the current position of an object.
; 
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	cx -- left edge of object
; 		dx -- top edge of object
;		ax, bp -- destroyed
;
	
MSG_VIS_SET_POSITION				message
;
;	MSG_VIS_SET_POSITION moves an object to a new location.  It is just 
; a move, only changes the instance data.  The geometry manager calls 
; MSG_VIS_POSITION_BRANCH when positioning objects; objects should subclass 
; off of this message when they want their child to do something special.
;
; Context:	Visual tree utility, often called by a composite's MSG_VIS_
;		POSITION_BRANCH handler.
; Source:	Unrestricted, often the visual parent of the destination,
;		acting as part of the geometry manager.
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;	cx -- left edge
;	dx -- top edge
;
; Return:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_GET_BOUNDS			message
;
;	MSG_VIS_GET_BOUNDS returns the current bounds of an object.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;	Nothing
;
; Returns:
;	ax -- left
;	bp -- top
;	cx -- right
;	dx -- bottom
;

MSG_VIS_GET_SIZE				message
;
;	MSG_VIS_GET_SIZE returns the current size of an object.  This should
; never be subclassed.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;	Nothing
; Returns:
;	cx -- current width
;	dx -- current height
;	ax, bp -- destroyed
;
	
MSG_VIS_SET_SIZE				message
;
; MSG_VIS_SET_SIZE stores a new size in the object's bounds.  Usually only
; called directly by the geometry manager, or possibly by an object
; to initially size itself.
;
; Context:	Visual tree utility, often called by a composite's MSG_VIS_
;		RECALC_SIZE handler.
; Source:	Unrestricted, often the visual parent of the destination,
;		acting as part of the geometry manager.
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;	cx -- new width
;	dx -- new height
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_GET_CENTER			message
;
;	MSG_VIS_GET_CENTER returns the center of an object.  It returns four 
;	values giving minimum amounts needed before and after the center.
;	These minimum values don't have to add up to the overall size of the
;	object.  This allows objects like buttons to "expand to fit" and 
; 	still return useful information about how much space it really needs
;	in terms of centering.
;
; Context:	Used in geometry calculations, usually by a composite's
;		MSG_VIS_RECALC_SIZE or MSG_VIS_POSITION_BRANCH handler.
; Source:	Usually the parent, working as part of the geometry manager.
; Destination:  Any VisClass object, usually a visual child of the caller.
; Interception: An object may want to signify a different place as the center
;		of the object rather than the true center, to affect the
;		geometrical layout of the objects.  For instance, the motif
;		specific UI uses this to center a bunch of horizontal
;		composites so that the right edges of their monikers line up
;		as they are placed vertically.  The object will then replace
;		the default behavior with its own.
;
; Pass:	
;	Nothing
;
; Returns: 
;	cx -- minimum space needed to the left of center
;	dx -- minimum space needed to the right of center
;	ax -- minimum space needed above center
;	bp -- minimum space needed below center
;

MSG_VIS_RECALC_SIZE			message
;
; MSG_VIS_RECALC_SIZE is called by the geometry manager to get an
; object to choose a size for itself.  Composites are expected to do the 
; same for their children and set their children's bounds before returning.
; The geometry manager passes suggestions for the object to use in determining 
; its size.
;
; Context:	Used in geometry calculations, usually by a composite's 
;		MSG_VIS_RECALC_SIZE handler.
; Source:	Usually the visual parent, working as part of the geometry
;		manager.
; Destination:  Any VisClass object, usually a visual child of the caller.
; Interception: The default behavior for a non-composite object is to just
;		return its current size, regardless of the suggested size.
;		An object that wants to have a size based on the suggestions
;		will want to replace this method and return the size it wants 
;		to be. Composite objects may also want to handle this method if
;		it plans to lay out its children a certain way that the geometry
;		manager doesn't handle.  (Composites can also muck with the
;		suggested values *before* calling the superclass to do 
;		superclass stuff.)
;
; Pass:	   cx -- RecalcSizeArgs -- suggested width for object
;	   dx -- RecalcSizeArgs -- suggested height
; Return:  cx -- width to use
;	   dx -- height to use
;	   ax, bp -- destroyed
;
	
RecalcSizeArgs		record
	RSA_CHOOSE_OWN_SIZE:1
			;Geometry manager wants object to choose its own size,
			;typically objects will use current size if any, or 
			;choose an initial size, if coming up for the first 
			;time.
	RSA_SUGGESTED_SIZE:15
			;Suggested size to use, if above bit is not set.
RecalcSizeArgs		end


MSG_VIS_POSITION_BRANCH				message
;
; MSG_VIS_POSITION_BRANCH positions all the objects under the current
; object.  This is the message that is called by the geometry manager, and is 
; the message that should be subclassed by objects that want to do their own 
; child object positioning or do something else based on the move.
;
; Context:	Used in geometry calculations, usually by a composite's
;		MSG_VIS_POSITION_BRANCH handler.
; Source:	Usually the visual parent, working as part of the geometry
;		manager.
; Destination:  Any VisClass object, usually the child of the caller.
; Interception: Any composite object that wants to position its children a
;		special way once all the sizes have been calculated will
;		want to replace the default handler.  Non-composites rarely 
;		will want to subclass this message.
;
; Pass:
;	cx -- left edge
;	dx -- top edge
;
; Return:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

			
MSG_VIS_NOTIFY_GEOMETRY_VALID		message
;
; If VGF_NOTIFY_GEOMETRY_VALID flag is set, sent out to an object when
; all of its geometry messages are completed and its geometry has been made
; valid.
;
; Context:	Used in geometry calculations, usually by a composite's
;		MSG_VIS_POSITION_BRANCH handler after all its children
;		have been positioned.
; Source:	Usually the visual parent, working as part of the geometry
;		manager.
; Destination:  Any VisClass object, usually a child of the caller.
; Interception: There is no default behavior for this message. Any object that 
;		needs to do some calculations once its geometry
;		has been made valid will want to handle this message.  It
;		must set VGA_NOTIFY_GEOMETRY_VALID in order to receive the
;		message at all, however.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed


MSG_VIS_BOUNDS_CHANGED			message
;
; Sent out by the geometry manager when an object's visible bounds have
; changed as a result of a geometry update.  The object should respond to
; this method by invalidating any parts of its old bounds and new bounds
; that it might have drawn in (the default action is to invalidate the passed 
; bounds).
; 
; Context:	Sent when an object's bounds have changed
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		ss:bp -- Rectangle: the old bounds (or zeroes if no old bounds
;  			 to invalidate)
;		dx    -- size Rectangle
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
	
MSG_VIS_RESET_TO_INITIAL_SIZE	message
;
; Sent to an object, and propagated every child under that object.  Clears 
; VGA_GEOMETRY_CALCULATED flag in the object, and sets its geometry invalid, 
; then starts an update at the top level.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		dl -- VisUpdateMode
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_VIS_RECALC_SIZE_AND_INVAL_IF_NEEDED		message
;
; This message is an optimized version of MSG_VIS_RECALC_SIZE which should be
; used by composite objects on their children when calculating their size.
; It checks various optimization flags to see whether a MSG_VIS_RECALC_SIZE
; is needed, and calls it if necessary.  It then clears the VOF_GEOMETRY_
; INVALID flag for the object, and if the object's bounds change, sets the
; object's and it's parents image invalid so it will redraw.  In assembly
; language, use the library routine VisRecalcSizeAndInvalIfNeeded instead.  See the
; geometry manager docs for more info on setting up geometry handlers for
; your composite.  Will also save the old bounds in temporary data, if not
; already done.
;
; Context:	Used in geometry calculations, usually by a composite's
;		MSG_VIS_RECALC_SIZE handler.
; Source:	Any VisClass object
; Destination:  Any VisClass object, usually a child of the caller.
; Interception: Unlikely
;
; Pass:		cx, dx -- RecalcSizeArgs: suggested width and height
; Return:	cx, dx -- width and height returned by the object
;		ax, bp -- destroyed
;	

MSG_VIS_POSITION_AND_INVAL_IF_NEEDED		message
;
; This message is an optimized version of MSG_VIS_POSITION_BRANCH, which
; checks various optimization flags to see whether a MSG_VIS_POSITION_BRANCH
; is needed, and calls it if necessary.  It then will set the object and
; its parent's image invalid if it has changed position, so they will be
; redrawn correctly.   In assembly language use the library routine VisSend-
; Position instead.  See the geometry docs for more info on setting up geometry
; handlers for your composite.  Will also save the old bounds in temporary
; data, if not already done, and after positioning, will check to see if
; the object's bounds moved and will invalidate the object`s old and new
; bounds if so.
;
; Context:	Used in geometry calculations, usually by a composite's
;		MSG_VIS_POSITION_BRANCH handler.
; Source:	Unrestricted
; Destination:  Any VisClass object, usually a child of the caller.
; Interception: Unlikely
;
; Pass:		cx, dx -- new position
; Return:	carry set if bounds have changed from old bounds
;		ax, bp -- destroyed
;
	
;-------------------------------------------------
;		Update mechanism messages
;-------------------------------------------------

MSG_VIS_MARK_INVALID			message
;
;	MSG_VIS_MARK_INVALID allows setting of an object's invalid flags
; so that it can be updated correctly later. The object is marked as being
; invalid, & the routine ensures that a path is marked from this object
; up to the window group, showing that when a MSG_VIS_VUP_UPDATE_WIN_GROUP
; is done, it may trace a path back to this object & get it updated.
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.
;
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Not allowed!
;
; Pass:		cl -- flags:  VOF_GEOMETRY_INVALID (causes geometry update)
;		      	      VOF_WINDOW_INVALID   (causes window move/resize)
;		              VOF_IMAGE_INVALID    (causes region invalidate)
;
;		dl 	- VisUpdateMode	   (how update, if any should be done)
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;


MSG_VIS_VUP_UPDATE_WIN_GROUP		message
;
;	High level routine for requesting a visual update.
;  MSG_VIS_VUP_UPDATE_WIN_GROUP travels up the Visible tree until it finds
; the head object which is marked as being a WIN_GROUP.  This window is marked
; for update, & a MSG_VIS_UPDATE_WIN_GROUP is sent to it, via the UI process
; queue.
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.
;
; Context:	Visual tree utility, often called by VisMarkInvalid to
;		begin a visual update.
; Source:	Unrestricted
; Destination:  The win group object that the source object is in.
; Interception: Not allowed!
;
; Pass:		dl - VisUpdateMode
; Returns:	carry	- set if VUP message found routine to process request
;		ax, cx, dx, bp - destroyed
;


;
; VisUpdateMode - Used for specifying when a visual update should happen:
;
VisUpdateMode 			etype byte
		
VUM_MANUAL 		    	enum VisUpdateMode   	;don't update. 
VUM_NOW 		    	enum VisUpdateMode	;update NOW.
VUM_DELAYED_VIA_UI_QUEUE    	enum VisUpdateMode	;delayed until UI
							; queue empty
VUM_DELAYED_VIA_APP_QUEUE   	enum VisUpdateMode	;delayed until APP
							; queue empty
			    
			    
MSG_VIS_UPDATE_WIN_GROUP		message
;
; MSG_VIS_UPDATE_WIN_GROUP performs actual update of a window group.
; This message should not be sent by anyone other than the message handler
; for MSG_VIS_VUP_UPDATE_WIN_GROUP, which sends this event via the UI process
; queue, to delay the actual work until this message comes in.
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.
;
; Context:	Part of the visual update mechanism.
; Source:	VisCompClass handler for MSG_VIS_VUP_UPDATE_WIN_GROUP,
;		which will send this message to itself when queue delays
;		are requested.
; Destination:  A win group object (sent by itself).
; Interception: Not allowed!
;
; Pass: 	dl 	- VisUpdateMode
; Return:	nothing
;	        ax, cx, dx, bp -- destroyed


MSG_VIS_UPDATE_GEOMETRY			message
;
; MSG_VIS_UPDATE_GEOMETRY is called by MSG_VIS_UPDATE_WIN_GROUP to 
; calculate any geometry that is currently invalid.
;
; Context:	Part of the visual update mechanism.
; Source:	Unrestricted, usually the visual parent of the destination; or
;		if the destination is a win group, by its own MSG_VIS_UPDATE_-
;		WIN_GROUP handler.
; Destination:  Any VisClass object.
; Interception: Can be subclassed if certain assumptions about the geometry
;		of things is known.  For instance, the MSG_VIS_UPDATE_GEOMETRY
;		handler cause geometry to happen on the current object.  If
;		the object changes size, a MSG_VIS_UPDATE_GEOMETRY will be
;		sent to the object's parent on the assumption that the parent's
;		geometry also needs to be redone.  If it is known that the
;		parent's geometry won't change, an optimization could possibly
;		be made.  A thorough understanding of the geometry update 
;		mechanism is recommended, though.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_UPDATE_WINDOWS_AND_IMAGE		message
;
;	Called by VisCompUpdateWinGroup to update invalid windows in an
; already realized branch.  Follows both VOF_WINDOW_UPDATE_PATH bits
; and VOF_IMAGE_UPDATE_PATH bits to update windows which need WinResizing, 
; and objects whose bounds need to be invalidated.  Typically needed after
; geometry changes.
;
; 	This message is also called by VUP_UPDATE_WIN_GROUP to update any
; areas whose image is out of date.  This currently works by invalidating
; the top-most composite needing invalidation.
;
; Idea for future improvement:  This might work by following the
; IMAGE_UPDATE_PATH bits, looking for an image invalid;  Once one is found,
; a MSG_VIS_DRAW will be invoked to update the image, passing
; DF_UPDATING_IMAGES.  The MSG_VIS_DRAW will clear all invalid bits found
; in it's path & invoke a new MSG_VIS_UPDATE_WINDOWS_AND_IMAGE should it
; encounter a window'ed composite in the path which is marked with
; an IMAGE_UPDATE_PATH bit.
;
; Won't travel across WIN_GROUP boundaries.
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.
;
; Context:	Part of the visual update mechanism.
; Source:	Unrestricted, usually the visual parent of the destination; or
;		if the destination is a win group, by its own MSG_VIS_UPDATE_-
;		WIN_GROUP handler.
; Destination:  Any VisClass object
; Interception: Not allowed!
;
; Pass:	cl 	- VisUpdateImageFlags
;		   Method callers should always clear this flag on
;		   entry.
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

VisUpdateImageFlags	record
	VUIF_ALREADY_INVALIDATED:1
			 ;  Set if we no longer need to invalidate things, 
			 ;  until we hit a window at some point.  If a VisComp
			 ;  object's image is invalidated, it will sometimes
			 ;  set this flag before broadcasting the message to
			 ;  its children so they'll know not to invalidate
			 ;  themselves.
	VUIF_SEND_TO_ALL_CHILDREN:1
			 ;  Set if we need to send the invalidation message to
			 ;  all children, regardless of what the path bit is.
			 ;  This is for cases where a composite object is 
			 ;  invalid, but only invalidates its margins to 
			 ;  minimize invalidation, and then only children whose
			 ;  geometry is invalid will be invalidated further.
	VUIF_JUST_OPENED:1
			 ;  Internal flag indicating that the object being
			 ;  updated has just been VIS_OPENED.  Usually in this
			 ;  case the object's image has been marked invalid
			 ;  so the area of the object will be redrawn.  Since
			 ;  we know that all the children have to be redrawn
			 ;  as well, the update mechanism will use this flag
			 ;  to completely redraw the object, rather than check
			 ;  all the children for image invalid flags, which are
			 ;  cleared in their MSG_VIS_OPEN anyway.
	:5
VisUpdateImageFlags	end
			
MSG_VIS_INVALIDATE			message
;
; MSG_VIS_INVALIDATE invalidates the entire bounding region of the object
; the message is passed to.  This will cause the window system to generate a
; MSG_META_EXPOSED, which will be sent to the object owning the window.  Only
; works for visual objects in a non-scaled window with normal (non-extended)
; coordinates.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: May want to subclass to work with scaled windows or extended
;		coordinates.
;
; Pass:		Nothing
; Returns:	Nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_VIS_ADD_RECT_TO_UPDATE_REGION	message
;
; Sent out by an object when it has some area to invalidate.  The win group
; object (or portal that keeps children in another window) will make sure that 
; this area is invalidated, either immediately or during the image update.
; 
; Context:	Sent out by an object when it needs to invalidate its bounds.
; Source:	Unrestricted
; Destination:  Any VisClass object, usually the source
; Interception: It can be assumed to be the object's bounds.  A composite
;		object may wish to optimize the area invalidated if only
;		draws in certain parts of its rectangle by messing with the
;		passed bounds and calling the superclass.
;
; Pass:		ss:bp -- VisAddRectParams
;		dx    -- size VisAddRectParams
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

VisAddRectFlags	record
	VARF_NOT_IF_ALREADY_INVALID:1
	; Don't invalidate the rectangle if any node going up to the win
	; group has its image or window marked invalid.
	
	VARF_ONLY_REDRAW_MARGINS:1
	; This flag indicates that the object is invalidating old bounds,
	; and can optimize invalidation if desired by splitting the message
	; into four, one for each margin, in some cases.
	
	VARF_UPDATE_WILL_HAPPEN:1
	; The caller knows of an impending update, so adding the rect to the
	; update region rather than invalidating is a reasonable (and fast)
	; thing to do.
	:5
VisAddRectFlags	end
		
VisAddRectParams	struct
	VARP_bounds	Rectangle	;rect to invalidate
	VARP_flags	VisAddRectFlags
	VARP_unused	byte		;word align
VisAddRectParams	ends
		
MSG_VIS_INVAL_TREE			message
;
; Invalidates the entire bounding region of the object the message is passed,
; to, including any child window areas.  This causes the window system to
; generate a MSG_META_EXPOSED for all windows effected.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;	Nothing
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;


;-------------------------------------------------
	
;-------------------------------------------------
;		Open/Close messages
;-------------------------------------------------

MSG_VIS_OPEN				message
;
;
;	Generated by VisCompUpdateWinGroup to get a visible tree realized
; if the SA_REALIZABLE bit is set & it is not yet realized.
; Opens graphics windows, recurses down to bottom visual objects
; to let them know they are becoming realized.  Does NOT cross over WIN_GROUP
; boundaries.
;
; Context:	Part of the visual update mechanism, usually called by the 
;		object's MSG_VIS_UPDATE_WINDOWS_AND_IMAGE handler.
; Source:	Unrestricted, usually the same as the destination
; Destination:  Any VisClass object
; Interception: Often subclassed by objects to do some prep work before the
;		object becomes visible on the screen.  Be sure to call the
;		object's superclass at some point in the handler.
; Pass:
;	bp	- 0 if top window, else window for object to open on
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed

MSG_VIS_CLOSE			message
;
;	Generated by VisCompUpdateWinGroup to get a visible tree unrealized
; if the SA_REALIZABLE bit is clear & it is currently realized.
; Closes graphics windows, recurses down to bottom visual objects
; to let them know they are being visually closed.  Does NOT cross over to
; WIN_GROUP boundaries, but should fatal error if it finds a lower WIN_GROUP
; which is realized (illegal state)
;
; Context:	Part of the visual update mechanism.
; Source:	Unrestricted, usually the visual parent of the destination; or
;		if the destination is a win group, by its own MSG_VIS_UPDATE_-
;		WIN_GROUP handler.
; Destination:  Any VisClass object
; Interception: Sometimes subclassed by objects to do some stuff as the object
;		is being taken down off the screen.  Be sure to call the
;		object's superclass at some point in the handler.
; Pass:
;	Nothing
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_DESTROY				message
;
; High level routine for VISIBLE-only object branch.
; Closes, removes & destroys a visible branch.  If realized, branch is
; VIS_CLOSEd before being removed from visible tree.  After being removed 
; from the visible tree, the branch is destroyed, by first sending MSG_DESTROY
; to each child, & then sending MSG_META_OBJ_FREE to the object itself.  Old
; parent is marked as invalid (geometry & image), & it is visually updated
; using VisUpdateMode passed.
;
; NOTE:  Does *not* mark parent object dirty.  If this is necessary, use
; ObjMarkDirty(obj) or MSG_META_SET_FLAGS(objChunk, mask OCF_DIRTY, 0) to do so.
;
; Context:	Visual tree utility
; Source:	Unrestricted, often the visual parent of the destination,
;		as part of MSG_VIS_DESTROYs being propagated throughout
;		the branch being destroyed.
; Destination:  Any VisClass object
; Interception: Default behavior can be replaced to subvert the invalidation of
;		the geometry and image in the parent object (done in the MSG_-
;		VIS_REMOVE handler, called by MSG_VIS_DESTROY), but it is not 
;		easily done.
;
; Pass: 	dl	- VisUpdateMode
; Return:	Nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_VIS_REMOVE				message
;
; High level routine for VISIBLE-only object branch.
; Closes & removes visible branch from tree.  If realized, branch is
; VIS_CLOSEd before being removed from visible tree.  Old parent is marked
; as invalid (geometry & image), & is visually updated using VisUpdateMode
; passed.  This message is static, & should not be subclassed.
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.  (It maps to the library routine VisRemove)
;
; NOTE:  Does *not* mark parent nor child object dirty.  If either is necessary,
; use ObjMarkDirty(obj) or MSG_META_SET_FLAGS(objChunk, mask OCF_DIRTY, 0)
; to do so.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Not allowed!
;
; Pass:		dl	- VisUpdateMode
; Return:	Nothing
;		ax, cx, dx, bp -- destroyed
;



MSG_VIS_QUERY_WINDOW			message
;
; Returns current window this object is in.  
;
; Context:	Visual tree utility
; Source:	Any VisClass object
; Destination:  The first VisClass object that responds to this query
; Interception: Unlikely
;
; Pass:		nothing
; Return:	^hcx -- window
;		ax, dx, bp -- destroyed
;

MSG_VIS_OPEN_WIN				message
;
;	MSG_VIS_OPEN_WIN is sent to a object marked as VTF_IS_WINDOW or
; VTF_IS_PORTAL to create a graphics window.  The window should normally be
; created the size of the vis bounds.   A handler for this message should be
; sure to set VCI_window to the opened window if the children are expected to
; appear inside that window.  
;
; Context:	Part of the visual update mechanism, usually called by
;		an object's MSG_VIS_OPEN handler.
; Source:	Any VisClass object
; Destination:  Any VisClass object, usually same as the source
; Interception: Unrestricted with VTF_IS_WINDOW will intercept this in order
;		to open the window associated with the visual object.  There
;		is no default behavior for this, since various parameters
;		will differ from window to window (background color, 
;		inputOD, etc.).  The window's handle must set VCI_window to the
;		opened window if the visual object and its children are
;		expected to appear inside that window.
;
; Pass:
;	^hbp	- parent window 
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_CLOSE_WIN			message
;
;	MSG_VIS_CLOSE_WIN is sent to a object marked as VTF_IS_WINDOW or
; VTF_IS_PORTAL to destroy the active graphics window.
;
; Context:	Part of the visual update mechanism, usually called by
;		an object's MSG_VIS_CLOSE handler.
; Source:	Any VisClass object
; Destination:  Any VisClass object, usually the same as the source
; Interception: An object may want to replace or augment the default handler 
;		if something besides calling WinClose on the window
;		in VCI_window is necessary.
;
; Pass:
;	Nothing
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_WIN_ABOUT_TO_BE_CLOSED		message
;
; Notification that the window stored in VI_gWin of this windowed composite
; object is about to be closed.  A default handler will move it off-screen
; if it has children, to prevent unecessary window reg calculations & screen
; flickering.  (Provided so that VisContent can intercept & prevent this
; behavior, as it intercepts & prevents MSG_WIN_CLOSE, for the same reason -
; it doesn't actually own the window; the GenView does.)
;
; Context:	Part of the visual update mechanism, usually called by
;		an object's MSG_VIS_CLOSE handler.
; Source:	Any VisClass object
; Destination:  Any VisClass object, usually the same as the source.
; Interception: If this behavior is not appropriate for the object
;		and its window, it may wish to circumvent the default behavior.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

		
		
		
MSG_VIS_MOVE_RESIZE_WIN			message
;		
;	MSG_VIS_MOVE_RESIZE_WIN is sent to an object marked as VTF_IS_WINDOW
; or VTF_IS_PORTAL to cause the window to be moved/resized.
;
; Context:	Part of the visual update mechanism, usually called by
;		an object's MSG_VIS_UPDATE_WINDOWS_AND_IMAGE handler.
; Source:	Any VisClass object
; Destination:  Any VisClass object, usually same as the source.
; Interception: Default behavior might be replaced if the object doesn't want 
;		its window to be resized to the object's visible bounds.
;
; Pass:
;	Nothing
;
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed
;
	
;-------------------------------------------------
;		Vis tree manipulation
;-------------------------------------------------


MSG_VIS_ADD_CHILD			message
;
; Adds a new child under this object in the visible tree.  
;
; If the parent has not yet been opened, the child will be opened 
; automatically when the parent does.  If the parent is already opened, a 
; MSG_VIS_MARK_INVALID should be sent to the child after adding it
; to mark the object as VOF_WINDOW_INVALID, choosing the appropriate update
; mode.  The object will be opened when its WinGroup is updated.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx - child object to add
;		bp - flags for how to add child (CompChildFlags)
; Return:	nothing
;		cx, dx - unchanged
;		ax, bp - destroyed

MSG_VIS_REMOVE_CHILD			message
;
; Primitive to remove a child from this object in the visible tree.  Should
; be used only with care, as the child should already be visually closed &
; have released all grabs, such as Gadget, Focus, Target.  If possible, 
; use the higher level MSG_VIS_REMOVE, which is sent directly to the child.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx - child object to remove
;		bp - mask CCF_MARK_DIRTY if we want to mark the links as dirty
; Return:	nothing
;		cx, dx - unchanged
;		ax, bp - destroyed

MSG_VIS_MOVE_CHILD			message
;
; Moves a child to a new position under this object in the visible
; tree.  Basically does a REMOVE, then ADD.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx - child object to add
;		bp - flags for how to add child (CompChildFlags)
; Return:	nothing
;		cx, dx - unchanged
;		ax, bp - destroyed


MSG_VIS_FIND_CHILD			message
;
; Determines the position of a visible child of this object
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:	 	^lcx:dx - child object
; Return:	carry - set if NOT FOUND
;		bp  - child position (0 = first child, -1 if not found)
;		cx, dx - preserved
;		ax - destroyed

MSG_VIS_FIND_CHILD_AT_POSITION		message
;
; Looks up a child's address, given its position in the tree.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		cx = # of child to find
; Return:	carry set if NOT FOUND
;		^lcx:dx -- child, or null if no child at that position
;		ax, bp -- destroyed
;
	
MSG_VIS_COUNT_CHILDREN		message
;
;	Counts the Vis children of an object. 
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:
;  	nothing
; Returns:
;	dx - # of Vis children 
;	ax, cx, bp -- destroyed
;

MSG_VIS_FIND_PARENT			message
;
; Finds the visible parent of this object
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	^lcx:dx - parent, or null if none
;		ax, bp - destroyed

MSG_VIS_CALL_PARENT				message
;
; This method simply delivers a method to the visual parent of the
; object which receives it.  (In C, you will want to use "@call visParent::"
; rather than using this message.)
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^hcx - ClassedEvent to call on parent
; Return:	carry clear if no parent
;		else, carry as returned by method handler
;		ax, cx, dx, bp - as returned by method handler
;		(event handle freed)
;
  
MSG_VIS_SEND_TO_PARENT				message
;
; This method simply delivers a method to the visual parent of the
; object which receives it.  (In C, you will want to use "@send visParent::"
; rather than using this message.)
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^hcx - ClassedEvent to send to parent
; Return:	nothing
;		(event handle freed)
;
	
MSG_VIS_SEND_TO_CHILDREN			message
;
; This message is used to send a method to all children of a visual object.
; The method is in the form of a classed event.  Any method data is
; encapsulated with the classed event.  (In C, you will want to use
; "@send @visChildren::" instead.)
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^hcx - ClassedEvent handle
; Return:	Nothing
;		(event handle freed)
;
		
		
;----------------------------------------------------------------
;	Mouse/Keyboard Grab Messages
;----------------------------------------------------------------
	
MSG_VIS_GRAB_MOUSE			message
; 
; This message can be used to grab the mouse for an object.
; MSG_VIS_RELEASE_MOUSE can be used to release the grab.
; In assembly language, you can also call the library routine
; VisGrabMouse.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_VIS_FORCE_GRAB_MOUSE		message
; 
; This message can be used to forcefully grab the mouse for an object,
; taking the grab away from another object that has it if necessary.
; MSG_VIS_RELEASE_MOUSE can be used to release the grab.
; In assembly language, you can also call the library routine
; VisForceGrabMouse.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_VIS_GRAB_LARGE_MOUSE		message
; 
; This message can be used to grab the mouse for an object,
; It requests that large (32-bit model) mouse events be sent to the
; grab.  MSG_VIS_RELEASE_MOUSE can be used to release the grab.
; In assembly language, you can also call the library routine
; VisGrabLargeMouse.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_VIS_FORCE_GRAB_LARGE_MOUSE		message
; 
; This message can be used to forcefully grab the mouse for an object,
; taking the grab away from another object that has it if necessary.
; It requests that large (32-bit model) mouse events be sent to the
; grab.  MSG_VIS_RELEASE_MOUSE can be used to release the grab.
; In assembly language, you can also call the library routine
; VisForceGrabLargeMouse.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
				
MSG_VIS_RELEASE_MOUSE			message
; 
; This message can be used to release the mouse grab for an object.
; In assembly language, you can also call the library routine
; VisReleaseMouse.  
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
	
MSG_VIS_ADD_BUTTON_PRE_PASSIVE		message
; 
; This message can be used to allow any subsequent button events anywhere
; in the system to be sent to this object BEFORE they are sent to their normal
; destination.  This object will receive the monitor message in the form of
; a MSG_META_PRE_PASSIVE_BUTTON, and will be passed the same position and flags as
; the destination object will receive.  The flag MRF_PREVENT_PASS_THROUGH can 
; be returned in ax to prevent the destination from receiving the button event.
; The pre-passive button events can be stopped by sending a MSG_VIS_REMOVE_-
; BUTTON_PRE_PASSIVE to the object.  In assembly language, you can also call 
; the library routine VisAddButtonPrePassive.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
; In the MSG_META_PRE_PASSIVE_BUTTON, your object can expect to receive:
;	Pass:	
;		cx - 		pointer x position
;		dx -		pointer y position
;		bp low -	ButtonInfo
;		bp high - 	ShiftState
; 	Return:
;		ax - 		MouseReturnFlags: MRF_PREVENT_PASS_THROUGH
;				can be passed to keep destination object
;				from receiving the message.
;		cx, dx, bp - destroyed
;
	
MSG_VIS_REMOVE_BUTTON_PRE_PASSIVE	message
;	
; Removes the pre-passive grab for this object.  In assembly language, you
; can also call the library routine VisRemoveButtonPrePassive.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;

MSG_VIS_ADD_BUTTON_POST_PASSIVE		message
; 
; This message can be used to allow any subsequent button events anywhere
; in the system to be sent to this object AFTER they are sent to their normal
; destination.  This object will receive the monitor message in the form of
; a MSG_META_POST_PASSIVE_BUTTON, and will be passed the same position and flags as
; the destination object received.  The post-passive button events can be 
; stopped by sending a MSG_VIS_REMOVE_BUTTON_POST_PASSIVE to the object.  
; In assembly language, you can also call the library routine 
; VisAddButtonPostPassive.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;
; In the MSG_META_POST_PASSIVE_BUTTON, your object can expect to receive:
;	Pass:	
;		cx - 		pointer x position
;		dx -		pointer y position
;		bp low -	ButtonInfo
;		bp high - 	ShiftState
; 	Return:
;		ax, cx, dx, bp - destroyed
;
	
MSG_VIS_REMOVE_BUTTON_POST_PASSIVE	message
;	
; Removes the post-passive grab for this object.  In assembly language, you
; can also call the library routine VisRemoveButtonPostPassive.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - preserved
;

MSG_VIS_TAKE_GADGET_EXCL			message
;
;	MSG_VIS_TAKE_GADGET_EXCL is used to set some object up as having
; the "Active" exclusive for an object.  The previous
; owner, if different, will receive a MSG_VIS_LOST_GADGET_EXCL, to
; let them know they don't have the exclusive anymore.  This
; mechanism is here to use at the discretion of the specific UI, to
; help implement walking of menus, exclusive elements, etc. In most
; cases this will be needed for purely visual interaction only.
;
; Pass:
;	^lcx:dx	- child object taking exclusive
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed

MSG_VIS_RELEASE_GADGET_EXCL			message
;
;	MSG_VIS_RELEASE_GADGET_EXCL is sent by an object which no longer
; wants the GADGET exclusive. If the object currently has the The Gadget
; exclusive, it will get a MSG_VIS_LOST_GADGET_EXCL event.
;
; Pass: 
;	^lcx:dx	- child object which is releasing exclusive.
; Returns:
;	Nothing
;	ax, cx, dx, bp -- destroyed

MSG_VIS_LOST_GADGET_EXCL			message
;
; 	This message is declared here, simply because we want any visible object
; to be able to receive this message, which is sent from a VisComp object
; when MSG_VIS_TAKE_GADGET_EXCL is used, to notify the previous owner of
; the exclusive that they have lost it.
;
; 	Pass:	- nothing
; 	Return:	- nothing
;		  ax, cx, dx, bp -- destroyed
;

VisMessages  	= VisMessages+2

MSG_VIS_VUP_QUERY_FOCUS_EXCL		message
;
; Queries up the visible tree to find out the object with the focus in the 
; current window.  
; 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:		nothing
; Return:	cx:dx -- object with the focus exclusive
;		bp    -- HierarchicalGrabFlags
;		ax    -- destroyed
;
;

MSG_VIS_FUP_QUERY_FOCUS_EXCL		message
;
; This message checks the focus node to see who currently has the focus.
; 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:		nothing
; Return:	^lcx:dx -- object current having the focus
;		bp      -- hierarchical grab flags
;		ax, cx, dx -- destroyed


MSG_VIS_VUP_ALTER_INPUT_FLOW		message
;
; Input flow primitive.  Grabs/Releases kbd/mouse for a visible object
; which is inside of a VisContentClass object.  Objects generally do
; not use this message directly, but instead call one of the utility routines
; Vis[Force]Grab/Release[[Large]Mouse/Kbd].
;
; Large (32-bit) objects & composites should intercept this message, & for
; the case of a mouse grab (VIFGF_MOUSE, VIFGF_GRAB set), add in their 32-bit
; offset amounts to the VAIFD_translation structure, before passing the 
; message on to their superclass.  This will result in mouse coordinate
; positions being translated by that amount for the duration of the mouse
; grab.
;
; NOTE:  Any object grabbing the active, pre-passive, or post-passive mouse
; grab is responsible for releasing these grabs before its death.  This is
; most commonly accomplished by also grabbing the GADGET_EXCL, & then providing
; a LOST_GADGET_EXCL handler to release any mouse grabs the object may have --
; the GADGET_EXCL is always release for a dying owner, by the system.
;
; Pass: 	dx	- size VupAlterInputFlowData
;		ss:bp	- VupAlterInputFlowData 
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;		
;
VisInputFlowGrabType	etype byte
;
VIFGT_ACTIVE		enum VisInputFlowGrabType
VIFGT_PRE_PASSIVE	enum VisInputFlowGrabType
VIFGT_POST_PASSIVE	enum VisInputFlowGrabType

VisInputFlowGrabFlags	record
	VIFGF_NOT_HERE:1
	; OVERRIDES all other flags!
	; Set if this request should NOT be honored here, but instead
	; sent on up the hierarchy with this bit cleared.  This bit
	; exists for two reasons:
	;	1) So that nodes can tell the difference between messages
	; 	   coming up from objects below & those requests which it has
	; 	   made for itself, which should be handled by the next node up.
	;	2) Thus allowing MSG_VIS_VUP_ALTER_INPUT_FLOW to be sent to
	;	   the object making the request itself, thereby allowing
	;	   nodes the freedom to direct the message in directions other
	;	   than the visual hierarchy, if the next node is not in that
	;	   direction.

	:1

	VIFGF_FORCE:1	; If VIFGF_GRAB & GrabType = VIFGT_ACTIVE:
			;    set to force grab away from current owner, clear
			;    if we should leave any current owner alone.
	VIFGF_GRAB:1 	; set to grab, clear to release.
			; NOTE 1: object must be passed in release case as well
			; 	  as grab.  Release will not occur unless object
			;	  matches.
			; NOTE 2: Only one obj may have the active grab at any
			; 	  one time, whereas any number of objects may
			;	  add themselves to a passive list.

	VIFGF_KBD:1	; set to grab/release kbd (keyboard)

	VIFGF_MOUSE:1	; set to grab/release mouse
	VIFGF_LARGE:1	; If VIFGF_MOUSE & VIFGF_GRAB:
			;    LARGE mouse events requested
	VIFGF_PTR:1	; If VIFGF_MOUSE, set if ptr events need to be sent


VisInputFlowGrabFlags	end

VupAlterInputFlowData	struct
	VAIFD_flags		VisInputFlowGrabFlags
	VAIFD_grabType		VisInputFlowGrabType

	VAIFD_object		optr

	VAIFD_gWin		hptr.Window
	; For mouse grabs, the window that the object is in

	VAIFD_translation	PointDWord
	; For mouse grabs, any additional 32-bit translation that should be
	; applied to all mouse data

VupAlterInputFlowData	ends


MSG_VIS_VUP_SET_MOUSE_INTERACTION_BOUNDS	message
;
; This message is sent up from a visual object requesting the grab, so that
; if it lives in a content, the content can notify the view of a new
; draggable bounds in case the user opts to select scroll.
; (NOTE:  STILL REQUIRES SOME WORK!)
;
; 	Pass:	ss:bp -- Rectangle: visible bounds
;		dx    -- size Rectangle
;	Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
						
MSG_VIS_VUP_GET_MOUSE_STATUS		message
;
; This message is provided for cases where it is not possible to keep track
; of the information locally by storing locally the info as it was last
; passed in a mouse event.
;
;	Pass:	nothing
;	Return: 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
;
;		bp high - UIFunctionsActive
;		ax, cx, dx - destroyed
;

MSG_VIS_VUP_TERMINATE_ACTIVE_MOUSE_FUNCTION	message
;
; Terminates any active mouse function, forcing it to become
; a lowly "OTHER" function in progress.  Used by the specific UI
; to "Kill" the START_SELECT in progress when the system menu
; is double-clicked on & held.  The problems was that PTR events
; following were marked as being a SELECT operation, & the window
; UNDER the window which was closed starts reacting to the SELECT
; operation.
;
;	Pass:	nothing
;	Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_VIS_VUP_BUMP_MOUSE		message
;
; Bump mouse ptr image on screen, as if user had done it.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		cx	- sword representing amount to bump mouse in X
;		dx	- sword representing amount to bump mouse in Y
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

;-------------------------------------------------
;		Miscellanious
;-------------------------------------------------

MSG_VIS_VUP_ALLOW_GLOBAL_TRANSFER	message
;
;	This message allows quick transfer destinations to receive
;	MSG_PTRs.  It should be sent to the gadget itself when
;	it starts a quick transfer.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass: 	nothing
; Return: 	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_VIS_CALL_ROUTINE			message
;
;	Used to do a direct call to a far routine, but under the
; disguise of being a VisClass message handler- all registers are set
; up as if the far routine WERE a message handler for VisClass.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		*ds:si 	- instance data
;		es     	- segment of VisClass
;		ax 	- MSG_VIS_CALL_ROUTINE
;
;		cx	- data to pass in ax
;
;		dx	- # of bytes on stack
;		bp	- pointer to stack frame
;
;		Pushed on stack in following order:
;
;		Word value to pass in cx
;		Word value to pass in dx
;		Word value to pass in bp
;
;		Segment, then offset of routine to call (Must be in fixed
;		memory, or in a locked block)
;
; Return:	ax, cx, dx, bp - whatever is returned by the routine
;
	
;
; Stack structure for MSG_VIS_CALL_ROUTINE
;
VCR_param	struct
    VCR_routine			dword
    VCR_BP_param		word
    VCR_DX_param		word
    VCR_CX_param		word
VCR_param	ends
		
		
;------------------------------------------------------------------------------
;	Moniker-related messages
;------------------------------------------------------------------------------
	
  
MSG_VIS_DRAW_MONIKER					message
;
; Draws a moniker for the object.  The moniker to draw and various to use
; are passed on the stack.   This is defined here chiefly to make it accessible
; in C.  Assembly language programmers should use VisDrawMoniker.  See that
; library routine for more info on how the arguments work.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		ss:bp -- MonikerMessageParams
;		dx    -- size MonikerMessageParams
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
; When designing a gstring moniker for a gadget, here's the state you can expect
; when the gstring begins drawing:
;
;     		* Line color, text color, area color set to the desired moniker
;		  for that gadget and specific UI, typically black.  You should
;		  use these if your gstring is black and white.  If you're using
;		  color, you can choose your own colors but you must be sure 
;		  they look OK against all of the specific UI background colors.
;
;		* Pen position set to the upper left corner of where the moniker
;		  should be drawn.  Your graphics string *must* be drawn
;		  relative to this pen position.
;
;      		* The moniker must return all gstate variables intact, except
;		  that colors and pen position can be destroyed.

MSG_VIS_GET_MONIKER_POS					message
; 
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Returns the position where the passed moniker would be drawn using the passed
; parameters, but doesn't actually draw the moniker.  Useful, along with 
; MSG_VIS_GET_MONIKER_SIZE, for finding out where a moniker will be drawn.
; are passed on the stack.   This is defined here chiefly to make it accessible
; in C.  Assembly language programmers should use VisDrawMoniker.  See that
; library routine for more info on how the arguments work.
; 
;
; Pass:		ss:bp  -- MonikerMessageParams
;		dx     -- MonikerMessageParams
; Return:	cx, dx -- x and y origin for moniker (zeroes if no moniker).
;		ax, bp -- destroyed
;

MSG_VIS_GET_MONIKER_SIZE				message
; 
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Returns the size of the passed moniker. Useful, along with 
; MSG_VIS_GET_MONIKER_POS, for finding out where a moniker will be drawn,
; and also useful for sizing an object if 
; are passed on the stack.   This is defined here chiefly to make it accessible
; in C.  Assembly language programmers should use VisDrawMoniker.  See that
; library routine for more info on how the arguments work.
;
; Pass:		ss:bp  -- MonikerMessageParams
;		dx     -- MonikerMessageParams
; Return:	cx, dx -- x and y origin for moniker
;		ax, bp -- destroyed
;

MSG_VIS_FIND_MONIKER					message
;
; Finds a moniker.
;
; Context:	Visual tree utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		ss:bp -- FindMonikerParams
;		dx    -- size FindMonikerParams
; Return:	^lcx:dx -- VisMoniker (null if none)
;		ax, bp  -- destroyed
;

MSG_VIS_CREATE_VIS_MONIKER			message
;
; Creates a visual moniker chunk.  New visual moniker is created from
; either a complete visual moniker, a visual moniker list, a text string, a
; graphics string, or a token.db token.  The source may be referenced by either
; a far pointer, a global heap block handle, or an optr.
; MSG_VIS_CREATE_VIS_MONIKER creates a new Visual Moniker chunk in the resource
; block of the object MSG_VIS_CREATE_VIS_MONIKER is sent to.  When a text
; string or a gstring is passed, a visual moniker structure will be create for
; the text string or gstring.  The new visual moniker chunk is marked as dirty
; according to the CVMF_DIRTY flag passed.  If a moniker list is passed to this
; message, it will be copied into the destination object's block.  You must
; ensure that the monikers in the moniker will exists when the list is used.
; (If some specific moniker in the list is desired, the moniker list can be
; resolved manually with the GenFindMoniker or VisFindMoniker routines.)
;
; This method is guaranteed NOT to force the specific building of any object.
;
; Context:	Utility message sent to create a visual moniker in the
;		destination object's resource block.
; Source:	Anyone
; Destination:	Any VisClass object
; Interception: Generally not intercepted.  However, custom gadgets may
;		handle.  In this case, call superclass if supplementing
;		default functionality else no need to call superclass if
;		replacing default functionality.
;
; Pass:		ss:bp - ptr to CreateVisMonikerFrame
;			CreateVisMonikerFrame	struct
;				CVMF_source	dword
;				CVMF_sourceType	VisMonikerSourceType
;				CVMF_dataType	VisMonikerDataType
;				CVMF_length	word
;				CVMF_width	word
;				CVMF_height	word
;				CVMF_flags	CreateVisMonikerFlags
;			CreateVisMonikerFrame	ends
;		dx - size of CreateVisMonikerFrame
; Return:	ax - chunk handle of new visual moniker
;		cx, dx, bp - destroyed
;

							
;------------------------------------------------------------------------------
;	Error checking
;------------------------------------------------------------------------------
	
MSG_VIS_VUP_EC_ENSURE_WINDOW_NOT_REFERENCED		message
;
; EC message -- anytime a window is being destroyed, this message should be sent
; up the visible tree.  Objects which store window handles should fatal error
; if they find that they have this handle stored.  Useful to make sure
; programmers are exiting correctly
;
; 	Pass:	^hcx -- window being destroyed
;	Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_VUP_EC_ENSURE_OBJ_BLOCK_NOT_REFERENCED	message
; 
; EC message -- anytime an object block is being destroyed, this message should
; be sent up the visible tree.  Objects which store object references should
; fatal error if they find that they have this handle stored.  Useful to make
; sure programmers are exiting correctly.
;
; 	Pass:	^hcx -- object block being destroyed
;	Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_VUP_EC_ENSURE_OD_NOT_REFERENCED		message
;
; EC message -- anytime an object is being destroyed, this message should
; be sent up the visible tree.  Objects which store object references should
; fatal error if they find that they have this handle stored.  Useful to make
; sure programmers are exiting correctly.
;
; 	Pass:	^lcx:dx -- object being destroyed
;	Return:	nothing
;		ax, cx, dx, bp -- destroyed

		
		
;------------------------------------------------------------------------------
;	Messages used for specific UI implementation
;------------------------------------------------------------------------------
;---------------------------------------------------		
; 	Spec build, unbuild messages
;---------------------------------------------------

MSG_SPEC_BUILD			message
;
; 	MSG_SPEC_BUILD	- This message is sent from within
; MSG_SPEC_BUILD_BRANCH, to each generic child within a given WIN_GROUP,
; or branch, which is being visually built.  It is the default visual
; build message for Generic objects having a visible part.
; VTF_IS_GEN must be set, or this routine will do nothing.
;
; This default handling does not handle all possibilities, but will handle
; all cases where:
;
;		* Generic object becomes sole visible object.
;		  (SA_SIMPLE_GEN_OBJ must be set)  NOTE that objects
;		  that visually appear as different objects that their
;		  generic object (dual build menus, a GenText in a View)
;		  must respond to the MSG_SPEC_GET_SPECIFIC_VIS_OBJECT so that
;		  THIS routine can place new objects created & added between
;		  the correct visual children.
;
;		* Generic object has NOT set SA_USES_DUAL_BUILD
;
;		* Object is to be placed visually on its generic parent,
;		  or, if not, then SA_CUSTOM_VIS_PARENT must be set, & 
;		  object must respond to the MSG_SPEC_GET_VIS_PARENT.
;
;	If an object must replace this message in whole, (As is the case
;	with fancy specific UI interpretations of generic objects, or with
; 	fancy application GenGadgets), it should do the following:
;
;	0) If object is already specifically built, just return.  This
;	check need NOT be performed for the WIN_GROUP portion of 
;	a WIN_GROUP object, since they will never be sent a
;	MSG_SPEC_BUILD for the WIN_GROUP portion if is already built.
;
;
;	1) Visually construct any object(s) necessary to visually implement
;	the generic object.  The visual object(s) should be added into the
;	visible tree at the desired place.  The routine VisAddChildRelativeToGen
;	may prove quite useful in your attempt to do this.
;
;	2) You must invalidate any aspects of the visual objects you have
;	added that are not up to date.  In addition, if your changes affect
;	the visual parent (such as screwing up its geometry), you should
;	invalidate any aspects of it that is wrong as well.  The routine
;	VisMarkFullyInvalid may be useful to you.
;
;	3) If you have created visual objects which are in a different
;	WIN_GROUP than the generic object being built, you must send the
;	visible objects created a MSG_VIS_VUP_UPDATE_WIN_GROUP, to ensure
;	that they are updated.  The field SBF_UPDATE_MODE passed in the 
;	SpecBuildFlags indicates how this update should be done.
;
;	4) If the generic portion of this object has a moniker handle,
;	see if the moniker is actually a list of monikers. If so, choose
;	the most appropriate moniker from the list and replace the list chunk
;	with that single moniker. (use VisFindMoniker or GenFindMoniker)
;
; < see also Spec/User/visual.doc >
;
; Context:	Part of the specific UI building mechanism, typically from
;		object's MSG_SPEC_BUILD_BRANCH handler.
; Source:	Unrestricted, usually the same object 
; Destination:  Any GenClass object
; Interception: Unlikely
;
; Pass:
;	bp	- SpecBuildFlags (below)
;
; Return:
;	nothing
;	ax, cx, dx, bp - destroyed
;

;
; Flags passed to spec build
;
SpecBuildFlags record
	SBF_IN_UPDATE_WIN_GROUP:1
;			  Used for Building only (Not used in Unbuilding)
;			  Set if SPEC_BUILD is being sent from within the
;			  MSG_VIS_VUP_UPDATE_WIN_GROUP.  This lets the object
;			  being called know that the tree is being updated
;			  now, & that if the SBF_WIN_GROUP flag is not set,
;			  then it is the WIN_GROUP that it's parent is in
;			  is the one which is being updated.
;
	SBF_WIN_GROUP:1
;			  Valid for non-branch (MSG_SPEC_BUILD &
;			  MSG_SPEC_UNBUILD) messages only.
;			  Used for both Building & Unbuilding
;			  Set if object being asked to visually build is a
;			  WIN_GROUP, & it is the head object being built.
;			  The flag is used by objects having DUAL_BUILD, so
; 			  that they can tell whether their being asked to
;			  be built as the WIN_GROUP object, or as the non-
;			  WIN_GROUP portion of the object.
;
	SBF_TREE_BUILD:1
;			  Used for Building only (Not used in Unbuilding)
;			  This optimization flag is set automatically when
;			  MSG_SPEC_BUILD_BRANCH is sent on to generic
;			  children of an object being built.
; 			  Indicates the object's generic parent & all
;			  siblings are being built at once. If so,
;			  VisAddChildRelativeToGen may assume that there
;			  no specifically built generic objects to the right
;			  of object currently being built.
;
	SBF_VIS_PARENT_WITHIN_SCOPE_OF_TREE_BUILD:1
;			  Used for Building only (Not used in Unbuilding)
;			  This optimization bit is set for the current
;			  object only if its visible parent turns out to
;			  be the generic parent, but may also be set for
;			  a branch by the specific UI in SPEC_BUILD handlers
;			  if it is sure no objects below that point will
;			  end up visually higher than the top generic
;			  Used by VisAddChildRelativeToGen to avoid the
;			  mess of work required to carefully position a
;			  new object within existing visual objects (When
;			  building within tree, all objects may just be
;			  added at the end, in the order encountered)
;
	SBF_SKIP_CHILD:1
; 			  INTERNAL flag, used within VisAddChildRelativeToGen.
;			  NOT passed to any global vis routines.  Is flag
;			  passed to FindVisParentMatch to indicate
;			  that an object should just clear the flag and
;			  return, thereby skipping processing for that object.
;
	SBF_FIND_LAST:1
;			  INTERNAL flag, used within VisAddChildRelativeToGen.
;			  NOT passed to any global vis routines.  Passed
;			  to FindVisParentMatch to indicate that we want to
;			  find the last child that matches, rather than the
;			  first.
	SBF_VIS_PARENT_UNBUILDING:1
;			Valid for MSG_SPEC_UNBUILD & MSG_SPEC_UNBUILD_BRANCH
;			only.  Used for unbuilding, is set if the object
;			receiving MSG_SPEC_UNBUILD_BRANCH *not* because of
;			a generic parent somewhere up the line being set
;			NOT_USABLE, but instead because a visual parent
;			somewhere up the line is being unbuilt.  This can
;			happen when generic objects build themselves visually
;			on a window other than the one their parent sits on.
;			The difference in the unbuild is threefold:
;				1) MSG_SPEC_UNBUILD_BRANCH is passed on down
;				   to visible children only, with this same
;				   flag set.
;				2) Only effected portions of object are
;				   unbuilt (i.e. only one of WIN_GROUP/
;				   non-WIN_GROUP piece for dual-build objects)
;				3) Dual-build objects must be careful to
;				   unbuild such that the remaining "side"
;				   continues to function, and the unbuilt
;				   side can re-build correctly and continue
;				   to work with the already built side.
;
	SBF_VIS_PARENT_FULLY_ENABLED:1
;			Passed to tell child object if its parent was fully
;			enabled.  Speeds up figuring out whether our object
;			should be set fully enabled.
	:6
;
	SBF_UPDATE_MODE:2
; 			  IMPORTANT - should be last two bits.  Holds
;			  VisUpdateMode to use
;
SpecBuildFlags		end
			  
		     
MSG_SPEC_BUILD_BRANCH			message
;
; MSG_SPEC_BUILD_BRANCH is called by MSG_VIS_UPDATE_WIN_GROUP to ensure 
; that all objects are visually built.
;
; Context:	Part of the mechanism for specifically building generic objects.
; Source:	Unrestricted, usually the generic parent of the destination.
; Destination:  Any GenClass object
; Interception: An object might want to subclass this if it needs to 
;		specifically build other objects than its generic children.
;
; Pass:		bp	- SpecBuildFlags
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
								


MSG_SPEC_UNBUILD_BRANCH			message
;
; 	MSG_SPEC_UNBUILD_BRANCH is generated as part of the
; updating of a window group which has been marked as not visible, if the
; window group's visible linkage has been built up.
; MSG_SPEC_UNBUILD_BRANCH traverses down the generic tree,
; recursively, sending a MSG_SPEC_UNBUILD
; to each child encountered, stopping short only at children which are not
; USABLE, & not going past WIN_GROUP objects. This is the opposite of
; MSG_SPEC_BUILD_BRANCH.
;
; Context:	Part of the mechanism for unbuilding generic objects.
; Source:	Unrestricted, usually the generic parent of the destination.
; Destination:  Any GenClass object
; Interception: Unlikely
;
; Pass:
;	bp	- SpecBuildFlags (note indications of which flags apply to
;				 Unbuild)
;		  NOTE:  if mask SBF_VIS_PARENT_UNBUILDING is set, then this
;			 object was sent the message because it is the visible
;			 child of a generic object which is visibly unbuilding,
;			 and NOT because the recipient object is unbuilding
;			 itself (kind of a notification).  Default behavior
;			 for non-generic object is to free the object.
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_SPEC_UNBUILD				message
;
; MSG_SPEC_UNBUILD is sent to generic objects to cause a visual
; unbuilding of the object.  This is the opposite of MSG_SPEC_BUILD, & is the
; default visual unbuild message for Generic objects having
; a visible part.  VTF_IS_GEN must be set, or this routine will do nothing.
;
;		MAY be used in cases where:
;
;			VisGetSpecificVisObject	returns the correct visible
;			object, which need only be visibly removed from
;			its parent, & not destroyed.
;
;
; Context:	Part of the mechanism for unbuilding generic object, usually
;		called by the object's MSG_SPEC_UNBUILD_BRANCH handler.
; Source:	Usually the same as the destination.
; Destination:  Any GenClass object.
; Interception: 
;	An object may need to do a few cleanup things as it's being
;	unbuilt, after which it can call the superclass to do the unbuild.
;
;	If an object must replace this message in whole, it should do the
;	following:
;
;	0) If object is already visibly unbuilt, just return.  This
;	check need NOT be performed for the WIN_GROUP portion of 
;	a WIN_GROUP object, since they will never be sent a
;	MSG_SPEC_UNBUILD for the WIN_GROUP portion if is already unbuilt.
;
;	1) Visually unconstruct any visual object(s) that have been created
;	for the object (if a WIN_GROUP, then only the WIN_GROUP or
;	non-WIN_GROUP portion as is specified.  This is typically done by
;	just using MSG_VIS_REMOVE_CHILD, plus the removal of any created
;	objects.
;
;	2) You must invalidate any aspects of the visual objects left after
;	the removal that are not up to date.  In addition, if your changes
;	affect the visual parent (such as screwing up its geometry), you should
;	invalidate any aspects of it that is wrong as well.
;
;	3) If you have created visual objects which are in a different
;	WIN_GROUP than the generic object being built, you must send the
;	visible objects created a MSG_VIS_VUP_UPDATE_WIN_GROUP, to ensure
;	that they are updated.  The field SBF_UPDATE_MODE passed in the 
;	SpecBuildFlags indicates how this update should be done.
;
; Pass:
;	bp	- SpecBuildFlags (note indications of which flags apply to
;				 Unbuild)
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_SPEC_GET_VIS_PARENT			message
;
; Method for use by specific UI only for the purpose of returning
; what visible object a visual representation of the generic object should
; be placed on when MSG_SPEC_BUILD'd.
;
; Context:	Part of the specific UI building mechanism, usually called by
;		the object's MSG_SPEC_BUILD or MSG_SPEC_SET_USABLE handler.
; Source:	Unrestricted, usually the same as the destination.
; Destination:  Any VisClass object
; Interception: If you want to visually link your object to something other
;		than its generic parent, you will probably want to replace
;		this message.
;
; Pass:	 	bp - SpecBuildFlags:
;		mask SBF_WIN_GROUP - set if looking for visual
;				     object used when referring to
;				     this gen object as a win
;				     group head object
; Return:	carry - Set if data found & returned, clear if no object
;			responded
;		^lcx:dx - visible object to use for a visible parent
;		bp - Same SpecBuildFlags as passed, although recipient of
;		     this method may or in  'mask
;		     SBF_BUILDING_WITHIN_WIN_GROUP', if the object is
;		     being placed visibly within the same WIN_GROUP that
;		     the generic object is under.  It is DESIRABLE to be
;		     able to or this flag in, as it allows an optimization
;		     when SPEC_BUILD'ing which speeds things up
;		     considerably.
;		ax - destroyed
;
	

MSG_SPEC_DETERMINE_VIS_PARENT_FOR_CHILD		message
;
; Returns vis parent for a child object.   This will be default be called from
; a child's MSG_SPEC_GET_VIS_PARENT, and if not answered, will be determined
; by the child.
;
; Context:	Part of the specific UI building mechanism, usually called by
;		the generic child's MSG_SPEC_GET_VIS_PARENT handler.
; Source:	Unrestricted, usually a generic child of the destination
; Destination:  Any GenClass object
; Interception: This can be replaced by objects that want to place their 
;		generic children visually below some object other than
;		themselves.
;
; Pass:		^lcx:dx -- child to get vis parent for
;		bp -- SpecBuildFlags:
;		mask SBF_WIN_GROUP - set if looking for visual
;				     object used when referring to
;				     this gen object as a win
;				     group head object
; Return:	carry set if method handled & therefore data returned:
;		^lcx:dx - vis parent to use
;		bp - Same SpecBuildFlags as passed, although recipient of
;		     this method may or in  'mask
;		     SBF_BUILDING_WITHIN_WIN_GROUP', if the object is
;		     being placed visibly within the same WIN_GROUP that
;		     the generic object is under.  It is DESIRABLE to be
;		     able to or this flag in, as it allows an optimization
;		     when SPEC_BUILD'ing which speeds things up
;		     considerably.
;		ax  -- destroyed
;


MSG_SPEC_GUP_QUERY_VIS_PARENT		message
;
; MSG_SPEC_GUP_QUERY_VIS_PARENT is a method reserved for use by the
; specific UI for the purpose of returning an
; Output Descriptor of object suitble for being
; a parent visible object for the type requested, in cx:dx
;
; Context:	Part of the specific UI building mechanism.
; Source:	Unrestricted
; Destination:  Any GenClass object that wishes to respond to the request
; Interception: This might be subclassed for any object that wants to 
;		grab a query before it gets to its normal destination,
;		or to handle new parent types that might be added.
;
; Pass:		cx	- SpecQueryVisParentType
; Return:	carry	- Set if data found & returned, clear if no object
;			  responded
;		^lcx:dx	- object suitable to be this object's
;			  visible parent
;		ax, bp	- destroyed
;

SpecQueryVisParentType 			etype word
SQT_VIS_PARENT_FOR_FIELD		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_APPLICATION		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_PRIMARY		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_DISPLAY		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_POPUP		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_URGENT		enum SpecQueryVisParentType
SQT_VIS_PARENT_FOR_SYS_MODAL		enum SpecQueryVisParentType


MSG_SPEC_GET_SPECIFIC_VIS_OBJECT		message
;
; Returns the visual object/branch, if any, created in the specific world
; to represent this generic object.
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any GenClass object
; Interception: An object will want to replace this method any time the 
;		object which represents the generic object visually
;		differs from the generic object.
;
; Pass:		bp - SpecBuildFlags:
;			mask SBF_WIN_GROUP	- set if looking for visual
;						  object used when referring to
;						  this gen object as a win
;						  group head object
; Return:	carry clear if object doesn't appear visually
;		^lcx:dx - visual object which represents visual object
;			created for non-win-group or win-group version of
;			generic object, as specified by SBF_WIN_GROUP flag
;			passed.  If generic object doesn't appear visually
;			in the mode that the flag was passed, 0 should be
;			returned.
;		ax, bp - destroyed
;

MSG_SPEC_ADD_CHILD_RELATIVE_TO_GEN	message
;
; A utility to add a child into the visual tree relative to another object.
; This message should be sent to the reference object in question.  If the
; generic parent of the reference object is the same as the object to add,
; the object will be added to the desired visual parent relative to the 
; reference object.  If the reference and object to add have differing visual
; or generic parents, the object will be added at the end.
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object.
; Interception: Unlikely
;
; Pass:		ss:bp -- AddChildRelativeParams
;		dx    -- size AddChildRelativeParams
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

AddChildRelativeParams	struct
	ACRP_child	optr
		;The object to add.

	ACRP_parent	optr
		;The visual parent to use.

	ACRP_buildFlags	SpecBuildFlags
		;The spec build flags to use.
AddChildRelativeParams  ends

MSG_SPEC_RESOLVE_MONIKER_LIST		message
;
; Used by Generic UI to implement the MSG_GEN_REPLACE_VIS_MONIKER,
; MSG_GEN_PRIMARY_REPLACE_LONG_TERM_MONIKER, and
; MSG_GEN_DYNAMIC_LIST_COPY_ITEM_MONIKER case where a moniker list is passed
; and the object is already built -- the specific UI must choose one of the
; monikers in the moniker list.
;
; Context:	Specific UI utility
; Source:	Generic UI internals
; Destination:	Any GenClass object
; Interception:	Unlikely, though possibly intercepted by specific UI to
;		handle the moniker list resolving when a specific moniker in
;		moniker list is desired, or if some work needs to be done
;		before or after resolving the list.
;
; Pass:		cx - chunk handle of moniker list, to be replaced by
;			most appropriate moniker
; Return:	most appropriate moniker from moniker list replaces passed
;			moniker list chunk
; 		ax, cx, dx, bp - destroyed

MSG_SPEC_RESOLVE_TOKEN_MONIKER		message
;
; Used by Generic UI to implement MSG_GEN_REPLACE_VIS_MONIKER,
; MSG_GEN_PRIMARY_REPLACE_LONG_TERM_MONIKER, and
; MSG_GEN_DYNAMIC_LIST_COPY_ITEM_MONIKER.  The specific UI chooses a moniker
; passed on the passed token chunk and replaces the chunk with the
; appropriate moniker.
;
; Context:	Specific UI utility
; Source:	Generic UI internals
; Destination:	Any GenClass object
; Interception:	Unlikely, though possibly intercepted by specific UI to
;		handle the token resolving when a specific moniker in moniker
;		list is desired.
;
; Pass:		cx - chunk handle of GeodeToken, to be replaced by
;			most appropriate moniker in Token Database's
;			moniker list for the token
; Return:	carry set if successful (token found)
;			passed chunk now contains most appropriate
;		carry clear if unsuccessful (token not in Token Database)
;			passed chunk unchanged!! -- DO NOT use for moniker
;				as it is not a moniker chunk
; 		ax, cx, dx, bp - destroyed
					
;---------------------------------------------------		
; 	Set/get attributes
;---------------------------------------------------

MSG_SPEC_SET_ATTRS		message
;
;	MSG_SPEC_SET_ATTRS may be called by the SPECIFIC UI only
; to change instance bits stored in VI_attrs which are reserved for use
; by the specific UI.  This message may only be sent to WIN_GROUP objects.
;
;	In order to make a WIN_GROUP come up on screen or go away,
; you used to use MSG_VIS_SET_ATTRS to set/clear VA_VISIBLE.  This
; bit is now reserved for the VISIBLE world & should not be used
; directly by Specific UI code.  Instead,  You manipulate the bits
; GS_USABLE, SA_ATTACHED, & SA_REALIZABLE.  All three must be set
; before the object is made visible.  This message allows the changing
; of SA_ATTACHED & SA_REALIZABLE.  See MSG_GEN_SET_USABLE &
; MSG_GEN_SET_NOT_USABLE to change the GS_USABLE bit.
; When all three bits are set, this message marks the visible object as VISIBLE,
; & updates it (based on the VisUpdateMode passed)
; < see also Spec/User/visual.doc >
; WARNING:  This message is statically defined & called, & therefore may not
; be intercepted via subclassing.
;
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:	cl	- SpecAttrs bits to be set
;	ch	- SpecAttrs bits to be cleared
; 			  
; 	Bits that may be changed are:
;
;	SA_ATTACHED		- if WIN_GROUP is attached
;	SA_REALIZABLE		- if WIN_GROUP is realizable
;
;	dl	- VisUpdateMode -  To be used for bringing up window,
;		  or updating visible WIN_GROUPs OTHER than this
;		  one which have objects removed from them as a result
;		  of this window coming down.  If window is brought
;		  down, it is always done immediately, so that the
;		  branch may be visibly unlinked immediately.
;
; Return:	nothing
;		cx, dx, bp - preserved
;		ax - destroyed
;


MSG_SPEC_GET_ATTRS			message					
;
; Returns specific attributes for an object.
; 
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	cl -- SpecAttrs
;		ax, ch, dx, bp -- destroyed
;

	
;---------------------------------------------------		
; 	Set usable, enabled, vis moniker
;---------------------------------------------------

MSG_SPEC_SET_USABLE			message
;
;	This message is sent to an object by the generic UI on the reciept of
; a MSG_GEN_SET_USABLE which results in the object transitioning from
; being not USABLE to being FULLY USABLE.  A default handler in VisClass
; performs visual operations needed to bring any visible representation of
; this generic object ON screen.  This message need normally not be subclassed,
; instead specific UI's will normally just subclass MSG_SPEC_BUILD in
; order to visually construct the object when requested.  (MSG_SPEC_BUILD
; is also not sent out unless the window that the object will appear in is
; currently specifically built, as well)
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:
;	dl	- VisUpdateMode
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_SPEC_SET_NOT_USABLE		message
;
;	This message is sent to an object by the generic UI on the reciept of
; a MSG_GEN_SET_NOT_USABLE which results in the object transitioning from
; being being FULLY USABLE to being NOT USABLE.  A default handler in VisClass
; performs visual screen repairs (Gets the visual representation of the
; generic object OFF screen).  This message need normally not be subclassed.
; instead specific UI's will normally just subclass MSG_SPEC_UNBUILD, in
; order to tear down the visible worl that it had created for the object.
; the default MSG_SPEC_UNBUILD actually does a pretty good job, making
; the need for a subclassing rare.
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:
;	dl	- VisUpdateMode
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_SPEC_NOTIFY_ENABLED		message
;
; Figures out for this visual UI object whether it can set the fully-invalid
; bit.
; 
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely.
;
; Pass:		dl -- update mode
;		dh -- NotifyEnabledFlags 
; Return:	carry set if visual state changed
;		ax, cx, dx, bp -- destroyed
;
	
			
MSG_SPEC_NOTIFY_NOT_ENABLED	message
;
; Figures out for this visual UI object whether it can clear the fully-invalid
; bit.
; 
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		dl -- update mode
;		dh -- NotifyEnabledFlags
; Return:	carry set if visual state changed
;		ax, cx, dx, bp -- destroyed
;
	
MSG_SPEC_UPDATE_VIS_MONIKER		message
;
;	Performs visual fix-up after object has a new moniker set
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:
;	dl	- VisUpdateMode
;	cx 	- width of old moniker  
;	bp 	- height of old moniker 
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed

	
;---------------------------------------------------		
; 	Spec UI update messages
;---------------------------------------------------

MSG_SPEC_UPDATE_VISUAL		message
;
;	Do visual update for whole generic object
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:
;	dl	- VisUpdateMode
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed


;---------------------------------------------------		
; 	Spec UI geometry related messages
;---------------------------------------------------

MSG_SPEC_GET_EXTRA_SIZE			message
;
; Returns the amount of space the object takes up without the monikers.  Used
; by the specific UI when the user wants to allocate a certain amount of space
; based on the size of the monikers he expects to use.
; 
; Context:	Called when converting a user-defined SpecSizeSpec size for an
;		object or group of objects to pixels.
; Source:	Unrestricted, usually the visual parent
; Destination:  Any generic VisClass object
; Interception: This must be subclassed by any object that has anything to
;		contribute to a conversion of SpecSizeSpec sizes to 
;		pixels.  This generally means any space in an object that is
;		*not* taken up by a moniker (which is calculated differently).
;
; Pass:		in composites only:
;		    bp -- number of children to get extra size for
; Return:	in composites only:
;		    bp -- children unaccounted for (there were fewer children
;			  than asked for)
; 		cx, dx -- width, height without the monikers
;		ax     -- destroyed
;
;

MSG_SPEC_CONVERT_DESIRED_SIZE_HINT	message
;
; Used when desired size hints such as HINT_FIXED_SIZE are encounted.  This 
; will generate the appropriate size based on the system font, screen size,
; and number of children if the object is a composite, accounting for extra
; size of the object and any children.
;
; Context:	Called when converting a user-defined SpecSizeSpec size for an
;		object or a group of objects to pixels.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		cx     -- {SpecSizeSpec} desired width
;		dx     -- {SpecSizeSpec} desired height
;		bp     -- {SpecSizeSpec} # of children to calc for (comps only)
; Return:	cx, dx -- converted width, height
;		ax, bp -- destroyed
;

MSG_SPEC_CONVERT_SIZE		message
;
; Converts a SpecSizeSpec argument to a pixel value, based on the current font
; and screen size, etc.  
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		cx     -- SpecSizeSpec argument
;		bp     -- gstate with the system font
; Return:	cx     -- converted pixel value
;
				
MSG_SPEC_VUP_GET_WIN_SIZE_INFO	message
;
; Used by specific UI windows to get the size of their window area and any 
; margins that their parent window might want to reserve for icon areas.  
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: This should be subclassed by any windowed VisClass object,
;		so that it can its size and any margins that it might
;		be keeping for icon areas (probably zero for any application-
;		defined UI windows and most others).
;
; Pass:		nothing
; Return:	cx, dx -- size of window area
;		bp low -- reserved areas at bottom of window
;		bp high -- reserved areas to right edge of window
;		ax, cx, dx -- destroyed
;

;------------------------------------------------------------------------------
;		Keyboard Navigation Messages
;------------------------------------------------------------------------------

	
;the following SPEC messages are defined here so that they can be used by
;applications on non-generic objects. They are defined at the VisClass level
;because they will travel the visible tree. When ever possible, use the
;generic counterparts to these messages (see genClass.asm).

MSG_SPEC_NAVIGATE_TO_NEXT_FIELD			message
MSG_SPEC_NAVIGATE_TO_PREVIOUS_FIELD		message
;
; This specific UI message is generally sent from an object as a result of a 
; MSG_GEN_NAVIGATE_TO_NEXT/PREVIOUS_FIELD, and travels up the
; VISIBLE tree to the first VisCompClass object which is a WIN_GROUP
; (in other words, the GenPrimary or GenSummons level), where it causes
; WIN_GROUP object to move the focus exclusive.  See MSG_GEN_NAVIGATE_TO_NEXT-
; FIELD for more info.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;
	
MSG_SPEC_NAVIGATE_COMMON			message
;
; Low level navigation routine, will generally be used by C handlers
; of MSG_SPEC_NAVIGATION_QUERY, in place of its assembly equivalent, 
; VisNavigateCommon.
;
; This is currently only available in C for GEOS 2.1 platforms and above.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		ss:bp -- NavigateCommonParams
;		dx    -- size NavigateCommonParams
; Return:	ss:bp -- NavigateCommonParams, with:
;			    NCP_object -- set to final recipient of message
;			    NCP_navFlags -- flags returned by final recipient
;			    NCP_backtrackFlag -- set if object is focusable
;						 via backtracking.
;		carry set if found the next/previous object we were seeking
;		ax, cx, dx -- destroyed
;

NavigateFlags	record
    ;reply flags:

    NF_COMPLETED_CIRCUIT:1
			;This is set when this message is recieved at a node
			;and the originating node (in ^lcx:dx) matches the
			;recipient node, meaning we have travelled the
			;entire circuit. Recursion ends at this point.
			;This is useful for preventing infinite looping
			;in cases where the circuit consists of 1 object,
			;and is handy for error checking after objects have
			;been added/removed from the WIN_GROUP.

    NF_REACHED_ROOT:1	;This might be useful for error checking. Is set
			;as this message is received by the root (WIN_GROUP
			;object, and is passed on to the first child.
    :6

    ;command flags: (MUST BE IN LOWER BYTE)

    :1			;reserved for future use
			;(lines up with VTF_IS_COMPOSITE)

    :1			;reserved for future use (lines up with GS_ENABLED
			;and NCF_FOCUSABLE)

    NF_NAV_MENU_BAR:1	;set to navigate through items considered part
			;or the menu bar area: menu buttons, icons in the
			;header area, etc. Clear this flag to navigate through
			;control-items in the window area.
			;(MUST MATCH NCF_MENU_RELATED)

    :1			;reserved for future use
			;(lines up with VTF_IS_WIN_GROUP and NCF_IS_ROOT)

    NF_INITIATE_QUERY:1	;when a MSG_SPEC_NAVIGATE_TO_NEXT/PREVIOUS_FIELD
			;sends this query to an object, this flag is set,
			;since the cx:dx passed = the object, and don't
			;want to get confused and think that we have already
			;travelled the entire circuit. This flag is reset
			;before the message is passed onto the next node
			;in the circuit.
    
    NF_SKIP_NODE:1	;set to tell the recipient to forward the message
			;on to the next object in the circuit.
			;if reset, and is composite, will forward message
			;to first child. If leaf node, will forward to
			;next sibling. If is last sibling, will forward to
			;parent passing NF_SKIP_NODE = TRUE so that parent
			;will forward to sibling/parent, etc.

    NF_TRAVEL_CIRCUIT:1	;set to force message to be passed through the entire
			;navigation circuit, back to the originating object.
			;This is useful for error checking, and for the
			;"navigate to previous" case.

    NF_BACKTRACK_AFTER_TRAVELING:1
			;This is used to implement "navigate to previous".
			;The message is sent to the focused object with
			;NF_TRAVEL_CIRCUIT and NF_BACKTRACK_AFTER_TRAVELING
			;both TRUE. When the message has travelled the
			;entire circuit, we begin to come back up through
			;the levels of recursion we have passed. At the
			;first level which was an object which can get
			;the focus, we return that object. The
			;un-recursion continues, and the original called
			;is returned. We call it expensive magic.
NavigateFlags	end

; If you want to subclass this message to change the navigation functionality
; for a particular class, look at the default and specific-UI handlers
; above to get a feel for how this message is handled. Also see the
; utility routines VisNavTestForTravelledCircuit, and VisNavToNextNode.

;this record is passed to VisNavigateCommon:

NavigateCommonFlags	record
    NCF_IS_COMPOSITE:1		;set this if calling from a composite object
				;(is subclass of VisCompClass)

    NCF_IS_FOCUSABLE:1		;set this if specific UI will allow this
				;object to get the focus.  If NCF_IS_COMPOSITE
				;is also set, means the object itself will get
				;the focus first, followed by its children,
				;in the navigation order.

    NCF_IS_MENU_RELATED:1	;set if this object is menu-related
				;(menu button, or icon in header area)

    NCF_IS_ROOT_NODE:1		;set if this node is the root level of the
				;tree. 
    :4
NavigateCommonFlags	end

		
NavigateCommonParams	struct
	NCP_object		optr	
		;When passed, the object that originated the message; when
		;returned, the final recipient of the message.

	NCP_navFlags		NavigateFlags

	NCP_navCommonFlags	NavigateCommonFlags

	NCP_genPart		lptr
		;Chunk handle of generic instance data for the calling object,
		;or zero if not there is no generic data.  Used for checking
		;for navigation hints.

	NCP_backtrackFlag	byte
		;Used as a return value, non-zero if object called is focusable
		;via backtracking.
NavigateCommonParams	ends
						
						
MSG_SPEC_ACTIVATE_INTERACTION_DEFAULT		message
;
; This message, sent in response to its generic counterpart, travels up the 
; VISIBLE tree to the first VisCompClass object which is a WIN_GROUP (in other 
; words, the GenPrimary or GenSummons level), where it causes the WIN_GROUP 
; object to send a MSG_GEN_ACTIVATE to the object which has the default 
; exclusive for the window. This is usually a GenTrigger which has HINT_-
; DEFAULT, although it can be another Trigger which has been navigated to or 
; clicked on.  see MSG_GEN_ACTIVATE_INTERACTION_DEFAULT for more details.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	carry set	- if activated default action.
;		ax, cx, dx, bp - destroyed
;
	
MSG_SPEC_NAVIGATE				message
;
; This message is used by the specific UI to implement the generic navigation
; messages MSG_GEN_NAVIGATE_TO_NEXT/PREVIOUS_FIELD. 
; This message walks the visible tree inside a WIN_GROUP, to find the
; object which is next/previous in the navigation circuit.
;
; Context:	Part of the UI keyboard navigation mechanism, typically called
;		by MSG_GEN_NAVIGATE_TO_NEXT/PREVIOUS_FIELD.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		bp	= NavigateFlags (see below)
; Returns:	carry set if answered, with:
;			^lcx:dx	= object which is replying (NEXT or PREVIOUS
;			node in relation to the originating node)
;		else
;			^lcx:dx = null
;		ax, bp	= destroyed

	
MSG_SPEC_NAVIGATION_QUERY			message
;
; This message is used by the specific UI to implement the generic navigation
; messages MSG_GEN_NAVIGATE_TO_NEXT/PREVIOUS_FIELD. It is defined here so
; that applications which subclass UI components can intercept it to alter
; navigation functionality, such as moving to a different field after
; toggling an exclusive setting. This message can be sent to almost any UI
; object. It is handled by the following specific UI objects:
; 
; This is currently only available in C for GEOS 2.1 platforms and above.
;
;	OLWinClass		for the WIN_GROUP root-level composite case
;	OLButtonClass		for the leaf node case
;	OLTextEditClass		for the leaf node case
;	OLSettingCtrlClass	for the leaf node case
;	VisCompClass		for the default composite node case
;	VisClass		for the default leaf node case,
;					for objects that will never be focused.
;
; Context:	Part of the specific UI keyboard navigation mechanism, called
;		by a MSG_SPEC_NAVIGATE handler.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: By custom vis objects needing to grab the focus.
;
; Pass:		^lcx:dx	= object which originated this query
;		bp	= NavigateFlags (see below)
;
; Returns:	carry set if object to give focus to, with:
;			^lcx:dx	= object which is replying
;		else
;			^lcx:dx = next object to query
;		bp	= NavigateFlags (will be altered as message is
;			  passed around)
;		al	= set if the object is focusable via backtracking
;			  (i.e. can take the focus if it is previous to the
;			  originator in backwards navigation)
;
		
MSG_SPEC_NOTIFY_NAVIGATION_COMPLETE			message
;
; Sent to the object that completes a MSG_SPEC_NAVIGATE call, in case it
; needs to know it.  (Objects can't otherwise find out, especially on 
; backwards navigation.)
;
; Pass:		bp 	= NavigateFlags returned from the last navigation
;				query
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;
	
MSG_SPEC_ACTIVATE_OBJECT_WITH_MNEMONIC			message
;
;	This checks keyboard characters against the object's mnemonic,
;	and those of its visual descendants children, to see if the object 
;	should be activated.  Sends a MSG_GEN_ACTIVATE to the non-win-group
; 	part of an object whose mnemonic matches.  Search stops when a match
; 	is encountered.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		cx = character value
;		dl = CharFlags
;		dh = ShiftState (ModBits)
;		bp low = ToggleState
;		bp high = scan code
; Return:	carry set if mnemonic found
;		ax, cx, dx, bp - destroyed
;

MSG_SPEC_CHECK_MNEMONIC			message
;
; Checks to see if an object's mnemonic matches the passed keyboard value.
; Assembly language programmers should use the library routine VisCheckMnemonic.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely, unless your object needs to do something special
;		when checking the passed character for a mnemonic match.
;
; Pass:
;	cx = character value
;	dl = CharFlags
;	dh = ShiftState
;	bp low = ToggleState
;	bp high = scan code
; Return:
;	carry set if matches generic mnemonic
;	ax, cx, dx, bp - destroyed
	

;------------------------------------------------------------------------------
;		Menu Separator Query
;------------------------------------------------------------------------------

MSG_SPEC_MENU_SEP_QUERY			message

; This message is used by the specific UI to recalc which GenInteractions
; within menus require separators to be drawn. It is defined here so
; that applications which subclass UI components can intercept it to alter
; this functionality. This message is handled by:
;
;	GenTriggerClass		for leaf node case
;	GenItemClass		for leaf node case
;	GenBooleanClass		for leaf node case
;	GenInteractionClass	for composite node case (or root node, for the
;				actual menu itself)
;
; This message walks the visible tree inside a WIN_GROUP, setting flags
; in the OLMenuItemGroup objects as it goes. This message is heavily recursive,
; and the flags passed to and object are just as important as those returned
; by it.
;
; Context:	Specific UI message
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		ch	= MenuSepFlags (see below)
;
; Returns:	ch	= MenuSepFlags (updated according to results)
;		ax, cl, dx, bp = destroyed
;

MenuSepFlags	record
    MSF_SEP:1		;When recursing to lower objects in the menu, this is
			;set when there is at least one usable object between
			;this object and the separator drawn above it.
			;When un-recursing (moving up the menu), this is set 
			;when there is at least one usable object between
			;this object and the separator drawn below it.

    MSF_USABLE:1	;When recursing to lower objects in the menu, this
   			;is set when an object has at least one previous sibling
			;which is GS_USABLE.

    MSF_FROM_CHILD:1	;Set when message is sent from a child to its visible
			;parent, so the parent can distinguish from the case
			;where it is called from its previous sibling or parent.

    :5
MenuSepFlags	end

		
		
MSG_SPEC_UPDATE_MENU_SEPARATORS			message
;
; This internal specific message is sent when an object in the menu decides that
; a separator in the menu might need to change. We start a wandering query, 
; which updates the appropriate items in the menu.
;
; Context:	Specific UI message.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

;------------------------------------------------------------------------------
;	Broadcast query for default focus object/window within a window.
;------------------------------------------------------------------------------

MSG_SPEC_START_BROADCAST_FOR_DEFAULT_FOCUS	message
;
; When GenClass receives MSG_GEN_START_BROADCAST_FOR_DEFAULT_FOCUS, it
; translates it into MSG_SPEC_START_BROADCAST_FOR_DEFAULT_FOCUS and sends
; it on to the specific ui. See MSG_GEN_START_BROADCASE_FOR_DEFAULT_FOCUS.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		nothing
; Return:	^lcx:dx - object with HINT (0 if none)
;		ax, bp - destroyed
;

MSG_SPEC_BROADCAST_FOR_DEFAULT_FOCUS		message

; This message is used by the specific UI to find the object or windowed object
; which has HINT_DEFAULT_FOCUS{_WIN}. It is defined here so that
; applications which subclass UI components can intercept it to alter this
; functionality. This message is handled by:
;
;	OLButtonClass		for leaf node case
;	OLTextDisplayClass	for leaf node case
;	OLSettingClass		for leaf node case
;	OLDisplayControlClass	for leaf windowed node case
;	OLCtrlClass		for composite node case (sends to kids)
;	OLMenuBarClass		for composite node case (prevents excess work)
;	
; This message is sent to every visible object inside a WIN_GROUP, until one
; handles the message by returning the carry set.
;
; Context:	Part of the specific UI keyboard navigation mechanism.
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx = other object in window which has hint
; Returns:	^lcx:dx	= this object if it has hint
;		bp	= OWNER_INFO_MASK (HierarchicalGrabFlags) -- info about
;				the node which has the hint.
;		ax	= destroyed

		

;-----------------------------------------------------------------------------
;	Visible Layer methods		
;-----------------------------------------------------------------------------
 
MSG_VIS_LAYER_SET_DOC_BOUNDS		message
; Set the 32-bit document bounds of a visible object.  
;
; Context:	Part of the Large Document model
; Source:	sent by a VisIsoContent object (when its
; 		VCNA_LARGE_DOCUMENT_MODEL flag is set) to all of its
; 		Vis children, which are assumed to be "layers"
;
; Destination:  Any Large (32-bit) visible object or composite.
;
; Interception: No default handler is supplied -- objects must create
;		their own.
;
; Pass:		ss:bp - pointer to RectDWord structure of new visible bounds.
;   	    	dx - size of RectDWord structure

;		
;
; Return:	nothing (ax,cx,dx,bp destroyed)

MSG_VIS_LAYER_GET_DOC_BOUNDS	message
;
; Return the 32-bit document bounds of a visible object
;
; Context:	Part of the Large Document model
;
; Source:	Sent by any object wishing to find out the 
; 		bounds of a Large (32-bit) visible object
;
; Destination:  Any Large (32-bit) visible object or composite.
;
; Interception: No default handler is supplied -- objects must create
;		their own.
;
; Pass:		cx:dx - Buffer of at least (size RectDWord) in which to
; 		place the bounds.
;
; Return:	cx:dx - pointer to RectDWord of object's bounds.
;		ax, bp destroyed


MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK	message	private
;
; If an object wants to receive ink methods, it needs to do the following:
;
; 1) Subclass this method.
; 2) In the method handler, compare the data3 value in the passed stack frame
;    with the top of the object.
; 3) If the upper bound of the object is < the data3 value in the stack
;    frame (or the value in data1 is 0), then the object should return its
;    upper bound in VCCIBF_data3, and its OD in data1:data2.
;
;    Else, it should return cx,dx and the stack frame unmolested.	
;
;    A default handler that performs the above steps is provided:
;	VisObjectHandlesInkReply(). If your object always wants ink, you can
;	just add a line like this after your class declaration:
;
;	message VisObjectHandlesInkReply, YourClassNameHere,
;					MSG_VIS_QUERY_IF_OBJECT_HANDLES_INK
;
; Context: Part of the ink support mechanism
;
; Source: Sent by the application object in an attempt to determine who
;	  to give captured ink to.
;
; Destination: Any realized object in the Vis linkage
;
; Interception: The default VisClass handler returns FALSE. Objects that want
;		ink should subclass this to return true.
;
; Pass: ss:bp - ptr to VisCallChildrenInBoundsFrame
;
; Return: 
;	ss:bp.VCCIBF_data1, data2 - OD of top item that desires ink
;	      VCCIBF_data3 - upper bound of object that desires ink
;

MSG_SPEC_SCAN_GEOMETRY_HINTS		message
;
; Message to cause a specific object to scan its generic geometry hints, taking
; into account their own default geometry attributes and overriding hints
; when needed.  All objects that rely on geometry hints should keep their
; hint-scanning code in a handler for MSG_SPEC_SCAN_GEOMETRY_HINTS, so that
; re-scanning can be done after objects have become usable.
;
; Context:	Often called by an object's MSG_SPEC_BUILD handler, will also
;		be called by MSG_SPEC_RESCAN_GEO_AND_UPDATE so that
;		hints can be rescanned by the object.
; Source:	Anyone
; Destination:	Any VisClass object marked VTF_IS_GEN.
; Interception:	Most specific UI objects will want to subclass this message
;		to do their own geometry thing.
;
; Pass:		nothing
; Return:	nothing
; 		ax, cx, dx, bp -- destroyed
;

MSG_SPEC_RESCAN_GEO_AND_UPDATE		message
;
; Sent to a specific object when geometry hints have changed, so it can send
; a MSG_SPEC_SCAN_GEOMETRY_HINTS to itself to redo its geometry, and invalidate
; itself as needed.
;
; Context:	Often called by an object's MSG_SPEC_BUILD handler, will also
;		be called by MSG_GEN_ADD_GEOMETRY_HINT or MSG_GEN_REMOVE_-
;		GEOMETRY_HINT so that hints can be rescanned by the specific
;		UI object.
; Source:	Anyone
; Destination:	Any VisClass object marked VTF_IS_GEN
; Interception:	Not usually intercepted.
; 
; Pass:		cl -- VisOptFlags to mark invalid
;		dl -- VisUpdateMode
; Return:	nothing
; 		ax, cx, dx, bp -- destroyed
;

MSG_SPEC_UPDATE_SPECIFIC_OBJECT		message
; 
; Used internally by generic objects to update their specific representation.
;
; Context:	Called by generic object when an update is needed.
; Source:	Any generic object.  Shouldn't be called by outside sources.
; Destination:  Same as source
; Interception:	Shouldn't be intercepted.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_RECREATE_CACHED_GSTATES		message
; 
; Have object destroy and recreate any cached gstates it has.
;
; Context:	Varied. For example, in the grobj, when a vis object
;		is moved, resize, rotated, etc, any cached gstates
;		it has will no longer map to the correct place in
;		the document. So at the end of these operations
;		the grobj sends this message to the vis object.
; Source:	Unrestricted
; Destination:  Any vis object
; Interception:	There is no default behaviour, so any object that.
;		caches a gstate must provide its own handler.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_LAYER_INSERT_OR_DELETE_SPACE	message
;
;	Insert or delete space in/from vis layer
;
; Context:	Vis Layer Utility. For example, when a column is
;		resized in the spreadsheet it needs to send
;		this message to the graphic layer.
; Source:	Unrestricted
; Destination:	Unrestricted
; Interception:	There is no default behaviour.
;
;PASS
;	ss:bp  - InsertDeleteSpaceParams
;
;RETURN
;	nothing
;
;DESTROYED:
;	ax
;
;	The point represents the upper left of the operation
;	The operation is an insert if the space is positive.
;	The operation is a delete if the space is negative.
;	You cannot have an insert in one dimension and a delete
;	in the other dimension.
;	The area affected by the operation hangs down and to the right
;	from the point and its magnitude the absolute value of the 
;	height and width of the space.
;	The horizontal section extends all the way to the right of 
;	the document and the vertical section extends all the way 
;	to the bottom of the document.

;Point->.---------->   \
;	|xxxxxxxxxx     } |space y|
;	|xx-------->   /
;	|xx|
;	|xx|
;	|xx|
;	v  v
;	\ /
;	 |
;    |space x|
;	 
;	Each object contains three permissions bits for insert and 
;	delete space operations: Move, Resize and Delete. The actions
;	specificed in the InsertAndDeleteSpaceTypes will not be
;	performed if the corresponding permission bit is not set.
;

InsertDeleteSpaceTypes	record
	:11				;force to word size
	;Move objects that are in the deleted space by the ammount of
	;space being deleted
	IDST_MOVE_OBJECTS_INSIDE_DELETED_SPACE_BY_AMOUNT_DELETED:1
	;Move objects that intersect the deleted space so that their left and
	;top are aligned with the left and top of the deleted space
	IDST_MOVE_OBJECTS_INTERSECTING_DELETED_SPACE:1	
	;If inserting space and line extending down and/or to right from
	;insert point intersects object then add inserted space to size
	;of object. 
	;If deleting space and deleted space intersects object then
	;remove space from object. Object can be shrunk to zero width and
	;height.
	IDST_RESIZE_OBJECTS_INTERSECTING_SPACE:1
	;if object is shrunk to zero width OR height during delete space
	;then delete it.
	IDST_DELETE_OBJECTS_SHRUNK_TO_ZERO_SIZE:1
	;If inserting space and object is below and or to right of insert
	;point then move object down and right the amount of inserted space. 
	;If deleting space and object is below or to right of deleted space
	;then move object up and to left the amount of the deleted space.
	;In most uses of this message, this bit will be set.
	IDST_MOVE_OBJECTS_BELOW_AND_RIGHT_OF_INSERT_POINT_OR_DELETED_SPACE:1
InsertDeleteSpaceTypes	end

InsertDeleteSpaceParams	struct
    IDSP_position	PointDWFixed
    IDSP_space		PointDWFixed
    IDSP_type		InsertDeleteSpaceTypes
InsertDeleteSpaceParams	ends

MSG_VIS_CREATE_CACHED_GSTATES		message
; 
; Many complex vis objects, such as VisText and VisSpline have a cached gstate
; and a reference count. When the reference count transistions from 0 to 1
; a gstate is created and with it transistions from 1 to 0 the gstate is
; destroyed. This handler increments the reference count for the vis 
; objects cached gstate.
;
; Context:	Varied. For example, the grobj uses it to
;		force the text object to keep its cached gstate
;		during resize so that the text object won't
;		create a gstate on every ptr event.
; Source:	Unrestricted
; Destination:  Any vis object
; Interception:	There is no default behaviour, so any object that.
;		caches a gstate must provide its own handler.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_VIS_DESTROY_CACHED_GSTATES		message
; 
; Many complex vis objects, such as VisText and VisSpline have a cached gstate
; and a reference count. When the reference count transistions from 0 to 1
; a gstate is created and with it transistions from 1 to 0 the gstate is
; destroyed. This handler decrements the reference count for the vis 
; objects cached gstate.
;
; Context:	Varied. For example, the grobj uses it to
;		force the text object to keep its cached gstate
;		during resize so that the text object won't
;		create a gstate on every ptr event.
; Source:	Unrestricted
; Destination:  Any vis object
; Interception:	There is no default behaviour, so any object that.
;		caches a gstate must provide its own handler.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
	
;---------------------------------------------------		
; 	Spec UI update messages (MOVE)
;---------------------------------------------------

MSG_SPEC_VIS_OPEN_NOTIFY	message
MSG_SPEC_VIS_CLOSE_NOTIFY	message
;
; These messages are sent by VisOpen/VisClose if GA_NOTIFY_VISIBILITY is set
; to allow the specific UI to implement the visibility notification
; mechanism.
;
; Pass: none
; Return: none

MSG_SPEC_GET_MENU_CENTER		message
;
; Internal specific UI message for querying for the moniker centers at the
; start of geometry.
;
; Context:	Called during geometry updates of a menu.
; Source:	Unrestricted
; Destination:  Any vis object
; Interception:	Subclassed on an object-by-object basis in the specific UI.
;		It would be unusual to subclass it further.
;
; Pass:		cx -- widest menu item moniker found so far
;		dx -- widest keyboard accelerator found so far.
;		bp -- non-zero if any menu item found so far has valid geometry
; Return:	cx, dx, bp -- possibly updated
;		ax, -- destroyed
;

MSG_SPEC_UPDATE_KBD_ACCELERATOR		message
; 
; Sent in response to a MSG_GEN_SET_KBD_ACCELERATOR.  Performs a visual fixup
; of the object.
;
; Context:	Specific UI utility
; Source:	Unrestricted
; Destination:  Any generic VisClass object
; Interception: Unlikely
;
; Pass:
;	dl	- VisUpdateMode
; Return:
;	nothing
;	ax, cx, dx, bp -- destroyed
;

MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD			message
;
; Performs all the functionality of MSG_VIS_ADD_CHILD, but it also increments the 
; in use count of the child so that it cannot be discarded. This is particularly
; important for the highest object in a vis tree that is saved to the file.
; This object must be added to the content/document when the file is opened, but
; you don't want to dirty the object because then the file would be dirty as
; soon as you opened it. However, if the object is not dirtied, it could be
; discarded and you would lose the pointer to the document/content object.
;
; If you add an object with this message you must remove it with either
; MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD or MSG_VIS_REMOVE_NON_DISCARDABLE
;
; Context:	Vis utility. See description above
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx - child object to add
;		bp - flags for how to add child (CompChildFlags)
;		CCF_MARK_DIRTY flag is ignored.
; Return:	nothing
;		cx, dx - unchanged
;		ax, bp - destroyed

MSG_VIS_REMOVE_NON_DISCARDABLE_VM_CHILD			message
;
; Performs all the functionality of MSG_VIS_REMOVE_CHILD, but should be used in
; conjunction with MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD. Decrements the in use count
; that was incremented in MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD.
;
; Context:	Vis utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		^lcx:dx - child object to remove
; Return:	nothing
;		cx, dx - unchanged
;		ax, bp - destroyed


MSG_VIS_REMOVE_NON_DISCARDABLE			message
;
; Performs all the functionality of MSG_VIS_REMOVE, but should be used in
; conjunction with MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD. Decrements the in use count
; that was incremented in MSG_VIS_ADD_NON_DISCARDABLE_VM_CHILD.
;
; Context:	Vis utility
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		dl - VisUpdateMode
; Return:	nothing
;		ax,cx,dx, bp - destroyed

MSG_VIS_INVAL_ALL_GEOMETRY			message
;
; A brute force invalidate of all geometry under this object (every object's
; geometry is marked invalid.)
;
; Context:	Desperation
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		dl - VisUpdateMode
; Return:	nothing
;		ax,cx,dx, bp - destroyed
;

MSG_SPEC_GUP_QUERY				message
;
; Specific-UI internal version of MSG_GEN_GUP_QUERY.
; Has a default VisClass handler to pass on to generic parent
; (may only be used on generic objects)  Parameters, use
; same as MSG_GEN_GUP_QUERY.
;

MSG_SPEC_RESET_SIZE_TO_STAY_ONSCREEN		message
;
; Resets geometry like MSG_VIS_RESET_TO_INITIAL_SIZE, but is specifically
; doing it as a result of the specific UI trying to make a window fit onscreen.
; Specific UI objects subclass this to aid in this process.
;
; Context:	Sent through visual branch by the specific UI.
; Source:	Unrestricted
; Destination:  Any VisClass object
; Interception: Unlikely
;
; Pass:		dl - VisUpdateMode
; Return:	nothing
;		ax,cx,dx, bp - destroyed
;

protominor LegosLooksSupport

MSG_SPEC_SET_LEGOS_LOOK	message
;	Set the look of a legos component.
;
; Context:	This will most likely be subclassed and used by a SpecUI
;		class which keeps track of its current look in SpecUI
;		instance data.  That way it will know what look it is
;		changing from and be able to delete hints correctly, then
;		add new hints for the new look.
;
; Source:	The component sends this to itself to change its look
; Destination:  
; Interception: Most likely the SpecUI class.
;
; Pass:		cl	- legos look
; Return:	carry	= set if old or new look was invalid (new look not set)
;			= clear if looks were valid, (new look set)
; Destroyed:	nothing
;

MSG_SPEC_GET_LEGOS_LOOK	message
;	Get the legos look of a component.
;
; Context:	
; Source:	
; Destination:  
; Interception: The SpecUI class that stores the look.
;
; Pass:		nothing
; Return:	cl	- legos look
;


protoreset


protominor UINoInputDestination

MSG_SPEC_NO_INPUT_DESTINATION	message
;
; Sent to composite object if there's no child to forward input message
; to.
;
; Pass:		cx, dx = mouse position
;		bp = input message
;

protoreset


;-------------------------------------------------
;		Generic Branch Info record
;-------------------------------------------------
;
; The following record is returned by the routine VisGetGenBranchInfo:
;

GenBranchInfo	record 
	GBI_USABLE:1
	; cleared if any generic parent found that is not usable

	GBI_BRANCH_MINIMIZED:1
	; set if in a branch which the specific UI has set the
	; SA_BRANCH_MINIMIZED in.  (Only valid if GBI_USABLE is set)

	:14

GenBranchInfo	end 

		

;------------------------------------------------------------------------------
;		Specific Size specification structures
;------------------------------------------------------------------------------
;
;	In order to allow general size specification for various UI
; elements, such as views, text areas, & scrolling lists, etc., we
; provide the concept of a "SpecSizeSpec", or "Specific Size Specification"
; word.  This word is comprised of a data type & a data value, which 
; contain highly typed-info, designed to allow high-level concepts
; such as percentage in the specification of a size.  Any "SpecSizeSpec"
; word may be converted into an actual integer which represents pixels
; by calling VisConvertSpecVisSize.  Some generic objects may have
; several pieces of data which are each SpecSizeSpec's - for instance,
; a view will have one for height, & one for width.   
;
SpecSizeType 				etype byte

SpecSizeSpec	record	SSS_TYPE SpecSizeType:6, SSS_DATA:10
;
; SSS_TYPE	- see SpecSizeType below
; SSS_DATA	- 10 bits of data, whose type is based on the SSS_TYPE
;		  portion of the record.
;
;
; SpecSizeType - note that this field is actually only 6 bits wide,
; & therefore we may only have 63 types.  
;
					
SST_PIXELS 				enum SpecSizeType
; 		  Size in pixels. This can be 1 through 1023.  This
;		  also may imply that it's an already converted desired
;		  size.  (0 is legal when used with HINT_CUSTOM_CHILD_SPACING).
SST_COUNT 				enum SpecSizeType
;		  This type is not a "size" type proper, and is the
;		  only exception to the general rule that
;		  Any SpecSizeSpec word may be converted by
;		  VisConvertSpecSizeSpec (Which will FATAL_ERROR if
;		  passed this).  This is offered because some generic
;		  objects would like to provide a "Count" option in
;		  addition to having an actual distance.  An example
;		  is a scrolling list, where we want to have both
;		  a SpecSizeSpec to indicate the height of each moniker,
;		  & one more to indicate how tall we want the scrolling
;		  list to be.  A nice option for how tall the scrolling
;		  list should be is to provide a "count" of how many
;		  list entries we'd like to display.
SST_PCT_OF_FIELD_WIDTH 		enum SpecSizeType
; 		  Percentage of screen width, where
;		  10-bit value is a fraction, which is multiplied by
;		  the width of the screen.
;		  For a list of predefined fractions, see below
;		  If you wish to calculate your own fraction, use a 
;		  10-bit value, where each bit has the fractional value:
;	 	  Bn = 2 ^ -n, where n = bit position
;		  MSB = 1, LSB = 10
SST_PCT_OF_FIELD_HEIGHT 	enum SpecSizeType
; 		  Percentage of screen height.
			PCT_0	equ	0000000000b
			PCT_5	equ	0000110011b
			PCT_10	equ	0001100110b
			PCT_15	equ	0010011001b
			PCT_20	equ	0011001100b
			PCT_25	equ	0100000000b
			PCT_30	equ	0100110011b
			PCT_35	equ	0101100110b
			PCT_40	equ	0110011001b
			PCT_45	equ	0111001100b
			PCT_50	equ	1000000000b
			PCT_55	equ	1000110011b
			PCT_60	equ	1001100110b
			PCT_65	equ	1010011001b
			PCT_70	equ	1011001100b
			PCT_75	equ	1100000000b
			PCT_80	equ	1100110011b
			PCT_85	equ	1101100110b
			PCT_90	equ	1110011001b
			PCT_95	equ	1111001100b
			PCT_100	equ	1111111111b
SST_AVG_CHAR_WIDTHS 		enum SpecSizeType
; 			Data is # to multiply times the 
;			width of the average character in the
;			set of the font being used.  This may be 1 to
;			300.
SST_WIDE_CHAR_WIDTHS 		enum SpecSizeType
; 			Data is # to multiply times the 
;			width of the widest character in the
;			set of the font being used.  To be used
;			in cases where we want to ensure that
;			"any 8 characters" for example, could
;			be displayed in the space allocated.  This may
;			be 1 to 200.
SST_LINES_OF_TEXT 		enum SpecSizeType
; 			Data is the # to multiply times the
;			height of a line of text in the font being used.
;			Often set to 1, can be from 1 to 150.
;

SpecWidth	record	SW_TYPE SpecSizeType:6, SW_DATA:10
SpecHeight	record	SH_TYPE SpecSizeType:6, SH_DATA:10
SpecChildCount	record	SCC_DATA:16
	

;------------------------------------------------------------------------------
;		Other desired size hint handling junk
;------------------------------------------------------------------------------
	
;
; This is the structure that is filled in by VisSetupSizeArgs, finding
; all the desired size hints and converting them as appropriate.  You can then
; pass the results to VisApplyInitialSizeArgs, VisApplySizeArgsToWidth, or 
; VisApplySizeArgsToHeight, which limit MSG_VIS_RECALC_SIZE suggested size
; arguments in various ways.  Or do anything else you wish with them.
;
SpecSizeArgs	struct
	SSA_minWidth		sword	;HINT_MINIMUM_SIZE
	SSA_minHeight		sword
	SSA_minNumChildren	sword
	SSA_maxWidth		sword	;HINT_MAXIMUM_SIZE
	SSA_maxHeight		sword
	SSA_maxNumChildren	sword
	SSA_initWidth		sword	;HINT_INITIAL_SIZE
	SSA_initHeight		sword
	SSA_initNumChildren	sword
	SSA_fixedWidth		sword	;HINT_FIXED_SIZE
	SSA_fixedHeight		sword
	SSA_fixedNumChildren	sword
SpecSizeArgs	ends



;------------------------------------------------------------------------------
;		Specific Window Size specification structures
;------------------------------------------------------------------------------
;
;	This structure allows us to represent the generic position or size
;of a windowed object (GenPrimary, GenDisplay, etc). One of these structures
;is used to store each component value (x position, y position, wdith,
;or height) as a ratio of its parent window's (or field's) size.
;Basically, this representation is sign and magnitude, where the magnitude
;has a 4-bit mantissa and a 10-bit fraction.

SpecWinSizeSpec	record
	SWSS_RATIO:1		;TRUE if value is ratio. If FALSE,
				;bits 14-0 contain signed pixel value.
				;(need to extend sign to bit 15)
	SWSS_SIGN:1		;sign of ratio (MUST BE BIT 14)
	SWSS_MANTISSA:4		;integer portion: 0-15
	SWSS_FRACTION:10	;fractional portion: 1/1024 to 1023/1024
				;(Can use Clayton's % constants here)
SpecWinSizeSpec	end

;This structure can be used to store an (x,y) pair, for positions, sizes, etc.

SpecWinSizePair	struct
	SWSP_x	SpecWinSizeSpec
	SWSP_y	SpecWinSizeSpec
SpecWinSizePair	ends


;------------------------------------------------------------------------------
;		Window Position and Size
;------------------------------------------------------------------------------

;This record is used to hold positioning and sizing requests for windowed
;objects. This is mainly a specific-UI concept, but these are defined here
;because the application can pass this info as a hint. This info, together
;with the WinPosSizeState record defined in cwinClass.asm, is used
;at ATTACH, SPEC_BUILD, and WIN_MOVE_RESIZE to decide which positioning
;and resizing behavior to exhibit.

;"Position this window..."

WinPositionType	etype	byte
WPT_AT_RATIO			enum	WinPositionType
		;Place this window at the specified position relative to
		;the parent window. The position information is
		;initially placed in the R_left and R_top fields of the
		;VI_bounds for the object, as the object is INITIALIZED.
		;During SPEC_BUILD, this info is converted from a Ratio
		;to actually coordinates.

WPT_STAGGER			enum	WinPositionType
		;Stagger this window down and to the right of previously
		;staggered windows on this parent object.

WPT_CENTER			enum	WinPositionType
		;Center this window on the parent window.

WPT_TILED			enum	WinPositionType
		;Tile this window with its siblings.
		;WE DON'T KNOW WHAT THIS MEANS YET

WPT_AT_MOUSE_POSITION		enum	WinPositionType
		;Place the top-left corner of this window where the mouse
		;pointer is. If the system has no mouse, the window is centered
		;on the parent window.

WPT_AS_REQUIRED			enum	WinPositionType
		;RESERVED for specific-UI use. Means that this window will
		;be positioned by the specific UI when and where it wants.
		;Used for menus, since they appear below their menu button.

WPT_AT_SPECIFIC_POSITION	enum	WinPositionType
		;RESERVED for specific-UI use. Means that this window will be
		; positioned at an exact pixel position. This is used by the
		; UI to restore the position of the floating keyboard. 

;"Size this window..."

WinSizeType	etype	byte
WST_AS_RATIO_OF_PARENT			enum	WinSizeType
		;This can be used to open a window a specific size. The size
		;information is initially placed in the R_right and R_bottom
		;fields of the VI_bounds of the object, as the object is
		;initialized. During SPEC_BUILD, this info is converted from
		;a Ratio to actually pixel-distance.

WST_AS_RATIO_OF_FIELD			enum	WinSizeType

WST_AS_DESIRED				enum	WinSizeType
		;Size the window according to its contents.

WST_EXTEND_TO_BOTTOM_RIGHT		enum	WinSizeType
		;This means size the window so that its bottom right corner is
		;at the same position on the screen as the bottom right corner
		;of the parent window.

WST_EXTEND_NEAR_BOTTOM_RIGHT		enum	WinSizeType
		;This means size the window so that its bottom right corner is
		;a fixed margin away from the bottom right corner of the parent
		;window. The margin is determined by the specific UI. CUA
		;uses this to open staggered GenPrimary windows which do
		;not cover the icon area at the bottom of the screen.

;"Constrain this window"...

WinConstrainType	etype	byte
WCT_NONE			enum	WinConstrainType
			;do not constrain window to parent. Allow complete
			;clipping of window area by parent window.

WCT_KEEP_PARTIALLY_VISIBLE	enum	WinConstrainType
    			;ensure that this window is at least partially
			;visible within its parent AT ALL TIMES. In Motif,
			;this means make sure the title bar is accessible.

WCT_KEEP_VISIBLE		enum	WinConstrainType
    			;ensure that this window is completely
			;visible within its parent AT ALL TIMES.

WCT_KEEP_VISIBLE_WITH_MARGIN	enum	WinConstrainType



WinPosSizeFlags	record

    ;this must line up with WPSS_HAS_STATE.

    WPSF_PERSIST:1	;TRUE for window to maintain its state (position, size,
   			;staggered slot #) when closed or DETACHed.
			;If FALSE, the window will revert back to the specified
			;position and size preferences (see below) when the
			;window is re-opened.
			;NOTE: could nuke this by adding HINT_DONT_PERSIST hint.

    WPSF_HINT_FOR_ICON:1
			;TRUE if this record is part of a hint for a GenPrimary
			;or GenDisplay, and the hint is intended for the
			;icon object.
			;NOTE: could nuke this by creating separate hint

    WPSF_NEVER_SAVE_STATE:1
			;TRUE for objects that NEVER should have state saved
			;when closed, such as menus. Overrides PERSIST.

    WPSF_SHRINK_DESIRED_SIZE_TO_FIT_IN_PARENT:1
			;can be set TRUE in objects where WPSF_SIZE_TYPE = 
			;WST_AS_DESIRED. After geometry has determined DESIRED
			;size of window, if right side or bottom portion of
			;window is not visible in parent window, this window
			;will be resized to fit.
    :4			;unused field.

    ;these three fields must be in the lower byte of this record

    WPSF_CONSTRAIN_TYPE WinConstrainType:2
			;which constraint algorithm to use (keep inside, etc)

    WPSF_POSITION_TYPE WinPositionType:3
			;if KEEP_POS_SIZE is FALSE or window has not
			;been moved/resized, this field indicates what position
			;algorithm should be used. See enum. type above.

    WPSF_SIZE_TYPE WinSizeType:3
			;if KEEP_POS_SIZE is FALSE or window has not
			;been moved/resized, this field indicates what sizing
			;algorithm should be used. See enum. type above.
WinPosSizeFlags	end

if 0
;Here are some common position/size combinations:

WPSF_STAGGER_MASK = \
	   mask WPSF_KEEP_VISIBLE \
	or mask WPSF_KEEP_POS_SIZE_AFTER_MOVE_RESIZE \
	or (WPT_STAGGER shl offset WPSF_POSITION_TYPE) \
	or (WST_AS_DESIRED shl offset WPSF_SIZE_TYPE)
	;for OpenLook staggered GenPrimary windows.

WPSF_STAGGER_LIMIT_NEAR_PARENT_MASK = \
	   mask WPSF_KEEP_VISIBLE \
	or mask WPSF_KEEP_POS_SIZE_AFTER_MOVE_RESIZE \
	or (WPT_STAGGER shl offset WPSF_POSITION_TYPE) \
	or (WST_EXTEND_NEAR_BOTTOM_RIGHT shl offset WPSF_SIZE_TYPE)
	;for CUA/Motif staggered GenPrimary windows.

WPSF_STAGGER_LIMIT_TO_PARENT_MASK = \
	   mask WPSF_KEEP_VISIBLE \
	or mask WPSF_KEEP_POS_SIZE_AFTER_MOVE_RESIZE \
	or (WPT_STAGGER shl offset WPSF_POSITION_TYPE) \
	or (WST_EXTEND_TO_BOTTOM_RIGHT shl offset WPSF_SIZE_TYPE)
	;for CUA/Motif staggered GenPrimary windows.

WPSF_MAXIMIZE_MASK = \
	   (WPT_AT_RATIO shl offset WPSF_POSITION_TYPE) \
	or (WST_EXTEND_TO_BOTTOM_RIGHT shl offset WPSF_SIZE_TYPE)
			;be sure to pass position = (0,0) pixels.

WPSF_MAKE_LARGE_MASK	= \
	   (WPT_AT_POSITION shl offset WPSF_POSITION_TYPE) \
	or (WST_EXTEND_NEAR_BOTTOM_RIGHT shl offset WPSF_SIZE_TYPE)
			;be sure to pass position = (0,0) pixels.

WPSF_CENTER_MASK = \
	   (WPT_CENTER shl offset WPSF_POSITION_TYPE) \
	or (WST_AS_DESIRED shl offset WPSF_SIZE_TYPE)
endif


			
			

;-------------------------------------------------
;		Display scheme messages
;-------------------------------------------------
;
; A DisplayScheme holds information regarding how UI gadgets should be
; drawn.  Its use is specific to each SPUI, but is general used as defined
; below.  The DisplayScheme is stored in GState private data when
; MSG_VIS_VUP_CREATE_GSTATE is handled by the Specific UI (SPUI).
; Applications should ignore this data, as its meaning will be different
; across different specific UI's.  Current parameters are:
;
;	Color scheme - The color indecies for the light and dark colors in
;		       the color scheme
;	Font and point size - The standard font and point size to use.  The
;			      point size is also a general indicator of the
;			      desired size of UI elements
;	Display type - Value of type DisplayType that denotes the type of
;		       video display
;

ColorScheme	record	CS_lightColor Color:4, CS_darkColor Color:4

;
; DisplayScheme.  fontId & pointSize conveniently set up so they'll be
; in registers cx:dx, to conform to graphics routines.
;
DisplayScheme	struct
    DS_colorScheme	byte			;passed in al
    DS_displayType	DisplayType		;passed in ah
    DS_lightColor	byte			;passed in bl
    DS_darkColor	byte			;passed in bh
    DS_fontID		FontID			;passed in cx
    DS_pointSize	sword			;passed in dx
DisplayScheme	ends

;DS_unused	equ	<{word}DS_lightColor>

;------------------------------------------------------------------------------
;	End of specific UI implementation
;------------------------------------------------------------------------------
	
	
	



;------------------------------------------------------------------------------
;		Visual Monikers
;------------------------------------------------------------------------------
;Visual monikers are the graphics strings (or null-terminated text strings)
;used to represent objects.  Requirements of visual monikers are:
;	* The gstring must be position independent (thus they must use drawing
;	  commands that work relative to the pen position).
;	* The gstring must return the graphics state unchanged except for the
;	  pen position which can be destroyed

VMStyle		etype byte	;MAX 16 VALUES! (See below)
VMS_TEXT		enum VMStyle	; normal text moniker
VMS_ABBREV_TEXT		enum VMStyle	; abbreviated text moniker i.e. a short
					; textual description rather than the
					; full title.  Used for name under icon
					; of an iconified primary.
VMS_GRAPHIC_TEXT	enum VMStyle	; textual gstring
VMS_ICON		enum VMStyle	; normal gstring moniker
VMS_TOOL		enum VMStyle	; moniker for a tool, normally smaller
					; than a standard moniker

;This structure serves a dual-purpose for Visual Monikers:
;	1) This record is the first of three words that make up a
;	   VisMonikerListEntry. Using this information, VisFindMoniker
;	   (called by the specific UI) can traverse a VisMonikerList to find
;	   the appropriate VisMoniker to use for a specific object drawn on a
;	   specific display.
;
;	2) The lower byte of this record is the first byte of a
;	   VisMoniker. This is a trick so that the VMLET_MONIKER_LIST field is
;	   in the first byte of a VisMoniker and a VisMonikerList.
;	   This allows the .UI file to provide VMs and VMLs interchangeably
;	   (with VMLET_MONIKER_LIST clear for VMs and set for VMLs);
;	   When a generic UI object is VIS_BUILT, the specific UI will
;	   see whether a VM or VML is given for the object. If it is a
;	   VML, the specific UI will call VisFindMoniker to scan the list
;	   and replace the list with the single VM which is to be used.

;IMPORTANT: the two structures below must match! (See above).
;WARNING: update the UIC compiler if you change this list.

VisMonikerListEntryType record
	:2,			;unused field
	VMLET_GS_SIZE DisplaySize:2,
				;- if is a GString, size of moniker. See
				;win.def.
	VMLET_STYLE VMStyle:4,	;style of this moniker
	;byte-align here
	;bits below must match VisMonikerType
	VMLET_MONIKER_LIST:1,	;The UIC compiler always sets this if flag,
				;indicating that this record is within a
				;VisMonikerListElement, not the actual
				;VisMoniker itself.
	VMLET_GSTRING:1,	;- TRUE if this moniker is a graphics string
				;(VisMonikerGString). If false, this moniker is
				;text (VisMonikerText).
	VMLET_GS_ASPECT_RATIO DisplayAspectRatio:2,
				;- if is a GString, aspect ratio of GString.
				;See win.def.
	VMLET_GS_COLOR DisplayClass:4
				;- if is a GString, color requirements of
				;GString. See win.def.
VisMonikerListEntryType end

	if (offset VMLET_GS_ASPECT_RATIO ne offset DT_DISP_ASPECT_RATIO)
	ErrMessage <VisMonikerListEntryType must match DisplayType>
	endif
	if (offset VMLET_GS_COLOR ne offset DT_DISP_CLASS)
	ErrMessage <VisMonikerListEntryType must match DisplayType>
	endif
	if (mask VMLET_MONIKER_LIST ne 0x0080)
	ErrMessage <VMLET_MONIKER_LIST must be bit 7 of VisMonikerListEntryType. See UIC.>
	endif

VisMonikerType record
	VMT_MONIKER_LIST:1,	;The UIC compiler always clears this flag,
				;indicating that this record is within a
				;VisMoniker.
	VMT_GSTRING:1,		;- TRUE if this moniker is a graphics string
				;(VisMonikerGString). If false, this moniker is
				;text (VisMonikerText).
	VMT_GS_ASPECT_RATIO DisplayAspectRatio:2,
				;- if is a GString, aspect ratio of moniker:
				;See win.def.
	VMT_GS_COLOR DisplayClass:4
				;- color requirements of GString. See win.def.
VisMonikerType end

	if (offset VMLET_MONIKER_LIST ne offset VMT_MONIKER_LIST)
	ErrMessage <VMLET_MONIKER_LIST must be same bit as VMT_MONIKER_LIST!>
	endif
	if (offset VMLET_GSTRING ne offset VMT_GSTRING)
	ErrMessage <VMLET_GSTRING must be same bit as VMT_GSTRING!>
	endif
	if (offset VMLET_GS_ASPECT_RATIO ne offset VMT_GS_ASPECT_RATIO)
	ErrMessage <VisMonikerListEntryType must match VisMonikerType>
	endif
	if (offset VMLET_GS_COLOR ne offset VMT_GS_COLOR)
	ErrMessage <VisMonikerListEntryType must match VisMonikerType>
	endif

;
; This structure defines the data at VM_data, for text monikers.
;
VisMonikerText	struct
	VMT_mnemonicOffset	byte		;offset to mnemonic, -1 if none
if DBCS_PCGEOS
	VMT_text		label wchar	;start of null-terminated text
else
	VMT_text		label byte	;start of null-terminated text
endif
VisMonikerText	ends
			
;
; This structure defines the data at VM_data, for graphics strings.
;
VisMonikerGString	struct
	VMGS_height		word		;cached gstring height
	VMGS_gstring		label byte	;start of gstring
VisMonikerGString	ends
			
; 
; Standard equate values for VMT_mnemonicOffset field, when field value is
; not an actual offset into the text string:
;
VMO_CANCEL			equ	0fdh	;value for std CANCEL mnemonic
VMO_MNEMONIC_NOT_IN_MKR_TEXT	equ	0feh	;value for mnemonic outside mkr
						;  (the mnemonic char will be
						;  after mkr's null terminator)
VMO_NO_MNEMONIC			equ	0ffh	;value for no mnemonic
			
			

;This structure is used for elements in a VisMonikerList. The list consists
;of any number of these elements inside a chunk.
;WARNING: update the UIC compiler if you change this structure.

VisMonikerListEntry	struct
     VMLE_type		VisMonikerListEntryType <>
						;type of moniker - used during
						;search to find correct moniker
     VMLE_moniker	optr			;OD of VisMoniker
VisMonikerListEntry	ends

;
; The width field in the vis-moniker structure can be set up marked as
; "not calculated" but giving hint information to the specific UI.
;

if PZ_PCGEOS

VisMonikerCachedWidth	record
    VMCW_HINTED:1		;If set then low 15 bits are cache info
    VMCW_PIZZA_KANJI_12:7	;Cached width for Pizza Kanji 12
    VMCW_PIZZA_KANJI_16:8	;Cached width for Pizza Kanji 16
VisMonikerCachedWidth	end

else

VisMonikerCachedWidth	record
    VMCW_HINTED:1		;If set then low 15 bits are cache info
    VMCW_BERKELEY_9:7		;Cached width for Berkeley 9
    VMCW_BERKELEY_10:8		;Cached width for Berkeley 10
VisMonikerCachedWidth	end

endif


;This structure is used to define Visual Monikers. Individual VMs can be
;combined into a list using a VisMonikerList structure (see above).
;WARNING: update the UIC compiler if you change this structure.


VisMoniker	struct
    VM_type	VisMonikerType <>		;low byte of word-record -
						;indicates that this is a
						;moniker and not a list.

    VM_width	word				;cached width of moniker -
						;will be calculated if 0s here
						;and if VMLET_GSTRING bit is 
						;*not* set.  (cached height 
						;kept with GSTRINGs)

    VM_data	label VisMonikerText		;if VMLET_GSTRING bit set in 
    						;VM_type then VisMonikerGString 
						;structure starts here. 
						;Otherwise a VisMoniker
						;Text structure starts here.
VisMoniker	ends

;
; Flags passed to MSG_VIS_CREATE_VIS_MONIKER and MSG_GEN_CREATE_VIS_MONIKER.
;
CreateVisMonikerFlags	record
	CVMF_DIRTY:1		; set to mark new moniker chunk OCF_DIRTY
	:7
CreateVisMonikerFlags	end

;
; Source type information passed to MSG_VIS_CREATE_VIS_MONIKER,
; MSG_GEN_CREATE_VIS_MONIKER and MSG_GEN_REPLACE_VIS_MONIKER.
;
VisMonikerSourceType	etype	byte
VMST_FPTR	enum	VisMonikerSourceType
; Indicates source is referenced by a fptr.  CVMF_source and RVMF_source fields
; are a fptr.

VMST_OPTR	enum	VisMonikerSourceType
; Indicates source is referenced by a optr.  CVMF_source and RVMF_source fields
; are an optr.

VMST_HPTR	enum	VisMonikerSourceType
; Indicates source is referenced by a hptr and offset.  CVMF_source and
; RVMF_source fields are a hptr and offset within the block.

;
; Source data information passed to MSG_VIS_CREATE_VIS_MONIKER,
; MSG_GEN_CREATE_VIS_MONIKER and MSG_GEN_REPLACE_VIS_MONIKER.
;
VisMonikerDataType	etype	byte
VMDT_NULL		enum	VisMonikerDataType
; Indicates that there is no source.  MSG_GEN_REPLACE_VIS_MONIKER will just
; free current vis moniker.  Not valid for MSG_VIS_CREATE_VIS_MONIKER and
; MSG_GEN_CREATE_VIS_MONIKER.  CVMF_source, RVMF_source, CVMF_length,
; RVMF_length, CVMF_width, CVMF_height, RVMF_width, and RVMF_height are unused.

VMDT_VIS_MONIKER	enum	VisMonikerDataType
; Indicates that source is a complete VisMoniker structure.  CVMF_length and
; RVMF_length indicate the size of the complete VisMoniker structure.
; CVMF_width, CVMF_height, RVMF_width, and RVMF_height are unused.

VMDT_TEXT		enum	VisMonikerDataType
; Indicates that source is a text string.  If null-terminated, CVMF_length and
; RVMF_length should be 0.  Otherwise, CVMF_length and RVMF_length indicate the
; length of the text string.  A VisMoniker structure will be created for the
; text string.  CVMF_width, CVMF_height, RVMF_width, and RVMF_height are unused.

VMDT_GSTRING		enum	VisMonikerDataType
; Indicates that source is a graphics string.  If CVMF_length and RVMF_length
; are 0, the gstring length will be determined by scanning the graphics string
; for GR_END_STRING.  Otherwise, CVMF_length and RVMF_length indicate the
; length of the graphics string.  CVMF_width, CVMF_height, RVMF_width and
; RVMF_height indicate the width and height of the graphics string.  If either
; is 0, the width and height will be computed by examining the string.  A
; VisMoniker structure will be created for the graphics string.

VMDT_TOKEN		enum	VisMonikerDataType
; Indicates that source is a GeodeToken.  CVMF_length, RVMF_length, CVMF_width,
; CVMF_height, RVMF_width, and RVMF_height are unused.  The destination object
; must be usable to use this data type because the specific UI must decide
; which moniker to choose from the moniker in the Token Database.

;
; Parameters passed to MSG_VIS_CREATE_VIS_MONIKER and
; MSG_GEN_CREATE_VIS_MONIKER.
;
CreateVisMonikerFrame	struct
	CVMF_source	dword
			; an optr, hptr, or fptr, depending on CVMF_sourceType

	CVMF_sourceType	VisMonikerSourceType
			;CVMF_source is optr, hptr, or fptr

	even		; word align for C

	CVMF_dataType	VisMonikerDataType
			; source is VisMoniker, text string, graphics string,
			; or GeodeToken

	even		; word align for C

	CVMF_length	word
			; byte-size of source; not used for VMST_OPTR; if
			; VMDT_TEXT and RVMF_length is 0, text is
			; assumed to be null-terminated; if VMDT_GSTRING
			; and RVMF_length is 0, length of gstring is computed
			; by scanning gstring

	CVMF_width	word
			; for VMDT_GSTRING, width of graphics string; if 0,
			; width of gstring is computed by scanning gstring

	CVMF_height	word
			; for VMDT_GSTRING, height of graphics string; if 0,
			; height of gstring is computed by scanning gstring

	CVMF_flags	CreateVisMonikerFlags
			; indicate whether to create the new moniker chunk
			; dirty

	even		; word align for C
CreateVisMonikerFrame	ends
				
				
;------------------------------------------------------------------------------
;	Vis/GenDrawMoniker, Vis/GenGetMonikerPos arguments
;------------------------------------------------------------------------------
DrawMonikerArgs 	struct
	DMA_xInset	word		;inset in x axis (left or right)
	DMA_yInset	word		;inset in y axis (top or bottom)
	DMA_xMaximum	word		;maximum width, height to draw if DMF_-
					;  CLIP_TO_MAX_WIDTH is also set.  Clips
	DMA_yMaximum	word		;  the moniker.  Pass MAX_COORD to 
					;  avoid clipping in x or y.
	DMA_gState	hptr.GState	;handle of graphics state
	DMA_textHeight	word		;height of the font we'd use for text
					;  monikers (from passing GFMI_HEIGHT 
					;  and GFMI_ROUNDED), or zero if we 
					;  don't know.  Speeds up various 
					;  calculations.
DrawMonikerArgs		ends

;
; DrawMonikerFlags - Justification and flags for VisDrawMoniker and 
; GenDrawMoniker.  (The justification flags are interchangeable with
; MatrixJustifications.)
; 
DrawMonikerFlags 	record
	DMF_TEXT_ONLY:1,		;set if we can only draw a text moniker
					;  on this object.
	DMF_UNDERLINE_ACCELERATOR:1,	;underlines accelerator key if set
	DMF_CLIP_TO_MAX_WIDTH:1, 	;causes the moniker to be clipped
					;  to the drawMkrMaxWidth.
	DMF_NONE:1			;TRUE to draw at current pen pos.
	DMF_Y_JUST:2=Justification,	;y justification
	DMF_X_JUST:2=Justification	;x justification
DrawMonikerFlags	end
			
;This record is passed to the GenFindMoniker or VisFindMoniker routines
;(along with a DisplayType) to specify what type of moniker to find in a
;VisMonikerList.  See VisTestMoniker for how this search is conducted.

VisMonikerSearchFlags record
	VMSF_STYLE VMStyle:4,	;preferred style of moniker
	:1,			;unused field

	;------------------------------------------------- COMMANDS ----------
	VMSF_COPY_CHUNK:1,	;- TRUE to copy the VisMoniker chunk 
				;into the specified object block, if the
				;search is successful, and the moniker is not
				;in that block already.

	VMSF_REPLACE_LIST:1,	;- TRUE to replace to VisMonikerList chunk
				;with the VisMoniker, if the search is
				;successful. The idea is that the chunk handle
				;for the list now points to the moniker.
	;------------------------------------------------- END OF COMMANDS ---

	VMSF_GSTRING:1,		;- TRUE if a gstring moniker is expected (i.e.
				;a VisMonikerGString), FALSE if a text moniker
				;is expected (i.e. a VisMonikerText).

	:8			;RESERVED FOR INTERNAL USE (do not set)
VisMonikerSearchFlags end

VMSF_TEXT_MASK	equ	0	;use when passing VisMonikerSearchFlags=0
				;to VisFindMoniker
					
MonikerMessageParams struct
	MMP_xInset		word
	; The x inset to the start of where to draw the moniker, if top or
	; bottom justifying.
	
	MMP_yInset		word
	; The y inset to the start of where to draw the moniker, if left or
	; right justifying.
	
	MMP_xMaximum		word
	MMP_yMaximum		word
	; The maximum size of the moniker, if VMF_CLIP_TO_MAXIMUM_WIDTH
	; is set in the monikerFlags.  Moniker will be clipped to that width.
	
	MMP_gState		hptr.GState
	; GState to use to draw the moniker (typically passed into MSG_VIS_DRAW)
	
	MMP_textHeight		word
	; If we happen to know the height of the system text, we should pass
	; it here for speed, or else pass 0.

	;fields above this must be the same as the DrawMonikerArgs structure
	
	MMP_visMoniker		lptr.VisMoniker
	; The vis moniker itself.  In the message versions, the moniker must
	; be in the same block as the object.
	
	MMP_monikerFlags	DrawMonikerFlags
	; Various justification and miscellanious flags for drawing the moniker.
	
MonikerMessageParams ends

;------------------------------------------------------------------------------
;	VarData for VisClass
;------------------------------------------------------------------------------

TEMP_VIS_OLD_BOUNDS		vardata		Rectangle
;	Used to save old bounds for an object during the update mechanism.
;	The data hopefully can be purged after we are done.  
;	argument of size Rectangle.
;
	
VarGeoData	struct
	VGD_lineWidth		word
	VGD_centerOffset	word
	VGD_secondWidth		word
VarGeoData	ends
	
ATTR_VIS_GEOMETRY_DATA	vardata		VarGeoData
	;Added and removed by the geometry manager as needed.  Keeps track
	;of some internal variables for some of the more complex features
	;in the geometry manager.
		
TEMP_VIS_INVAL_REGION	vardata		lptr
	;Keeps the chunk handle of an invalidation region for a win group.
	;Takes an hptr argument.


protoreset

protominor UINewForResponder


ATTR_SPEC_POSITION	vardata		Point
ATTR_SPEC_POSITION_X	vardata		sword
ATTR_SPEC_POSITION_Y	vardata		sword
	;Internal only, allows position hints to be used by specific UI's
	; on non-generic specific objects.
	
protoreset


;------------------------------------------------------------------------------
;	Instance Variables
;------------------------------------------------------------------------------

;
; VisAttrs	- general purpose visible state flags.   These flags are
;		alterable via MSG_VIS_SET_ATTRS.  Some of these possibly
;		belong in another variable.
;
VisAttrs		record 
	VA_VISIBLE:1 
; 		VA_VISIBLE - For WIN_GROUP's only. (Ignored if non-WIN-GROUP 
;		object)  Set if object may be visually built out, meaning that
; 		it is allowed to be linked visually into a composite, and if 
;		that composite is realized, then it would be made visible, too.
;
	VA_FULLY_ENABLED:1
;		Flag to tell whether a vis object is enabled or not.  If cleared
;		visual objects typically don't allow clicks and are drawn in a
;		50% pattern, even if they're not generic.
;		Set by MSG_SPEC_BUILD, MSG_SPEC_NOTIFY_ENABLED, and
;		MSG_SPEC_NOTIFY_NOT_ENABLED in generic objects.

	VA_MANAGED:1 
; 		set if object is managed, that is, space is reserved
; 		for it in the composite via the geometry manager.
; 		set if no space should be allocated for it.  A message will 
;		allow this status to change, & if the window on which this 
;		object is placed is realized, then we must have the geometry 
;		manager redo the geometry.
;
	VA_DRAWABLE:1
; 		set if object is drawn, set if invisible.  A message will
; 		allow setting of this flag.  If the window on which this object
;		resides is realized when this happens, the bounding box of the 
;		object will be invalidated on that window.
;
	VA_DETECTABLE:1
; 		set if object might respond to mouse, ptr, kbd,
; 		etc. data.  set if composite shouldn't bother to send such data
; 		onto the child.  This bit will only be tested when a composite 
;		is passing a message down to its children.  Display only objects
;		should have this bit clear.  The message allowing changing of 
;		this bit will NOT change any grab in progress on the object.  
;		NOTE that a window composite MAY NOT have this bit clear.  
;		Basically, we can't avoid an implied grab to a window.
;
	VA_BRANCH_NOT_MINIMIZABLE:1
;		For Generic objects only  (Would be a SpecAttrs if room)
;		Used to keep modal windows up on screen even if they are generic
;		children of a primary which is minimized. 
		
	VA_OLD_BOUNDS_SAVED:1		
;		(Would be in optFlags or geoFlags if room)
;		Flag to keep track of whether old bounds have been saved for
; 		the object by the geometry manager for use by the invalidation
;		mechanism.  Bounds are kept in variable data type VVDT_OLD_-
;		BOUNDS.
;
	VA_REALIZED:1
; 		set by default VisOpen & VisClose messages to indicate if
; 		object is realized (visible within a window) onscreen or not.  
;		Is also used to ensure that all objects receive a VisOpen, 
;		even if the visible part of the tree has just been added to a 
;		branch that is already realized, & then updated -- this should 
;		all be done in one operation, without delaying the update -- & 
;		the top object of the branch to be realized should be
; 		marked as "WINDOW_INVALID", even if it is a non-windowed object,
;		as the MSG_UPDATE_WINDOWS will follow the path bits & figure
;		out that the object needs to be sent a MSG_VIS_OPEN.
; 		May NOT be set by MSG_VIS_SET_ATTR.
;
VisAttrs		end

;
; Initial state set by VisInitialize for VisAttrs, to match default values:
;
VA_INITIAL_BITS = mask VA_MANAGED or mask VA_DRAWABLE or mask VA_DETECTABLE or \
		  mask VA_FULLY_ENABLED
;



;
;=============================================================================

;
; VisOptFlags
;
VisOptFlags record 
	VOF_GEOMETRY_INVALID:1
; 		set by MSG_VIS_MARK_INVALID, which, if followed by a
; 		MSG_VIS_VUP_UPDATE_WIN_GROUP will insure that changes in the 
;		object bounds will be reflected in the window.
;
	VOF_GEO_UPDATE_PATH:1
; 		set by MSG_VIS_MARK_INVALID to leave a trail to objects
; 		that have invalid geometry, for UPDATE_GEOMETRY to follow.
;
	VOF_IMAGE_INVALID:1
; 		set by MSG_VIS_MARK_INVALID, which, if followed by a
; 		MSG_VIS_VUP_UPDATE_WIN_GROUP will insure that visual changes in 
;		the object will be reflected in the window.
;
	VOF_IMAGE_UPDATE_PATH:1
; 		set by MSG_VIS_MARK_INVALID to leave a trail to
; 		objects that have invalid geometry, for
;		UPDATE_WINDOWS_AND_IMAGE to follow.
;
	VOF_WINDOW_INVALID:1
; 		set by MSG_VIS_MARK_INVALID, which, if followed by a
; 		MSG_VIS_VUP_UPDATE_WIN_GROUP will insure that changes in the 
;		window's view will be reflected in the window.  (valid for 
;		windows only)
;
	VOF_WINDOW_UPDATE_PATH:1
; 		set by MSG_VIS_MARK_INVALID to leave a trail to
; 		windows that have invalid views, for UPDATE_WINDOWS_AND_IMAGE
;		to follow.  (valid for composites only)
;
	VOF_UPDATE_PENDING:1
; 		used for Group windows only, indicates that a
; 		MSG_VIS_UPDATE_WIN_GROUP is still in the UI event queue for this
;		window, & hasn't arrived yet.
;
	VOF_UPDATING:1
; 		set while updating visible branch, so we can give an
; 		error if we get into a nested update situation.  Also may be
;		useful for knowing how to update an object.
VisOptFlags	end

		
; NOTE: Don't change the order of the above bits unless you're willing to
; change VisMarkInvalid.

VOF_PATH_BITS = (mask VOF_GEO_UPDATE_PATH) or (mask VOF_WINDOW_UPDATE_PATH) or (mask VOF_IMAGE_UPDATE_PATH)

VOF_INVALID_BITS = (mask VOF_GEOMETRY_INVALID) or (mask VOF_WINDOW_INVALID) or (mask VOF_IMAGE_INVALID)
		 
;
; Initial state set by VisInitialize for VisOptFlags:
;
VOF_INITIAL_BITS = VOF_INVALID_BITS or VOF_PATH_BITS
		 
;=============================================================================

;
; Geometry manager optimization flags for visual objects
;
VisGeoAttrs record 
	;
	; Geometry state flags, kept here so things are compact.
	;
	VGA_GEOMETRY_CALCULATED:1
;		Set in an after the first time an object's geometry has been
;		calculated.  This is used by the specific UI size hint handlers 
;		to figure out whether an initial size hint should be applied to 
;		an object or not.  This is set at the time an object's size and
;		position has been completely determined.  It can be cleared
;		if need be -- the specific UI clears this in METHOD_GEN_RESET_TO
;		INITIAL_GEOMETRY.
;
	VGA_NO_SIZE_HINTS:1
;		Specific attribute only: if set, we have checked to see if the
;		object has one or more of HINT_INITIAL_SIZE, HINT_MINIMUM_SIZE, 
;		HINT_MAXIMUM_SIZE, HINT_FIXED_SIZE set, and it doesn't.  We
; 		clear this flag if one of the desired size methods are called.
;		
	
	;
	; Miscellanious flags.
	;
	VGA_NOTIFY_GEOMETRY_VALID:1
;		If set, geometry manager will notify object when its geometry
; 		messages have all been finished and its geometry is valid.
;
	VGA_DONT_CENTER:1
;		Allows an object to individually override the parent
;		composite's centering along its width.  Will appear
; 		on the top (of a horizontal composite, left edge if vertical)
;		instead.
;
;
;	Flags that do optimizations to avoid message calls:
;
	VGA_USE_VIS_SET_POSITION:1		
; 		All objects that use the default Vis or VisComp handlers
;		for MSG_VIS_SET_POSITION and MSG_VIS_POSITION_BRANCH should set 
;		this flag.  It's an optimizationn that allows static calls to 
;		the geometry manager.
;
	VGA_USE_VIS_CENTER:1
;		If set, geometry manager uses standard vis or visComp center
; 		message to calculate the object's center.
;
	VGA_ONLY_RECALC_SIZE_WHEN_INVALID:1
; 		set this if your object wants its message
; 		called the first time after its geometry is invalid, and then 
;		always return the current size.  Example:  buttons in a 
;		horizontal composite.  
;
;
;	Flags to avoid built-in optimizations:
;
	VGA_ALWAYS_RECALC_SIZE:1
;		If set, doesn't do optimizations to calculate the size of this
;		object.  May be needed for composites that expand to fit and
;		center their children to match their parent, or
;		some other obscure cases where the size might change from
;		one call to another.
VisGeoAttrs	end
  
  
;=============================================================================

;
; VisTypeFlags - Type of visible object.  Normally set when initialized or
; built.
;
VisTypeFlags	record 
	VTF_IS_COMPOSITE:1
; 		set if object is a VisCompClass and therefore can have
; 		children (although, of course, a composite may at times have no 
;		children)
;
	VTF_IS_WINDOW:1
; 		set if IS_COMPOSITE & creates a window with the window system
; 		in order to display itself & children in.  If set, then the 
;		assumption is made that the window is the size of VI_bounds and
;		therefore messages like DRAW and BUTTON that traverse all 
;		children skip children with this bit set.  Also, the routine 
;		that returns the window handle that a visible object
; 		sits on will return this object's VCI_window if this bit is set.
;		Note that this flag differs subtly from the VTF_IS_PORTAL flag 
;		described below.
;
	VTF_IS_PORTAL:1
;		Set if object has its own window, which is stored
;		elsewhere.  Any visible children appear in that 
;		window.  Object still may have portions which
;		appear in its parents window.  An example is
;		the display control object, which manages several
;	 	child windows inside its own window area.  Its border
;		is drawn in the parent window, and its own window is
;		then inset one pixel from its bounds.
;
; 		The flag has several effects:
; 			* it causes UPDATE_WINDOWS and CLOSE_WIN messages to be
;			  sent to the object
; 			* the optimizations made for VTF_IS_WINDOW are not 
;			  done.  This object gets a DRAW and a BUTTON from its
;			  parent.
; 			* only one of the flags VTF_IS_WINDOW and VTF_IS_PORTAL
;			  can be set at a time.
;
	VTF_IS_WIN_GROUP:1
; 		set for top visible object in a visible branch, which
; 		makes that branch a realizable entity.  Visual updates happen 
;		on whole WIN_GROUP's.  VTF_IS_WINDOW & VTF_IS_COMPOSITE
; 		must be set.
;
	VTF_IS_CONTENT:1
; 		set if the object is basically the output descriptor of
; 		another window object.  VTF_IS_WINDOW and VTF_IS_WIN_GROUP 
;		must also be set.  Has a few subtle differences from a win 
;		group, one being gWin is expected to be stuffed in by the 
;		"parent" object.
;
	VTF_IS_INPUT_NODE:1
;		Basically, an optimization bit which is req'd to receive 
;		certain messages:
;		Set if this object controls input flow for either Kbd or Mouse,
;		such as VisContentClass, or is a focus or target node that
;		is not a WinGroup.  MSG_VIS_VUP_ALTER_INPUT_FLOW's are
;		sent directly to objects having this bit set, unless there
;		is a need for them actually to VUP up through each object (as
;		is the case for mouse grabs in a 32-bit content model)
;		Likewise, MSG_META_MUP_ALTER_FTVMC_EXCL's &
;		MSG_VIS_FUP/VUP_QUERY_FOCUS_EXCL are sent to the first visible
;		object up the tree that is either a WinGroup or has this
;		bit set.

	VTF_IS_GEN:1
; 		set if object has a Generic master part.  This flag must be
;		set for the object to handle "SpecClass" messages such as
;		MSG_SPEC_BUILD.  For optimization reasons, their is no
;		SpecClass subclassed off of VisClass, but one can think of it
;		that way.
;
	VTF_CHILDREN_OUTSIDE_PORTAL_WIN:1
;		only if VTF_IS_PORTAL is set, means that visible children
;		lie in the portal's parent window areas, rather than in the
;		window created by the portal object itself, thus they keep
;		the portal's parent window in the their instance data.
;		An example of this is the pane, whose visual children lie around
;		the outside of the pane's own created window.  A display
;		control, by contrast, has its visual children reside inside
;		its window and thus would not have this flag set.  
;
VisTypeFlags	end
		
;=============================================================================

;
; SpecAttrs - Flags used by Specific UI to implement generic objects
; built.
;
SpecAttrs	record	
	SA_ATTACHED:1
; 		For WIN_GROUP's only (Ignored if non-WIN-GROUP object)
; 		Set for normal operation, clear if application is being 
;		shutdown, & therefore windows should be closed down, even if 
;		the VA_VISIBLE bit is set.
;
	SA_REALIZABLE:1
; 		For WIN_GROUP's only (Ignored if non-WIN_GROUP object)
; 		Set to indicate that the specific UI think's it is OK to 
; 		make this object visual.  It will not be set visual until the 
;		object is also USABLE & ATTACHED.  This is the "specific UI's 
;		vote" for whether or not this WIN_GROUP should appear on screen.
;
	SA_BRANCH_MINIMIZED:1
; 		Set if this generic object is "minimized" & 
; 		specific UI wants to force ALL generic children in the branch 
;		to become non-visible.  If this bit is set, the NO objects in 
;		the generic branch below this point which have WIN_GROUP parts 
;		will be allowed to be visible.
;
	SA_USES_DUAL_BUILD:1
; 		set for objects which behave as both a non-WIN_GROUP
; 		and a WIN_GROUP, & thus require two seperate visible builds in 
;		order to get built.  This is done by allowing it to act as both
;		a WIN_GROUP object, which gets its own SPEC_BUILD, & as a simple
;		object, which will receive a SPEC_BUILD from up above itself in
;		 the hierarchy.
;
	SA_CUSTOM_VIS_PARENT:1
; 		set for generic objects which will not
; 		just be attached visually to their generic parent.  Causes a
; 		MSG_SPEC_GET_VIS_PARENT to be sent out to determine what 
;		visual object the object should be placed on (in the default 
;		MSG_SPEC_BUILD handler)
;
	SA_SIMPLE_GEN_OBJ:1
; 		set for generic objects which become a single visible
; 		object, via the VIS, SPECIFIC, GEN master class scheme.  If 
;		this bit is set, then MSG_GEN_GET_SPECIFIC_VIS_OBJECT need 
;		not sent out to determine what visible object the gen object 
;		has/will become.  is both a generic & visual object.
;
	SA_CUSTOM_VIS_PARENT_FOR_CHILD:1
;		Set for objects who want to use a different visual parent for
;		their generic children than themselves.  If this bit is set,
;		children will send out a MSG_SPEC_DETERMINE_VIS_PARENT_FOR_CHILD
;		to this object.
;
	SA_TREE_BUILT_BUT_NOT_REALIZED:1
;		For WIN_GROUP's only, this bit is set whenever the tree
;		has been specifically built, but is now unrealized.  The object
;		is NOT actually in a visible composite when this bit is
;		set, although it appears this way, since the object is
;		given a one-way visible link upward.  Having a one-way
;		link is far superior to our old message of removing the
;		WIN_GROUP from the visible tree, as this required an
;		exception handling when setting an object immediately
;		under a WIN_GROUP usable, in trying to figure out whether
;		we needed to SPEC_BUILD it right away  (the old message never
;		did work).  This way, if VI_link is non-zero, then the 
;		whole tree (all USABLE objects) is vis-built, & should
;		be maintained that way.  Also, this makes for quicker
;		setting of such a WIN_GROUP to be realized again, as
;		we can just add the object to the parent link stored in
;		VI_link, WITHOUT having to send a recursive
;		MSG_SPEC_BUILD_BRANCH down the tree.
;
	
SpecAttrs	end
	
	
SA_INITIAL_BITS = mask SA_ATTACHED

;=============================================================================

		
;
; NOTE!  The following structure must not be changed, as this would destroy
; the integrity of all existing GeoWrite & GeoDraw documents.  Any change
; must be accompanied by some mechanism to manage different version levels
; of such documents.
;
    VI_bounds		Rectangle <0, 0, 0, 0>	
    	; Bounds of visible object.  Can be set vis MSG_VIS_SET_POSITION and
	; MSG_VIS_SET_SIZE (also VisSetPosition and VisSetSize).  Bounds can
	; be obtained via a MSG_VIS_GET_BOUNDS

    VI_typeFlags	VisTypeFlags 	0
    	; Visible type flags, for setting attributes for things like whether
	; the object has a window, is a composite, win group, content object,
	; etc.  Set vis MSG_VIS_SET_TYPE_FLAGS, gotten via MSG_VIS_GET_TYPE_
	; FLAGS.

    VI_attrs		VisAttrs 	(mask VA_MANAGED or \
    					 mask VA_DRAWABLE or \
					 mask VA_DETERACTABLE or \
					 mask VA_FULLY_ENABLED)
    	; Various state flags for the visible object for whether it's managed,
	; drawable, enabled, visible, detectable, realized, etc.  Set via 
	; MSG_VIS_SET_ATTRS; obtained via MSG_VIS_GET_ATTRS.

    VI_optFlags		VisOptFlags	(mask VOF_GEOMETRY_INVALID or \
    					 mask VOF_GEO_UPDATE_PATH or \
					 mask VOF_IMAGE_INVALID or \
					 mask VOF_WINDOW_INVALID or \
					 mask VOF_WINDOW_UPDATE_PATH or \
					 mask VOF_IMAGE_INVALID or \
					 mask VOF_IMAGE_UPDATE_PATH)
    	; Various flags for keeping track of the invalid drawn, realized, or
	; geometry state of the object.  Cannot be set directly; one must
	; use MSG_VIS_MARK_INVALID to set an object invalid in some way.

    VI_geoAttrs		VisGeoAttrs	0
    	; Vis level geometry manager flags, for whether an object is managed, 
	; various optimizations to speed up geometry handling, etc.  Can
	; be set via MSG_VIS_SET_GEO_ATTRS; obtained via MSG_VIS_GET_GEO_ATTRS.

    VI_specAttrs	SpecAttrs	0
    	; Specific UI attributes, for generic objects only.  Can be set via 
    	; MSG_SPEC_SET_ATTRS; obtained via MSG_SPEC_GET_ATTRS.

    VI_link		LinkPart <>	
    	; Vis link last, so it can be next to composite part in VisComp class.
    	; Holds the visual link to its next sibling. Not accessible directly;
	; use MSG_VIS_ADD_CHILD, MSG_VIS_MOVE_CHILD, MSG_VIS_REMOVE_CHILD
	; to manipulate an object's place in the visual tree.  Use MSG_VIS_
	; GET_PARENT to return the visual parent of the object.


VisClass		endc

EndLibrary	ui
