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

	Copyright (c) GeoWorks 1989 -- All Rights Reserved

PROJECT:	PC GEOS
FILE:		Objects/gInterC.def

DECLARER:	UI

DESCRIPTION:
	This file defines GenInteractionClass

	$Id: gInterC.def,v 1.1 97/04/04 14:17:53 newdeal Exp $

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

SetDef  __GINTERC

StartLibrary	ui

include Objects/genC.def

GenInteractionClass	class	GenClass

;------------------------------------------------------------------------------
;	Methods
;------------------------------------------------------------------------------

MSG_GEN_INTERACTION_GET_TYPE		message
;
; Gets the GenInteractionType enum from the instance data.
;
; Context:	Used to get GetInteraction type.
; Source:	Anyone
; Destination:	Any GenInteraction.
; Interception:	Normally not intercepted.
;
; Pass:		nothing
; Return:	cl - GenInteractionType
;		ax, ch, dx, bp - destroyed
;

MSG_GEN_INTERACTION_SET_TYPE		message
;
; Sets the GenInteractionType enum from the instance data.
;
; NOTE:	If you send this method *after* the object has come up on
;	screen, it can have unpredictable results.
;
; Context:	Used to set GenInteraction type before being set usable.
; Source:	Anyone
; Destination:	Any NOT USABLE GenInteraction.  As the attributes are used
;		during resolving specific object, they should only be set when
;		the object is not usable.
; Interception:	Normally not intercepted.
;
; Pass:		cl - GenInteractionType to set
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_GET_VISIBILITY	message
;
; Gets the GenInteractionVisibility enum from the instance data.
;
; Context:	Used to get GetInteraction visibility type.
; Source:	Anyone
; Destination:	Any GenInteraction.
; Interception:	Normally not intercepted.
;
; Pass:		nothing
; Return:	cl - GenInteractionVisibility
;		ax, ch, dx, bp - destroyed
;

MSG_GEN_INTERACTION_SET_VISIBILITY	message
;
; Sets the GenInteractionVisibility enum from the instance data.
;
; NOTE:	If you send this method *after* the object has come up on
;	screen, it can have unpredictable results.
;
; Context:	Used to set GenInteraction visibiltiy type before being set
;		usable.
; Source:	Anyone
; Destination:	Any NOT USABLE GenInteraction.  As the attributes are used
;		during resolving specific object, they should only be set when
;		the object is not usable.
; Interception:	Normally not intercepted.
;
; Pass:		cl - GenInteractionVisibility to set
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_GET_ATTRS		message
;
; Gets the GenInteractionAttrs record from the instance data.
;
; Context:	Used to get GetInteraction attributes.
; Source:	Anyone
; Destination:	Any GenInteraction.
; Interception:	Normally not intercepted.
;
; Pass:		nothing
; Return:	cl - GenInteractionAttrs
;		ax, ch, dx, bp - destroyed
;

MSG_GEN_INTERACTION_SET_ATTRS		message
;
; Sets the GenInteractionAttrs record from the instance data.
;
; NOTE:	If you send this method *after* the object has come up on
;	screen, it can have unpredictable results.
;
; Context:	Used to set GenInteraction attributes before being set usable.
; Source:	Anyone
; Destination:	Any NOT USABLE GenInteraction.  As the attributes are used
;		during resolving specific object, they should only be set when
;		the object is not usable.
; Interception:	Normally not intercepted.
;
; Pass:		cl - GenInteractionAttrs bits to set
;		ch - GenInteractionAttrs bits to clear
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_ACTIVATE_COMMAND	message
;
; Searches for and activates developer-supplied GenTrigger having the passed
; InteractionCommand stored in ATTR_GEN_TRIGGER_INTERACTION_COMMAND, or if
; no such GenTrigger exists, calls MSG_GEN_GUP_INTERACTION_COMMAND to the
; GenInteraction itself to perform the InteractionCommand.  Note that
; IC_INTERACTION_COMPLETE should not be used with this message because it is
; not an explicit command but a notification.
;
; Context:	Used to activate an interaction command.
; Source:	Anyone.
; Destination:	Any GenInteraction except GIT_ORGANIZATIONAL.
; Interception:	May be intercepted to change or supplement default
; 		functionality of standard or custom interaction commands.
;		Standard specific UI-supplied triggers for GenInteraction will
;		use this to perform their actions, so intercepting this will
;		allow changing the default behavior of the standard triggers.
;
; Pass:		cx - InteractionCommand (IC_INTERACTION_COMPLETE not allowed,
;			as this is a psuedo-command for which triggers are not
;			provided nor suppliable)
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_INITIATE		message
;
; Brings GenInteraction on-screen and gives it focus and target, if it wants
; it.  If GenInteraction is already initiated, brings it to the front and gives
; it focus and target, if it wants it.  The GenInteraction must be in a generic
; tree and USABLE before this can be used.  Not allowed for
; GIA_INITIATED_VIA_USER_DO_DIALOG GenInteractions.
;
; Context:	High-level message to bring interactions on-screen.
; Source:	Anyone.
; Destination:	Any USABLE GenInteraction, though only meaningful for
;		GIV_DIALOG interactions or GIV_CONTROL_GROUP interactions that
;		become windows.
; Interception:	Not normally intercepted.  May be intercepted to find out
;		when GenInteraction is coming on-screen or to set up UI
;		gadgetry in the GenInteraction about to come on-screen.  If
;		setting up UI gadgetry, superclass should be called after doing
;		so to avoid visual changes once the interaction is on-screen.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_GEN_INTERACTION_INITIATE_NO_DISTURB	message
;
; Brings GenInteraction on-screen, but places it in the back and does not
; shift the focus or target, so as not to disturb users busy working on some
; other part of the application.  If GenInteraction is already initiated, does
; nothing.  Useful for cases where initiation is generated by something other
; than the user, such as notification of email arrival.  The GenInteraction
; must be in a generic tree and USABLE before this can be used.  Not allowed
; for GIA_MODAL and GIA_INITIATED_VIA_USER_DO_DIALOG interactions.  The dialog
; will take the focus and target when the user interacts with it.
; HINT_INTERACTION_NO_DISTURB may be used to indicate that the dialog should
; never shift the focus and target. 
;
; Context:	High-level message to bring interactions on-screen.
; Source:	Anyone.
; Destination:	Any USABLE GenInteraction, though only meaningful for
;		GIV_DIALOG interactions or GIV_CONTROL_GROUP interactions that
;		become windows.  Not allowed for GIA_MODAL and
;		GIA_INITIATED_VIA_USER_DO_DIALOG interactions.
; Interception:	Not normally intercepted.  May be intercepted to find out
;		when GenInteraction is coming on-screen or to set up UI
;		gadgetry in the GenInteraction coming on-screen.  If setting
;		up UI gadgetry, superclass should be called after doing so
;		to avoid visual changes once the interaction is on-screen.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_INITIATE_BLOCKING_THREAD_ON_RESPONSE	message
;
; Sent by UserDoDialog to initiate dialog and block until dialog's completion.
; GIA_INITIATED_VIA_USER_DO_DIALOG required.  Should NOT be sent from anywhere
; else.
;
; Context:	Internal, used by UserDoDialog.
; Source:	Internal, should not be sent by applications.
; Destination:	Internal, only GIA_INITIATED_VIA_USER_DO_DIALOG GenInteractions.
; Interception:	Internal, should not be intercepted.
;
; Pass:		dx:bp	- far ptr to UserDoDialogStruct, which should be stored
;			  with the resulting data, & the semaphore V'd.
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

MSG_GEN_INTERACTION_RELEASE_BLOCKED_THREAD_WITH_RESPONSE	message
;
; Sent to GenInteraction itself to free thread blocked in UserDoDialog,
; and return InteractionCommand to caller.
;
; Context:	Internal, used via UserDoDialog
; Source:	Internal, should not be sent by applications.
; Destination:	Internal, only GIA_INITIATED_VIA_USER_DO_DIALOG GenInteractions.
; Interception:	Internal, should not be intercepted.
;
; Pass:		cx - InteractionCommand
; Return:	nothing
;		ax, cx, dx, bp - destroyed
;

;related messages in GenClass:
;
;MSG_GEN_GUP_INTERACTION_COMMAND	message
;
; Travels up the generic tree until it reaches a non-GIT_ORGANIZATIONAL
; GenInteraction.  Once there, it performs the indicated InteractionCommand.
; See InteractionCommand declaration for the different command types and how
; specific UI's interpret the commands.  If the GenInteraction is a dialog
; brought up with UserDoDialog, InteractionCommand will be returned to the
; caller, after performing the command, via
; MSG_GEN_INTERACTION_RELEASE_BLOCKED_THREAD_WITH_RESPONSE.
;
; Context:	Used to unconditionally perform one of the InteractionCommand
;		types.
; Source:	Anyone.  Normally sent by MSG_GEN_INTERACTION_ACTIVATE_COMMAND
;		handler or by a custom trigger's action message handler to
;		perform some default command after perform some application-
;		specific function.
; Destination:	Any GenClass object.  Will travel up generic tree, stopping at
;		first non-GIT_ORGANIZATIONAL GenInteraction.
; Interception:	Not normally intercepted.
;
; Pass:		cx - InteractionCommand
; Return:	nothing
;

GenInteractionMessages = GenInteractionMessages + 1
MSG_GEN_INTERACTION_TEST_INPUT_RESTRICTABILITY		message
;
; Message called on modal window by application object to find out whether or
; not the various input restricting mechanisms (input holdup up, input ignore,
; busy) should be overriden or not.
; 
; Context:	Part of input flow/modality mechanism
; Source:	GenApplication object, in MSG_GEN_APPLICATION_NOTIFY_MODAL_WIN_CHANGE
;		handler.
; Destination:	InputOD of any windowed object having MODAL priority.  (Such
;		as a modal GenInteraction)
; Interception:	May be intercepted to provide custom or dynamically changing
;		behavior.  Default behavior at GenInteraction is to check for
;		the existance of a
;		ATTR_GEN_INTERACTION_OVERRIDE_INPUT_RESTRICTIONS or
;		ATTR_GEN_INTERACTION_ABIDE_BY_INPUT_RESTRICTIONS request, in
;		which case these are honored.  If neither or found, a default
;		value is returned, based on the GenInteractionType, & whether
;		or not UserDoDialog is used to bring up the interaction.
;
; Pass: 	^lcx:dx	- InputOD of an windowed object to check
; Return: 	carry	- set to override input restrictions, i.e. to allow
;			  mouse & keyboard input to flow regardless of
;			  hold up/ignore input flags, & to not display the
;			  busy cursor (unless COMPLETELY_BUSY, which may not
;			  be overridden)
;		ax, cx, dx, bp - destroyed

MSG_GEN_INTERACTION_POP_OUT				message
;
; Used to 'pop out' a GIV_POPOUT type GenInteraction.  Removes it from parent
; object and places it in a dialog box.  Does nothing for non-GIV_POPOUT types
; or if GIV_POPOUT is already 'popped out'.
;
; Context:	GIV_POPOUT utility message
; Source:	Anyone
; Destination:	GIV_POPOUT GenInteraction
; Interception:	May be intercepted to tell when GIV_POPOUT is being popped out.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_GEN_INTERACTION_POP_IN				message
;
; Used to 'pop in' a GIV_POPOUT type GenInteraction.  Removes it from its pop
; out dialog box and restores its original position.  Does nothing for non-
; GIV_POPOUT types or if GIV_POPOUT is already 'popped in'.
;
; Context:	GIV_POPOUT utility message
; Source:	Anyone
; Destination:	GIV_POPOUT GenInteraction
; Interception:	May be intercepted to tell when GIV_POPOUT is being popped in.
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_GEN_INTERACTION_TOGGLE_POPOUT			message
;
; Used to toggle the state of a GIV_POPOUT GenInteraction.  The specific UI
; defines this behavior, but it will consist of some sequence to setting the
; interaction 'popped in', 'popped out', and 'popped out' but hidden (popout
; dialog is dismissed).
;
; Pass:		nothing
; Return:	nothing
;		ax, cx, dx, bp - destroyed

MSG_GEN_INTERACTION_DISABLE_DISCARDING			message
;
; Used to tell an interaction with HINT_INTERACTION_DISCARD_WHEN_CLOSED that
; it should not get discarded until it has been brought off screen. This is
; used by applications that need to initialize dialog boxes before bringing
; them on screen -- this message should be sent before the initialization
; is performed, to ensure that the dialog box doesn't get discarded between
; the time that the initialization is performed and the time that the box
; comes on-screen.
;
; Pass:		nothing
; Return: 	nothing
;		ax, cx, dx, bp - destroyed
;

;------------------------------------------------------------------------------
;	Variable Data
;------------------------------------------------------------------------------

;	Descriptive hints:

HINT_INTERACTION_SINGLE_USAGE			vardata
	; This indicates that this property box contains attributes
	; which are needed only once.  The IC_APPLY interaction command trigger
	; (if any) will also dismiss the dialog box.
	;
	; In Motif, the "Apply" moniker is changed to "OK".

HINT_INTERACTION_FREQUENT_USAGE			vardata
	; This indicates that this property box contains attributes that
	; are likely to be used frequently.  IC_APPLY and IC_RESET will leave
	; the dialog on-screen.
	;
	; Motif does this by default.
	;
	; In OPEN LOOK, this indicates that dialogs should be initially pinned.

HINT_INTERACTION_COMPLEX_PROPERTIES		vardata
	; This indicates that this property box contains many components for
	; the user to set.  A reset trigger would be useful.
	;
	; Motif will add a "Reset" trigger that performs the IC_RESET
	; interaction command.

HINT_INTERACTION_SIMPLE_PROPERTIES		vardata
	; This indicates that this property group contains few attributes for
	; the user to set.  A reset trigger is probably unneeded.
	;
	; Motif does this by default.

HINT_INTERACTION_RELATED_PROPERTIES		vardata
	; This indicates that this properties group contains individual
	; attributes that are closely related.   The individual attributes
	; should be changed in the selected object as a group.
	;
	; Motif will run the properties in delayed mode, creating an "Apply"
	; trigger for this property dialog that will the allow the user to set
	; the individual attributes as a group.

HINT_INTERACTION_UNRELATED_PROPERTIES		vardata
	; This indicates that this properties group contains individual
	; attributes that are not related.  The individual attributes may
	; be changed in the selected object one by one.
	;
	; Motif will run the properties in immediate mode, with no "Apply" or
	; "Reset" triggers.

HINT_INTERACTION_SLOW_RESPONSE_PROPERTIES	vardata
	; This indicates that this properties group has individual attributes
	; in which changes take a relatively long time to be reflected in the
	; selected object.
	;
	; Motif will run the properties in delayed mode, creating an "Apply"
	; trigger that will allow the attributes in the property dialog to be
	; set all at once, after the user has made the desired setting for each
	; of the individual attributes.

HINT_INTERACTION_FAST_RESPONSE_PROPERTIES	vardata
	; This indicates that this properties group has individual attributes
	; in which changes can be quickly reflected in the selected object.
	;
	; Motif will run the properties in immediate mode, with no "Apply" or
	; "Reset" triggers.

HINT_INTERACTION_REQUIRES_VALIDATION		vardata
	; This indicates that the attributes in this property dialog require
	; validation by the application.
	;
	; Motif will ensure that the properties are working in delayed mode
	; and will allow ATTR_GEN_TRIGGER_INTERACTION_COMMAND (IC_APPLY) to
	; provide a custom apply trigger to do the validation.

;	Command hints:

HINT_INTERACTION_MAKE_RESIZABLE 		vardata
	; This indicates that a dialog should be resizable.

HINT_INTERACTION_CANNOT_BE_DEFAULT		vardata    
	; Put this hint on your GenInteraction if you don't want it to be
	; activated as some part of a system default.  Often GenInteractions
	; are represented by triggers in a dialog box -- this hint will
	; prevent the representative trigger from being the default in that
	; dialog box.

HINT_INTERACTION_MODAL					vardata
	; Set to indicate that this dialog GenInteraction needs to be
	; application modal because the interaction is only meaningful to
	; the user in a very specific context.  It will not be appropriate
	; for the dialog box to stay on-screen while allowing the user to
	; work in other areas of the application (i.e. can't have non-modal
	; dialog box).  See also GIA_MODAL.

HINT_INTERACTION_UNUSED_1		vardata

ATTR_GEN_INTERACTION_UNUSED_2		vardata

ATTR_GEN_INTERACTION_UNUSED_3		vardata

TEMP_GEN_INTERACTION_WITH_ACTION_RESPONSE		vardata	ActionDescriptor
	; Internal variable data.  Do not use.

HINT_INTERACTION_NO_DISTURB			vardata
	; Set to indicate that this dialog GenInteraction should not
	; grab the focus or target when the user interacts with it.
	; MSG_GEN_INITIATE_NO_DISTURB may be used to just initiate a dialog
	; without having the take the focus or target, but still taking the
	; focus and target when the user interacts with it.

;Related vardata defined in GenClass
;
;HINT_SEEK_REPLY_BAR				vardata
;	; This indicates that this object (usually GenTrigger) is a reply bar
;	; trigger.
;	;
;	; Motif will place the trigger in the reply bar of the first
;	; non-GIT_ORGANIZATIONAL GenInteraction that is a window (either a
;	; GIV_DIALOG or a GIV_CONTROL_GROUP that becomes a dialog).

;Related vardata defined in GenTriggerClass:
;
;ATTR_GEN_TRIGGER_INTERACTION_COMMAND	vardata	word
;	; This indicates that this GenTrigger is a interaction command trigger
;	; for the parent GenInteraction.  Takes a word of data that is the
;	; command type of the trigger.  The trigger can perform one of the
;	; standard interaction commands by using one of the pre-defined
;	; InteractionCommand types.
;	;
;	; If trigger ouput and message are null, the interaction command data
;	; word will be sent with MSG_GEN_GUP_INTERACTION_COMMAND to the trigger
;	; itself.  This will travel up the generic tree to the first non-
;	; GIT_ORGANIZATIONAL GenInteraction, where it will be handled.  So,
;	; leaving the output and message null are equivalent to setting the
;	; following:
;	;
;	;	GTI_destination = "TO_SELF";
;	;	GTI_actionMsg = MSG_GEN_GUP_INTERACTION_COMMAND;
;	;	ATTR_GEN_TRIGGER_ACTION_DATA = { data };
;	;
;	; where the data for ATTR_GEN_TRIGGER_ACTION_DATA is the same as the
;	; data for ATTR_GEN_TRIGGER_INTERACTION_COMMAND:
;	;
;	;	ATTR_GEN_TRIGGER_INTERACTION_COMMAND = { data };
;	;
;	; For GenInteractions displayed with UserDoDialog, the
;	; ATTR_GEN_TRIGGER_INTERACTION_COMMAND has the effect of storing the
;	; return value of the trigger if that trigger is the response used to
;	; dismiss the dialog.

;
; GenInteraction group types.  Used as data for ATTR_GEN_INTERACTION_GROUP_TYPE.
;
GenInteractionGroupType	etype	byte
	GIGT_FILE_MENU		enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the File menu.  Can
	; contain DocumentControl or other file-related commands.
	;
	GIGT_EDIT_MENU		enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the Edit menu.  Can
	; contain EditControl or other edit commands.
	;
	GIGT_VIEW_MENU		enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the View menu.  Can
	; contains ViewControl or other view commands.
	;
	GIGT_OPTIONS_MENU	enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the Options menu.  Can
	; contain application options.
	;
	GIGT_WINDOW_MENU	enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the Window menu.  Can
	; contain GenDisplayControl or other window commands.
	;
	GIGT_HELP_MENU		enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the Help menu.
	;
	GIGT_PRINT_GROUP	enum	GenInteractionGroupType
	; Set to indicate that this GenInteraction is the Print group.  Can
	; contain PrintControl or other print commands.
	;

ATTR_GEN_INTERACTION_GROUP_TYPE	vardata	GenInteractionGroupType
	; This indicates that this GenInteraction is a special group that the
	; specific UI should be aware of.  Takes a byte of data that is a
	; InteractionGroupType.
	;
	; Define as follows in .goc file:
	;
	;	ATTR_GEN_INTERACTION_GROUP_TYPE = { group-type }

ATTR_GEN_INTERACTION_UNUSED_4	vardata


ATTR_GEN_INTERACTION_OVERRIDE_INPUT_RESTRICTIONS	vardata
	; This attribute overrides input hold up, ignore, & busy states
	; for modal dialogs boxes.  Many of the GenInteractionTypes
	; (PROGRESS, NOTIFICATION, AFFIRMATION, MULTIPLE_RESPONSE,
	; UserDoDialog-initiated) use this behavior by default, but this
	; attribute may be set for cases where this effect is desired, but
	; not normally provided.

ATTR_GEN_INTERACTION_ABIDE_BY_INPUT_RESTRICTIONS	vardata
	; This attribute allows input hold up, ignore, & busy states
	; to apply to this interaction.  Many of the GenInteractionTypes
	; (PROGRESS, NOTIFICATION, AFFIRMATION, MULTIPLE_RESPONSE, 
	; UserDoDialog-initiated)) provide default behavior in which
	; these mechanisms are overridden.  Such behavior can be turned
	; off using this attribute.

HINT_INTERACTION_DEFAULT_ACTION_IS_NAVIGATE_TO_NEXT_FIELD	vardata

HINT_INTERACTION_INFREQUENT_USAGE	vardata
	; This hint is used by PM to denote submenus which should not cascade
	; automatically. (Cascade only if mouse pointer is over the right
	; arrow mark.)

HINT_CUSTOM_SYS_MENU		vardata		word
	;PM: This hint specifies that this menu is the custom sys menu.
	;The standard system menu will be added as a submenu of the custom
	;sys menu.  The word argument specifies the position at which the
	;standard sys menu will be added to the custom sys menu.
	;(The first position is 0).

ATTR_GEN_INTERACTION_POPPED_OUT	vardata
	; This indicates that a GIV_POPOUT GenInteraction is in its 'popped
	; out' state.

TEMP_GEN_INTERACTION_SAVE_POPOUT_INFO		vardata GenSaveWindowInfo
;
; This is used internally to save the size and position of the dialog portion
; of a GIV_POPOUT GenInteraction across shutdown and restore.
;

ATTR_GEN_INTERACTION_POPOUT_NOT_CLOSABLE	vardata
	; This indicates that the user should not be able to close a GIV_POPOUT
	; GenInteraction when it is 'popped out'.  They will just be able to
	; pop it back in.

ATTR_GEN_INTERACTION_PEN_MODE_KEYBOARD_OBJECT	vardata	optr
;
;	Contains the OD of a GenPenInputControlClass object (or equivalent).
;	Can be 0:0, if no keyboard is desired for the dialog. Should not
;	be in the gen linkage.
;

HINT_INTERACTION_MAXIMIZABLE		vardata
;
; Why not let dialogs be maximizable (and restorable).
;

HINT_INTERACTION_POPOUT_HIDDEN_ON_STARTUP	vardata
;
; Used to specify that a GIV_POPOUT GenInteraction should be hidden
; ('popped out' and dismissed) on startup.  Must be used with
; ATTR_GEN_INTERACTION_POPPED_OUT.
;

TEMP_GEN_INTERACTION_POPOUT_HIDDEN		vardata
;
; Used internally to indicate that the menu bar for this GIV_POPOUT
; GenInteraction is hidden, across shutdown/restore.
;

HINT_INTERACTION_DISCARD_WHEN_CLOSED		vardata
;
; Used to specify that a given interaction should be discarded when it
; has been brought off screen. This is used as an optimization for
; interactions that are seldom-used, so they can free up memory after
; they've been used.
;
; If an interaction contains this hint it must:
;
;	1) Have the GIA_NOT_USER_INITIATABLE bit set.
;	2) Be of type GIV_DIALOG.
;	3) Have a one-way upward generic link only
;	4) Have all of its children in the same block as it is
;	5) Have the block marked notDetachable and discardable
;	6) Have no other objects in the block except for itself and
;	   its children
;

GenInteractionDiscardInfo	struct
	GIDI_inUse		word
	; If non-zero, the interaction is onscreen, or is about to go
	; onscreen, so it should not be discarded.

	GIDI_discardCount	word
	; Count of MSG_GEN_DESTROY_AND_DISCARD_BLOCK messages that have to
	; come in before the block is discarded.
GenInteractionDiscardInfo	ends

TEMP_INTERACTION_DISCARD_INFO		vardata	GenInteractionDiscardInfo
; Used internally to keep track of when it's OK to discard an interaction
; that has HINT_INTERACTION_DISCARD_WHEN_CLOSED.
;

protoreset

protominor UINewForResponder

HINT_INTERACTION_ACTIVATED_BY		vardata optr
; Optional hint to specify the object which initiated this interaction,
; for cases where the programmer defines a separate generic object
; that initiates the interaction.   Some UI's may draw windows differently if 
; the activating object is present (i.e. draw a bubble with an arrow to the 
; object).  Most do not.   For the ones that do, this hint can be put on
; triggers or item groups.   In the latter case, the focused item will be
; assumed to be the activator.
;

HINT_INTERACTION_FOCUSABLE		vardata
; For post 2.1 specific UI's that support this, allows childless organizational
; GenInteractions to take the focus itself, rather than looking for children
; to give the focus to.   This doesn't cause anything interesting 
; to happen in and of itself, but allows programmers to subclass the object
; and allow it to take navigation as if it were a trigger or some other
; generally focusable object.   The specific UI may or may not draw the
; interaction differently when it has the focus.   For general application
; development, it's best to assume that this hint isn't available, and
; use a composite or non-composite GenGadget to do what you want.

protoreset


HINT_INTERACTION_FOLDER_TAB_DIALOG	vardata
; This hint specifies that the interaction should be drawn with folder tabs
; along the top of the dialog.  Each child of the interaction is considered
; a tab group.
;

HINT_INTERACTION_NOTEBOOK_STYLE		vardata
; This hint specifies that the interaction should be drawn to look like an
; open notebook.  This hint works only on subgroup GenInteractions.  This
; is used in Penelope to draw notebook binder rings in the interaction.
;

protominor UINewForDove

HINT_INTERACTION_ACTIVATOR_POINT	vardata		Point
; This hint is used on bubble dialogs to specify a position for the
; bubble dialog to point to.  This hint should be used when the dialog
; does not point to a specific object, but rather to some position on
; the screen.  This hint only works with SPUIs that use bubble
; dialogs.
;

protoreset

;------------------------------------------------------------------------------
;	Constants & Structures
;------------------------------------------------------------------------------

;
; The following structure is passed to
; MSG_GEN_INTERACTION_INITIATE_BLOCKING_THREAD_ON_RESPONSE.
;

UserDoDialogStruct	struct
	UDDS_callingThread	hptr
	; The handle of the thread that is waiting for this dialog to come
	; down. If 0, it means that the thread has no event queue, and
	; is instead blocking on UDDS_semaphore.

	UDDS_semaphore		hptr
	; The handle of a semaphore that a non-event-driven thread is blocking
	; on. See note above.
	
	UDDS_response	word
	; This is the "response" value returned by the dialog to UserDoDialog.
	; It is most often a value from the enumerated type InteractionCommand.

	UDDS_complete	word
	; Set non-zero upon dialog completion.  UDDS_reponse should be set 
	; before UDDS_complete is set non-zero.

	UDDS_boxRunByCurrentThread	word
	; Set non-zero if the box is run by the current thread	

	UDDS_dialog	optr
	; The optr of the dialog that's up.  Needed internally by UserDoDialog
	; for loop dispatching mode, to help assertain which events should be
	; dispatched & which saved off.

	UDDS_queue	hptr
	; Backed up queue of events arriving for thread, but not dispatched
	; due to the determination that they weren't relavent to the dialog's
	; operation.  These are reinserted into the queue upon completion of
	; the dialog.

UserDoDialogStruct	ends

;
; Pre-defined command types for GenInteraction.  Used as
; ATTR_GEN_TRIGGER_INTERACTION_COMMAND data and as argument for
; MSG_GEN_INTERACTION_ACTIVATE_COMMAND and
; MSG_GEN_GUP_INTERACTION_COMMAND.
;
InteractionCommand	etype	word
	IC_NULL			enum	InteractionCommand
	; Special interaction command for use with UserDoDialog and
	; UserStandardDialog, et. al.  When returned as the dialog response,
	; this indicates that the interaction was terminated by the system
	; (for example, the system shut down while the box was on-screen).
	;
	; This should not be sent with MSG_GEN_INTERACTION_ACTIVATE_COMMAND or
	; MSG_GEN_GUP_INTERACTION_COMMAND.
	;
	IC_DISMISS		enum	InteractionCommand
	; Dismisses interaction, making it non-visible.  Will always cause
	; window to come down, even overridding the user's preference, such as
	; having pinned the window.
	;
	IC_INTERACTION_COMPLETE	enum	InteractionCommand
	; Notification to the GenInteraction that the user has completed
	; one interaction.  The specific UI must then decide whether the
	; interaction should stay around to allow the user multiple
	; interactions, or whether it should come down.
	;
	; Motif will dismiss the interaction if it is modal, or if
	; HINT_INTERACTION_SINGLE_USAGE is set.
	;
	; OPEN LOOK will dismiss the interaction if it is currently not pinned.
	;
	; This command is automatically sent as a side effect to the
	; interaction, via MSG_GEN_GUP_INTERACTION_COMMAND, when a trigger is
	; activated that has GA_SIGNAL_INTERACTION_COMPLETE set, and does
	; not send any other MSG_GEN_GUP_INTERACTION_COMMAND as a result of
	; being activated.
	;
	; Has no effect if the interaction has already been dismissed.
	;
	; This command is special in that a button may not be created for
	; the sole purpose of activating this command.  Because of this,
	; IC_INTERACTION_COMPLETE may not be used with
	; ATTR_GEN_TRIGGER_INTERACTION_COMMAND or
	; MSG_GEN_INTERACTION_ACTIVATE_COMMAND.  It can be used with
	; MSG_GEN_GUP_INTERACTION_COMMAND.
	;
	IC_APPLY		enum	InteractionCommand
	; Standard response for GIT_PROPERTIES.  Applies properties.  Causes
	; MSG_GEN_APPLY to be sent to the UI gadgets under the GenInteraction.
	;
	IC_RESET		enum	InteractionCommand
	; Standard response for GIT_PROPERTIES.  Resets properties.  Causes
	; MSG_GEN_RESET to be sent to the UI gadgets under the GenInteraction.
	;
	IC_OK			enum	InteractionCommand
	; Standard response for GIT_NOTIFICATION.
	;
	IC_YES			enum	InteractionCommand
	; Standard response for GIT_AFFIRMATION.
	;
	IC_NO			enum	InteractionCommand
	; Standard response for GIT_AFFIRMATION.
	;
	IC_STOP			enum	InteractionCommand
	; Standard response for GIT_PROGRESS.
	;
	IC_EXIT			enum	InteractionCommand
	; Special interaction command used to indicate that this GenTrigger
	; exits the application.  Motif has a "Exit" item in the "File" menu.
	;
	; This should only be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND,
	; not with MSG_GEN_GUP_INTERACTION_COMMAND or
	; MSG_GEN_INTERACTION_ACTIVATE_COMMAND.  It is only supported for
	; GenTriggers under GIV_POPUP GenInteractions.
	;
	IC_HELP			enum	InteractionCommand
	; Special interaction command used to indicate that this GenTrigger
	; brings up help.
	;
	; This should only be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND.
	;
	IC_INTERNAL_1		enum	InteractionCommand
	IC_INTERNAL_2		enum	InteractionCommand
	;
	; Used internally.
	;
protominor	UINewInteractionCommands
	IC_NEXT			enum	InteractionCommand
	; Next (e.g next dialog in sequence of dialogs).  This should only
	; be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND, where it will
	; provide only a default moniker, no default action is provided.
	;
	IC_PREVIOUS		enum	InteractionCommand
	; Previous (e.g. previous dialog in sequence of dialogs).  This
	; should only be used with ATTR_GEN_TRIGGER_INTERACTION_COMMAND,
	; where it will provide only a default moniker, no default action
	; is provided.
	;
protoreset

;
; Application-defined response values for UserDoDialog and UserStandardDialog
; must start here so as not to conflict with the predefined InteractionCommands.
; Of course, the predefined InteractionCommands may be used if their
; functionality is desired.
;
IC_CUSTOM_START	equ	1000

;
; Types of GenInteractions.
;
GenInteractionType	etype	byte
	GIT_ORGANIZATIONAL	enum	GenInteractionType
	; Specifies an interaction that is only used for grouping its children.
	; Has two chief uses:
	;
	;	1) For geometry purposes.  Collecting a group of gadgets or
	;	   interactions together allows specifying the geometry
	;	   for that group via HINTs, & results in the group being dealt
	;	   with as a single entity from a geometry viewpoint at the
	;	   next interaction up.
	;
	;	2) As a place to put non-user-initiatable dialogs, to get them
	;	   out of sight while leaving them in the generic tree where
	;	   they can be initiated.  As you generally don't want this
	;	   organizational interaction to be visible itself, either,
	;	   you will most likely want to mark it as a GIV_DIALOG and
	;	   GIA_NOT_USER_INITIATABLE as well.  (Optimization note:
	;	   This also has the side effect of avoiding the loading in
	;	   of the resources that the child dialog boxes reside in,
	;	   should this object receive MSG_SPEC_BUILD.)
	;
	; Does not support a reply bar, even if GIV_DIALOG is used to specify
	; that this GenInteraction should become a dialog box.  Motif will
	; ensure that there is a way for the user to dismiss any
	; GIT_ORGANIZATIONAL interaction that does becomes a visible dialog.
	;
	GIT_PROPERTIES		enum	GenInteractionType
	; Specifies an interaction that contains UI gadgets used for object
	; properties.  The IC_APPLY and IC_RESET interaction commands can be
	; used for apply and reset functionality.  If GenInteractionVisibility
	; causes this GenInteraction to become a dialog box, Motif will create
	; "Apply" and "Close" triggers that provide the IC_APPLY and IC_DISMISS
	; interaction commands.
	;
	; In Motif, the following table shows the standard triggers that will
	; be provided with various hints (given a GIT_PROPERTIES GenInteraction
	; that becomes a dialog):
	;
	; Hints (HINT_INTERACTION_...)		Triggers
	; -----					--------
	; none					"Apply" "Close" (delayed
	;							properties)
	;
	; _UNRELATED_PROPERTIES or		none (immediate properties)
	;  or _FAST_RESPONSE_PROPERTIES
	;
	; _RELATED_PROPERTIES			"Apply" "Close"
	;  or _SLOW_RESPONSE_PROPERTIES
	;  or _REQUIRES_VALIDATION
	;
	; _COMPLEX_PROPERTIES			"Apply" "Reset" "Close"
	;  and (_RELATED_PROPERTIES
	;   or _SLOW_RESPONSE_PROPERTIES
	;   or _REQUIRES_VALIDATION)
	;
	; _SINGLE_USAGE				"OK" "Close"
	;  and (_RELATED_PROPERTIES
	;   or _SLOW_RESPONSE_PROPERTIES
	;   or _REQUIRES_VALIDATION)
	;
	; _SINGLE_USAGE				"OK" "Reset" "Close"
	;  and _COMPLEX_PROPERTIES
	;  and (_RELATED_PROPERTIES
	;   or _SLOW_RESPONSE_PROPERTIES
	;   or _REQUIRES_VALIDATION)
	;
	; modal dialog				"OK" "Cancel"
	;
	; modal dialog				"OK" "Reset" "Cancel"
	;  and _COMPLEX_PROPERTIES
	;
	; Example:
	;	+---------------------------------------+
	;	|	Size:  o 10  o 12  o 18  o 24	|
	;	|	Color:  o R  o B  o  G		|
	;	|					|
	;	+---------------------------------------+
	;	|	  Apply		Close		|
	;	+---------------------------------------+
	;
	GIT_PROGRESS		enum	GenInteractionType
	; Specifies an interaction used to report progress information for
	; some operation.  If GenInteractionVisibility causes this
	; GenInteraction to become a dialog box, Motif will create a "Stop"
	; trigger that provides the IC_STOP interaction command.
	;
	; Input hold up, ignore, & busy states are overridden by default to
	; allow users to interact with modal implementations of this style
	; GenInteraction.
	;
	; Example:
	;	+---------------------------------------+
	;	|		Disk Format		|
	;	|				 	|
	;	|	complete: 44%			|
	;	+---------------------------------------+
	;	|		   Stop			|
	;	+---------------------------------------+
	;
	GIT_COMMAND		enum	GenInteractionType
	; Specifies an interaction that contains commands.  If
	; GenInteractionVisibility causes this GenInteraction to become a
	; dialog box, Motif will create a "Close" trigger that provides the
	; IC_DISMISS interaction command.  Any command triggers must be
	; provided with ATTR_GEN_TRIGGER_INTERACTION_COMMAND and
	; HINT_SEEK_REPLY_BAR.
	;
	; Example:
	;	+---------------------------------------+
	;	| Rename:  blah				|
	;	|     To:				|
	;	|					|
	;	+---------------------------------------+
	;	|	Rename		Cancel		|
	;	+---------------------------------------+
	;
	GIT_NOTIFICATION	enum	GenInteractionType
	; Specifies an interaction used for notification.  Motif will implement
	; this as a dialog box with an "OK" trigger that provides the IC_OK
	; interaction command.
	;
	; Motif will not provide "Close" or "Cancel" trigger to merely dismiss
	; the interaction without response.
	;
	; Input hold up, ignore, & busy states are overridden by default to
	; allow users to interact with modal implementations of this style
	; GenInteraction.
	;
	; Example:
	;	+---------------------------------------+
	;	| New mail has arrived.			|
	;	|					|
	;	+---------------------------------------+
	;	|		  OK			|
	;	+---------------------------------------+
	;
	GIT_AFFIRMATION		enum	GenInteractionType
	; Specifies an interaction used to allow the user to confirm an
	; operation.  The interaction should include a prompt in the form
	; of a question.  Motif will implement this as a dialog box with "Yes"
	; and "No" triggers that provide the IC_YES and IC_NO interaction
	; commands.
	;
	; Motif will not provide "Close" or "Cancel" trigger to merely dismiss
	; the interaction without response.
	;
	; Input hold up, ignore, & busy states are overridden by default to
	; allow users to interact with modal implementations of this style
	; GenInteraction.
	;
	; Example:
	;	+-----------------------------------------------+
	;	| Are you sure you wish to delete this file?	|
	;	|						|
	;	+-----------------------------------------------+
	;	|		Yes		No		|
	;	+-----------------------------------------------+
	;
	GIT_MULTIPLE_RESPONSE	enum	GenInteractionType
	; Specifies an interaction that contains multiple responses (two or
	; more), one of which must be choosen.  Motif will implement this as a
	; dialog box to which response triggers must be added with
	; ATTR_GEN_TRIGGER_INTERACTION_COMMAND and HINT_SEEK_REPLY_BAR.
	;
	; Motif will not provide "Close" or "Cancel" trigger to merely dismiss
	; the interaction without response.
	;
	; Input hold up, ignore, & busy states are overridden by default to
	; allow users to interact with modal implementations of this style
	; GenInteraction.
	;
	; Example:
	;	+-----------------------------------------------+
	;	| The file you are closing has been changed.	|
	;	|						|
	;	+-----------------------------------------------+
	;	| Save changes    Ignore changes    Don't close |
	;	+-----------------------------------------------+
	;

;
; Visibility options for GenInteraction.
;
; Certain GenInteractionTypes (GIT_NOTIFICATION, GIT_AFFIRMATION,
; and GIT_MULTIPLE_RESPONSE) may override this.
;
GenInteractionVisibility	etype	byte
	GIV_NO_PREFERENCE	enum	GenInteractionVisibility
	; Specifies no visual preference for this interaction.  Specific UI
	; will determine how this should appear depending on hints, location
	; in visual/generic tree, visual/generic children, etc.
	;
	GIV_POPUP		enum	GenInteractionVisibility
	; Specifies that this interaction should appear as a popup (menu or
	; popup list).
	;
	GIV_SUB_GROUP		enum	GenInteractionVisibility
	; Specifies that this interaction should appear as a sub-group within
	; a larger window.
	;
	GIV_CONTROL_GROUP	enum	GenInteractionVisibility
	; Specifies that this interaction contains controls and so should
	; not be placed directly in a popup interaction.  May appear as a
	; sub-group in a larger window or as separate dialog box.
	;
	GIV_DIALOG		enum	GenInteractionVisibility
	; Specifies that this interaction should appear as a dialog box.
	; Specific UI will create a trigger that brings up the dialog box
	; unless GIA_NOT_USER_INITIATABLE is set.
	;
	GIV_POPOUT		enum	GenInteractionVisibility
	; Specifies that this interaction can be 'popped out' into a dialog
	; box.  The interaction will normally behave as a GIV_SUB_GROUP
	; until it is 'popped out'.  Then it behaves as a GIV_DIALOG.
	; MSG_GEN_INTERACTION_POP_IN and MSG_GEN_INTERACTION_POP_OUT may be
	; used to 'pop' the interaction in and out.
	; ATTR_GEN_INTERACTION_POPPED_OUT is used to indicate that the
	; interaction is popped out.  If set in .ui/.goc file, the interaction
	; will be popped out on startup.
	;

;
; GenInteraction attributes.
;
GenInteractionAttrs	record
	GIA_NOT_USER_INITIATABLE:1
	; Set to indicate that this dialog GenInteraction should not be
	; implemented as a trigger that brings up the dialog when the trigger
	; is activated.  Instead, the user won't see the dialog until it
	; is brought up by the application itself via 
	; MSG_GEN_INTERACTION_INITIATE or UserDoDialog.  A convenient place
	; to stick such objects which don't appear where placed in the
	; generic tree is below the GenPrimary or GenApplication, or in
	; the case of use by controller objects, as children of the
	; controller.
	;
	; This state of this bit is ignored & the dialog presumed not user
	; initiatable if GIA_INITIATED_VIA_USER_DO_DIALOG is set.
	;
	GIA_INITIATED_VIA_USER_DO_DIALOG:1
	; Set to indicate that this dialog GenInteraction will be displayed
	; with UserDoDialog.
	;
	; NOTE:  visibility must be set to "dialog", & either "modal" or
	; "sysModal" attributes must also be set, in addition to having this
	; bit set, in order to use UserDoDialog on this object.
	;
        ; Input hold up, ignore, & busy states are overridden by default to
        ; allow users to interact with this type of GenInteraction (& thereby
	; prevent user-lock-out which could potentially occur because the
	; app thread is blocked unable to turn off these states itself).
	;
	GIA_MODAL:1
	; Set to indicate that this dialog GenInteraction needs to be
	; modal because the application has been coded in such a way that
	; the it cannot deal with having the dialog box stay on-screen while
	; allowing the user to work in other areas of the application (e.g.
	; selection information in the dialog box is not updated if the user
	; were to chagne the selection).  See also HINT_INTERACTION_MODAL.
	;
	GIA_SYS_MODAL:1

	:4
GenInteractionAttrs	end

;related attributes in GenClass
;
;GenAttributes	record
;	GA_SIGNAL_INTERACTION_COMPLETE:1
;	; Set to indicate that this GenTrigger completes user interaction
;	; with the associated GenInteraction when activated.  This causes a
;	; MSG_GEN_GUP_INTERACTION_COMMAND with IC_INTERACTION_COMPLETE to be
;	; sent to the GenTrigger itself (eventually making its way up to the
;	; associated GenInteraction) after the trigger's action message is
;	; sent out.  The specific UI (in MSG_GEN_GUP_INTERACTION_COMMAND
;	; handler) will then determine whether this dialog should be dismissed
;	; or not.
;	;
;	; This should be set for any ATTR_GEN_TRIGGER_INTERACTION_COMMAND
;	; trigger with IC_APPLY, IC_OK, IC_YES, IC_NO, or IC_STOP (this should
;	; not be set for IC_RESET triggers, as their usefullness depends on the
;	; dialog staying on-screen after their activation), and for any other
;	; HINT_SEEK_REPLY_BAR triggers that should dismiss the dialog after
;	; usage.
;	;
;	; This should not be used for GIA_INITIATED_VIA_USER_DO_DIALOG
;	; GenInteractions as the command triggers in those dialogs, by
;	; definition, signal interaction completion.

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

	GII_type	GenInteractionType (GIT_ORGANIZATIONAL)
	GII_visibility	GenInteractionVisibility (GIV_SUB_GROUP)
	GII_attrs	GenInteractionAttrs

GenInteractionClass	endc

EndLibrary	ui
