Edit

IMAPIViewContext::ActivateNext

  • Article

Applies to: Outlook 2013 | Outlook 2016

Activates the next or previous message in the view order.

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 value

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.

MFCMAPI reference

For MFCMAPI sample code, see the following table.

File Function Comment
MyMAPIFormViewer.cpp
CMyMAPIFormViewer::ActivateNext
MFCMAPI implements the IMAPIViewContext::ActivateNext method in this function.

See also