Class IRollupWindow
See Also: Class ICustomControl, Class IRollupPanel, Custom Controls, Class Interface.
class IRollupWindow : public ICustomControl
Description:
This control is used to access existing rollup pages or if you are creating a dialog box which will not be used in the command panel. This control may be used to add a container area for rollup pages to be added to the dialog, and provides a scroll bar just like the command panel itself.
Note that this is a special case. Normally, adding rollup pages to the command panel is done using the simple AddRollupPage() method of the Interface class. This control is only used when you want to have a scrolling region for rollup pages in a dialog box.
To initialize the pointer to the control call:
IRollupWindow *GetIRollup(HWND hCtrl);
To release the control call:
void ReleaseIRollup(IRollupWindow *irw);
The value to use in the Class field of the Custom Control Properties dialog is: RollupWindow
Methods:
Prototype:
virtual void Show()=0;
Remarks:
This causes all the rollup windows to be visible.
Prototype:
virtual void Hide()=0;
Remarks:
This causes all the rollup windows to become invisible.
Prototype:
virtual void Show(int index)=0;
Remarks:
This will make the rollup window whose index is passed visible.
Parameters:
int index
The index of the rollup to show.
Prototype:
virtual void Hide(int index)=0;
Remarks:
This will make the rollup window whose index is passed invisible.
Parameters:
int index
The index of the rollup to hide.
Prototype:
virtual HWND GetPanelDlg(int index)=0;
Remarks:
Returns the handle of the rollup page whose index is passed.
Parameters:
int index
The index of the rollup whose handle is to be returned.
Prototype:
virtual int GetPanelIndex(HWND hWnd)=0;
Remarks:
Returns an index to the rollup page given its handle.
Parameters:
HWND hWnd
The handle of the rollup.
Prototype:
virtual void SetPanelTitle(int index,TCHAR *title)=0;
Remarks:
This method sets the title text displayed in the rollup page whose index is passed.
Parameters:
int index
Specifies the rollup whose title is to be set.
TCHAR *title
The title string.
Prototype:
virtual int AppendRollup(HINSTANCE hInst, TCHAR *dlgTemplate, DLGPROC dlgProc, TCHAR *title, LPARAM param=0,DWORD flags=0, int category = ROLLUP_CAT_STANDARD)=0;
Remarks:
This method is used to add a rollup page.
Parameters:
HINSTANCE hInst
The DLL instance handle of the plug-in.
TCHAR *dlgTemplate
The dialog template for the rollup page.
DLGPROC dlgProc
The dialog proc to handle the message sent to the rollup page.
TCHAR *title
The title displayed in the title bar.
LPARAM param=0
Any specific data to pass along may be stored here.
DWORD flags=0
Append rollup page flags:
APPENDROLL_CLOSED
Starts the page in the rolled up state.
int category = ROLLUP_CAT_STANDARD
The category parameter provides flexibility with regard to where a particular rollup should be displayed in the UI. RollupPanels with lower category fields will be displayed before RollupPanels with higher category fields. For RollupPanels with equal category value the one that was added first will be displayed first. Allthough it is possible to pass any int value as category there exist currently 5 different category defines: ROLLUP_CAT_SYSTEM, ROLLUP_CAT_STANDARD, and ROLLUP_CAT_CUSTATTRIB.
When using ROLLUP_SAVECAT, the rollup page will make the provided category sticky, meaning it will not read the category from the RollupOrder.cfg file, but rather save the category field that was passed as argument in the CatRegistry and in the RollupOrder.cfg file.
The method will take the category of the replaced rollup in case the flags argument contains ROLLUP_USEREPLACEDCAT. This is mainly done, so that this system works with param maps as well.
Return Value:
The index of the new page is returned.
Prototype:
virtual int AppendRollup(HINSTANCE hInst, DLGTEMPLATE *dlgTemplate, DLGPROC dlgProc, TCHAR *title, LPARAM param=0,DWORD flags=0, int category = ROLLUP_CAT_STANDARD)=0;
Remarks:
This method is available in release 4.0 and later only.
This method is used to add a rollup page, but is currently not used.
Parameters:
HINSTANCE hInst
The DLL instance handle of the plug-in.
DLGTEMPLATE *dlgTemplate
The dialog template for the rollup page.
DLGPROC dlgProc
The dialog proc to handle the message sent to the rollup page.
TCHAR *title
The title displayed in the title bar.
LPARAM param=0
Any specific data to pass along may be stored here.
DWORD flags=0
Append rollup page flags:
APPENDROLL_CLOSED
Starts the page in the rolled up state.
int category = ROLLUP_CAT_STANDARD
The category parameter provides flexibility with regard to where a particular rollup should be displayed in the UI. RollupPanels with lower category fields will be displayed before RollupPanels with higher category fields. For RollupPanels with equal category value the one that was added first will be displayed first. Allthough it is possible to pass any int value as category there exist currently 5 different category defines: ROLLUP_CAT_SYSTEM, ROLLUP_CAT_STANDARD, and ROLLUP_CAT_CUSTATTRIB.
When using ROLLUP_SAVECAT, the rollup page will make the provided category sticky, meaning it will not read the category from the RollupOrder.cfg file, but rather save the category field that was passed as argument in the CatRegistry and in the RollupOrder.cfg file.
The method will take the category of the replaced rollup in case the flags argument contains ROLLUP_USEREPLACEDCAT. This is mainly done, so that this system works with param maps as well.
Return Value:
The index of the new page is returned.
Prototype:
virtual int ReplaceRollup(int index, HINSTANCE hInst, TCHAR *dlgTemplate, DLGPROC dlgProc, TCHAR *title, LPARAM param=0,DWORD flags=0)=0;
Remarks:
This method is used to replace the rollup page whose index is passed.
Parameters:
int index
Specifies the rollup whose to be replaced.
HINSTANCE hInst
The DLL instance handle of the plug-in.
TCHAR *dlgTemplate
The dialog template for the rollup page.
DLGPROC dlgProc
The dialog proc to handle the message sent to the rollup page.
TCHAR *title
The title displayed in the title bar.
LPARAM param=0
Any specific data to pass along may be stored here.
DWORD flags=0
Append rollup page flags:
APPENDROLL_CLOSED
Starts the page in the rolled up state.
Return Value:
The index of the replacement page is returned.
Prototype:
virtual int ReplaceRollup(int index, HINSTANCE hInst, DLGTEMPLATE *dlgTemplate, DLGPROC dlgProc, TCHAR *title, LPARAM param=0,DWORD flags=0, int category = ROLLUP_CAT_STANDARD)=0;;
Remarks:
This method is available in release 4.0 and later only.
This method is used to replace the rollup page whose index is passed, but is currently not used.
Parameters:
int index
Specifies the rollup whose to be replaced.
HINSTANCE hInst
The DLL instance handle of the plug-in.
DLGTEMPLATE *dlgTemplate
The dialog template for the rollup page.
DLGPROC dlgProc
The dialog proc to handle the message sent to the rollup page.
TCHAR *title
The title displayed in the title bar.
LPARAM param=0
Any specific data to pass along may be stored here.
DWORD flags=0
Append rollup page flags:
APPENDROLL_CLOSED
Starts the page in the rolled up state.
int category = ROLLUP_CAT_STANDARD
The category parameter provides flexibility with regard to where a particular rollup should be displayed in the UI. RollupPanels with lower category fields will be displayed before RollupPanels with higher category fields. For RollupPanels with equal category value the one that was added first will be displayed first. Allthough it is possible to pass any int value as category there exist currently 5 different category defines: ROLLUP_CAT_SYSTEM, ROLLUP_CAT_STANDARD, and ROLLUP_CAT_CUSTATTRIB.
When using ROLLUP_SAVECAT, the rollup page will make the provided category sticky, meaning it will not read the category from the RollupOrder.cfg file, but rather save the category field that was passed as argument in the CatRegistry and in the RollupOrder.cfg file.
The method will take the category of the replaced rollup in case the flags argument contains ROLLUP_USEREPLACEDCAT. This is mainly done, so that this system works with param maps as well.
Return Value:
The index of the replacement page is returned.
Prototype:
virtual void DeleteRollup(int index, int count)=0;
Remarks:
This method deletes the rollup pages starting at the index passed. The count parameter controls how many pages are deleted.
Parameters:
int index
The starting index.
int count
The number of pages.
Prototype:
virtual void SetPageDlgHeight(int index,int height)=0;
Remarks:
This method is used to change the height of a rollup page.
Parameters:
int index
The index of the rollup to change.
int height
The new height of the dialog in pixels.
Prototype:
virtual void SaveState(RollupState *hState)=0;
Remarks:
This method saves the state of the rollup (the position of the scroll bars, which pages are open, etc...).
Parameters:
RollupState *hState
Pointer to storage for the rollup state. Note: typedef void *RollupState;
Prototype:
virtual void RestoreState(RollupState *hState)=0;
Remarks:
This methods restores a saved state.
Parameters:
RollupState *hState
Pointer to storage for the rollup state. Note: typedef void *RollupState;
Prototype:
virtual int GetNumPanels()=0;
Remarks:
This method returns the number of panels used in the rollup.
Prototype:
virtual void DlgMouseMessage(HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)=0;
Remarks:
Passing WM_LBUTTONDOWN, WM_MOUSEMOVE, and WM_LBUTTONUP to this function allows hand cursor scrolling with unused areas in the dialog.
Parameters:
HWND hDlg
The handle of the dialog.
UINT message
The message to pass along: WM_LBUTTONDOWN, WM_MOUSEMOVE, or WM_LBUTTONUP.
WPARAM wParam
LPARAM lParam
These are passed as part of the message sent in. Pass them along to this method.
Prototype:
virtual BOOL IsPanelOpen(int index) = 0;
Remarks:
This method return TRUE if the rollup page whose index is passed is open and FALSE if it is closed.
Prototype:
virtual void SetPanelOpen(int index, BOOL isOpen, BOOL ignoreFlags = TRUE) =0;
Remarks:
This causes the page whose index is passed to either open or close. If isOpen is passed a value of TRUE, the page is opened.
Parameters:
int index
The page to open or close.
BOOL isOpen
If TRUE, the page is opened, if FALSE it is closed.
BOOL ignoreFlags = TRUE
The method would close the panel if the DONTAUTOCLOSE flag is not set on the rollup. This flag indicates if it should be closed anyway, even if the flag is set.
Prototype:
virtual int GetScrollPos()=0;
Remarks:
This method returns the scroll position of the window.
Prototype:
virtual void SetScrollPos(int spos)=0;
Remarks:
This method sets the scroll position of the window.
Parameters:
int spos
The scroll position to set.
Prototype:
virtual void MoveRollupPanelFrom(IRollupWindow *from, HWND hPanel, BOOL top)=0;
Remarks:
This method is available in release 4.0 and later only.
This methods moves a RollupPanel to another RollupWindow. It either inserts it at the top, or appends it at the end (depending on the top parameter)
Parameters:
IRollupWindow *from
A pointer to the rollup window you are moving from.
HWND hPanel
The handle to the destination panel.
BOOL top
TRUE to insert at the top; FALSE to append at the end.
Prototype:
virtual int GetPanelHeight(int index)=0;
Remarks:
This method is available in release 4.0 and later only.
Returns the height of the specified RollupPanel.
Parameters:
int index
The zero based index of the rollup panel.
Prototype:
virtual int GetScrollHeight()=0;
Remarks:
This method is available in release 4.0 and later only.
Returns the height of a RollupWindow, that it is longer than the visible area
Prototype:
virtual IRollupPanel *GetPanel(HWND hWnd)=0;
Remarks:
This method is available in release 4.0 and later only.
Returns a pointer to the rollup panel for the specified window handle. An IRollupPanel describes the properties of a single rollup.
Parameters:
HWND hWnd
The window handle to get the rollup for.
Prototype:
virtual void RegisterRollupCallback(IRollupCallback *callb)=0;
Remarks:
This method is available in release 4.0 and later only.
This method allows you to register a rollup callback function to handle any custom handling for dragging and dropping rollouts.
Parameters:
IRollupCallback *callb
A pointer to the callback function you wish to register.
Prototype:
virtual void UnRegisterRollupCallback(IRollupCallback *callb)=0;
Remarks:
This method is available in release 4.0 and later only.
This method allows you to unregister a rollup callback function.
Parameters:
IRollupCallback *callb
A pointer to the callback function you wish to unregister.
Prototype:
virtual void RegisterRCMenuItem(IRollupRCMenuItem *item)=0;
Remarks:
This method is available in release 4.0 and later only.
This method allows you to register a rollup right-click menu item which will be added to the list of items. For rollups that support Drag and Drop this is used to register a ResetCategories RightClickMenu. Reset Cateories will get rid of all the changes that have been made through drag and drop and restore the default.
Parameters:
IRollupRCMenuItem *item
A pointer to the right-click menu item you wish to register.
Prototype:
virtual void UnRegisterRCMenuItem(IRollupRCMenuItem *item)=0;
Remarks:
This method is available in release 4.0 and later only.
This method allows you to unregister a rollup right-click menu item.
Parameters:
IRollupRCMenuItem *item
A pointer to the right-click menu item you wish to unregister.
Prototype:
virtual void ResetCategories(bool update = true)=0;
Remarks:
This method is available in release 4.0 and later only.
This method will reset the category information on all the panels in the rollup window. The plugin will have to be reloaded (EndEditParams, BeginEditparams) in order to show this in the UI.
Parameters:
bool update = true
TRUE to update the layout, otherwise FALSE. Leave this on TRUE.
Prototype:
virtual void UpdateLayout()=0;
Remarks:
This method is available in release 4.0 and later only.
This method is used internally
This function is not part of this class but is available for use:
Function:
BOOL IsRollupPanelOpen(HWND hDlg);
Remarks:
This function returns TRUE if a particular rollup panel is open given a handle to the dialog window in the panel.
Parameters:
HWND hDlg
Handle to the dialog window in the panel.