IMAPIViewContext::ActivateNext

The IMAPIViewContext::ActivateNext method activates the next or previous message in the view order.

Quick Info

HRESULT ActivateNext(
  ULONG ulDir,        
  LPCRECT prcPosRect  
);

Parameters

ulDir

[in] Status flags giving information about the message to be activated. Valid flag settings are:

VCDIR_CATEGORY

The viewer should activate a message in another category of the view. The message to be activated is:

· The first message in the next view category if this flag is ORed with VCDIR_NEXT.

· The last message in the previous view category if this flag is ORed with VCDIR_PREV and the previous category is expanded.

· The first message in the previous view category if this flag is ORed with VCDIR_PREV and the previous category is not expanded. In this case the previous category undergoes automatic expansion.

VCDIR_DELETE

The viewer should activate the next or previous message because the current message has been deleted.

VCDIR_MOVE

The viewer should activate the next or previous message because the current message has been moved.

VCDIR_NEXT

The viewer should activate the next message in the view order.

VCDIR_PREV

The viewer should activate the previous message in the view order.

VCDIR_UNREAD

The viewer should activate the next or previous unread message in the view order.

prcPosRect

[in] Pointer to a Windows RECT structure containing the size and position of the window to be used to display the activated message.

Return Values

S_OK: The message was activated successfully.
S_FALSE: The message was activated successfully, but a different type of form was opened in the process.

Remarks

Form objects call the IMAPIViewContext::ActivateNext method to change what message is displayed to the user. The value passed in the ulDir parameter indicates which message should be activated and, in some cases, why. The VCDIR_NEXT and VCDIR_PREVIOUS flags correspond to users choosing the Next or Previous command in a view, respectively. These operations usually correspond to moving up or down one message in the form viewer's list of messages.

The VCDIR_DELETE and VCDIR_MOVE flags are set by the IMAPIMessageSite::DeleteMessage and IMAPIMessageSite::MoveMessage methods, respectively. Implementations of these methods call ActivateNext with the appropriate direction and then perform the requested operation on the message if the ActivateNext call did not fail. Form viewers typically enable users to specify the direction to move in the message list.

Notes to Implementers

Your implementation of IMAPIViewContext::ActivateNext makes the next or previous message in the folder, depending on the value of ulDir, the current message. After ActivateNext returns, call IMAPIMessageSite::GetMessage to get a pointer to the newly activated message.

Notes to Callers

If ActivateNext returns S_FALSE, or if a current message is not present, perform your normal shutdown procedure which should include calling your form's IMAPIForm::ShutdownForm method. If a next or previous message is displayed, use the window rectangle passed in the prcPosRect parameter to display it.