OpDescriptor Class Reference

#include <opdesc.h>

Inheritance diagram for OpDescriptor:

List of all members.

Public Member Functions
virtual OpState	GetOpsState (String_256 *, OpParam *pOpParam=NULL)
	This function will get called to determine the greyed/ticked state of the operation. It tests various conditions (based on the AutoStateFlgs) and then if the op survives this, calls the GetState fn which was registered with the operation.
void	Invoke (OpParam *pOpParam=NULL, BOOL fWithUndo=TRUE)
	This Function uses the Operation runtime class to create an instance of the operation object and call its DO function.
	OpDescriptor (UINT32 toolID, UINT32 txID, CCRuntimeClass *Op, TCHAR *tok, pfnGetState gs, UINT32 helpId=0, UINT32 bubbleID=0, UINT32 resourceID=0, UINT32 controlID=0, BOOL ReceiveMessages=FALSE, BOOL Smart=FALSE, BOOL Clean=TRUE, UINT32 OneOpenInstID=0, UINT32 AutoStateFlags=0, BOOL fCheckable=FALSE)
	Construct a new OpDescriptor object and link it into the list of all OpDescriptors Both the resource and control IDs may be zero (the default case) in which case the OpDescriptor is not connected to any form of control. If the resource ID alone is supplied it is taken to refer to a bitmap and the Opdescriptor will be connected to a bitmap button. If both resource and control IDs are supplied then they refer to an arbitrary control.
	~OpDescriptor ()
	Standard destructor.
OpFlgs	GetOpFlags ()
	To obtain the OpFlags describing the type of the operation.
void	SetBarControlInfo (BarControlInfo ThisInfo)
void	AliasOperation (CCRuntimeClass *AliasOp, pfnGetState AliasGetState, UINT32 AliasAutoStateFlags=0, UINT32 AliasTextID=0, UINT32 AliasBubbleID=0)
	Allows you to alias an op descriptor, i.e. provide an alternative operation and GetState function for a registered op descriptor. This mechanism allows a standard operation, or user action, to have a different internal action or implementation.
void	RemoveAlias ()
	Removes the alias for this operation.
BOOL	IsAliased ()
	Tells you whether the OpDesc is aliased or not.
BOOL	IsHotKeyEnabled () const
	Determines whether or not the hot key associated with this op should be shown to the user via HotKey::FindHotKey() Notes: Presently used to disable Ctrl-S when save op is used for update. See Also: DisableHotKey(), EnableHotKey().
void	DisableHotKey ()
	Disables the hot key associated with this op See Also: IsHotKeyEnabled(), EnableHotKey().
void	EnableHotKey ()
	Enables the hot key associated with this op See Also: DisableHotKey(), IsHotKeyEnabled().
virtual BOOL	GetText (String_256 *Description, OpTextFlags WhichText)
	This function will use the TextID and ModuleID values to obtain a String resource describing an operation. String resources may have one or more text descriptions in them, therefore, a TextFlag can be used to identify the the appropriate text required.
virtual MsgResult	Message (Msg *Msg)
	The default OpDescriptor message handler.
BOOL	BuildGadgetList (List *pOutputList)
	Builds a list of GadgetListItems, each item holding a DialogBarOp* and a CGadgetID for a control associated with this OpDescriptor. This allows the caller to manipulate the controls even if there isn't a message from them needing processing. NB. the caller is responsible for allocating and deallocating this list!
virtual void	OnControlCreate (OpDescControlCreateMsg *CreateMsg)
	The OnControlCreate method is called by the OpDescriptor's default Message handler when a new control has just been created. You should override this method to perform gadget initialisation.
virtual void	OnSelectionChange (OpDescControlMsg *SelChangedMsg, List *GadgetList)
	The OnSelectionChange method is called whenever the user selects a new value from the gadget .. (blah blah.
virtual void	OnSliderChanging (OpDescControlMsg *SliderChangingMsg)
	Called when the sliders position is being changed (if its associated with this opdescriptor).
virtual void	OnSliderSet (OpDescControlMsg *SelChangedMsg)
	Called when the sliders position changes (if its associated with this opdescriptor).
virtual void	OnSliderCancelled (OpDescControlMsg *SelChangedMsg)
	Called when the sliders position is being cancelled (if its associated with this opdescriptor).
TCHAR *	ReadString (TCHAR *pDesc)
	Reads the string until delimeter or end of string.
TCHAR *	GetMenuNameString (TCHAR *pDesc)
	Reads the menu text in position one and removes any ampersands denoting an accelerator.
void	SetStringPos (TCHAR **pDesc, OpTextFlags WhichText)
	Scans through a string and sets the pDesc pointer to the appropriate text in the string resource. The text position is determined by the ordinal value of the WhichText value.
UINT32	GetHelpId ()
	returns the Help Id
UINT32	GetToolID ()
	Returns the Tool ID.
UINT32	GetBubbleId ()
	returns the string resource ID of the "bubble-help" text.
const BarControlInfo *	GetBarControlInfo ()
	Returns the bar control info of the OpDescriptor. This is a platform-indy representation of the control which can be placed on toolbars to invoke this Operation.
Static Public Member Functions
static OpDescriptor *	FindOpDescriptor (TCHAR *Token)
	To search the OpDescriptor list and find the OpDescriptor described by Token.
static OpDescriptor *	FindOpDescriptor (CCRuntimeClass *Op)
	To search the OpDescriptot list and find the OpDescriptor described by Token.
static OpDescriptor *	FindOpDescriptor (ResourceID res)
	To search the OpDescriptor list and find an entry with the given resource ID. Note it is compared against the 'control' entry.
static void	DestroyAll ()
	Since the OpDescriptor maintains its own static list of all the OpDescriptors created in the program, and since none of them are actually destroyed with a call to a destructor, we have to do it ourselves by a call to this function in the DeInit kernel type of function. Basically it walks through the list of OpDescriptors and destroys them all.
static void	RemoveAllAliases ()
	Goes through the list of op descriptors, removing all aliases.
static OpListItem *	GetFirstDescriptor ()
	returns the first OpListItem in the list
static OpListItem *	GetNextDescriptor (OpListItem *CurrOp)
	returns the next OpListItem in the list
static void	LinkDescriptor (OpDescriptor *ThisOp)
	Add the OpDescriptor to the list of all OpDescriptors.
static BOOL	DelinkDescriptor (OpDescriptor *pThisOp)
	Delete the OpDescriptor from the list of all OpDescriptors.
Public Attributes
String	Token
Protected Member Functions
TCHAR *	GetDescription (TCHAR *pDesc, OpTextFlags WhichText)
	Scans through a string and retrieves the text associated with the text flag passed in as a parameter.
Protected Attributes
DWORD	ModuleID
UINT32	TextID
UINT32	HelpID
UINT32	BubbleID
BarControlInfo	BarCtrlInfo
CCRuntimeClass *	OpClass
OpFlgs	Flags
BOOL	m_bHotKeyEnabled
BOOL	Aliased
CCRuntimeClass *	AliasOpClass
pfnGetState	OldGetState
UINT32	OldAutoStateFlags
UINT32	OldTextID
UINT32	OldBubbleID
UINT32	OneInstID
UINT32	AutoStateFlgs
pfnGetParamState	GetParamState
Private Attributes
pfnGetState	GetState
Static Private Attributes
static List	OpList

---

Detailed Description

Definition at line 455 of file opdesc.h.

---

Constructor & Destructor Documentation

OpDescriptor::OpDescriptor (  UINT32  toolID, UINT32  txID, CCRuntimeClass *  Op, TCHAR *  tok, pfnGetState  gs, UINT32  helpID = 0, UINT32  bubbleID = 0, UINT32  resourceID = 0, UINT32  controlID = 0, BOOL  ReceiveMessages = FALSE, BOOL  Smart = FALSE, BOOL  Clean = TRUE, UINT32  OneOpenInstID = 0, UINT32  AutoStateFlags = 0, BOOL  fCheckable = FALSE )

Construct a new OpDescriptor object and link it into the list of all OpDescriptors Both the resource and control IDs may be zero (the default case) in which case the OpDescriptor is not connected to any form of control. If the resource ID alone is supplied it is taken to refer to a bitmap and the Opdescriptor will be connected to a bitmap button. If both resource and control IDs are supplied then they refer to an arbitrary control. ); Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 10/8/93 Parameters: [INPUTS]  toolID - Module resource Identifier txID - Text description resource Identifier tok - pointer to a static string that describe the operation gs - pointer to the GetState function in your operation The following flags specify the type of the operation. They have default values for a normal non-undoable operation. ReceiveMessages - should the OpDescriptor receive system messages Smart - Smart Duplicate Clean - does the operation change the document helpId - Help Identifier that acts as an index into a help file bubbleID - string resource for "bubble help" text. resourceID - resource identifier of the resource containing the control. controlID - control identifier within that resource. OneOpenInstID - When non 0 only one live instance of the operation is permitted, and OneOpenInstID is the string resource ID describing why.This is useful for 1 open instance dialogs. AutoStateFlags - These flags are used to specify when the Operation should automatically be greyed, ticked etc. they cut down the number of tests that need to be made in the GetState fn. See the top of OpDesc.h for an uptodate list of these. The flags should be or'd eg. GREY_WHEN_NO_CURRENT_DOC | GREY_WHEN_NO_SELECTION Returns: Errors: ENSURE fails if any of the params are NULL (ie leaving params off is NOT allowed. Definition at line 271 of file opdesc.cpp. : MessageHandler(CC_RUNTIME_CLASS(OpDescriptor), ReceiveMessages), ModuleID(Tool::GetModuleID(toolID)), TextID(txID), HelpID(helpID), BubbleID(bubbleID), BarCtrlInfo(resourceID,controlID,toolID), OpClass(Op), OneInstID(OneOpenInstID), AutoStateFlgs(AutoStateFlags), GetState(gs), Token(tok) { Flags.Smart = Smart; Flags.Clean = Clean; Flags.fCheckable = fCheckable; Aliased = FALSE; m_bHotKeyEnabled = TRUE; GetParamState = NULL; ENSURE( tok /*&& gs*/, "OpDescriptor: new OpDescriptor called with a NULL parameter" ); LinkDescriptor(this); }

OpDescriptor::~OpDescriptor (   )

Standard destructor. Author: Neville_Humphrys (Xara Group Ltd) <camelotdev@xara.com> Date: 16/12/96 Definition at line 326 of file opdesc.cpp. { // Could now call the DelinkDescriptor }

---

Member Function Documentation

void OpDescriptor::AliasOperation (  CCRuntimeClass *  AliasOp, pfnGetState  AliasGetState, UINT32  AliasAutoStateFlags = 0, UINT32  AliasTextID = 0, UINT32  AliasBubbleID = 0 )

Allows you to alias an op descriptor, i.e. provide an alternative operation and GetState function for a registered op descriptor. This mechanism allows a standard operation, or user action, to have a different internal action or implementation. Author: Mark_Neves (Xara Group Ltd) <camelotdev@xara.com> Date: 19/7/94 Parameters: AliasOp  - The runtime class of the operation you wish this OpDesc to invoke [INPUTS] as an alternative to the one that was registered with the OpDesc If NULL, then the registered op will be invoked AliasGetState - Alternative GetState function used to gather info on the op such as whether menu items should be greyed, etc If NULL, then the registered GetState fn will be used AliasAutoStateFlags - Auto state flags to use instead of the ones provided when op was registered. Only used if param AliasGetState is NOT NULL. AliasTextID - Alternative text ID (0 if you don't want this changed) AliasBubbleID - Alternative bubble help ID (0 if you don't want this changed) Returns: - When aliasing an OpDesc, you can provide just one of the two params. AliasOperation(NULL,MyGetState,MyAutoStateFlags) means you are quite happy with the standard op but you want to replace the way the state of the OpDesc is determined. The registered auto state flags are replaced with MyAutoStateFlags AliasOperation(MyOp,NULL,MyAutoStateFlags) means you want to change the internal implementation but the state function is OK and does the job. The registered auto state flags is retained. I.e. MyAutoStateFlags param IS IGNORED!!!!! AliasOperation(NULL,NULL) causes an error in debug builds - i.e. what is the point? IMPORTANT: When aliasing an OpDesc it is very important that the high level functionality of the op remains the same. E.g. Aliasing the "Cut" op should not suddenly create a flower in the current layer. It should "Cut" something in a way that is consistant with the user's perception of the op. E.g. "Delete" has a menu item and button. When in the selector tool, he'd expect Delete to delete the selected objects. When in the grid tool, he'd expect Delete to delete the selected grids. However, the mechanisms of the two tools are very different. So the grid tool needs to alias the Delete op descriptor, so an alternative operation is invoked when the "Delete" menu item or button (or keypress!) is activated by the user. The grid tool may do something like this when it becomes active: Find the pre-registered OpDesc that we're interested in OpDescriptor* pOpDesc = FindOpDescriptor(OPTOKEN_DELETE); Alias it with an alternative op and GetState pOpDesc->AliasOperation(CC_RUNTIME_CLASS(GridDeleteOp),GridDeleteOpGetState,0); NOTE: At the time of writing this mechanism, it was asumed only tools would be allowed to alias OpDescs. To aid this, a call to RemoveAllAliases() has been placed in the tool mechanism at the point where the tool is deselected. Returns: Errors: In debug builds it will ENSURE if the OpDesc is already aliased, or if both params are NULL. Definition at line 674 of file opdesc.cpp. { ENSURE(Aliased == FALSE,"This OpDesc is already aliased"); if (Aliased) return; ENSURE((AliasOp != NULL) || (AliasGetState != NULL),"What is the point of aliasing an OpDesc when both params are NULL?"); if ((AliasOp == NULL) && (AliasGetState == NULL)) return; // Note the alias op class AliasOpClass = AliasOp; // Save the old state OldGetState = GetState; OldAutoStateFlags = AutoStateFlgs; OldTextID = TextID; OldBubbleID = BubbleID; // Have we an alternative GetState func? if (AliasGetState != NULL) { // Only replace the GetState and AutoStateFlags if an alternative has been provided GetState = AliasGetState; AutoStateFlgs = AliasAutoStateFlags; } // Only replace the text & bubble help IDs if they have been provided if (AliasTextID > 0) TextID = AliasTextID; if (AliasBubbleID > 0) BubbleID = AliasBubbleID; Aliased = TRUE; }

BOOL OpDescriptor::BuildGadgetList (  List *  pOutputList  )

Builds a list of GadgetListItems, each item holding a DialogBarOp* and a CGadgetID for a control associated with this OpDescriptor. This allows the caller to manipulate the controls even if there isn't a message from them needing processing. NB. the caller is responsible for allocating and deallocating this list! Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> Date: 18/5/94 Parameters: A  pointer to a list which will hold the gadgets. [INPUTS] A  list of gadgets. [OUTPUTS] Returns: TRUE if there are some gadgets associated with this OpDescriptor, FALSE if there aren't any. Errors: - See also: class GadgetListItem Definition at line 1058 of file opdesc.cpp. { #if !defined(EXCLUDE_FROM_RALPH) return ControlList::Get()->BuildGadgetList(pOutputList, this); #else return FALSE; #endif // Old code #if 0 ENSURE(pOutputList != NULL, "Null output list in OpDescriptor::BuildGadgetList"); PORTNOTETRACE("other","OpDescriptor::BuildGadgetList - do nothing"); // Get a pointer to the list of DialogBarOps, if there is one. List* pDialogBarOpList = MessageHandler::GetClassList(CC_RUNTIME_CLASS(DialogBarOp)); if (pDialogBarOpList == NULL) return FALSE; // Get the first item on the DialogBarOp list. DialogBarOp* pDialogBarOp = (DialogBarOp*) pDialogBarOpList->GetHead(); while (pDialogBarOp != NULL) { if (pDialogBarOp->WindowID != 0) { BarItem* pBarItem = pDialogBarOp->GetPtrBarHead(); while (pBarItem != NULL) { if (pBarItem->IsKindOf(CC_RUNTIME_CLASS(BarControl))) { BarControl* pBarControl = (BarControl*) pBarItem; BOOL bIsHorizontal = pDialogBarOp->IsHorizontal(); if (pBarControl->GetOpDescriptor(bIsHorizontal) == this) { // Found a control associated with this OpDescriptor, so add it // to our list of gadgets. CGadgetID gid = pBarControl->GetUniqueGadgetID(); GadgetListItem* pgListItem = new GadgetListItem(pDialogBarOp, gid); if (pgListItem == NULL) { pOutputList->DeleteAll(); return FALSE; } pOutputList->AddHead(pgListItem); } } pBarItem = pDialogBarOp->GetPtrBarNext(pBarItem); } } pDialogBarOp = (DialogBarOp*) pDialogBarOpList->GetNext(pDialogBarOp); } // Return TRUE/FALSE depending on if there are any entries on the list. return !pOutputList->IsEmpty(); #endif }

BOOL OpDescriptor::DelinkDescriptor (  OpDescriptor *  pThisOp  )  [static]

Delete the OpDescriptor from the list of all OpDescriptors. Author: Neville_Humphrys (Xara Group Ltd) <camelotdev@xara.com> Date: 16/12/96 Parameters: pointer  to the OpDescriptor [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: - Scope: private Definition at line 372 of file opdesc.cpp. { // Search the list of ops and remove this item from the list OpListItem* pOpListItem = OpDescriptor::GetFirstDescriptor(); while (pOpListItem) { if (pThisOp == pOpListItem->pOpDesc) { // remove this item from the list OpList.RemoveItem(pOpListItem); delete pOpListItem; return TRUE; } pOpListItem = OpDescriptor::GetNextDescriptor(pOpListItem); } // Didn't find anything or do anything return FALSE; }

void OpDescriptor::DestroyAll (   )  [static]

Since the OpDescriptor maintains its own static list of all the OpDescriptors created in the program, and since none of them are actually destroyed with a call to a destructor, we have to do it ourselves by a call to this function in the DeInit kernel type of function. Basically it walks through the list of OpDescriptors and destroys them all. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 22/7/93 Definition at line 843 of file opdesc.cpp. { ListItem* Item; while( (Item = OpList.RemoveHead()) != NULL ) { delete ((OpListItem*)Item)->pOpDesc; delete Item; } }

void OpDescriptor::DisableHotKey (   )

Disables the hot key associated with this op See Also: IsHotKeyEnabled(), EnableHotKey(). Author: Colin_Barfoot (Xara Group Ltd) <camelotdev@xara.com> Date: 24/09/96 Definition at line 807 of file opdesc.cpp. { m_bHotKeyEnabled = FALSE; }

void OpDescriptor::EnableHotKey (   )

Enables the hot key associated with this op See Also: DisableHotKey(), IsHotKeyEnabled(). Author: Colin_Barfoot (Xara Group Ltd) <camelotdev@xara.com> Date: 24/09/96 Definition at line 823 of file opdesc.cpp. { m_bHotKeyEnabled = TRUE; }

OpDescriptor * OpDescriptor::FindOpDescriptor (  ResourceID  res  )  [static]

To search the OpDescriptor list and find an entry with the given resource ID. Note it is compared against the 'control' entry. Author: Alex Bligh <alex@alex.org.uk> Date: 17/01/2005 Parameters: res  - ID of resource to find [INPUTS] Returns: a pointer to the OpDescriptor that contains Token, or NULL if it could not be found Definition at line 589 of file opdesc.cpp. { OpListItem* CurrentItem = GetFirstDescriptor(); while (CurrentItem != NULL) { // if we have found a match, return a pointer to it if ( CurrentItem -> pOpDesc -> BarCtrlInfo.ControlID == res ) return CurrentItem -> pOpDesc; CurrentItem = GetNextDescriptor( CurrentItem ); // next item in the list } return NULL; // failed to find a match, so return null }

OpDescriptor * OpDescriptor::FindOpDescriptor (  CCRuntimeClass *  Op  )  [static]

To search the OpDescriptot list and find the OpDescriptor described by Token. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 5/10/93 Parameters: CCRuntimeClass  - a pointer to a RuntimeClass [INPUTS] Returns: a pointer to the OpDescriptor that contains Token, or NULL if it could not be found Definition at line 559 of file opdesc.cpp. { OpListItem* CurrentItem = GetFirstDescriptor(); while (CurrentItem != NULL) { // if we have found a match, return a pointer to it if ( CurrentItem -> pOpDesc -> OpClass == Op ) return CurrentItem -> pOpDesc; CurrentItem = GetNextDescriptor( CurrentItem ); // next item in the list } return NULL; // failed to find a match, so return null }

OpDescriptor * OpDescriptor::FindOpDescriptor (  TCHAR *  Token  )  [static]

To search the OpDescriptor list and find the OpDescriptor described by Token. Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 16/7/93 Parameters: Token  - a pointer to a string to find [INPUTS] Returns: a pointer to the OpDescriptor that contains Token, or NULL if it could not be found Definition at line 529 of file opdesc.cpp. { OpListItem* CurrentItem = GetFirstDescriptor(); while (CurrentItem != NULL) { // if we have found a match, return a pointer to it if (camStrcmp( CurrentItem -> pOpDesc -> Token, Token ) == 0) return CurrentItem->pOpDesc; CurrentItem = GetNextDescriptor( CurrentItem ); // next item in the list } return NULL; // failed to find a match, so return null }

const BarControlInfo * OpDescriptor::GetBarControlInfo (   )

Returns the bar control info of the OpDescriptor. This is a platform-indy representation of the control which can be placed on toolbars to invoke this Operation. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> F (modified by Phil 13/04/94) Date: 16/2/94 Definition at line 946 of file opdesc.cpp. { return (&BarCtrlInfo); }

UINT32 OpDescriptor::GetBubbleId (   )

returns the string resource ID of the "bubble-help" text. Author: Justin_Flude (Xara Group Ltd) <camelotdev@xara.com> F Date: 16/2/94 Definition at line 930 of file opdesc.cpp. { return BubbleID; }

TCHAR * OpDescriptor::GetDescription (  TCHAR *  pDesc, OpTextFlags  WhichText )  [protected]

Scans through a string and retrieves the text associated with the text flag passed in as a parameter. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 9/8/93 Parameters: TextFlag  - Identifies which text string to retrieve from the string resource [INPUTS] Description - Operation description string. Returns: Pointer to string description or NULL otherwize Note: Put as a class function by Neville 11/12/96 Has this man never heard of the switch statement ??? Definition at line 1373 of file opdesc.cpp. { /**** Has this man never heard of the switch statement ??? ****/ // if Menu Text is required then return text string. if (WhichText == OP_MENU_TEXT) return ReadString(pDesc); else // if Help Description is required then return text string if (WhichText == OP_DESC_TEXT) { SetStringPos(&pDesc, WhichText); return ReadString(pDesc); } else // if Undo Text is required then return text string. if (WhichText == OP_UNDO_TEXT) { SetStringPos(&pDesc, WhichText); return ReadString(pDesc); } // if Menu Name is required then return text string. if (WhichText == OP_MENU_NAME) { return GetMenuNameString(pDesc); } // Add next string type here!!! else return NULL; }

static OpListItem* OpDescriptor::GetFirstDescriptor (   )  [inline, static]

returns the first OpListItem in the list Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 30/6/93 Definition at line 650 of file opdesc.h. { return ((OpListItem*)(OpList.GetHead())); }

UINT32 OpDescriptor::GetHelpId (   )

returns the Help Id Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 25/1/94 Definition at line 902 of file opdesc.cpp. { return HelpID; }

TCHAR * OpDescriptor::GetMenuNameString (  TCHAR *  pDesc  )

Reads the menu text in position one and removes any ampersands denoting an accelerator. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 18/10/93 Parameters: Description  - Operation description string. [INPUTS] Definition at line 1490 of file opdesc.cpp. { const TCHAR ACCELERATOR_LETTER = '&'; static TCHAR pText[MAX_TEXT_SIZE]; UINT32 pos = 0; // Get Text String while ( (*pDesc != END_OF_STRING) && (*pDesc != STRING_DELIMETER) && (pos <= (MAX_TEXT_SIZE - 1))) { if (*pDesc != ACCELERATOR_LETTER) pText[pos++] = *pDesc; pDesc++; } // Set end of string pText[pos] = END_OF_STRING; return pText; }

static OpListItem* OpDescriptor::GetNextDescriptor (  OpListItem *  CurrOp  )  [inline, static]

returns the next OpListItem in the list Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 30/6/93 Parameters: pointer  to last OpListItem returned by GetFirst ot GetNextDescriptor [INPUTS] Definition at line 668 of file opdesc.h. { return ((OpListItem*)OpList.GetNext(CurrOp)); }

OpFlgs OpDescriptor::GetOpFlags (   )

To obtain the OpFlags describing the type of the operation. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 22/3/94 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: The OpFlags Errors: - See also: - Definition at line 195 of file opdesc.cpp. { return Flags; }

OpState OpDescriptor::GetOpsState (  String_256 *  Desc, OpParam *  pOpParam = NULL )  [virtual]

This function will get called to determine the greyed/ticked state of the operation. It tests various conditions (based on the AutoStateFlgs) and then if the op survives this, calls the GetState fn which was registered with the operation. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 26/8/94 Parameters: -  [INPUTS] -  [OUTPUTS] Returns: Desc: A description of why the op is greyed. Errors: - See also: - Definition at line 1134 of file opdesc.cpp. { OpState OpSt; String_256 DisableReason; // Test the AutoStateFlgs to determine if any automatic checks are required for this // OpDescriptor. if (AutoStateFlgs & GREY_WHEN_NO_CURRENT_DOC) { // Check if there is a selected (user) document if (Document::GetSelected() == NULL) { // There is no current document OpSt.Greyed = TRUE; // Load reason why operation is disabled DisableReason = String_256(_R(IDS_NO_DOC)); *Desc = DisableReason; goto End; } } if (AutoStateFlgs & GREY_WHEN_NO_SELECTION) { // Find the first node which is selected Node* FirstSelectedNode = GetApplication()->FindSelection()->FindFirst(); if (FirstSelectedNode == NULL) { // No nodes are selected OpSt.Greyed = TRUE; // Load reason why operation is disabled DisableReason = String_256(_R(IDS_NO_OBJECTS_SELECTED)); *Desc = DisableReason; goto End; } } // Changed 10/1/95 by MarkN & Phil // // The new 'if' statement is a temp fix until we are in a position to put correct logic in and // change all the ops to cope with the change. // // This fix allows ops that have "grey when no current doc" and/or "grey when no selection" to // still work when select-inside is present. // // if (AutoStateFlgs & ~DONT_GREY_WHEN_SELECT_INSIDE) if (!(AutoStateFlgs & DONT_GREY_WHEN_SELECT_INSIDE) && ((AutoStateFlgs & GREY_WHEN_NO_CURRENT_DOC) || (AutoStateFlgs & GREY_WHEN_NO_SELECTION) ) ) { // Find the selection range Range Sel(*(GetApplication()->FindSelection())); RangeControl rg = Sel.GetRangeControlFlags(); rg.PromoteToParent = TRUE; Sel.Range::SetRangeControl(rg); if ( Sel.ContainsSelectInside() ) { // The selection contains selection inside OpSt.Greyed = TRUE; // Load reason why operation is disabled DisableReason = String_256(_R(IDS_GREY_WHEN_SELECT_INSIDE)); *Desc = DisableReason; goto End; } } if (OneInstID != 0) { // Only one live instance of the operation is allowed. It's probably a dialog if (MessageHandler::MessageHandlerExists(OpClass)) { OpSt.Greyed = TRUE; *Desc = String_256(OneInstID); goto End; } } // The operation survived all auto tests, so call the GetState fn // First, try to newer, parameterised way fo getting state info if (GetParamState != NULL && pOpParam!=NULL) { return (GetParamState(Desc, this, pOpParam)); } // If that didn't do anything fall back to the older way of doing things if (GetState != NULL) { return (GetState(Desc, this)); } End: // We jump here when we know the correct state, if there are ever any // auto tick test's things will be a bit different cos an op could be // ticked and greyed (well its possible, but not very likely) return OpSt; }

BOOL OpDescriptor::GetText (  String_256 *  Description, OpTextFlags  WhichText )  [virtual]

This function will use the TextID and ModuleID values to obtain a String resource describing an operation. String resources may have one or more text descriptions in them, therefore, a TextFlag can be used to identify the the appropriate text required. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 9/8/93 Parameters: TextFlag  - Identifies which text string to retrieve from the string resource [INPUTS] Description  - Operation description string if it is found or [OUTPUTS] NULL otherwise. Returns: TRUE if successfully retrieves the string and FALSE othersise. See also: GetDescription Note: Made virtual by Neville 11/12/96 Reimplemented in ParamOpDescriptor, PlugInOpDescriptor, FrameInFrontOpDescriptor, and FrameBehindOpDescriptor. Definition at line 875 of file opdesc.cpp. { String_256 ResourceText( TextID, ModuleID ); TCHAR* ok; // Explicitly cast return value from GetDescription from a TCHAR* to a String_256 ok = GetDescription((TCHAR*) ResourceText, WhichText); // if description is found then return true else return false if (ok) { *Description = String_256(ok); return TRUE; } else return FALSE; }

UINT32 OpDescriptor::GetToolID (   )

Returns the Tool ID. Author: Phil_Martin (Xara Group Ltd) <camelotdev@xara.com> Date: 20/04/94 Definition at line 916 of file opdesc.cpp. { return BarCtrlInfo.ToolID; }

void OpDescriptor::Invoke (  OpParam *  pOpParam = NULL, BOOL  fWithUndo = TRUE )

This Function uses the Operation runtime class to create an instance of the operation object and call its DO function. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 10/8/93 Parameters: [INPUTS]  pOpParam: Optional operation parameters. If pOpParam is NULL then the operations Do function is called, if pOpParam is not NULL then DoWithParam is called. fWithUndo if FALSE then don't put this Operation in the undo buffer. USE WITH CAUTION (this must be tested on an Op by Op basis). By default TRUE, ie. make undo info. Returns: Errors: As a safeguard before the operation is invoked its GetState fn is invoked to make sure that the Operation is executable. If the Operation is not executable then an ENSURE failure will occur in a debug build. In a retail build DialogBarOp::UpdateStateOfAllBars is called and the operation is not executed. See also: OpDescriptor::OpDescriptor OpParam Operation::Do Operation::DoWithParam Definition at line 428 of file opdesc.cpp. { // Before we invoke the operation we call the operation's GetState fn to make sure // that it is executable. String_256 Dummy; OpState State = GetOpsState(&Dummy); if (!State.Greyed) { Operation* Op; CCRuntimeClass* TheOpClass; // Find out which operation this OpDesc should invoke, i.e. has it been aliased if (Aliased) { if (AliasOpClass != NULL) TheOpClass = AliasOpClass; else TheOpClass = OpClass; } else TheOpClass = OpClass; // Use the TheOpClass pointer to a runtime class in order to generate an instance of // the appropriate operation object Op = (Operation*) TheOpClass->CreateObject(); if (Op) { #if !defined(EXCLUDE_FROM_RALPH) // Update the state of the bars DialogBarOp::SetSystemStateChanged(TRUE); // If the op has not got its own way of showing the progress BOOL ShowProgressIndicator = !(Op->GetOpFlgs().HasOwnTimeIndicator); if (ShowProgressIndicator) { // Bring up the progress indicator (This has been made re-enterant) BeginSlowJob(); } #endif // On all but OpExit, send around an OpMsg::START. if (!IS_A(Op, OpExit)) BROADCAST_TO_ALL(OpMsg(Op, OpMsg::BEGIN)); // Discard undo information if appropriate. if (!fWithUndo) Op->SucceedAndDiscard(); // Call either parameterised or default Do function. if (pOpParam == 0) Op->Do(this); else Op->DoWithParam(this, pOpParam); #if !defined(EXCLUDE_FROM_RALPH) if (ShowProgressIndicator) { EndSlowJob(); } #endif } } else { #if !defined(EXCLUDE_FROM_RALPH) // The operation is disabled. This means that DialogBarOp::UpdateStateOfAllBars // was not called after a change in the state of the system. // If ShouldUpdateBarState returns TRUE then the operation was probably invoked before // the Idle event had a chance to update it. // If this ENSURE goes bang it indicates that SetSystemStateChanged was not called when it // should have been. ENSURE(DialogBarOp::ShouldUpdateBarState(), "Trying to execute operation which should be disabled"); // This ENSURE does not indicate a real error but I think its worth keeping it in as it indicates // that the idle update processing may not be frequent enough. //ENSURE(FALSE, "Trying to execute Operation before we have had a chance to disable it"); // Update the bar state and leave DialogBarOp::SetSystemStateChanged(); DialogBarOp::UpdateStateOfAllBars(); // Beep(); // Just to annoy him ! #endif } }

BOOL OpDescriptor::IsAliased (   )

Tells you whether the OpDesc is aliased or not. Author: Mark_Neves (Xara Group Ltd) <camelotdev@xara.com> Date: 27/7/94 Parameters: -  [INPUTS] Returns: TRUE if it is aliased, FALSE otherwise. Definition at line 748 of file opdesc.cpp. { return (Aliased); }

BOOL OpDescriptor::IsHotKeyEnabled (   )  const

Determines whether or not the hot key associated with this op should be shown to the user via HotKey::FindHotKey() Notes: Presently used to disable Ctrl-S when save op is used for update. See Also: DisableHotKey(), EnableHotKey(). Author: Colin_Barfoot (Xara Group Ltd) <camelotdev@xara.com> Date: 24/09/96 Definition at line 791 of file opdesc.cpp. { return m_bHotKeyEnabled; }

void OpDescriptor::LinkDescriptor (  OpDescriptor *  ThisOp  )  [static]

Add the OpDescriptor to the list of all OpDescriptors. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 27/03/94 Parameters: pointer  to the OpDescriptor [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: - Scope: private Note: Moved from header file to here 16/12/96 Definition at line 348 of file opdesc.cpp. { OpListItem* OpItem = new OpListItem; // A bit naughty I know but its got to be called from // the constructor (during initialisation) OpItem->pOpDesc = ThisOp; OpList.AddTail(OpItem); }

MsgResult OpDescriptor::Message (  Msg *  Msg  )  [virtual]

The default OpDescriptor message handler. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 16/4/94 Parameters: Msg,:  The message to handle [INPUTS] -  [OUTPUTS] Returns: - Errors: - See also: - Reimplemented from MessageHandler. Reimplemented in ChangeFeatherSizeSliderOpDesc, ChangeFeatherProfileOpDesc, OpZoomDescriptor, and OpZoomComboDescriptor. Definition at line 966 of file opdesc.cpp. { // Is this a message for the OpDescriptor ?? if (MESSAGE_IS_A(Msg,OpDescMsg)) { if ( ((OpDescMsg*)Msg)->OpDesc == this) { if (MESSAGE_IS_A(Msg,OpDescControlCreateMsg)) { // The control associated with the OpDescriptor is being created // call the virtual OnControlCreate method to allow the control // to be initialised. OnControlCreate((OpDescControlCreateMsg*)Msg); } if (MESSAGE_IS_A(Msg,OpDescControlMsg)) { OpDescControlMsg* CtlMsg = (OpDescControlMsg*)Msg; switch((CtlMsg)->DlgMsg) { case DIM_LFT_BN_CLICKED: { // Invoke the Operation Invoke(); break; } case DIM_SELECTION_CHANGED: //case DIM_SELECTION_CHANGED_COMMIT: Removed by Simon cos Jason changed the // semantics of DIM_SELECTION_CHANGED_COMMIT for combos { // Combo and slider messages handled here OnSelectionChange(CtlMsg, NULL); break; } case DIM_COMMIT: { // profile dialog message boxes handled here OnSelectionChange(CtlMsg, NULL); } break; case DIM_SLIDER_POS_CHANGING: { OnSliderChanging(CtlMsg); break; } case DIM_SLIDER_POS_SET: { OnSliderSet(CtlMsg); break; } case DIM_SLIDER_POS_CANCELLED: { OnSliderCancelled(CtlMsg); break; } default: break; } } return EAT_MSG; } } return (MessageHandler::Message(Msg)); }

void OpDescriptor::OnControlCreate (  OpDescControlCreateMsg *  CreateMsg  )  [virtual]

The OnControlCreate method is called by the OpDescriptor's default Message handler when a new control has just been created. You should override this method to perform gadget initialisation. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 10/06/94 Parameters: CreateMsg,:  [INPUTS] Returns: This base class fn does nothing Returns: Errors: - See also: Reimplemented in OpChangeLineAttribOpDesc, OpChangeLineWidthOpDesc, OpNameGalleryPropIndexDesc, ChangeFeatherSizeSliderOpDesc, ChangeFeatherProfileOpDesc, QualitySliderDescriptor, and OpLibGalClipTheme. Definition at line 1257 of file opdesc.cpp. { // Override this fn is a derived class to initialise a control which has just been created // - Most useful for combo/listbox/edit controls. }

void OpDescriptor::OnSelectionChange (  OpDescControlMsg *  SelChangedMsg, List *  GadgetList )  [virtual]

The OnSelectionChange method is called whenever the user selects a new value from the gadget .. (blah blah. Author: Simon_Maneggio (Xara Group Ltd) <camelotdev@xara.com> Date: 10/06/94 Parameters: SelChangedMessage,:  The selection changed message [INPUTS] GadgetList: A list of all gadgets associated with this OpDescriptor Returns: Should Enter/Tab and selection handling be bundled ?????? - possibly Because there can be more than one control associated with an OpDescriptor When the user makes a selection all gadgets need to be updated. The GadgetList parameter allows this ........ (Incomplete fn header) Returns: Errors: - See also: Reimplemented in OpChangeLineAttribOpDesc, OpChangeLineWidthOpDesc, OpNameGalleryPropIndexDesc, ChangeFeatherSizeSliderOpDesc, OpLibGalClipTheme, and OpZoomComboDescriptor. Definition at line 1289 of file opdesc.cpp. { // }

void OpDescriptor::OnSliderCancelled (  OpDescControlMsg *  SliderChangingMsg  )  [virtual]

Called when the sliders position is being cancelled (if its associated with this opdescriptor). Author: Marc_Power (Xara Group Ltd) <camelotdev@xara.com> Date: 04/11/05 Parameters: SliderChangingMsg  - The message details [INPUTS] Reimplemented in ChangeFeatherSizeSliderOpDesc. Definition at line 1343 of file opdesc.cpp. { // Base class does nothing }

void OpDescriptor::OnSliderChanging (  OpDescControlMsg *  SliderChangingMsg  )  [virtual]

Called when the sliders position is being changed (if its associated with this opdescriptor). Author: Chris_Snook (Xara Group Ltd) <camelotdev@xara.com> Date: 15/3/2000 Parameters: SliderChangingMsg  - The message details [INPUTS] Reimplemented in ChangeFeatherSizeSliderOpDesc. Definition at line 1325 of file opdesc.cpp. { // Base class does nothing }

void OpDescriptor::OnSliderSet (  OpDescControlMsg *  SelChangedMsg  )  [virtual]

Called when the sliders position changes (if its associated with this opdescriptor). Author: Rik_Heywood (Xara Group Ltd) <camelotdev@xara.com> Date: 2/11/94 Parameters: SelChangedMsg  - The message details [INPUTS] Reimplemented in ChangeFeatherSizeSliderOpDesc, and QualitySliderDescriptor. Definition at line 1307 of file opdesc.cpp. { // Base class does nothing }

TCHAR * OpDescriptor::ReadString (  TCHAR *  pDesc  )

Reads the string until delimeter or end of string. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 6/10/93 Parameters: Description  - Operation description string. [INPUTS] Definition at line 1458 of file opdesc.cpp. { static TCHAR pText[MAX_TEXT_SIZE]; UINT32 pos = 0; // Get Text String while ( (*pDesc != END_OF_STRING) && (*pDesc != STRING_DELIMETER) && (pos <= (MAX_TEXT_SIZE - 1))) { pText[pos++] = *pDesc; pDesc++; } // Set end of string pText[pos] = END_OF_STRING; return pText; }

void OpDescriptor::RemoveAlias (   )

Removes the alias for this operation. Author: Mark_Neves (Xara Group Ltd) <camelotdev@xara.com> Date: 27/7/94 Parameters: -  [INPUTS] Returns: - Errors: In debug builds, it will ENSURE if the OpDesc is not aliased. Definition at line 723 of file opdesc.cpp. { ENSURE(Aliased,"This OpDesc is NOT aliased"); if (!Aliased) return; GetState = OldGetState; AutoStateFlgs = OldAutoStateFlags; TextID = OldTextID; BubbleID = OldBubbleID; Aliased = FALSE; }

void OpDescriptor::RemoveAllAliases (   )  [static]

Goes through the list of op descriptors, removing all aliases. Author: Mark_Neves (Xara Group Ltd) <camelotdev@xara.com> Date: 19/7/94 Parameters: -  [INPUTS] Returns: - Definition at line 765 of file opdesc.cpp. { ListItem* Item = OpList.GetHead(); while (Item != NULL) { OpDescriptor* pOpDesc =((OpListItem*)Item)->pOpDesc; if (pOpDesc->IsAliased()) pOpDesc->RemoveAlias(); Item = OpList.GetNext(Item); } }

void OpDescriptor::SetBarControlInfo (  BarControlInfo  ThisInfo  )  [inline]

Definition at line 551 of file opdesc.h. { BarCtrlInfo = ThisInfo;};

void OpDescriptor::SetStringPos (  TCHAR **  pDesc, OpTextFlags  WhichText )

Scans through a string and sets the pDesc pointer to the appropriate text in the string resource. The text position is determined by the ordinal value of the WhichText value. Author: Mario_Shamtani (Xara Group Ltd) <camelotdev@xara.com> Date: 6/10/93 Parameters: WhichText  - used to determine the position of the text to be obtained [INPUTS] Description - Operation description string. Definition at line 1423 of file opdesc.cpp. { UINT32 StringPos = 0; while ( (StringPos < (UINT32) WhichText) && (**pDesc != END_OF_STRING)) { // Read until next string delimeter is reached while ( (**pDesc != END_OF_STRING) && (**pDesc != STRING_DELIMETER)) { (*pDesc)++; } if (**pDesc != END_OF_STRING) // Move pointer to beginning of next string (*pDesc)++; //Increment String position by 1 StringPos++; } }

---

Member Data Documentation

BOOL OpDescriptor::Aliased [protected]

Definition at line 472 of file opdesc.h.

CCRuntimeClass* OpDescriptor::AliasOpClass [protected]

Definition at line 473 of file opdesc.h.

UINT32 OpDescriptor::AutoStateFlgs [protected]

Definition at line 485 of file opdesc.h.

BarControlInfo OpDescriptor::BarCtrlInfo [protected]

Definition at line 465 of file opdesc.h.

UINT32 OpDescriptor::BubbleID [protected]

Definition at line 464 of file opdesc.h.

OpFlgs OpDescriptor::Flags [protected]

Definition at line 468 of file opdesc.h.

pfnGetParamState OpDescriptor::GetParamState [protected]

Definition at line 495 of file opdesc.h.

pfnGetState OpDescriptor::GetState [private]

Definition at line 492 of file opdesc.h.

UINT32 OpDescriptor::HelpID [protected]

Definition at line 463 of file opdesc.h.

BOOL OpDescriptor::m_bHotKeyEnabled [protected]

Definition at line 470 of file opdesc.h.

DWORD OpDescriptor::ModuleID [protected]

Definition at line 461 of file opdesc.h.

UINT32 OpDescriptor::OldAutoStateFlags [protected]

Definition at line 475 of file opdesc.h.

UINT32 OpDescriptor::OldBubbleID [protected]

Definition at line 477 of file opdesc.h.

pfnGetState OpDescriptor::OldGetState [protected]

Definition at line 474 of file opdesc.h.

UINT32 OpDescriptor::OldTextID [protected]

Definition at line 476 of file opdesc.h.

UINT32 OpDescriptor::OneInstID [protected]

Definition at line 484 of file opdesc.h.

CCRuntimeClass* OpDescriptor::OpClass [protected]

Definition at line 467 of file opdesc.h.

List OpDescriptor::OpList [static, private]

Definition at line 634 of file opdesc.h.

UINT32 OpDescriptor::TextID [protected]

Definition at line 462 of file opdesc.h.

String OpDescriptor::Token

Definition at line 499 of file opdesc.h.

---

The documentation for this class was generated from the following files:

• Kernel/opdesc.h (r1785/r1261)
• Kernel/opdesc.cpp (r1785/r1282)

---