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

	Copyright (c) GeoWorks 1989 -- All Rights Reserved

PROJECT:	PC GEOS
FILE:		Objects/eMenuC.def

DECLARER:	UI

DESCRIPTION:
	This file defines ExpressMenuControlClass

	$Id: eMenuC.def,v 1.2 98/03/18 00:42:37 joon Exp $

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

SetDef	__EXPRESSMENUC

StartLibrary	ui

;
; Message(s) sent out:
;  MSG_NOTIFY_EXPRESS_MENU_CHANGE
;
; Notification type(s) responded to:
;
; GenApplication GCN lists to be placed on:
; 	MGCNLT_ACTIVE_LIST, only if controller is not associated with a
;		GenField object
;
; Standard GCN lists to be placed on:
;	GCNSLT_EXPRESS_MENU_OBJECTS (done automatically)
;
;
; NOTE: An ExpressMenuControlClass object may not be set NOT_USABLE unless it
; has previously been sent a MSG_META_DETACH. Without the MSG_META_DETACH, the
; various utilities that are interested in express menus will not be able
; to clean up after themselves properly.
; 


ExpressMenuControlClass	class	GenControlClass

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

;
; parameters for MSG_EXPRESS_MENU_CONTROL_CREATE_ITEM
;

CreateExpressMenuControlItemFeature	etype	word
CEMCIF_GEOS_TASKS_LIST	enum	CreateExpressMenuControlItemFeature
CEMCIF_DOS_TASKS_LIST	enum	CreateExpressMenuControlItemFeature
CEMCIF_CONTROL_PANEL	enum	CreateExpressMenuControlItemFeature
CEMCIF_UTILITIES_PANEL	enum	CreateExpressMenuControlItemFeature
CEMCIF_SYSTEM_TRAY	enum	CreateExpressMenuControlItemFeature

CreateExpressMenuControlItemPriority	etype	word
CEMCIP_SPOOL_CONTROL_PANEL enum CreateExpressMenuControlItemPriority, 100h
CEMCIP_NETMSG_SEND_MESSAGE enum CreateExpressMenuControlItemPriority, 200h
CEMCIP_SAVER_SCREEN_SAVER  enum CreateExpressMenuControlItemPriority, 300h
CEMCIP_SAVER_SCREEN_LOCK   enum CreateExpressMenuControlItemPriority, 400h
CEMCIP_STANDARD_PRIORITY   enum CreateExpressMenuControlItemPriority, CCO_LAST

CreateExpressMenuControlItemParams	struct
	CEMCIP_feature			CreateExpressMenuControlItemFeature
	; feature to which item is to be created.  Only EMCF_GEOS_TASKS_LIST,
	; EMCF_DOS_TASKS_LIST, ECMF_CONTROL_PANEL, and ECMF_UTILITIES_PANEL
	; allowed
	;
	CEMCIP_class			fptr.ClassStruct
	; class of object to create.  Must be a subclass of GenItemClass
	; for CEMCIF_GEOS_TASKS_LIST or a subclass of GenTrigger for
	; CEMCIF_DOS_TASKS_LIST or a subclass of GenClass for
	; CEMCIF_CONTROL_PANEL and CEMCIF_UTILITIES_PANEL.
	;
	CEMCIP_itemPriority		CreateExpressMenuControlItemPriority
	; Specifies the relative position for the newly created item.
	; Lower numbers will be added in front (above) higher numbers.
	; Use CEMCIP_STANDARD_PRIORITY for default position.
	;
	CEMCIP_responseMessage		word
	; message to send with newly created object's optr.
	;
	CEMCIP_responseDestination	optr
	; destination for response message
	;
	CEMCIP_responseData		word
	; opaque word of data copied to CEMCIRP_data field to help destination
	; figure out what it should do with the new item.
	; 
	CEMCIP_field			optr
	; Only Express Menu Control objects associated with this GenField
	; object will be affected.  Pass 0 if the GenField the Express Menu
	; Control is associated with doesn't matter.
	;
CreateExpressMenuControlItemParams	ends

;
; parameters for response message of CreateExpressMenuControlItemParams
;
CreateExpressMenuControlItemResponseParams	struct
	CEMCIRP_newItem			optr
	; optr of newly created item
	;
	CEMCIRP_data			word
	; opaque word of data copied from CEMCIP_responseData field to help
	; destination figure out what it should do with the new item.
	; 
	CEMCIRP_expressMenuControl	optr
	; optr of Express Menu Control object that created the new item
	;
CreateExpressMenuControlItemResponseParams	ends

MSG_EXPRESS_MENU_CONTROL_CREATE_ITEM		message
;
; Adds object to one of the features in Express Menu Control.  The allowed
; features are DOS Tasks List, GEOS Tasks List, Control Panel, and Utilities
; Panel.
;
; The object is left not-usable with no moniker.  The optr of the object is
; not returned directly by this message, but via a caller-defined message sent
; back to a caller-defined destination.  This allows sending this message to
; all Express Menu Control objects in the system with GCNListSend and the
; GCNSLT_EXPRESS_MENU_OBJECTS_LIST.  The handler of the caller-defined response
; message should set a moniker for the created item and set it usable.  Use
; MSG_EXPRESS_MENU_CONTROL_DESTROY_CREATED_ITEM to destroy this object when you
; are done with it.  If the Express Menu Control object doesn't support the
; requested feature, no item will be created and no response message will be
; sent.  If only Express Menu Control objects associated with a certain
; GenField object should be affected, pass the optr of the field, otherwise
; pass 0.
;
; NOTE:  the identifier of the created item is used internally and
; should not be altered.
;
; Pass:
;	ss:bp = CreateExpressMenuControlItemParams
;	dx = size CreateExpressMenuControlItemParams
; Return:
;	nothing - optr of newly-created object is returned via passed message
;		and destination
;
;	Passed with response-message to response-destination:
;		ss:bp = CreateExpressMenuControlItemResponseParams
;

MSG_EXPRESS_MENU_CONTROL_DESTROY_CREATED_ITEM		message
;
; Destroy a created item.  Use with objects created with
; MSG_EXPRESS_MENU_CONTROL_CREATE_ITEM
;
; Pass:
;	^lcx:dx = optr of object to destroy
;	bp = VisUpdateMode (in low byte, high byte clear)
; Return:
;	nothing
;

;-----------------------------------------------------------------------------
;		Internal methods
;-----------------------------------------------------------------------------

MSG_EMC_LAUNCH_APPLICATION		message
; pass: ^lcx:dx = GenTrigger for application
;	bp = non-zero to force launching application in "desk accessory" mode

MSG_EMC_EXIT_TO_DOS			message
; pass: nothing

MSG_EMC_SELECT_GEOS_TASKS_LIST_ITEM	message
; pass: cx = identifier of selected GEOS Tasks List item
;	bp = # of items selected

MSG_EMC_OPEN_FLOATING_KBD		message
; pass: nothing

MSG_EMC_RETURN_TO_DEFAULT_LAUNCHER	message
; pass:	nothing

MSG_EMC_REALLY_LAUNCH_APPLICATION	message
; pass: ^lcx:dx = GenTrigger for application  (Redwood only)
;	bp = non-zero to force launching application in "desk accessory" mode

MSG_EMC_OPEN_DOCUMENT			message
; pass: ^lcx:dx = GenTrigger for document

;-----------------------------------------------------------------------------
;		Hints
;-----------------------------------------------------------------------------

ATTR_EMC_SET_NOT_USABLE_ON_DETACH	vardata
;
; Used for GenField Express Menu Control instances.  These are sent a
; MSG_META_DETACH when the field is exited and not necessarily when the
; system is detaching.  We want to allow these to be removed from memory
; cleanly.
;

TEMP_EMC_HAS_RETURN_TO_DEFAULT_LAUNCHER	vardata char
;
; Used internally for GenField Express Menu Control instances to indicate
; that this Express Menu Control should add a "Return to <default launcher>"
; button.  Data is name (or path) of default launcher.
;

ATTR_EMC_TRIGGERS_SIGNAL_INTERACTION_COMPLETE	vardata
;
; Used to cause triggers added to the express menu to signal interaction
; complete when they are activated.  (GA_SIGNAL_INTERACTION_COMPLETE)
;

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

; Features flags (used with ATTR_GEN_CONTROL_REQUIRE_UI and
; ATTR_GEN_CONTROL_PROHIBIT_UI)

EMCFeatures	record
    EMCF_DOCUMENTS_LIST:1
    EMCF_GEOS_TASKS_LIST:1
    EMCF_DESK_ACCESSORY_LIST:1
    EMCF_MAIN_APPS_LIST:1
    EMCF_OTHER_APPS_LIST:1
    EMCF_CONTROL_PANEL:1
    EMCF_DOS_TASKS_LIST:1
    EMCF_UTILITIES_PANEL:1
    EMCF_EXIT_TO_DOS:1
EMCFeatures	end

EMC_DEFAULT_FEATURES equ mask EMCF_DOCUMENTS_LIST or \
				mask EMCF_GEOS_TASKS_LIST or \
				mask EMCF_DESK_ACCESSORY_LIST or \
				mask EMCF_MAIN_APPS_LIST or \
				mask EMCF_OTHER_APPS_LIST or \
				mask EMCF_CONTROL_PANEL or \
				mask EMCF_DOS_TASKS_LIST or \
				mask EMCF_UTILITIES_PANEL or \
				mask EMCF_EXIT_TO_DOS

; Suggested features for different UI levels

EMC_SUGGESTED_INTRODUCTORY_FEATURES equ mask EMCF_DESK_ACCESSORY_LIST or \
					mask EMCF_CONTROL_PANEL or \
					mask EMCF_DOS_TASKS_LIST or \
					mask EMCF_UTILITIES_PANEL

EMC_SUGGESTED_BEGINNING_FEATURES equ EMC_SUGGESTED_INTRODUCTORY_FEATURES

EMC_SUGGESTED_INTERMEDIATE_FEATURES equ EMC_SUGGESTED_BEGINNING_FEATURES or \
					mask EMCF_GEOS_TASKS_LIST or \
					mask EMCF_MAIN_APPS_LIST or \
					mask EMCF_OTHER_APPS_LIST or \
					mask EMCF_EXIT_TO_DOS

EMC_SUGGESTED_ADVANCED_FEATURES equ EMC_SUGGESTED_INTERMEDIATE_FEATURES

; Constants and structures

;-----------------------------------------------------------------------------
;		Variable Data
;-----------------------------------------------------------------------------
EMCDetachData	struct
    EMCDD_ackEvent	hptr		; recorded MSG_META_ACK that will be
					;  sent back by everyone on the
					;  EXPRESS_MENU_CHANGE list
    EMCDD_childBlock	hptr		; handle of child block to be freed when
					;  MSG_META_DETACH_COMPLETE comes in,
					;  saying that everyone who could
					;  possibly care has acknowledged the
					;  detach, so it's safe to actually
					;  free the child block, which the
					;  GenControl object won't do when it
					;  receives a MSG_META_DETACH
EMCDetachData	ends

TEMP_EXPRESS_MENU_CONTROL_DETACH_DATA	vardata	EMCDetachData

ATTR_EMC_SYSTEM_TRAY			vardata

;-----------------------------------------------------------------------------
;		Instance Data
;-----------------------------------------------------------------------------

ExpressMenuControlClass	endc

EndLibrary	ui
