Option

From 3e3d96886b5e8b3fa531a94c11e802ed230b0c8c Mon Sep 17 00:00:00 2001 From: Kimmo Varis Date: Wed, 23 Mar 2005 21:50:50 +0000 Subject: [PATCH] PATCH: [ 1168733 ] Doc for options --- Docs/Developers/Options.html | 81 ++++++++++++++++++++++++++++++++++++++++++++ Src/readme.txt | 4 +++ 2 files changed, 85 insertions(+) create mode 100644 Docs/Developers/Options.html diff --git a/Docs/Developers/Options.html b/Docs/Developers/Options.html new file mode 100644 index 000000000..79f0d29c6 --- /dev/null +++ b/Docs/Developers/Options.html @@ -0,0 +1,81 @@ + + + + Option + + + +

WinMerge Options system

+ +

WinMerge stores options into registry:

HKCU/Software/Thingamahoochie/WinMerge

+ +

Accessing options

Two ways to read and save options:

+ Direct access with WinAPI (GetProfileInt(), GetProfileString, + WriteProfileInt() & WriteProfileString()). +
Using COptionsMgr class (recommended)

+ +

Direct access with WinAPI

This is handy for settings needed in few events or cases (star, exit).

+ +

COptionsMgr

Using COptionsMgr is recommended for all new options. Also all options +visible in Options-dialog must use COptionsMgr. Currently there is one +COptionsMgr (or actually CRegOptions) instance in CMainFrame. +But that can change in future.

+ +

Using COptionsMgr is pretty simple and straightforward:

All options are accessed by constant names, listed in OptionsDef.h.
+ Options are initialised in CMainFrame::CMainFrame(). When initialised, + type is determined and default value given. If option with that name + does not yet exist, new one is created. +
Option value is read using COptionsMgr::GetBool(), GetInt() or GetString().
Option value is stored using COptionsMgr::SaveOption(). Note that value is saved to registry immediately.
Option value can be reset to default value using COptionsMgr::GetDefault()

+ +

Adding a new option

+ Add option name and registry path into OptionsDef.h. Please try to keep + options organised in registry, although all existing options aren't. + And use meaningful names for options. +
+ Add option initialiser to CMainFrame::CMainFrame(), with sensible + default value. Remember default value is what most users see when first + time using WinMerge or new feature using it. So it really must be good + for normal use. +
Use GetX() functions to read values and SaveOption() to store values.

+ +

Caching

There are some very frequently used option values, like color values for +editor syntax highlight. Reading and writing these kind of values through +COptionsMgr every time would be pretty inefficient. So we only read them +to local variables when needed and store when they are changed.

+ +

Options dialog

OptionsDialog (CPreferencesDlg) receives pointer to COptionsMgr when +initialised for access to options.

+ +

CPreferencesDlg::ReadOptions() is place to read option values and update +values to UI. CPreferencesDlg::SaveOptions() is place to save option values +to COptionsMgr when dialog is closed with OK.

+ +

If options page (dialog consists of several sub-pages) has 'Defaults' button +it needs pointer to COptionsMgr. Usually its easiest to give it in +constructor. Then page can call COptionsMgr::GetDefault() for options it +wants to reset to defaults when button is selected.

+ + diff --git a/Src/readme.txt b/Src/readme.txt index 215d2d593..617a474c0 100644 --- a/Src/readme.txt +++ b/Src/readme.txt @@ -1,3 +1,7 @@ +2005-03-23 Kimmo + PATCH: [ 1168733 ] Doc for options + Docs/Developers new file: Options.html + 2005-03-21 Kimmo BUG: [ 1162037 ] Missing localization (German) Translation update from Tim Gerundt -- 2.11.0