DIBLOOK Sample: Illustrates the Use of DIBs and Color Palettes

The DIBLOOK sample illustrates the use of device-independent bitmaps (DIB) and the closely related use of color palettes.

DIBLOOK also illustrates a document that has an externally defined file format (in this case, the DIB file format). This is in contrast to an internally defined file format, which is otherwise implied when the framework automatically calls the document's Serialize function to store the contents of the document on disk. DIBLOOK further illustrates use of the Clipboard, CFile, and scroll views.

Security Note
This sample code is intended to illustrate a concept, and it shows only the code that is relevant to that concept. It may not meet the security requirements for a specific environment, and it should not be used exactly as shown. We recommend that you add security and error-handling code to make your projects more secure and robust. Microsoft provides this sample code "AS IS" with no warranties.

To get samples and instructions for installing them:

To access samples from Visual Studio

• On the Help menu, click Samples.

  By default, these samples are installed in drive:\Program Files\Microsoft Visual Studio 10.0\Samples\.

• For the most recent version of this sample and a list of other samples, see Visual Studio Samples on the MSDN Web site.

Building and Running the Sample

To build and run the DIBLOOK sample

1. Open the solution DibLook.sln.

2. On the Build menu, click Build.

3. On the Debug menu, click Start Without Debugging.

DIBLOOK is a multiple document interface (MDI) application that lets you view multiple bitmaps at the same time. Use File Open to open an existing device-independent bitmap (.dib) file or device-dependent bitmap (.bmp) file. Alternately, you can create a new bitmap document by copying a bitmap from another application, such as Paint, using the Clipboard, as follows:

• From the other application, copy a bitmap to the Clipboard.

• Use the DIBLOOK New command on the File menu to create a new bitmap document.

• Use the Paste command on the Edit menu to copy the bitmap from the Clipboard into the new document.

Although you cannot edit the image in DIBLOOK, you can save the bitmap to another file by using the Save As command on the File menu. The bitmap is saved in device-independent bitmap format, even if its original format was device dependent.

Externally Defined Document Format

DIBLOOK reads and stores bitmaps in the standard Windows device-independent bitmap format. While in memory, the bitmap is managed by Windows using an opaque HDIB handle. The internal format of the bitmap is visible to the application. Thus, DIBLOOK's document does not itself store the bitmap bits or the color table. Instead, CDibDoc holds a handle to the DIB (HDIB m_hDIB). DIBLOOK is an application whose document format is defined externally (typically some standard file format standard such as DIB), in contrast to an application whose document format is implicitly defined according to the sequence in which it serializes the document items in the CDocument::Serialize override.

DIBLOOK does not override CDocument::Serialize. Instead, DIBLOOK overrides CDocument::OnOpenDocument and OnSaveDocument. Both overrides use the pszPathName, passed in by the framework, to open a CFile object and to read or save the DIB. The actual code for reading and saving the DIB file is provided in Myfile.cpp; this code is reusable by any application that needs to read and save DIB files.

Using DIBs and Color Palettes

DIBLOOK illustrates how to display a DIB in a window and how to prepare the color palette for the window displaying the DIB.

After DIBLOOK reads the DIB from a file, it prepares a CPalette object based on the color table of the DIB and stores the palette as m_palhDIB in the CDibDoc object. When DIBLOOK displays the DIB in its CDibView::OnDraw, it calls a Windows ::PaintDIB routine implemented in DIBLOOK's Dibapi.cpp file. PaintDIB in turn calls the Windows function ::SetDIBitsToDevice or ::StretchDIBits, using the color table of the DIB as the color palette. The DIB-displaying routines in Dibapi.cpp are reusable by any application that displays DIBs.

DIBLOOK selects a color palette that is optimal for the currently active window. DIBLOOK selects a color palette matching the color table of the DIB displayed in the currently active MDI child window. When an application is about to receive the input focus (shifting away from another application), its top-level window receives the WM_QUERYNEWPALETTE message. DIBLOOK's CMainFrame window handles this message by sending an application-defined message, WM_DOREALIZE**,** to each of the descendant windows. The list of descendant windows includes all the views of the possible multiple opened documents. In turn, each view selects into its display context as a foreground or background palette, depending on whether the view is the active one or not.

If another application changes the system palette, DIBLOOK receives the WM_PALETTECHANGED message. In this case, the CMainFrame window again sends the application-defined message, WM_DOREALIZE**,** to each view. Each view selects its palette into the display context as a background palette, however, yielding the foreground palette to the other application.

When the focus shifts within the application from one view to another, DIBLOOK selects and realizes the palette for the currently active view (see CDibView::OnActivateView). When the new palette is realized, Windows sends the WM_PALETTECHANGED message to all application top-level windows, including those of DIBLOOK. DIBLOOK handles the message by realizing as a background palette the color tables associated with the other DIBs in the other views.

Keywords

This sample demonstrates the following keywords:

AfxGetApp; CCmdTarget::BeginWaitCursor; CCmdTarget::EndWaitCursor; CCmdUI::Enable; CDC::RealizePalette; CDC::SelectPalette; CDialog::DoModal; CDocument::DeleteContents; CDocument::OnNewDocument; CDocument::OnOpenDocument; CDocument::OnSaveDocument; CDocument::ReportSaveLoadException; CDocument::SetModifiedFlag; CDocument::SetPathName; CDocument::UpdateAllViews; CFile::Abort; CFile::Close; CFile::GetLength; CFile::Open; CFile::Read; CFile::ReadHuge; CFile::Write; CFile::WriteHuge; CFrameWnd::GetActiveView; CFrameWnd::LoadFrame; CMDIFrameWnd::MDIGetActive; CObject::AssertValid; CObject::Dump; CPalette::CreatePalette; CScrollView::SetScrollSizes; CStatusBar::Create; CStatusBar::SetIndicators; CString::LoadString; CToolBar::Create; CToolBar::LoadBitmap; CToolBar::SetButtons; CView::DoPreparePrinting; CView::GetDocument; CView::OnActivateView; CView::OnDraw; CView::OnInitialUpdate; CView::OnPreparePrinting; CWinApp::AddDocTemplate; CWinApp::EnableShellOpen; CWinApp::InitInstance; CWinApp::LoadStdProfileSettings; CWinApp::RegisterShellFileTypes; CWnd::DoDataExchange; CWnd::OnCreate; CWnd::OnPaletteChanged; CWnd::OnQueryNewPalette; CWnd::OpenClipboard; CWnd::SendMessage; CWnd::SendMessageToDescendants; CWnd::ShowWindow; CWnd::UpdateWindow; CloseClipboard; DragAcceptFiles; EmptyClipboard; GetClipboardData; GetDeviceCaps; GlobalAlloc; GlobalFree; GlobalLock; GlobalSize; GlobalUnlock; IsClipboardFormatAvailable; MessageBox; SelectPalette; SetClipboardData; SetDIBitsToDevice; SetStretchBltMode; StretchDIBits; memcpy

See Also

Other Resources

MFC Samples