lnview.hpp

IBM Lotus C++ API 7.0a for IBM Lotus Notes/Domino Directory Release --------- ------------------

//===========================================================================
//
// Module:		LNVIEW.HPP
//
// Description:
//
//		Class definitions and data for the view and folder classes.
//
//===========================================================================
//
// Copyright (c) 1996-1999 Lotus Development Corporation. All rights reserved
// This software is subject to the Lotus Software Agreement, Restricted
// Rights for U.S. government users, and applicable export regulations.
//
//===========================================================================

#ifndef LNVIEW_HPP
#define LNVIEW_HPP

//Default Cache Size for ViewFolder
#define LNDEFAULTVFCACHESIZE 100 //Default cache size of 100

// LNNAVIGATION: navigation targets for the LNVFNavigator::Goto function.

enum LNNAVIGATION					// go to:
{
	LNNAVIGATION_CHILD = 0,			// child of current entry
	LNNAVIGATION_FIRST,				// first entry
	LNNAVIGATION_FIRST_SIBLING,		// first sibling of current entry
	LNNAVIGATION_LAST,				// last entry
	LNNAVIGATION_LAST_SIBLING,		// last sibling of current entry
	LNNAVIGATION_MAIN,				// main topic for current entry
	LNNAVIGATION_NEXT,				// next entry
	LNNAVIGATION_NEXT_CATEGORY,		// next category entry
	LNNAVIGATION_NEXT_MAIN,			// next main topic
	LNNAVIGATION_NEXT_NON_CATEGORY,	// next non-category entry
	LNNAVIGATION_NEXT_PARENT,		// next sibling of current entry's parent
	LNNAVIGATION_NEXT_SIBLING,		// next sibling of current entry
	LNNAVIGATION_NEXT_UNREAD,		// next unread entry
	LNNAVIGATION_NEXT_UNREAD_MAIN,	// next unread entry or main topic
	LNNAVIGATION_PARENT,			// parent of current entry
	LNNAVIGATION_PREV,				// previous entry
	LNNAVIGATION_PREV_CATEGORY,		// previous category entry
	LNNAVIGATION_PREV_MAIN,			// previous main topic
	LNNAVIGATION_PREV_NON_CATEGORY,	// previous non-category entry
	LNNAVIGATION_PREV_PARENT,		// previous sibling of current entry's parent
	LNNAVIGATION_PREV_SIBLING,		// previous sibling of current entry
	LNNAVIGATION_PREV_UNREAD,		// previous unread entry
	LNNAVIGATION_PREV_UNREAD_MAIN,	// previous unread entry or main topic
	LNNAVIGATION_COUNT				// number of enumeration values
};

// LNVFCALENDARFORMATS
typedef BYTE LNVFCALENDARFORMATS;

#define LNVFCALENDARFORMATS_TWO_DAY		VIEW_CAL_FORMAT_TWO_DAY		//0x01
#define LNVFCALENDARFORMATS_ONE_WEEK	VIEW_CAL_FORMAT_ONE_WEEK	//0x02
#define LNVFCALENDARFORMATS_TWO_WEEKS	VIEW_CAL_FORMAT_TWO_WEEKS	//0x04	
#define LNVFCALENDARFORMATS_ONE_MONTH	VIEW_CAL_FORMAT_ONE_MONTH	//0x08
// This one is not exposed	
//#define LNVFCALENDARFORMATS_ONE_YEAR	VIEW_CAL_FORMAT_ONE_YEAR	//0x10
#define LNVFCALENDARFORMATS_ONE_DAY		VIEW_CAL_FORMAT_ONE_DAY		//0x20  	
#define LNVFCALENDARFORMATS_FORMAT_ALL	VIEW_CAL_FORMAT_ALL			//0xff

enum LNVFCALENDARINITIALFORMAT
{
	LNVFCALENDARINITIALFORMAT_LAST_VIEWED = 0, 
	LNVFCALENDARINITIALFORMAT_TWO_DAY = LNVFCALENDARFORMATS_TWO_DAY,
	LNVFCALENDARINITIALFORMAT_ONE_WEEK = LNVFCALENDARFORMATS_ONE_WEEK,
	LNVFCALENDARINITIALFORMAT_TWO_WEEKS = LNVFCALENDARFORMATS_TWO_WEEKS,
	LNVFCALENDARINITIALFORMAT_ONE_MONTH = LNVFCALENDARFORMATS_ONE_MONTH,
	// This one is not exposed	
//	LNVFCALENDARINITIALFORMAT_ONE_YEAR = LNVFCALENDARFORMATS_ONE_YEAR,
	LNVFCALENDARINITIALFORMAT_ONE_DAY = LNVFCALENDARFORMATS_ONE_DAY 
};

// LNVFCOMPARISON: comparison for LNViewFolder and LNVFNavigator Find function

enum LNVFCOMPARISON
{
	LNVFCOMPARISON_EQ		= FIND_FIRST_EQUAL,
							// find first entry that matches key
	LNVFCOMPARISON_LAST_EQ	= FIND_LAST_EQUAL,
							// find last entry that matches key
	LNVFCOMPARISON_LT		= FIND_LESS_THAN,
							// find last entry that is less than key
	LNVFCOMPARISON_GT		= FIND_GREATER_THAN
							// find first entry that is greater than key
};

// LNVFENTRYTYPE: view/folder entry type

enum LNVFENTRYTYPE
{
	LNVFENTRYTYPE_CATEGORY,		// category
	LNVFENTRYTYPE_MAIN,			// main topic
	LNVFENTRYTYPE_RESPONSE,		// response
	LNVFENTRYTYPE_TOTAL			// total or statistical entry
};

// LNVFHEADINGDISPLAY: how to display column headings

enum LNVFHEADINGDISPLAY
{
	LNVFHEADINGDISPLAY_NONE,	// do not display column headings
	LNVFHEADINGDISPLAY_SIMPLE,	// display simple column headings (default)
	LNVFHEADINGDISPLAY_BEVELED	// display beveled column headings
};

// LNVFHEADINGSORTOPTION: how to sort column when user clicks on column heading

enum LNVFHEADINGSORTOPTION
{
	LNVFHEADINGSORTOPTION_NONE					= 0,
								// do not re-sort column (default)
	LNVFHEADINGSORTOPTION_ASCENDING				= VCF1_M_ResortAscending,
								// re-sort column in ascending order
	LNVFHEADINGSORTOPTION_DESCENDING			= VCF1_M_ResortDescending,
								// re-sort column in desending order
	LNVFHEADINGSORTOPTION_BOTH					= (VCF1_M_ResortAscending |
												   VCF1_M_ResortDescending),
								// cycle between ascend/descend order
	LNVFHEADINGSORTOPTION_CHANGE_VIEW_FOLDER	= VCF1_M_ResortToView
								// switch to another view/folder
};


// LNVFJUSTIFICATION: how to justify column entries

enum LNVFJUSTIFICATION
{
	LNVFJUSTIFICATION_LEFT		= VIEW_COL_ALIGN_LEFT,		// left justify
	LNVFJUSTIFICATION_RIGHT		= VIEW_COL_ALIGN_RIGHT,		// right justify
	LNVFJUSTIFICATION_CENTER	= VIEW_COL_ALIGN_CENTER		// center
};

// LNVFOPENFLAGS: flags used to open a view/folder (collection)

typedef DWORD LNVFOPENFLAGS;

#define LNVFOPENFLAGS_DEFAULT			0
							// default options
#define LNVFOPENFLAGS_REBUILD_INDEX		OPEN_REBUILD_INDEX
							// rebuild index before opening collection
#define LNVFOPENFLAGS_NO_UPDATE			OPEN_NOUPDATE
							// don't update collection before opening it
#define LNVFOPENFLAGS_NO_CREATE			OPEN_DO_NOT_CREATE
							// don't create collection if it doesn't exist
#define LNVFOPENFLAGS_USE_UNREAD_LIST	0x10000
							// associate collection with unread list
#define LNVFOPENFLAGS_DESIGN_ONLY		0x20000
							// open for access to design properties only;
							// don't open the collection

// LNVFOPENPOSITION: initial position of cursor when opening view/folder

enum LNVFOPENPOSITION
{
	LNVFOPENPOSITION_LAST_OPENED	= 0,
					// position cursor on last-opened document (default)
	LNVFOPENPOSITION_TOP			= VIEW_TABLE_GOTO_TOP_ON_OPEN,
					// position cursor on topmost (first) document	
	LNVFOPENPOSITION_BOTTOM			= VIEW_TABLE_GOTO_BOTTOM_ON_OPEN
					// position cursor on bottommost (last) document
};

// LNVFREFRESHOPTION: how to refresh the view/folder window when data changes

enum LNVFREFRESHOPTION
{
	LNVFREFRESHOPTION_DISPLAY_INDICATOR	= 0,
			// do not refresh window; display refresh indicator (default)
	LNVFREFRESHOPTION_REFRESH_TOP		= VIEW_TABLE_GOTO_TOP_ON_REFRESH,
			// refresh window and move cursor to first document
	LNVFREFRESHOPTION_REFRESH_BOTTOM	= VIEW_TABLE_GOTO_BOTTOM_ON_REFRESH,
			// refresh window and move cursor to last document
	LNVFREFRESHOPTION_REFRESH			= (VIEW_TABLE_GOTO_TOP_ON_REFRESH |
										   VIEW_TABLE_GOTO_BOTTOM_ON_REFRESH)
			// refresh window and leave cursor more or less where it is
};

// LNVFROWSPACING: spacing between view/folder rows

enum LNVFROWSPACING
{
	LNVFROWSPACING_SINGLE	= VIEW_TABLE_SINGLE_SPACE,		 // (default)
	LNVFROWSPACING_1_25		= VIEW_TABLE_ONE_POINT_25_SPACE,
	LNVFROWSPACING_1_5		= VIEW_TABLE_ONE_POINT_50_SPACE,
	LNVFROWSPACING_1_75		= VIEW_TABLE_ONE_POINT_75_SPACE,
	LNVFROWSPACING_DOUBLE	= VIEW_TABLE_DOUBLE_SPACE
};

// LNVFSEPARATOR: separator for multiple values in a column

enum LNVFSEPARATOR
{
	LNVFSEPARATOR_NONE		= 0x0000,
	LNVFSEPARATOR_SPACE		= 0x1000,
	LNVFSEPARATOR_COMMA		= 0x2000,	
	LNVFSEPARATOR_SEMICOLON	= 0x3000,
	LNVFSEPARATOR_NEWLINE	= 0x4000
};

// LNVFSORTOPTION: how to sort column entries

enum LNVFSORTOPTION
{
	LNVFSORTOPTION_NONE,		// do not sort column (default)
	LNVFSORTOPTION_ASCENDING,	// sort column in ascending order
	LNVFSORTOPTION_DESCENDING	// sort column in descending order
};

// LNVFSTYLE: view/folder style

enum LNVFSTYLE
{
	LNVFSTYLE_STANDARD,			// tabular view/folder (default)
	LNVFSTYLE_CALENDAR			// calendar view/folder
};

// LNVFTIMESLOTDISPLAY: how to display time slots for calendar view/folders

enum LNVFTIMESLOTDISPLAY
{
	LNVFTIMESLOTDISPLAY_NONE,			// no time slots (default)
	LNVFTIMESLOTDISPLAY_TIME_SLOTS,		// display time slots
	LNVFTIMESLOTDISPLAY_BITMAPS			// display time slots with bitmaps
};

// LNVFTIMESLOTDURATION: duration of time slots for calendar view/folders

enum LNVFTIMESLOTDURATION
{
	LNVFTIMESLOTDURATION_15_MINUTES	= 15,	// 15 minute slots
	LNVFTIMESLOTDURATION_30_MINUTES	= 30,	// 30 minute slots
	LNVFTIMESLOTDURATION_1_HOUR		= 60,	// 1 hour slots (default)
	LNVFTIMESLOTDURATION_2_HOURS	= 120	// 2 hour slots
};

// LNVFTOTALSOPTION: type of column totals/statistics to display, if any

enum LNVFTOTALSOPTION
{
	LNVFTOTALSOPTION_NONE	 = (NIF_STAT_NONE << VCF2_S_SubtotalCode),
							// no totals or statistics (default)
	LNVFTOTALSOPTION_TOTAL	 = (NIF_STAT_TOTAL << VCF2_S_SubtotalCode),
							// show total of all main docs at end of column
	LNVFTOTALSOPTION_AVERAGE = (NIF_STAT_AVG_PER_ENTRY << VCF2_S_SubtotalCode),
							// show average of all main docs at end of column
	LNVFTOTALSOPTION_AVERAGE_PER_CATEGORY
							 = (NIF_STAT_AVG_PER_CHILD << VCF2_S_SubtotalCode),
							// show average of main docs in each category
	LNVFTOTALSOPTION_PERCENT = (NIF_STAT_PCT_OVERALL << VCF2_S_SubtotalCode),
							// show % of total for each doc and category
	LNVFTOTALSOPTION_PERCENT_PER_CATEGORY
							 = (NIF_STAT_PCT_PARENT << VCF2_S_SubtotalCode)
							// show % of total for each category
};

// LNVFUNREADMARKDISPLAY: how to display unread marks

enum LNVFUNREADMARKDISPLAY
{
	LNVFUNREADMARKDISPLAY_NONE		= 0,	// no unread marks (default)
	LNVFUNREADMARKDISPLAY_DOCS		= VIEW_TABLE_FLAG_DISP_UNREADDOCS,
						// show unread marks for unread docs only
	LNVFUNREADMARKDISPLAY_STANDARD	= VIEW_TABLE_FLAG_DISP_ALLUNREAD
						// show unread marks for unread docs and their ancestors
};

//---------------------------------------------------------------------------
// 	Class name:	LNViewFolder
//
//	Description:
//
//	LNViewFolder represents a Notes database view or folder, and is the base
//	class for the LNView and LNFolder classes.
//---------------------------------------------------------------------------

class LNIMPEXPCL LNViewFolder : public LNNote
{
friend class LNViewFolderArray;

public:
	LNViewFolder() {}
	LNViewFolder( const LNViewFolder &viewfolder ) : LNNote(viewfolder)
		{ ValidateNoteType(viewfolder); }
	LNViewFolder( const LNNote &other ) : LNNote(other)
		{ ValidateNoteType(other);}

	~LNViewFolder() {}
	
	LNViewFolder & operator=( const LNViewFolder &viewfolder )
		{ LNNote::operator=(viewfolder); return *this; }
	LNViewFolder & operator=( const LNNote &other )
		{ LNNote::operator=(other); return *this; }

	LNCLASSID GetClassID() const { return LNCLASSID_LNVIEWFOLDER; }

	LNSTATUS FolderAddDocument( const LNNote &doc );
	LNSTATUS FolderAddDocument( NOTEID noteid );
	
	LNSTATUS FolderAddDocuments( const LNNoteArray &docs );
	LNSTATUS FolderAddDocuments( const LNViewFolder &viewfolder );
	LNSTATUS FolderAddDocuments( const LNVFNavigator &nav );
	LNSTATUS FolderAddDocuments( HANDLE idtable );
	
	LNSTATUS FolderRemoveAllDocuments();
	
	LNSTATUS FolderRemoveDocument( const LNNote &doc );
	LNSTATUS FolderRemoveDocument( NOTEID noteid );
	
	LNSTATUS FolderRemoveDocuments( const LNNoteArray &docs );
	LNSTATUS FolderRemoveDocuments( const LNViewFolder &viewfolder );
	LNSTATUS FolderRemoveDocuments( const LNVFNavigator &nav );
	LNSTATUS FolderRemoveDocuments( HANDLE idtable );
	
	LNSTATUS FTSearch( const LNString &query, LNVFNavigator *results ) const;
	LNSTATUS FTSearch
		( const LNString &query, LNVFNavigator *results,
		  const LNFTSearchOptions &options ) const;
	LNSTATUS FTSearch
		( const LNString &query, LNVFNavigator *results,
		  const LNFTSearchOptions &options, const LNVFNavigator &input ) const;

	LNSTATUS GetChildren( LNVFNavigator *navigator ) const
		{ return GetDescendants(navigator, 1); }

	LNString GetColumnTitle( LNINT n ) const;
	
	LNSTATUS GetDescendants( LNVFNavigator *navigator ) const;
	LNSTATUS GetDescendants( LNVFNavigator *navigator, LNINT levels ) const;
	
	LNSTATUS GetEntries( LNVFNavigator *navigator ) const;
	
	LNDatabase GetEntryDatabase() const;
	
	LNSTATUS Open( LNVFOPENFLAGS flags = LNVFOPENFLAGS_DEFAULT );
	LNSTATUS Open( LNVFOPENFLAGS flags, const LNDatabase &db );
	LNSTATUS Open
		( LNVFOPENFLAGS flags, const LNString &pathname,
		  const LNString &server = "" );
	

	// LNVFNavigator functions:

	
	LNVFEntry operator[]( LNINT n ) const;

	LNSTATUS DeleteAllEntries() const;

	LNSTATUS DeleteEntries( LNVFEntry *entry, LNBOOL deletetree = FALSE ) const;
	LNSTATUS DeleteEntries
		( const LNVFPosition &position, LNBOOL deletetree = FALSE ) const;

	LNSTATUS Find
		( const LNString &key, LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNString &key, const LNVFFindOptions &options,
		  LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNDatetime &key, LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNDatetime &key, const LNVFFindOptions &options,
		  LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNNUMBER &key, LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNNUMBER &key, const LNVFFindOptions &options,
		  LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNVFFindKeys &keys, LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	LNSTATUS Find
		( const LNVFFindKeys &keys, const LNVFFindOptions &options,
		  LNVFEntry *entry = 0, LNINT *count = 0,
		  LNVFNavigator *results = 0 ) const;
	
	LNINT	GetCacheSize() const;

	LNSTATUS GetEntry( LNVFEntry *entry ) const;
	LNSTATUS GetEntry( LNVFEntry *entry, const LNVFPosition &position ) const;
	
	LNINT GetEntryCount() const;
	
	LNSTATUS GetPosition( LNVFPosition *position ) const;
	LNSTATUS SetPosition( const LNVFPosition &position ) const;
	
	LNSTATUS GotoChild( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_CHILD, entry); }
	LNSTATUS GotoFirst( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_FIRST, entry); }
	LNSTATUS GotoFirstSibling( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_FIRST_SIBLING, entry); }
	LNSTATUS GotoLast( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_LAST, entry); }
	LNSTATUS GotoLastSibling( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_LAST_SIBLING, entry); }
	LNSTATUS GotoMain( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_MAIN, entry); }
	LNSTATUS GotoNext( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT, entry); }
	LNSTATUS GotoNextCategory( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_CATEGORY, entry); }
	LNSTATUS GotoNextMain( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_MAIN, entry); }
	LNSTATUS GotoNextNonCategory( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_NON_CATEGORY, entry); }
	LNSTATUS GotoNextParent( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_PARENT, entry); }
	LNSTATUS GotoNextSibling( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_SIBLING, entry); }
	LNSTATUS GotoNextUnread( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_UNREAD, entry); }
	LNSTATUS GotoNextUnreadMain( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_NEXT_UNREAD_MAIN, entry); }
	LNSTATUS GotoParent( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_PARENT, entry); }
	LNSTATUS GotoPrevious( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_PREV, entry); }
	LNSTATUS GotoPreviousCategory( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_PREV_CATEGORY, entry); }
	LNSTATUS GotoPreviousMain( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_PREV_MAIN, entry); }
	LNSTATUS GotoPreviousNonCategory( LNVFEntry *entry = 0 ) const
		{ return Goto(LNNAVIGATION_PREV_NON_CATEGORY, entry); }
	LNSTATUS GotoPreviousParent( LNVFEntry *entry = 0 ) const