Using SECShortcutBar

Objective Toolkit : Chapter 11 Shortcut Bar : Using SECShortcutBar

The following topics describe how you can use SECShortcutBar in your projects.

To incorporate an SECShortcutBar into your application

1. In the class for the parent window, instantiate an SECShortcutBar object. For example:

SECShortcutBar m_scBar;

2. During the creation of the parent frame, call the SECShortcutBar::Create() method to create the shortcut bar window. For example:

m_scBar.Create(this,

WS_CHILD | WS_VISIBLE | SEC_OBS_VERT |

SEC_OBS_ANIMATESCROLL,

IDC_SHORTCUTBAR);

To add selectable icons to a shortcut bar

1. In one of your classes, create two CImageList members to hold the normal and small bitmap images. You need to create both lists for the images to ensure the icons appear correctly in the shortcut bar. For example, in the declaration file type:

CImageList m_imlNormal;

CImageList m_imlSmall;

In the implementation file, insert:

m_imlNormal.Create( 32, 32, ILC_COLOR|ILC_MASK, 8, 1);

m_imlSmall.Create( 16, 16, ILC_COLOR|ILC_MASK, 8, 1);

CBitmap bmpNormal;

CBitmap bmpSmall;

VERIFY(bmpNorm.LoadBitmap(IDB_INBOX));

VERIFY(bmpSmall.LoadBitmap(IDB_INBOX_SMALL));

m_idInbox = m_imlNormal.Add( &bmpNorm,

RGB(255,0,255));

m_imlSmall.Add( &bmpSmall,

RGB(255,0,255));

bmpNorm.DeleteObject();

bmpSmall.DeleteObject();

VERIFY(bmpNorm.LoadBitmap(IDB_CONTACTS));

VERIFY(bmpSmall.LoadBitmap(IDB_CONTACTS_SMALL));

m_idContacts = m_imlNormal.Add( &bmpNorm,

RGB(255,0,255));

m_imlSmall.Add( &bmpSmall,

RGB(255,0,255));

bmpNorm.DeleteObject();

bmpSmall.DeleteObject();

2. Use the AddBar() method to create an SECListBar with a label. For example:

SECListBar* pListBar = NULL;

pListBar = m_wndShortcutBar.AddBar(_T(“Fill With”));

ASSERT_VALID(pListBar);

NOTE >> When you embed CWnd objects in the shortcut bar, the bar class is SECBar, not SECListBar.

3. Add the image lists to the SECListBar.

pListBar->SetImageList( &m_imgNormal, LVSIL_NORMAL );

pListBar->SetImageList( &m_imgSmall, LVSIL_SMALL );

4. Set the notification window if you want to receive notification messages. This is important if the shortcut bar is embedded in a splitter window.

pListBar->SetNotifyWnd( this );

5. You can also set some extra information about the list bar.

//Little bit of info used to figure out who I am...

pListBar->SetExtraData( (void*)FillPane );

6. Add icons using the image ID’s in the image lists using either the InsertItem() or AddItem() methods. For example:

//School Data records...

pListBar->InsertItem( 0, _T("School Data"), 0 );

pListBar->SetItemData( 0, (DWORD)IDS_SCHOOL_FILE );

//Factory Data records

pListBar->InsertItem( 1, _T("Factory Data"), 1 );

pListBar->SetItemData( 1, (DWORD)IDS_FACTORY_FILE );

To embed a window in a shortcut bar

Call the overloaded AddBar() method, which accepts a CWnd parameter. For example:

m_scBar.AddBar( &m_tabWnd, _T("3D Tab Wnd") );

To change the way the bars are drawn

Derive a class from SECBar and then override the Draw() method. For example:

class MyBar : public SECBar

{

//Required if you want to use your own bar objects

//without deriving a new class from SECShortcutBar

TOOLKIT_DECLARE_DYNCREATE(MyBar)

public:

MyBar();

protected:

virtual void Draw( CDC& dc );

};

//After creating the SECShortcutBar but before adding

//any bar objects, add this line.

m_wndShorcutBar.SetBarClass( RUNTIME_CLASS(MyBar) );

//If you don’t want to use your new bar class

//for all the bars, you could do this

CRuntimeClass* pOrigBarClass = m_wndShortcutBar.GetBarClass();

m_wndShortcutBar.SetBarClass( RUNTIME_CLASS(MyBar) );

//Add as many bars of your new class as you want

//Prepare to add standard bars

m_wndShortcutBar.SetBarClass( pOrigBarClass );

//Add standard bars

NOTE >>	For an SECListBar derivative, the call to SetBarClass()in the above code should be replaced with a call to SetListBarClass().

To allow shortcut bars to behave like buttons

Use the SEC_OBS_BUTTONFEEDBACK style flag as a parameter for the Create() or ModifyBarStyles() methods. When this style is specified, the bar remains pressed, like a button, giving the user additional feedback on which bar was clicked. For example:

m_scBar.ModifyBarStyle( 0, SEC_OBS_BUTTONFEEDBACK);

See “Shortcut Bar Styles” for more style flags and their descriptions.

To enable context menus in a shortcut bar

1. Use the SEC_OBS_CONTEXTMENU style as a parameter for the Create() or ModifyBarStyles() methods. For example:

m_scBar.ModifyBarStyle( 0, SEC_OBS_CONTEXTMENU);

2. Associate a context menu with the shortcut bar by calling the SetBarMenu() method.

//Grab the zoom menu

CMenu * pPopupMenu =

AfxGetApp()->m_pMainWnd

->GetMenu()->GetSubMenu(3);

ASSERT(pPopupMenu != NULL);

m_scBar.SetBarMenu(pPopupMenu);

NOTE >> The context menu specified here does not appear when an SECShortcutListCtrl window is right clicked. The SECShortcutListCtrl has its own context menu that is displayed when a right click occurs.

See “Shortcut Bar Styles” for more style flags and their descriptions.

To have the shortcut bars display the focus rectangle

Use the SEC_OBS_BUTTONFOCUS style flag as a parameter for the Create() or ModifyBarStyles() methods. For example:

m_scBar.ModifyBarStyle( 0, SEC_OBS_BUTTONFOCUS);

See “Shortcut Bar Styles” for more style flags and their descriptions.

To enable/disable animated scrolling

1. Use the SEC_OBS_ANIMATESCROLL style flag as a parameter for the Create() or ModifyBarStyles() methods. For example:

m_scBar.ModifyBarStyle( 0, SEC_OBS_ANIMATESCROLL);

2. To control the scrolling behavior further, call the SetAnimationSpeed() and SetAnimationStep() methods.

See “Shortcut Bar Styles” for more style flags and their descriptions.

To receive notifications when an icon in the SECShortcutListCtrl is clicked

1. In your parent window class (frame window, dialog, or other), add the ON_NOTIFY_RANGE macro to your message map macro list using the SEC_NM_ITEMCLICKED notification message. For example:

ON_NOTIFY_RANGE( SEC_NM_ITEMCLICKED, SEC_IDW_BARCLIENT_FIRST,

SEC_IDW_BARCLIENT_LAST, OnListBarClicked )

2. Override SECShortcutBar::OnListBarClicked(). The prototype looks like this.

afx_msg void OnListBarClicked( UINT nID,

NMHDR* pNMHDR, LRESULT* pResult );

See “Shortcut Bar Notification Messages” for more information on notification messages.

To determine which icon is clicked in an SECListBar window

When the user clicks an icon, it generates an SEC_NM_ITEMCLICKED notification. Typically, you would add a message map entry like the following to your listbar’s parent window (frame window, dialog).

ON_NOTIFY_RANGE( SEC_NM_ITEMCLICKED,

SEC_IDW_BARCLIENT_FIRST,

SEC_IDW_BARCLIENT_LAST,

OnListBarClicked )

The prototype for OnListBarClicked() is as follows:

afx_msg void OnListBarClicked( UINT nID,

NMHDR* pNMHDR, LRESULT* pResult );

The following is an example handler.

void CMainFrame::OnListBarClicked( UINT nID,

NMHDR* pNMHDR,

LRESULT* pResult )

{

ASSERT( pNMHDR->idFrom == nID );

ASSERT( nID >= SEC_IDW_BARCLIENT_FIRST );

ASSERT( nID <= SEC_IDW_BARCLIENT_LAST );

// Get the item clicked and display it

SEC_SCNMHDR* pSCNMHDR=(SEC_SCNMHDR *)pNMHDR;

TCHAR szMsg[80];

SECListBar* pListBar =

(SECListBar*)&(m_scListBar.GetActiveBar());

SECShortcutListCtrl* pCtrl =

pListBar->GetListCtrl();

CString strLab = pCtrl->GetItemText(

pSCNMHDR->iSelItem,0);

wsprintf(szMsg,_T("You clicked icon number %d\n Item Label: %s\n"),

pSCNMHDR->iSelItem, strLab);

AfxMessageBox(szMsg);

// Apply focus back to the listbar such that

// the hot-tracked state is properly cleaned

// up from the recent activation change.

::SetFocus(pNMHDR->hwndFrom);

}

To change the orientation of the shortcut bar at run time

Call the SetAlignStyle() method. For example:

//Change the SECShortcutBar to horizontal alignment

m_wndShortcutBar.SetAlignStyle( SEC_OBS_HORZ );

//change back to vertical

m_wndShortcutBar.SetAlignStyle( SEC_OBS_VERT );

To embed an SECShortcutBar into a splitter pane

1. Derive a new class from CSplitterWnd. In the derived splitter class, introduce a handler for the WM_MOUSEWHEEL message and remove the call to the base CSplitterWnd handler. Return FALSE instead. For example:

BOOL CMySplitterWnd::OnMouseWheel(UINT nFlags,

short zDelta,

CPoint pt)

{

//Do not call the base class handler.

// Return false instead.

return FALSE;

}

2. Create a splitter window using the run-time class SECShortcutBar to create the shortcut bar as a child of the splitter window. For example:

// 1 row, 3 cols

m_splitter.CreateStatic( this, 1, 3 );

m_splitter.CreateView( 0, 0, RUNTIME_CLASS(SECShortcutBar),

CSize(0,0), pContext );

3. Retrieve a pointer to the shortcut bar from the splitter window. For example:

//m_pShortcutBar is a pointer to SECShortcutBar

m_pShortcutBar =

(SECShortcutBar*)m_wndSplitterWindow.GetPane(0,0);

ASSERT_VALID(m_pShortcutBar);

4. Use the AddBar() method to add bars to the shortcut bar. See “To add selectable icons to a shortcut bar” and “To embed a window in a shortcut bar”.