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

	Copyright (c) GeoWorks 1991 -- All Rights Reserved

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

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

DESCRIPTION:
	Object definitions for VisContentClass.   

	$Id: vCntC.def,v 1.1 97/04/04 14:18:48 newdeal Exp $

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

SetDef	__VCNTC

VisContentClass	class	VisCompClass

;------------------------------------------------------------------------------
;	Messages
;------------------------------------------------------------------------------
	
MSG_VIS_CONTENT_GET_WIN_SIZE	message
.assert (MSG_VIS_CONTENT_GET_WIN_SIZE eq FIRST_VIS_CONTENT_GCN_LIST_TYPE)
;
; 	Returns size of the content's window.
;	
; Context:	Utility
; Source:	No restrictions.
; Destination:  A VisContent
; Interception: Would be unusual.
;
; Pass:		nothing
; Return:	cx, dx -- width, height of content's window
;		ax, bp -- destroyed
;
	
MSG_VIS_CONTENT_SET_ATTRS	message
;
; Sets various attributes for the content object.  It is up to the caller
; to invalidate geometry, etc. themselves if they want some immediate visual
; effect of this change.
;
; Context:	Utility
; Source:	No restrictions.
; Destination:  A VisContent
; Interception: Would be unusual.
;
; Pass:		cl -- bits to set
;		ch -- bits to clear
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
		
MSG_VIS_CONTENT_GET_ATTRS	message
;
; Returns current content attributes.
;
; Context:	Utility
; Source:	No restrictions.
; Destination:  A VisContent
; Interception: Would be unusual.
;
; Pass:		nothing
; Return:	cl -- content attributes
;		ax, ch, dx, bp -- destroyed
	
MSG_VIS_CONTENT_RECALC_SIZE_BASED_ON_VIEW	message
;
; Sends a MSG_VIS_RECALC_SIZE to itself, suggesting either the current size
; or the view size in each direction, depending on VCNA_SAME_WIDTH_AS_VIEW
; and VCNA_SAME_HEIGHT_AS_VIEW.   
;
; Context:	Called by the content's MSG_VIS_UPDATE_GEOMETRY handler, (or
;		by the view's MSG_VIS_RECALC_SIZE handler if the view is
;		following the content's geometry.)
;
; Source:	No restrictions (Usually itself, or the view.)
; Destination:  A VisContent
; Interception: Would be unusual.
;
; Pass:		nothing
; Return:	cx -- width
;		dx -- height
;		ax, bp -- destroyed
;
	
MSG_VIS_CONTENT_HOLD_UP_INPUT_FLOW	message
;
; Increments "hold up input" count, which if non-zero, & MSG_VIS_ISO_
; CONTENT_DISABLE_HOLD_UP has not been called, results in all
; input-related events being queued up, & not "played" until the count
; reaches zero again.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_CONTENT_RESUME_INPUT_FLOW	message
;
; Decrements "hold up input" count.  If count becomes zero, all backed up
; input in the hold-up queue is flushed, or "played".  The handler for
; this routine will fatal error if decremented past zero.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_CONTENT_DISABLE_HOLD_UP		message
;
; Prevents hold-up mechanism from holding up input until
; MSG_VIS_CONTENT_ENABLE_HOLD_UP is called.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_CONTENT_ENABLE_HOLD_UP		message
;
; Allows hold-up mechanism to hold up input again.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_CONTENT_TEST_IF_ACTIVE_OR_IMPLIED_WIN	message
;
; Tests to see if the window handle passed is the same as the
; active or implied window being used to translate button & ptr
; events.  Used by OLPortWindow on the application's IsoContent
; to see if mouse was in actual port window, or whether it was
; just over the port border.
;
; Pass:		bp	- window handle to test against
; Return:	carry	- clear if match
;		ax, cx, dx, bp - destroyed
;

MSG_VIS_CONTENT_UNWANTED_MOUSE_EVENT	message
;
; A mouse event which had no destination, i.e. was being
; sent to a VisMouseGrab which has a null optr stored for 
; the destination object.  This happens if there is no active,
; & no implied mouse grab, most commonly if the ptr has been
; clicked outside of a modal window or outside the visual 
; area of an application.  Default behavior here is to beep,
; but on presses only, and to return flags = 0.
;
; Pass:		cx:dx	- ptr to VisMouseGrab
;		bp	- same as MSG_META_PTR
; Return:	MouseReturnFlags  (MRF_REPLAY & MRF_PREVENT_PASS_THROUGH
;				   only are considered upon return)
;		ax, cx, dx, bp - destroyed

MSG_VIS_CONTENT_UNWANTED_KBD_EVENT	message
;
; Sent on the occassion that a kbd event has arrived at the VisContent, &
; there is no kbd grab set up.  Default behavior is to beep on presses.
;
; Pass:		cx, dx, bp - same as MSG_META_KBD_CHAR
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;		

MSG_VIS_CONTENT_REMOTE_OBJ_MESSAGE_VIA_HOLD_UP_QUEUE	message
;
; Basically the same as MSG_META_REMOTE_OBJ_MESSAGE, but instead
; of being relative to the flow object, is relative to the
; input flow -- i.e. if the input flow is being held up, then
; so will the remote OBJ_MESSAGE.  Since the caller may wish
; to just queue this up with other input, or alternatively
; put this at the front of the input queue for processing,
; the message flags for how to put this method into the
; hold-up queue may be passed.
;
; Pass:	cx      - MessageFlags to be used for putting this onto the hold-up
;                 input queue, if one exists. Should be either:
;                       mask MF_FORCE_QUEUE or mask MF_ON_STACK
;                       -OR-
;                       mask MF_FORCE_QUEUE or mask MF_INSERT_AT_FRONT \
;                                        or mask MF_ON_STACK
;        dx      - size ObjMessageParams
;        ss:bp   - pointer to ObjMessageParams

MSG_VIS_CONTENT_SET_DOC_BOUNDS			message
;
; In the Large document model, this message is used to convey
; information about the document's 32-bit bounds.  The VisContent
; forwards this message to the GenView (as
; MSG_GEN_VIEW_SET_DOC_BOUNDS) and to all visible children, which are
; assumed to be "layers", with the message
; MSG_VIS_LAYER_SET_DOC_BOUNDS.
;
; This message can ONLY be sent to a VisContent which has its
; VCNA_LARGE_DOCUMENT_MODEL bit set (a fatal error will result if the
; bit isn't set).
;
; Context:	Sent whenever document bounds change (should also be
;		sent to initialize same).
;
; Source:	Might be one of the object's Vis children (layers), or
;		from a UI object (page size setup, etc).
; Destination:  VisContent class
; Interception: Can be subclassed to modify default behavior.  Care
; 		should be taken to ensure that the GenView is
;		receiving the proper message
;
; Pass:	dx 	- size RectDWord
;	ss:bp	- pointer to RectDWord of new document bounds

MSG_VIS_CONTENT_NOTIFY_ACTIVE_MOUSE_GRAB_WIN_CHANGED	message
;
; A message we send ourselves from within our MSG_VIS_VUP_ALTER_INPUT_FLOW
; handler in the case that VCNI_activeMouseGrab.VMG_gWin changes.  Used
; by the specific UI's implementation of GenApplicationClass to keep track
; of the currently active window within the application.
; 
; Context:	Called on self anytime VCNI_activeMouseGrab.VMG_gWin changes.
; Source:	Self
; Destination:	Self
; Interception:	Intercepted by specific UI's implementation of GenApplication,
;		for the purpose of finding out a change in the active window
;		within the application has occurred.  It will in turn update
;		the window system so that mouse grabs & ptr image changes
;		will work properly.
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed.


;------------------------------------------------------------------------------
;	Hints
;------------------------------------------------------------------------------
;------------------------------------------------------------------------------
;	Constants & Structures
;------------------------------------------------------------------------------
	
VisContentAttrs	record
	VCNA_SAME_WIDTH_AS_VIEW:1
	; Set if the content's width should just follow the subview's
	; window width, if possible.  You want to set this if the view
	; is not supposed to be horizontally scrollable.

	VCNA_SAME_HEIGHT_AS_VIEW:1
	; Set if the content's height should just follow the subview's
	; window height, if possible.  You want to set this if the view
	; is not supposed to be vertically scrollable.

	VCNA_LARGE_DOCUMENT_MODEL:1
	;
	; Set if using a large document model, in which this object will be
	; a large (32-bit) VisContent.  Effects:
	;
	; Bounds are larger than the graphics space under this model, so
	; the 16-bit Visible bounds of this object are meaningless.
	; The application must initialize the GenView, or use
	; MSG_GEN_VIEW_SET_DOC_SIZE, to set the view's document size.
	;
	; If no active mouse grab:  Incoming mouse events are converted
	; into 32-bit LARGE mouse events & sent to the VisContent,
	; where the default handler will send them on to the first visible
	; child, thereby providing correct behavior for the single-child case.
	; Applications having multiple visible layers (32-bit children of
	; VisContents) must intercept these messages & direct them to the
	; correct layer.
	;
	; MSG_VIS_DRAW is by default sent on to the first visible child,
	; thereby providing correct behavior for the single-shild case.
	; Applications having multiple visible layers (32-bit children of
	; VisContents) must intercept this message & direct it to the
	; correct layer(s).
	;
	; See Management/UserInterface/Large_Document_Model for more info
	; on large (32-bit) document models
	
	VCNA_WINDOW_COORDINATE_MOUSE_EVENTS:1
	;
	; Required if VCNA_LARGE is set.  Support for this bit requires
	; a VisContentClass object.
	;
	; Set if the GenView associated with this content has been set up
	; to send mouse events in window coordinates, instead of
	; document coordinates  (For either 32-bit support capability
	; or fractional mouse position capability).  Indicates that
	; the VisContent will need to convert the coords to document
	; coords before sending them on.  This is done via the equation:
	;
	;       Doc Coords = (Win Coords/Scale Factor) + Doc Origin
	;	

	VCNA_ACTIVE_MOUSE_GRAB_REQUIRES_LARGE_EVENTS:1
	;
	; This bit only used by VisContentClass objects.
	;;
	; Set/cleared by MSG_VIS_VUP_ALTER_INPUT_FLOW routine to indicate
	; whether the current mouse grab wishes to receive LARGE mouse events
	; in place of the standard ones.  Note that this mechanism may
	; be used even when the bit VCNA_LARGE is not set.

	VCNA_VIEW_DOC_BOUNDS_SET_MANUALLY:1
	;
	; Not often used, this will prevent the content from automatically
	; sending off its size to the view on geometry updates.
	; The view's document bounds must be set some other way.
	; Setting VCNA_LARGE_DOCUMENT_MODEL will also cause this behavior.
	;

; Taken care of at higher level, so we don't have to.
;	VCNA_WIN_CHANGE_SINCE_LAST_MSG_META_BUTTON
;	; Used for VisContentClass only:
;	; Set if window that mouse is over has changed since the last mouse
;	; press.  Used to nuke double-press if first press didn't occur in
;	; same window.

	VCNA_VIEW_DOES_NOT_WIN_SCROLL:1
	; Set to indicate that the view does not actually scroll its window,
	; it just sends origin messages to the content when the user interacts
	; with the scrollbar.	 Visual invalidation will use this flag to
	; invalidate the correct region of the content.  Should be set whenever
	; ATTR_GEN_VIEW_DO_NOT_WIN_SCROLL is set in the view.

	:1
VisContentAttrs end

		
VisMouseGrab	struct
; Data associated w/object requesting mouse grab.  Set by handler for
; MSG_VIS_VUP_ALTER_INPUT_FLOW.  (12 bytes)

	VMG_object		optr
	; Object having mouse grab

	VMG_gWin		hptr.Window <>
	; Window that object having grab resides in, or 0 if in same window
	; as VisContent

	VMG_translation		PointDWord
	; 32 bit translation to use for grab.
	; Set by handler for MSG_VIS_VUP_ALTER_INPUT_FLOW, this is the 32-bit
	; translation passed by that message in VAIFD_translation, which is
	; set by large visible objects subclassing the message.  Mouse event
	; positions are adjusted by this amount before being sent out.

	VMG_flags		VisInputFlowGrabFlags
	; Stored here so that we have a record of VIFGF_LARGE preference of
	; object having grab.  Set by MSG_VIS_VUP_ALTER_INPUT_FLOW

	VMG_unused		byte
	; Word align

VisMouseGrab	ends


;
; Hold-up state flags
;

;HoldUpInputFlags	record
;	HUIF_FLUSHING_QUEUE:1
;	; Set if the HoldUpInputQueue is in the process of being flushed.
;	; Used to allow reentrant calls into VisContentFlushHoldUpInputQueue.
;
;	HUIF_HOLD_UP_MODE_DISABLED:1
;	; Set on call to VisContentDisableHoldUpInput.  Forces input data to
;	; flow normally until cleared.  Used only by the system object when
;	; a system-modal dialog box is put on screen, to ensure that user
;	; can interact with it.
;
;	:6
;HoldUpInputFlags	end

		
;------------------------------------------------------------------------------
;	Instance data
;------------------------------------------------------------------------------


    VCNI_view		optr	<>
	noreloc	VCNI_view
	; View this object appears under.  Set by the content; not readily
	; obtainable; use MSG_VIS_VUP_CALL_OBJECT_OF_CLASS or MSG_VIS_VUP__
	; SEND_TO_OBJECT_OF_CLASS (passing GenViewClass as the destination
	; in the passed event) to send a message to the content's view.
	
    VCNI_window		hptr.Window <>
	noreloc	VCNI_window
	; Window this object appears in.  Set by the content.  Is internal;
	; use MSG_VIS_VUP_QUERY_GWIN to get the window if you're an object
	; under the content.
	noreloc VCNI_window
	
    VCNI_viewHeight	word	0	; height of window we're in
    VCNI_viewWidth	word	0	; width of window
     	; Size of parent view window. Obtained via MSG_VIS_CONTENT_GET_
	; WIN_SIZE.  Set by the content itself.
	
    VCNI_attrs		VisContentAttrs		0
    	; Attributes for the content.  Set via MSG_VIS_CONTENT_SET_ATTRS;
	; Cleared via MSG_VIS_CONTENT_GET_ATTRS.

    VCNI_docOrigin	PointDWord <<0, 0>, <0, 0>>
    ; Current document origin for view.  Updated whenver GenView sends us
    ; a MSG_META_CONTENT_VIEW_ORIGIN_CHANGED.  (8 bytes)

    VCNI_scaleFactor	PointWWFixed <<0, 1>, <0, 1>>
    ; Current scale factor for view.  Updated whenver GenView sends us
    ; a MSG_VIS_CONTENT_SCALE_FACTOR_CHANGED.  (8 bytes)

    VCNI_prePassiveMouseGrabList	lptr.ChunkArrayHeader <>
    ; (2 bytes)

    VCNI_impliedMouseGrab	VisMouseGrab <			        \
				  <>, <>,	 		        \
				  <0, 0>, <0, 0>,			\
				  (mask VIFGF_MOUSE or maskVIFGF_PTR),	\
				  0 				       	\
				>
	noreloc VCNI_impliedMouseGrab.VMG_object
	noreloc VCNI_impliedMouseGrab.VMG_gWin
    ; Where to send mouse data if no active grab.  (12 bytes)

    VCNI_activeMouseGrab	VisMouseGrab <                   \
					  <>, <>, 		 \
					  <0, 0>, <0, 0>,        \
					  0,			 \
					  0 			 \
				>
	noreloc VCNI_activeMouseGrab.VMG_object
	noreloc VCNI_activeMouseGrab.VMG_gWin
    ; Current Mosue grab within content.  Set by MSG_VIS_VUP_ALTER_INPUT_FLOW.
    ; (12 bytes)

    VCNI_postPassiveMouseGrabList	lptr.ChunkArrayHeader
    ; (2 bytes)

    VCNI_kbdGrab	KbdGrab <			       \
				  <>, 0, 		       \
			>
    ; Current Kbd grab within content.  Set by MSG_VIS_VUP_ALTER_INPUT_FLOW.
    ; (6 bytes)

    VCNI_focusExcl	FTVMCGrab <				\
				<>, (mask MAEF_FOCUS), 	        \
			>
    ; focusExcl is a "BasicGrab" (defined in userFlow.asm).  It
    ; contains an OD, a word of data which may be stored w/whomever has
    ; grab, and two messages, one which is the "loss" message & is sent out
    ; when the OD loses the grab, & the other the "gain" message, which is
    ; sent out when an OD gains the grab.  THIS instance of a BasicGrab is
    ; for the object within the view which currently has the focus
    ; (such as a text object or view).  (6 bytes)
	noreloc VCNI_focusExcl.FTVMC_OD

    VCNI_targetExcl	FTVMCGrab <				\
				<>, (mask MAEF_TARGET),		\
			>
	noreloc VCNI_targetExcl.FTVMC_OD
    ; targetExcl is also a "BasicGrab", but is used to indicate which object
    ; in the view has the target exclusive - the object which may have the
    ; active target selection with which an application may perform an
    ; operation on.  (6 bytes)

    VCNI_holdUpInputQueue	hptr <>
	noreloc VCNI_holdUpInputQueue
    ; Handle of queue used to hold held-up input.  (2 bytes)
   
    VCNI_holdUpInputCount	word 	0
    ; Number of requestors that wish for UI input
    ; to be held up -- if non-zero, request is
    ; granted.  (2 bytes)

    VCNI_holdUpInputFlags	HoldUpInputFlags	0
    ; Current state of hold-up mechanism   (1 byte)


VisContentClass	endc
	
