Skip over navigation

Welcome to the all new DelphiDabbler website.

I hope you like it.

There are going to be bugs. Please report any you find on the website's issues page (GitHub account required). Thanks.

Click the close button and you won't see this message again.

Window State Components

Components that save and restore window size, location & state

Version 5.6.1
Released 28 Oct 2014
Platforms Win32 & Win64
Framework VCL
Compatibilty Delphi 5 and later

Overview

The window state components can save and restore a window's size, position and state between program executions. Three components are provided that use different means of storing the information. They are:

TPJWdwState

Records window information in an ini file. The user has control over the ini file name (via the IniFileName property) and the name of the section of the ini file where window information is recorded (using the Section property). Alternatively the ini file and section names can be configured by handling the OnGetIniData event that is triggered immediately before the ini file is read or written.

TPJRegWdwState

Uses the registry to record window information. The registry root key and sub key where the information is stored are controlled by the RootKey(Ex) and SubKey properties, or by handling the OnGetRegData(Ex) event. This event is triggered just before the registry is accessed. Additional application defined data can be read from or written to the registry by handling the OnGettingRegData and OnPuttingRegData events that are triggered after the component reads or writes the registry.

You are discouraged from using TPJRegWdwState for programs compiled with Delphi 5 and earlier that may be run on 64 bit Windows, because the component may not be able to access the 64 bit registry correctly and window state may be lost.

TPJUserWdwState

When using this component the user must handle saving and reading the window state data to or from persistent storage. The component gives the most flexibility of all the components at the expense of placing the storage burden on the user. The component triggers OnReadData and OnSaveData events when it is ready to read or save data.

All components implement the same functionality, controlled by some common properties and events, as follows:

  • The components can automatically restore and save windows when the program starts up and closes down (using the AutoSaveRestore property). If AutoSaveRestore is set to False then the Restore and Save methods must be called from the host application.
  • The Options property can be used to customise the way the window is restored:
    • The components can be instructed to ignore the saved window state – the window is then displayed in the normal state.
    • The window's saved size can be ignored and the default size of the form used instead. This is useful for dialogue boxes and fixed size windows.
    • The window can be kept within the current work area of the desktop. If this option is used the window also appears on the correct monitor on multi-monitor systems. If the form containing the window state component is a MDI child form this option keeps the window within the parent form's client area, after allowing for any menu, toolbars or status bar etc.
  • When the form is to be restored in a minimized state it briefly appears on screen in the normal state before being minimized. The MinimizeDelay property controls the delay between the window appearing and being minimized.

TPJWdwState and TPJRegWdwState also support the OnReadWdwState event. Handling this event enables the stored window's state, size and position values to be changed before the window is restored. This event is called after reading the data and before sizing the window. TPJUserWdwState does not expose this event because the user is in charge of reading the data and can modify it in the OnReadData event.

All the components derive from an abstract base class named TPJCustomWdwState. This class provides the core window handling and sizing functionality. It provides abstract methods for accessing the required storage medium. Therefore it is quite straightforward to create further components that use alternative storage systems. All that needs to be provided are methods to read/write the window information along with any additional properties that are required to configure the storage medium.

There are four demo projects included with these components. They are:

  1. StandardDemo.dpr – Demonstrates how to use the components in the standard way, i.e. dropped on a form from the component palette. This demo uses TPJRegWdwState.
  2. StandAloneDemo.dpr – Demonstrates how to create and use the components dynamically using the CreateStandAlone constructor. This demo uses TPJWdwState.
  3. UserDemo.dpr – Demonstrates how to use TPJUserWdwState and load and save data in the OnReadData and OnSaveData events.
  4. MDIDemo.dpr – Demonstrates the use of TPJWdwState with MDI applications.

The underlying principle used in the code is described in the article "How to remember a window's size, state and position".

We can't rely on Delphi's own Width and Height properties for recording window size, since these do not maintain size of the normalised window size when the window is maximized. Instead we have to use the GetWindowPlacement and SetWindowPlacement Windows API calls.

Finding the right time to restore a window on application startup has proved problematic. It is not possible to call the Restore method before the form's window handle has been created. We therefore need to delay any such restoration until the form has been shown. A hook class is used to peek at the Windows messages sent to the parent form. This class forwards relevant messages to the component.

One side effect of this complexity is that you can't create instances of the components at run time using the standard constructor. The code is not initialised properly unless the component is added to a form at design time. A special constructor – CreateStandAlone – has been provided that makes dynamic construction possible.

Get The Code

You can download the latest version of the Window State Components directly from SourceForge as dd-wdwstate-5.6.1.zip.

Download v5.6.1

Window State Components is a sub-project of the DDabLib project which is maintained in a Subversion repository. The code is developed in the trunk/projects/wdwstate branch.

Subversion users can check out the source code of the current release from the repository on SourceForge by doing:

svn checkout http://svn.code.sf.net/p/ddablib/code/tags/projects/wdwstate/release-5.6.1 codedir

where codedir is the directory where you want to checkout code. To check out other versions, simply specify a different version number.

The latest development tree can be checked out using:

 svn checkout http://svn.code.sf.net/p/ddablib/code/trunk/projects/wdwstate codedir

Check outs are read only, but you can easily contribute code: see Feedback & Queries below.

Installation

The Window State Components are supplied in a zip file. Before installing you need to extract all the files from the zip file, preserving the directory structure. The following files will be extracted:

  • PJWdwState.pas – component source code.
  • PJWdwState.dcr – resource file containing component palette glyphs.
  • ReadMe.htm – read-me file.
  • ChangeLog.txt – the project's change log.
  • MPL-2.txt – the Mozilla Public License v2.0.
  • Documentation.URL – short-cut to the component's online documentation.
  • PJWdwState.hlp – component help file that integrates with the Delphi 4 to 7 OpenHelp system. Deprecated
  • PJWdwState.als – a-link keyword file for integration with the Delphi 6 or 7 OpenHelp system. Deprecated

In addition to the above files you will find the the source code of four demo projects along with readme files in the Demos directory and its 1, 2, 3 and 4 sub-directories. Read DemoReadMe.htm for details of the demos. Although the components are known to compile with Delphi 5 and later, the demos require Delphi 7 as a minimum.

You can now install the components into the Delphi IDE. If you need help doing this see here.

Documentation

The Window State Components are comprehensively documented online here

The project's change log can be viewed on SourceForge

A read-me file (ReadMe.htm) is included in the project download.

A legacy WinHelp help file is included in the download that can only be integrated with the IDE in Delphi 7 and earlier. this article explains how to do it.

This help file is deprecated and is no longer being updated. The last update was in the v5.4.1 release. The help file will be removed from any future release.

WinHelp is an optional download for Windows Vista through to Windows 8.1 and can't be installed at all on Windows 10.

There is also an FAQ.

Feedback & Queries

If you find any bugs or want to suggest a new feature please report them using the Issue Tracker.

Click the Create Ticket button to create a ticket then complete the form giving as much information as possible.

The issue tracker is shared among all the projects in the DelphiDabbler Code Library, so please make sure you enter wdwstate in the Project edit box to make it clear which project you are referring to. You should also choose Defect in the Type drop down list to report a bug or Enhancement to request a new feature.

If you have created a bug fix or have implemented a new feature please attach a zip file to your ticket that contains your source code.

Should you have any queries about using the components please read the documentation and/or FAQ. If you can't find an answer in the documentation then post a message in the discussion group

License

The Window State Components are open source. They are copyright © 1999-2014 by Peter Johnson. The source code is made available under the terms of the Mozilla Public License v2.0. All relevant trademarks are acknowledged.

The following people contributed to the project:

  • Stefan Winter
  • Enrico Bortolazzi
  • Bruce J Miller
  • Craig Symons