// ==========================================================================
// Class Specification : COXSplashWnd
// ==========================================================================
//
// Header file : OXSplashWnd.h
//
// Version: 9.3
//
// Properties:
// NO Abstract class (does not have any objects)
// YES Derived from CWnd
//
// YES Is a CWnd.
// YES Two stage creation (constructor & Create())
// YES Has a message map
// YES Needs a resource (template)
//
// NO Persistent objects (saveable on disk)
// NO Uses exceptions
//
// Description:
//
// COXSplashWnd is a class that allows a programmer to show an
// initial window when the applications starts. A bitmap (even 256-
// color) can be shown within this window. After a short period of
// time (e.g. 0.8 seconds) the window will disappear. This can be
// used to show an initial logo, copyright information etc.
// A special feature of this class allows the window region to be
// fitted according to the bounding region of the bitmap. So when the
// bitmap is not rectangular, neither will be the window. This
// bounding path is calculated based upon color differences.
// "Holes" within the bitmap are not supported.
//
/////////////////////////////////////////////////////////////////////////////
#ifndef __OXSPLASHWND_H__
#define __OXSPLASHWND_H__
#if _MSC_VER >= 1000
#pragma once
#endif // _MSC_VER >= 1000
#include "OXDllExt.h"
// v9.3 - update 03 - 64bit - included for OXTPARAM
#include "UTB64Bit.h"
#ifndef CLR_NONE
#define CLR_NONE 0xFFFFFFFFL
#endif // CLR_NONE
#ifndef CLR_DEFAULT
#define CLR_DEFAULT 0xFF000000L
#endif // CLR_DEFAULT
#define SPLASH_NOTIMER -1 // flag for Show() function, splash windows stays
#define OXSPLASHWND_TIMERID_HIDE 1
#include "OXSplashWndDIB.h"
/////////////////////////////////////////////////////////////////////////////
class OX_CLASS_DECL COXSplashWnd : public CWnd
{
// Data members -------------------------------------------------------------
public:
static int m_nDefaultTimeout;
// --- Default time out value for splash window (in milliseconds)
protected:
static COXSplashWnd* c_pGlobalWnd;
static BOOL c_bShowSplashWnd;
int m_nTimeout;
BOOL m_bAutoDelete;
COXSplashWndDIB m_dib;
CRgn m_rgn;
COLORREF m_crBorder;
BYTE m_crBorderR;
BYTE m_crBorderG;
BYTE m_crBorderB;
BYTE m_nTolerance;
CWnd m_invisParent;
BOOL m_bUserCancel;
private:
// Member functions ---------------------------------------------------------
public:
COXSplashWnd();
// --- In :
// --- Out :
// --- Returns :
// --- Effect : Constructor of object
virtual ~COXSplashWnd();
// --- In :
// --- Out :
// --- Returns :
// --- Effect : Destructor of object
BOOL GetAutoDelete() const;
// --- In :
// --- Out :
// --- Returns : AutoDelete setting
// --- Effect : retrieve AutoDelete setting. TRUE if the C++ object
// (COXSplashWnd) should be deleted automatically when
// the Windows's window is destroyed. FALSE otherwise.
// Default value is (1) FALSE when an explicit object was
// created (a regular object); (2) TRUE when static function
// was called to implicitly create an object (a global
// splash window)
void SetAutoDelete(BOOL bAutoDelete = TRUE);
// --- In : bAutoDelete, the new AutoDelete setting
// --- Out :
// --- Returns :
// --- Effect : specifies whether the C++ object (COXSplashWnd) should
// be deleted automatically when the Windows's window is
// destroyed.
void SetUserCancel(BOOL bUserCancel = TRUE);
// --- In : bUserCancel - if TRUE then user can cancel displaying
// of splash window by clicking any mouse
// button or pressing any button on a keyboard
// --- Out :
// --- Returns :
// --- Effect : specifies whether splash window will be hidden in result of
// clicking any mouse button or pressing any button on a keyboard
// by an user. Set to TRUE by default.
BOOL GetUserCancel();
// --- In :
// --- Out :
// --- Returns : TRUE if splash window will be hidden in result of clicking any
// mouse button or pressing any button on a keyboard by an user,
// or FALSE otherwise.
// --- Effect :
virtual BOOL LoadBitmap(LPCTSTR lpszResourceName,
COLORREF crBorder = CLR_DEFAULT, LPPOINT pStartPoint = NULL,
BYTE nTolerance = 0);
virtual BOOL LoadBitmap(UINT nIDResource, COLORREF crBorder = CLR_DEFAULT,
LPPOINT pStartPoint = NULL, BYTE nTolerance = 0);
virtual BOOL LoadBitmapFile(LPCTSTR lpszFileName,
COLORREF crBorder = CLR_DEFAULT, LPPOINT pStartPoint = NULL,
BYTE nTolerance = 0);
// --- In : lpszResourceName, nIDResource, the bitmap resource
// crBorder, indicates which color should be used as
// border color. Every outer pixel in this color
// will be made invisible. This will create the
// necessary shape of the splash window. You can
// either specify the color or use one of the two
// special values:
// CLR_NONE: no border color needs to be used.
// The bitmap will just be shown as a
// rectangle bitmap.
// CLR_DEFAULT:the color of the pixel specified
// by pStartPoint should be used.
// pStartPoint, indicates which pixel within the bitmap
// should be used to start looking for the actual border.
// When no starting point is specified, (0,0) is used
// by default.
// nTolerance, indicates how much the color has to be
// different from crBorder before it is actaully accepted
// as a different color. A tolerance of 0 indicates that
// all colors except an exact match with crBorder are
// treated as different.
// --- Out :
// --- Returns : TRUE if successful; FALSE otherwise.
// --- Effect : Loads the bitmap from resource, and specify parameters for
// determining the shape (visible-invisible boundary).
virtual BOOL Show(int nTimeOut = m_nDefaultTimeout, CWnd* pParentWnd = NULL,
CPoint* pptDisplayAt = NULL);
// --- In : nTimeOut, indicates how long the window should exist
// (in milliseconds). If this nTimeout is SPLASH_NOTIMER, no
// timer is set and the user must take care of the hiding. Can
// be used in conjunction with the Hide() function.
// pParentWnd, the parent window if NULL is specified the splash
// window is a toplevel window with no parent window
// pptDisplayAt, pointer to the point on the screen at which splash
// window should be displayed, if it's NULL then splash window
// will be centered
// --- Out :
// --- Returns : TRUE if successful; FALSE if no valid bitmap was loaded.
// --- Effect : Display the splash window.
virtual BOOL Hide(int nTimeOut = 0);
// --- In : nTimeOut, indicates how long the window should exist
// (in milliseconds)and be visible after calling this
// function.
// --- Out :
// --- Returns : TRUE if successful;
// --- Effect : Hides and destructs the the splash window after a certain time.
BOOL GetRegion(CRgn& rgn);
// --- In :
// --- Out : rgn, a copy of the previously calculated region
// --- Returns : whether a valid region has been returned or not.
// --- Effect : When the class has already calculated the border region
// (in LoadBitmap()) a copy of the region will be returned
// by this function.
BOOL SetRegion(CRgn& rgn);
// --- In : rgn, the region describing the shape of the bitmap to
// display
// --- Out :
// --- Returns : TRUE if successful; FALSE otherwise
// --- Effect : Pass an existing region to the COXSplashWnd object.
// The region will be copied, so destruction of rgn is
// the caller's resposibility.
COXSplashWndDIB* GetDIB();
// --- In :
// --- Out :
// --- Returns: pointer to COXSplashWndDIB object used internally to display
// loaded bitmap resource.
// --- Effect : Retrieves internal COXSplashWndDIB object. Refer to the
// documentation on COXSplashWndDIB class for full reference
// of all its public functions
// Global Functions:
// The class contains one static pointer to an object of the class.
// This can be useful, because normally an application uses only one
// splash window (at startup). All functions that have the word
// "Global" in their name act on this object. The meaning is the same
// as the counterpart without "Global" in its function name.
// NOTE:when LoadGlobalBitmap() is called, an COXSplashWnd object
// was created and the AutoDelete attribute will be set to TRUE,
// meaning the C++ object will be deleted automatically when the
// window is destroyed.
// Calling ShowGlobal() without a previous successful call to
// LoadGlobalBitmap() will not succeed. A failure of LoadGlobalBitmap()
// could be due to a not-found bitmap, or an empty region was calculated
// from the loading process. A TRACE message from the LoadGlobalBitmap()
// would describe the reason why it failed.
static void EnableSplashScreen(BOOL bEnable /*= TRUE*/);
// --- In : bEnable, specify whether global splash window will
// be enabled
// --- Out :
// --- Returns :
// --- Effect : enable/disable global splash window.
// NOTE: This function can be called before
// LoadGlobalBitmap(), and the global window will not
// be created only after LoadGlobalBitmap() succeeds.
// This function has no effects on a regular object as
// opposed to the global object created through
// LoadGlobalBitmap().
// A common use of this function would be in
// CMyApp::InitInstance():
// ...
// CCommandLineInfo cmdInfo;
// ParseCommandLine(cmdInfo);
// COXSplashWnd::EnableSplashScreen(cmdInfo.m_bShowSplash);
static COXSplashWnd* GetGlobalWnd();
// --- In :
// --- Out :
// --- Returns : pointer to the global COXSplashWnd object
// --- Effect : obtain the pointer to the global COXSplashWnd object
static BOOL LoadGlobalBitmap(LPCTSTR lpszResourceName,
COLORREF crBorder=CLR_DEFAULT, LPPOINT pStartPoint=NULL,
BYTE nTolerance=0);
static BOOL LoadGlobalBitmap(UINT nIDResource, COLORREF crBorder=CLR_DEFAULT,
LPPOINT pStartPoint=NULL, BYTE nTolerance=0);
static BOOL LoadGlobalBitmapFile(LPCTSTR lpszFileName,
COLORREF crBorder=CLR_DEFAULT, LPPOINT pStartPoint=NULL,
BYTE nTolerance=0);
static BOOL ShowGlobal(int nTimeOut = m_nDefaultTimeout, CWnd* pParentWnd = NULL,
CPoint* pptDisplayAt = NULL);
static BOOL HideGlobal(int nTimeOut = 0);
static BOOL GetGlobalRegion (CRgn& rgn);
static BOOL SetGlobalRegion (CRgn& rgn);
//{{AFX_VIRTUAL(COXSplashWnd)
protected:
virtual void PostNcDestroy();
virtual BOOL PreTranslateMessage(MSG* pMsg);
//}}AFX_VIRTUAL
protected:
virtual BOOL BuildRegion(POINT ptStart);
virtual BOOL IsBorder(POINT pt, BOOL bConsiderInvalidAsBorder = TRUE);
//{{AFX_MSG(COXSplashWnd)
// v9.3 - update 03 - 64-bit - using OXTPARAM here - see UTB64Bit.h
afx_msg void OnTimer(OXTPARAM nIDEvent);
afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);
afx_msg void OnPaint();
//}}AFX_MSG
DECLARE_MESSAGE_MAP()
private:
};
// inline functions
#include "OXSplashWnd.inl"
#endif // __OXSPLASHWND_H__
// end of OXSplashWnd.h
/////////////////////////////////////////////////////////////////////////////