*** formsC unit ***
(TFormC, TFormTaskbarC, TMainFormC, TMonitorList)

by Arash Ramin - http://www.digitalroom.net
version 1.20 (August 09, 2001)


DESCRIPTION
-----------

- TFormC: centers forms relative to their parent window and fixes other
  VCL quirks (with full multi-monitor compliancy).

- TFormTaskbarC: places and minimizes forms to the taskbar

- TMainFormC: adds animation & system sounds when minimizing/restoring an
  application (for C++Builder 1/3/4)

- TMonitorList: provides full multi-monitor support to applications.

Freeware (w/source) provided I'm not held liable for any use or misuse etc.
Please e-mail any bugs, suggestions etc.


COMPATIBILITY
-------------
C++Builder 1/3/4/5

The C++Builder 5 VCL fixes the 'hidden application window' animation problem,
so using TMainFormC isn't necessary unless you want to use its MinimizeOnClose
property.

All the code germane to this will be conditionally compiled for C++Builder 1/3/4
only.


USAGE
-----
- Copy \include\multimon.h to your C++Builder\Include directory if you're
  using C++Builder 1 or 3.
  (multi-monitor header file from the Sept. 1998 MS Platform SDK)

- Add formsC.cpp to your project OR
  install as a component (it won't show up on the component palette!)
- Include header file (formsc.h) in all forms.

- You may safely ignore any warnings generated by the multimon.h header file.


REFERENCE
---------

Global functions:
=================

- Ensure window is not displayed off the screen, or in a multi-monitor
  environment displayed entirely on one monitor:

	TPoint __fastcall CheckPosition(HWND hWnd)


- Centers the window (hWnd) relative to its parent (hParent):

	TPoint __fastcall CenterForm(HWND hWnd, HWND hParent);

  (CenterForm places a call to CheckPosition)


- Minimize/Restore application with animation & sounds (C++Builder 1/3/4 ONLY):

	void __fastcall AppMinimize();
	void __fastcall AppRestore();


TFormC
======

Ensure that your application's regular forms descend from TFormC instead of
TForm, as follows:

Header (.h) file:
-----------------
REPLACE DECLARATION
class TForm1 : public TForm
WITH
class TForm1 : public TFormC

Source (.cpp) file:
-------------------
REPLACE CONSTRUCTOR 
__fastcall TForm1::TForm1(TComponent* Owner) : TForm(Owner) {}
WITH
__fastcall TForm1::TForm1(TComponent* Owner) : TFormC(Owner) {}


*** METHODS ***

- The following two methods are the same as Show/ShowModal, except they
  center the form relative to the parent window (specified by hParent):

	HIDESBASE void __fastcall ShowCenter(HWND hParent);
	int __fastcall ShowModalCenter(HWND hParent);


- Sets the ontop property of the form without the annoying flicker effect
  (WARNING - this does not update the TForm:FormStyle property)

	void __fastcall TFormC::SetOnTop(bool OnTop)


*** COMMENTS ***

- Make sure that your TFormC::Position is not set to poScreenCenter if you're
  using ShowCenter or ShowModalCenter - otherwise your forms will always be
  centered to the screen.


TFormTaskbarC
=============

This class subclasses TFormC, but overrides the CreateParams method to minimize
the form to the taskbar.  If you want to place/minimize any of your forms on the
taskbar, ensure your custom form descends from TFormTaskbarC instead of TFormC.

(see TFormC info. for usage)


TMainFormC
==========

Ensure that your application's MainForm descends from TMainFormC instead of
TForm (same method as above).  This will automatically add animation
and system sounds to your application when you minimize/restore provided
you use the AppMinimize() and AppRestore() functions.

Only your MainForm should use this class!

*** PROPERTIES ***

TMessageEvent OnAppMessage;
- you must use OnAppMessage instead of Application->OnMessage for any message
  handling to the TApplication window.


bool MinimizeOnClose;
- if true, then any request to close the form through the application through the
  window's caption will minimize the application instead (this might be useful
  for system services, or other applications that generally run 24/7)

*** COMMENTS *** (IMPORTANT!)

- To minimize/restore your application in code, use the AppMinimize(),
  AppRestore() global functions.  Application->Minimize(), Application->Restore()
  will still work, but won't give you animation or sounds.

- TMainFormC uses the Application->OnMessage event handler to trap the
  minimize/restore messages.  Use the TMainFormC::OnAppMessage event handler
  instead as an application based message handler.

- If you're using C++Builder 5 or higher, use TFormC instead of TMainFormC for
  your MainForm (unless you wish to use TMainFormC.MinimizeOnClose).
  AppMinimize() and AppRestore() methods are only compiled for C++Builder 1/3/4.


TMonitorList
============

Adds support for secondary displays on multi-monitor systems (Win 98/Me/2000/XP).

NB - As of C++Builder 4.0, multi-monitor displays are supported through the VCL.

*** PROPERTIES ***

	int Count;

- returns the number of monitors on the system
  (Windows 95/NT 4.0 will always return 1)

	monitorInfo *Monitor[int Index];

- returns the monitorInfo struct for the given Monitor index
  (0 being the primary display)

	struct monitorInfo {
	  HMONITOR Handle; // handle to the specified display
	  RECT ScreenArea; // RECT structure for entire screen area
	  RECT WorkArea;   // RECT structure for display's working area (not obscured by docking windows)
	};

- if the specified display is no longer valid, an exception will be raised.

*** METHODS ***

	TMonitorList()
	~TMonitorList()

(you have to instantiate a TMonitorList object in order to use it -
it is NOT automatically created)


ACKNOLWEDGEMENTS
----------------

- Animation code originally from Delphi Developer Journal
  (http://www.zdjournals.com/ddj/), but with several fixes.

- Some multi-monitor code based on examples from MSDN.

- Thanks to Mike McCollister for sound code and bug fixes.


HISTORY
-------

Version 1.20 (August 09, 2001)
- Minimize/restore animation and sound code conditionally compiled for
  C++Builder 1/3/4 only (as of C++Builder 5, this has been fixed).
- added TFormTaskbarC class - minimizes a form to the taskbar.


Version 1.10 (February 19, 2000)
- methods return a VCL style TPoint type (instead of the Win32 POINT struct)
- added SetOnTop() - updates form's ontop property without the flicker effect
- added CheckPosition() - ensures form is not displayed off the screen,
  or in a multi-monitor environment displayed entirely on one monitor
- FormC:Show() and FormC():ShowModal() automatically call CheckPosition()


Version 1.02 (June 03, 1999)
- AppRestore() ensures that the enabled control has window focus


Version 1.01 (October 30, 1998)
- Fixed minimize/restore sound bug
  (if no system sound was specified, default sound was played instead)


Version 1.0 (October 23, 1998)
- Initial Release