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 provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices. Microsoft assumes no liability for incidental or consequential damages should the sample code be used for purposes other than as intended.

To get samples and instructions for installing them:

• On the Visual Studio Help menu, click Samples.

  For more information, see Visual Studio Samples.

• The most recent version and complete list of samples is available online from the Visual Studio 2008 Samples page.

• You can also locate samples on your computer's hard disk. By default, samples and a Readme file are copied into a folder under \Program Files\Visual Studio 9.0\Samples\. For Express editions of Visual Studio, all samples are located online.

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 FileOpen 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