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

	Copyright (c) GeoWorks 1992 -- All Rights Reserved

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

REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	chris	1/92		Initial version

DESCRIPTION:
	Object definitions for GenItemGroupClass.   

	$Id: gItemGC.def,v 1.1 97/04/04 14:18:26 newdeal Exp $

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

SetDef	_GITEMGC

StartLibrary	ui

include ui.def

global 	GenItemSendMsg:far

		
GenItemGroupClass	class	GenClass

;------------------------------------------------------------------------------
;	Messages
;------------------------------------------------------------------------------

MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED	message
; 
; Sets no selections for any GenItemGroup.  Will clear the item group's
; modified flag; to set the flag call MSG_GEN_ITEM_GROUP_SET_MODIFIED_
; STATE.  To set more than one selection, call MSG_GEN_ITEM_GROUP_SET_SINGLE_-
; SELECTION or MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS.
;
; Context:	Can be called externally at any time; is also used internally
;		when responding to keypresses.
; Source:	No restrictions
; Destination:	A GenItemGroupObject.
; Interception:	Generally not intercepted.
;
; Pass:		dx	- non-zero if indeterminate
; Return:	nothing
; 		ax, cx, dx, bp - destroyed

MSG_GEN_ITEM_GROUP_SET_SINGLE_SELECTION		message
; 
; Sets exactly one or none selection for the GenItemGroup.  Old selection(s) are
; unselected, if any, regardless of item group behavior type. If visually built,
; updates the items visually.  Clears the item group's modified bit;  to set it,; call MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE.  If the item group is a scrollable, exclusive or exclusive-none item group, it will in most cases ensure that the
; selected item is onscreen.  A selection can be passed that represents an item
; that is not usable, not enabled, or not an item in the item group (useful for
; linked item groups).  If the selected item is not usable or not in the item 
; group, no item will be visually selected, although the selection is still 
; stored.   If you want to set multiple selections in a non-exclusive or 
; extended-selection-exclusive item group, call MSG_GEN_ITEM_GROUP_SET_MULTIPLE-
; SELECTIONS.  
; 
;
; Context:	Can be called externally at any time; is also used internally
;		when responding to keypresses.
; Source:	No restrictions
; Destination:	A GenItemGroupObject.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier of the item to select
;		dx -- non-zero if indeterminate
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;


MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS	message
;
; Allows a GenItemGroup to set multiple selections for the item group.  The
; caller passes a list of ID's representing the items that should be selected.
; All items not in the list will be deselected.   This message will clear the
; item group's modified flag; to set it, call MSG_GEN_ITEM_GROUP_SET_MODIFIED_-
; STATE.  This message will also leave the indeterminate state of the item group
; unchanged -- to set or clear it, call MSG_GEN_ITEM_GROUP_SET_INDETERMINATE_-
; STATE.  To select one or no items, see MSG_GEN_ITEM_GROUP_SET_SINGLE_-
; SELECTION and MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED.
;
; Context:	Can be called by apps at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass: 	cx:dx   - buffer with the selections.
;		bp	- number of selections
; Return:	nothing
;		ax, cx, dx, bp - destroyed


MSG_GEN_ITEM_GROUP_GET_SELECTION		message
; 
; Returns the current selection in the item group.  If there is no selection, 
; returns GIGS_NONE (-1).  If there is more than one selection, returns 
; the first selection in the item group.   If there are multiple selections, 
; MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS should be used.   A selection may 
; be returned even if the item is not usable, not enabled, or not in the item 
; group.
;
; Context:	Can be called by apps at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	ax -- current selection, or GIGS_NONE if no selections,
;		      or the first selection in the item group if there are 
; 		      multiple selections in a non-exclusive or extended-
; 		      selection-exclusive item group.
;		carry set if none selected
;		cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS		message
; 
; Returns the current number of selections for the item group.  Returns zero if
; there is no selection.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	ax -- number of selections
;		cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS	message
; 
; Returns the current list of selections for non-exclusive and extended-
; selection-exclusive item groups.  The caller must allocate a buffer for the 
; entries and pass the size of the buffer.  If there is insufficient space in 
; the passed buffer for the selections, the buffer will not be filled in.
; Call MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS if you don't know the number of
; selections beforehand.    If you are using an exclusive item group, or know
; that the item group has none or one item selected, an easier way to get the
; selection is to call MSG_GEN_ITEM_GROUP_GET_SELECTION.  
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx:dx -- Buffer to hold the selections.
;		bp    -- Max number of selections to place in buffer
; Return:	cx:dx -- preserved, filled in with the identifiers of the
;			 selections (the list will not be null-terminated).
;		ax    -- Number of selections.
;		bp    -- destroyed
;

MSG_GEN_ITEM_GROUP_SET_INDETERMINATE_STATE	message
;
; Allows setting the item group's indeterminate state.  This may be used in
; conjunction with MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS.  MSG_GEN_ITEM_-
; GROUP_SET_SINGLE_SELECTION and MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED set the
; indeterminate state themselves.  See GIGS_INDETERMINATE for more info.
;
; Context:	Can be sent any time
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- non zero to set the item group indeterminate
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_IS_INDETERMINATE		message
; 
; A boolean message for querying the item group to see if its selection is 
; currently indeterminate.  See GIGS_INDETERMINATE for more info.
;
; Context:	Can be sent any time
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	carry set if item group is indeterminate.
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE		message
;
; Items are normally marked as "not modified" anytime their state is
; set, marked "modified" anytime the user interacts with them, and marked
; "not modified" again on MSG_APPLY.  This primitive provides a way to 
; control the modified status outside of these events.
; Items can be operated on via this message, even if they are not usable,
; not enabled, or not represented by a GenItem in the GenItemGroup
; (useful for linked GenItemGroups).
;
; Pass:		cx -- non-zero to mark modified, zero to mark not modified.
; Return:	nothing
;		ax, cx, dx, bp -- destroyed


MSG_GEN_ITEM_GROUP_IS_MODIFIED			message
; 
; A boolean message for querying the item group to see if its selection has been
; modified by the user since the last apply.  See GIGS_MODIFIED for more 
; info.
;
; Context:	Can be sent any time
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	carry set if item group is modified.
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG		message
;
; Causes boolean group to send out the "Status" message as specified in
; ATTR_GEN_ITEM_GROUP_STATUS_MSG.  The message will include the current
; state of the object, as well as the "change" bit we pass here.
; This message will still function even if the item group is not enabled or
; not usable.
; 
; Pass:		cx -- non-zero if GIGSF_MODIFIED bit should be passed set in
;		      status message
; Return:	nothing
;		ax, cx, dx, bp - destroyed

;------------------------------------------------------------------------------
;	Item Messages
;------------------------------------------------------------------------------


MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR		message
; 
; Returns the optr of the requested item.  Useful for sending messages 
; directly to an item, for things like enabling/disabling, setting usable/not-
; usable, changing the item's moniker, or getting/setting the identifier for
; the item.   If the item is not found in the generic tree of the item group, a
; null OD will be returned.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier to look for
; Return:	carry set if item found
;		^lcx:dx -- optr of item, or null if none found
;		ax, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_SET_ITEM_STATE			message
;
; Sets state for a particular item in a GenItemGroup.  If the item group is
; exclusive or exclusive-none, deselects any other items; otherwise, it
; leaves other items unchanged.   Clears the item group's modified state;
; to set the item group modified, send MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE.
; If the identifier passed doesn't match an item in the item group, or
; matches an item that is not usable, it will still be made the selection in 
; exclusive or exclusive-none item groups, or added to the selection in non-
; exclusive item groups.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier of item to select
;		dx -- non-zero if item should be selected, zero if not
; Return:	nothing
;		ax, cx, dx, bp -- destroyed

MSG_GEN_ITEM_GROUP_IS_ITEM_SELECTED		message
;
; A boolean function that returns whether an item in a GenItemGroup is selected.
; If the item is the selection (or one of the selections), the carry will be
; returned set, even if the identifier doesn't match a usable GenItem in the
; item group.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier of item to check on
; Return:	carry set if item is selected
;		ax, cx, dx, bp -- destroyed


MSG_GEN_ITEM_GROUP_MAKE_ITEM_VISIBLE		message
; 
; Ensures that an item in a scrolling item group is visible, by scrolling the 
; item group if necessary.  Has no effect if item group is not scrollable or 
; usable.  Does not change item group state.    See ATTR_GEN_ITEM_GROUP_-
; SCROLLABLE.
;
; Context:	Can be called any time the object is USABLE.  Has
;		no effect otherwise.
; Source:	No restrictions
; Destination:	Any scrollable, USABLE GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier of item to ensure visible
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

;------------------------------------------------------------------------------
;	Other instance data Messages
;------------------------------------------------------------------------------

MSG_GEN_ITEM_GROUP_GET_DESTINATION		message
;
; Returns the current destination object, as specified in GIGI_destination.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	^lcx:dx -- the current destination object
;		ax, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_SET_DESTINATION		message
;
; Sets a new destination object, as specified in GIGI_destination.  Apply
; messages and status messags are sent out to this object.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		^lcx:dx -- destination object
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_GET_APPLY_MSG		message
; 
; Returns the current apply message for the item group.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	ax -- the current apply message
;		cx, dx, bp -- destroyed
;


MSG_GEN_ITEM_GROUP_SET_APPLY_MSG		message
; 
; Sets a new apply message for the item group.  
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- new notification message
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_GET_BEHAVIOR_TYPE		message
; 
; Returns the current behavior type for the item group.  
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	al -- GenItemGroupBehaviorType
;		ah, cx, dx, bp -- destroyed
;


MSG_GEN_ITEM_GROUP_SET_BEHAVIOR_TYPE		message
; 
; Sets a new behavior type for the item group.  Should NOT be sent while
; the object is usable!
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any NON-USABLE GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cl -- new GenItemGroupBehaviorType
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;


MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER	message
;
; Returns a word value that does not match the identifiers of any generic
; children of the GenItemGroup.  This can be used by applications that don't
; have any means of generating a unique identifier of their own, by sending
; this message to the GenItemGroup, then in turn passing it to the item via
; MSG_GEN_ITEM_SET_IDENTIFIER.   Will *not* check across linked item groups
; for an appropriate identifier.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any NON-USABLE GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	ax -- a unique identifier (not used among the generic children
;			of this GenItemGroup).
;		cx, dx, bp -- destroyed
; 

;------------------------------------------------------------------------------
;	Internal messages
;------------------------------------------------------------------------------


MSG_GEN_ITEM_GROUP_SCAN_ITEMS			message
;
; Called by the item group to find another item in the group, usually for
; moving the focus as a result of keyboard navigation.  A dynamic list may
; subclass this to ensure that the item to be found will be onscreen (and
; therefore in the generic tree) before doing the usual stuff.  If the initial
; item is not found, the message will return that item; otherwise, it will
; use the scan amount to find the nth usable items away from the initial item,
; where n is the scan amount.   It will then return the nth item if is is both
; usable and enabled, or keep looking until it can return a usable or enabled
; item.  If the scan amount forces the search past the beginning or end of
; the list, it may wraparound and keep looking, depending on the GSIF_WRAP_-
; AROUND flag.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cl -- GenScanItemsFlags
;		dx -- initial item identifier
;		bp -- absolute scan amount (direction depends on GSIF_FORWARD)
; Return:	carry clear if no enabled or usable item found, with:
;			(used internally by dynamic lists)
;			ax -- the position of the identifier not found, relative
;				to the first usable item
;			dx -- identifier of first usable & enabled child found
;			bp -- identifier of last usable & enabled child found
;			cl -- GenScanItemsFlags, updated
;		else carry set , with: 
;			ax -- the resulting identifier
;			cx, dx, bp -- destroyed
;

GenScanItemsFlags	record
	GSIF_FROM_START:1
		;There's no initial item.  This allows us to easily get the
		;beginning (with GSIF_FORWARD set) or end (with GSIF_FORWARD
		;clear) of the list by passing zero for the scan amount.
	GSIF_FORWARD:1
		;Direction of scan.  The scan amount passed will be negated if
		;this is set.
	GSIF_WRAP_AROUND:1
		;Flag for wrapping around to the beginning if we go past the
		;end, or to the end if we go past the beginning.  
	GSIF_INITIAL_ITEM_FOUND:1
		;Used internally for when we find the initial item.  If we 
		;can't find the item, we return it with no changes.
	GSIF_USABLE_AND_ENABLED_ITEM_FOUND:1
		;Also used internally, marks whether there were any usable
		;and enabled items.
	GSIF_EXISTING_ITEMS_ONLY:1
		;Look through currently existing items only, even if in a 
		;dynamic list.
	GSIF_DYNAMIC_LIST:1
		;Set if item group handler is dealing with a dynamic list,
		;so that when the scan fails, it returns various data back
		;to the dynamic list rather than returning the first or last
		;item.
	:1
GenScanItemsFlags	end



MSG_GEN_ITEM_GROUP_REDRAW_ITEMS		message
;
; Used internally for redrawing items.  Should not be called by the
; application.  Used for dynamic list updates.
;
; Context:	Can be called at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- offset from top item to item to start redrawing from
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;



MSG_GEN_ITEM_GROUP_SET_MONIKER_SELECTION	message
;
; Sets a single selection based on the text passed. Checks to see if any item's
; moniker matches the passed text, and selects the item if so; otherwise 
; leaves none selected.   The text passed need not comprise the entire text
; of the item moniker.   Generally not called by the application, although it
; can be.
;
; Context:	Can be called at any time.
; Source:	No restrictions, usually a GenText object, however.
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		cx:dx -- fptr to text
;		bp -- non-zero if must be exact match, zero if passed text
;			can be incomplete (will find first item whose moniker
;			matches the characters passed)
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_UPDATE_EXTENDED_SELECTION	message
;
; Updates extended selection, given the new extent item passed.  Calculates
; what items have changed, and what kind of selection this is, and updates
; that items that are changing.   Internal!  Do not call this from the
; application.
;
; Context:	Can be called at any time.
; Source:	A GenItemGroup object.
; Destination:	Itself.
; Interception:	Generally not intercepted.
;
; Pass:		ss:bp -- GenItemGroupUpdateExtSelParams
;		dx -- size GenItemGroupUpdateExtSelParams
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

ExtSelFlags	record
	ESF_INITIAL_SELECTION:1		;set if initial selection -- will update
					;   all items between anchor and extent
	ESF_XOR_INDIVIDUAL_ITEMS:1	;whether xoring changed items.  If
					;   clear, sets items within new 
					;   selection, clears others.
	ESF_CLEAR_UNSELECTED_ITEMS:1	;set to clear non-selected items.
	ESF_SELECT:1			;set when items in the selection 
					;   should be turned on, rather than
					;   off.
	:4
ExtSelFlags	end

GenItemGroupUpdateExtSelParams		struc
	GIGUESP_anchorItem	word		;anchor item
	GIGUESP_extentItem	word		;extent item
	GIGUESP_prevExtentItem	word		;previous extent item
	GIGUESP_setSelMsg	word		;message to send to change 
						;  items (dh non-zero to select,
						;  dh zero to select)
	GIGUESP_flags		ExtSelFlags
	GIGUESP_passFlags	byte		;internal: flags to pass to
						;  message in dl
GenItemGroupUpdateExtSelParams		ends

protominor userExclAPI

MSG_GEN_ITEM_GROUP_GET_FOCUS_ITEM				message
; 
; Returns the item which currently has the focus, and therefore
; the cursor, in the item group.
; If there is nothing that has the cursor, returns GIGS_NONE (-1).
; This differs from calling MSG_META_GET_FOCUS_EXCL in that this
; continues to work even if the list doesn't have the focus,
; and doesn't suffer from synchronization problems possible when
; querying for the focus item's optr, then querying the optr for its
; identifier.
;
; Context:	Can be called by apps at any time.
; Source:	No restrictions
; Destination:	Any GenItemGroup object.
; Interception:	Generally not intercepted.
;
; Pass:		nothing
; Return:	ax -- item identifier of current focus exclusive,
;		      or GIGS_NONE if none, or not spec built.
;		carry set if no user exclusive or not spec built.
;		cx, dx, bp -- destroyed
;

MSG_GEN_ITEM_GROUP_SET_FOCUS_ITEM				message
; 
; Moves focus to the specified item in the GenItemGroup,
; scrolling the item group so that the item is visible (in
; scrollable groups).  An item ID can be passed that represents
; an item that is not usable, not enabled, or not an item in the
; item group (useful for linked item groups).  If the selected
; item is not usable, or not in the item group, no item will be
; given the focus exclusive.
;
; Context:	Can be sent by apps at any time, but only has an effect
;		if the list is visually built.
; Source:	No restrictions
; Destination:	A GenItemGroupObject.
; Interception:	Generally not intercepted.
;
; Pass:		cx -- identifier of the item to move the focus exclusive to
;			GIGS_NONE if no exclusive is desired
; Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

protoreset


;------------------------------------------------------------------------------
;	Vardata
;------------------------------------------------------------------------------

ATTR_GEN_ITEM_GROUP_STATUS_MSG	vardata	word
;	Allows a message to be specified for receiving notification of the
;	gadget's current status following user interaction, or the app's
;	forcing of the message via MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG.
;	attribute takes a word argument specifying the message to be sent out.
;	The parameters for the notification message differs from the normal
; 	apply notification:
;
;	Pass:	cx -- current selection, or first selection in item group,
;		      if more than one selection, or GIGS_NONE if no
;		      selection
;		bp -- number of selections
;		dl -- GenItemGroupStateFlags
;		      GIGSF_MODIFIED will be set if a user activation has
;		      just changed the status of the group.  Will be clear
;		      if a redundant user activation has occurred, such as
;		      the re-selection of the singly selected exclusive item.
;		      If message is a result of
;		      MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG being sent, then this
;		      bit will hold the value passed in that message.
;
;	Return:	nothing
;		ax, cx, dx, bp -- destroyed
;

ATTR_GEN_ITEM_GROUP_SET_MODIFIED_ON_REDUNDANT_SELECTION	vardata
; 	In Item group styles GIGBT_EXCLUSIVE and GIGBT_EXTENDED_SELECTION, which
; 	are not indeterminate in state, if the user redundantly clicks or 
;	activates the currently selected item, no change in state takes place. 
;	This is not normally considered to be a "modification".  Setting this 
;	attribute, however, will cause the group to be marked as modified in 
;	such situations. The apply message will then be sent out in response to
;	a MSG_GEN_APPLY being sent to the item group.

ATTR_GEN_ITEM_GROUP_CUSTOM_DOUBLE_PRESS		vardata		word
	;This is an attribute for specially handling double presses in an
	;exclusive GenBooleanGroup.  By default a double press will activate the
	;interaction default in an exclusive item group's window. The data
	;sent with the specified message is the default data for an action:
	; 
	; Pass:		cx -- current selection
	;		bp -- number of selections
	;		dl -- GenItemGroupStateFlags
	; Return:	nothing
	;		ax, cx, dx, bp -- destroyed
	;
	;This will not usually apply to non-exclusive and exclusive-none lists,
	;because of their toggling ability (their state changes on the second
	;double-click, so a double-clicking functions is usually inappropriate.)

HINT_ITEM_GROUP_SCROLLABLE			vardata
	; Allows a GenItemGroup to be a scrolling list of items.  Good for
	; long lists of GenItems.  Exclusive, non-exclusive, exclusive-none,
	; and extended-selection-exclusive behavior are all supported under
	; a scrolling list, and the messages are all the same as for a non-
	; scrolling list.  If you have a really long list of items, or if it
	; looks like a lot of work to create the GenItem objects from your
	; app's data, consider using a GenDynamicList, which instead of using
	; GenItems, allows apps to supply monikers for items as needed.

HINT_ITEM_GROUP_MINIMIZE_SIZE			vardata
	; Tells item group to come up in the smallest space available.
	; In motif, this will direct the item group to appear in a popup
	; list.  In other situations, it might appear as a one-line scrolling
	; object.  Items in a popup list can either be scrollable or not.

HINT_ITEM_GROUP_RADIO_BUTTON_STYLE	vardata 
	; If available in the specific UI, draw items like radio buttons.
	; This is the default behavior in CUA style user interfaces.
	; In Motif, this hint will cause items to use diamond shaped buttons,
	; their radio button equivalent and also their default behavior.  This 
	; style is not available in Open Look.

HINT_ITEM_GROUP_TOOLBOX_STYLE	vardata 
	; If available in the specific UI, draw boolean objects in a toolbox
	; style, usually with a simple box around the visual moniker.  This
	; This is the default behavior in motif for objects in toolbars
	; (denoted by HINT_TOOLBOX), but not for other boolean objects.

HINT_ITEM_GROUP_DISPLAY_CURRENT_SELECTION	vardata
	; With HINT_ITEM_GROUP_MINIMIZE_SIZE, will display the current
	; selection in the object that activates the popup list.  By
	; default the object will show the item group's moniker.

HINT_ITEM_GROUP_MINIMIZE_SIZE_IF_VERTICAL_SCREEN	vardata
	; This is used like HINT_ITEM_GROUP_MINIMIZE_SIZE, but only takes
	; effect on screens that are taller than wide.

ATTR_GEN_ITEM_GROUP_LINK			vardata	optr
	; Allows two or more GenItemGroups to be linked together, each 
	; containing one or more items with identifiers unique to all other
	; items in the linked item groups.  The links should be circular, with 
	; the last item group in the linkage pointing back to the first.  All 
	; item groups should always have identical state stored in them.  
	; (As yet not used.)

ATTR_GEN_ITEM_GROUP_INIT_FILE_BOOLEAN	vardata
	; Uses "true/false" values in .ini file (useful for an
	; exclusive item group with 2 children whose identifiers are
	; TRUE and FALSE, respectively.

HINT_ITEM_GROUP_SHOW_SELECTION_EVEN_WHEN_NOT_FOCUS	vardata
	; Scrolling lists in some UI's (namely Rudy) don't show the selection
	; when the focus is not on the list.   This hint forces the selection 
	; to be shown for some unusual cases, where objects take the focus from
	; the list, but the list still appears to the user to have the focus
	; and be navigable.

protominor PCVLooks_2
HINT_ITEM_GROUP_LOWER_LEFT_STYLE	vardata
HINT_ITEM_GROUP_LOWER_RIGHT_STYLE	vardata
	; Draw in the lower left  or lower right style.  These draw only
	; the top and right,or top and left edges of the button (rounded
	; corner) to look like they are in the lower left or lower right
	; of the screen
	;
HINT_ITEM_GROUP_UPPER_TAB_STYLE		vardata
HINT_ITEM_GROUP_LOWER_TAB_STYLE		vardata
	; The lower and upper tab styles are meant to be used on items
	; that are arranged horizontally.  When one is pressed it looses
	; its top or bottom (according to being upper or lower) so it 
	; looks like it has been pressed.
	;
HINT_ITEM_GROUP_BLANK_STYLE		vardata
	; As simple as it gets, draws no UI.
	;
HINT_ITEM_GROUP_PCV_RADIO_BUTTON_STYLE	vardata
	; Draw a radio button.  The packing order does not matter.
protoreset

protominor	UINewForPenelope
HINT_ITEM_GROUP_TAB_STYLE		vardata
	; Used to denote a tab style for the items in this group.
	; Modified by HINT_ORIENT_CHILDREN_VERTICALLY/HORIZONTALLY,
	; HINT_RIGHT/LEFT_JUSTIFY_CHILDREN, &
	; HINT_DRAW_STYLE_3D_RAISED/LOWERED.  First used in Odie Spui.
	;

ScrollListGridState	record
    SLGS_HGRID_LINES:1		; TRUE if item should draw horiz grid lines
    SLGS_HGRID_SPACING:7	; spacing between horiz grid lines
    SLGS_VGRID_LINES:1		; TRUE if item should draw vert grid lines
    SLGS_VGRID_SPACING:7	; spacing between vert grid lines
ScrollListGridState	end

HINT_ITEM_GROUP_GRID_LINES		vardata	ScrollListGridState
	; Lines and spacing separating the items in a scrollable item group.

HINT_ITEM_GROUP_PREV_LINK		vardata optr
HINT_ITEM_GROUP_NEXT_LINK		vardata optr
	; Allows scrollable item groups to be linked together for keyboard
	; navigation.  Pressing the <lt/rt/up/dn> key will move the focus
	; between items in the list and also between linked lists.

ScrollOutOfBoundsMsgs	struct
    SOOBM_upMessage	word	; msg to send when moving up from top item
    SOOBM_downMessage	word	; msg to send when moving down from bottom item
ScrollOutOfBoundsMsgs	ends

HINT_ITEM_GROUP_SCROLL_OUT_OF_BOUNDS_MSGS	vardata ScrollOutOfBoundsMsgs
	; If the user attempts to navigate up from the top of the list
	; or down from the bottom of a scrollable item group, the
	; SOOBM_{up/down}Message will be sent to GIGI_destination.
protoreset

HINT_ITEM_GROUP_WRAPPING_LIST			vardata
HINT_ITEM_GROUP_NON_WRAPPING_LIST		vardata
	; Hint allowing programmer to specify wrapping behavior of list.
	; In other words, if the list is wrapping, then the user can
	; navigate to the fist item from the last by specifying the
	; next item, or navigate to the last item from the first by
	; selecting the previous item.  First used in selection boxes 
	; (Item groups with HINT_MINIMIZE_SIZE in Odie Spui).

HINT_ITEM_GROUP_DONT_CENTER_TABBED_CHILDREN	vardata
	; If HINT_ITEM_GROUP_TAB_STYLE is supported, then ignore hints
	; to center children.

;------------------------------------------------------------------------------
; 	Constants
;------------------------------------------------------------------------------

GenItemGroupBehaviorType	etype	byte, 0

GIGBT_EXCLUSIVE		enum	GenItemGroupBehaviorType
	; In this mode, anytime the user selects one item, all others will
	; become deselected.  The user may not deselect a currently selected
	; item.

GIGBT_EXCLUSIVE_NONE	enum	GenItemGroupBehaviorType
	; This can be added to a GenItemGroup to cause exclusive-none 
	; behavior in the item group.  Under this mode, a user can click on an
	; already selected item to deselect it, leaving no items selected.
	; GenItemGroups can show a no-selected state by returning GEGS_NONE_
	; SELECTED (-1) in place of the selected item's indentifier.

GIGBT_EXTENDED_SELECTION	enum	GenItemGroupBehaviorType
	; Creates a type of item group where the default
	; behavior is to deselect other items when the user selects
	; an item.  If the user drags across items, or extends the
	; selection (usually done by holding a key down while clicking),
	; several items can be selected.  This is sometimes useful for
	; selecting a target for an operation, where choosing one item
	; is good enough for the novice, but selecting multiple items
	; can be useful for the experienced user.   Like GIGBT_NON_EXCLUSIVE,
	; an application will need to deal with 
	; sending and receiving item groups of identifiers for multiply selected
	; items.

GIGBT_NON_EXCLUSIVE	enum	GenItemGroupBehaviorType
	; This can be added to a GenItemGroup to cause non-exclusive behavior
	; in the item group.  All non-exclusive GenItemGroups will appear as 
	; scrolling item groups -- if you're looking for checkboxes, and have 
	; less than 16 GenItems, you'll want to use GenItemGroup instead.  
	; Special messages, MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS and 
	; MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS, will need to be used in 
	; order to handle multiple selections.


GIGS_NONE	equ	-1	
	;Value used for none selected in exclusive-none item groups, returned in
	;get message, passed in notification messages, 


GenItemGroupStateFlags record
	GIGSF_INDETERMINATE:1,
		;Set if the current selection is indeterminate.  This means
		;that for whatever data is being represented, there is more
		;than one selection.  Current selection in this case refers
		;to the state at the beginning of the data being represented.
		;Refers to the item group as a whole, even if in non-exclusive 
		;mode.

	GIGSF_MODIFIED:1,
		;As stored in instance data, & sent in MSG_APPLY:
		;
		;Whether or not the item group is "modified".  Cleared anytime
		;state is set, set anytime user changes the state of
		;the group (which does not happen if they redundantly click on
		;the already selected item in a GIGBT_EXCLUSIVE or
		;GIGBT_EXTENDED_SELECTION style non-indeterminate group,
		;which causes no state change), and cleared on MSG_APPLY or
		;on any of the selection setting messages if sent by the app.
		;This status may further be modified using
		;MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATUS.  It may be checked
		;using MSG_GEN_ITEM_GROUP_IS_MODIFIED.  The apply message is
		;normally  only sent out on MSG_APPLY if this bit is non-zero,
		;though this behavior can be overridden using
		;ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
		;
		;As sent in status message:
		;
		;GIGSF_MODIFIED will be set if the user has done something
		;to change the state of the item group.  If the user just 
		;clicks on the current exclusive in a GIGBT_EXCLUSIVE or 
		;GIGBT_EXTENDED_SELECTION style group, then this bit will be 
		;clear. If message is the result of a
		;MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG being sent, then this
		;bit will be the value passed in that message.
	:6
GenItemGroupStateFlags end


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

GIGI_behaviorType	GenItemGroupBehaviorType	GIGBT_EXCLUSIVE
	;The type of behavior to use for the list.  Can be set via MSG_GEN_-
	;ITEM_GROUP_SET_BEHAVIOR_TYPE and retrieved vis MSG_GEN_ITEM_GROUP_-
	;GET_BEHAVIOR_TYPE.

GIGI_selection		word	GIGS_NONE
	;The identifier of the item currently selected, if there is one.  If
	;more than one item is selected, is a chunk handle to a list of 
	;selections.  For one or no selections, this can be gotten via a
	;MSG_GEN_ITEM_GROUP_GET_SELECTION; for more than one selection, MSG_GEN-
	;ITEM_GROUP_GET_MULTIPLE_SELECTIONS.  Likewise, the selection can be set
	;via a MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED for no selections, MSG_GEN_-
	;ITEM_GROUP_SET_SINGLE_SELECTION for one selection (with exclusive-none
	;behavior), or MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS for more than
	;one selection (in non-exclusive behavior).

GIGI_numSelections	word	0
	;Current number of selections.  For an exclusive item group, will be set
	;automatically to 1.  For exclusive-none item groups, can be zero.  For 
	;others, can be any value.  Can be queried for via MSG_GEN_ITEM_GROUP_-
	;GET_NUM_SELECTIONS.  Set automatically when the selection(s) are set.

GIGI_stateFlags		GenItemGroupStateFlags	0
	;GenItemGroupStates, for the indeterminate and modified flags.
	;Are set automatically based on selection setting messages; are included
	;in notifications, or can be gotten via MSG_GEN_ITEM_GROUP_IS_MODIFIED
	;and MSG_GEN_ITEM_GROUP_IS_INDETERMINATE.

GIGI_destination	optr
	;The destination of any messages sent out by the object.  This can
	;be set via MSG_GEN_ITEM_GROUP_SET_DESTINATION, and retrieved via
	;MSG_GEN_BOOLEAN_ITEM_GET_DESTINATION.

GIGI_applyMsg	word	0
	;Message to send out to the destination on notifications.  This can
	;be set via MSG_GEN_ITEM_GROUP_SET_ACTION_MSG, and gotten via MSG_GEN_
	;ITEM_GROUP_GET_ACTION_MSG.   The arguments passed in the notify message
	;are as follows:
	;
	; Pass:		cx -- current selection, or first selection in item 
	;		      group, if more than one selection, or GIGS_NONE 
	;		      of no selection
	;		bp -- number of selections
	;		dl -- GenItemGroupStateFlags
	; Return:	nothing
	;		ax, cx, dx, bp -- destroyed
	;


GenItemGroupClass	endc

EndLibrary	ui
