OWL_Compatibility_modes

OWL Compatibility Build Modes in OWLNext

This article describes special build modes that allow greater compatibility with OWL. These modes should be used only when porting old code from OWL to OWLNext. After completing the migration, it is recommended that compatibility build modes are turned off, and that your code is adapted to the latest changes in OWLNext.

For our recommended upgrade approach, see Upgrading from OWL.

Note: The compatibility modes were altogether removed in OWLNext 8, and the rest of this article hence only applies to version 7 and earlier.

• OWL Compatibility Build Modes in OWLNext
  • Usage
  • Obsolete compatibility modes
  • OWL5_COMPAT build mode
    • Namespace changes
    • Message dispatch and response tables
    • Calling sequence for TWindow::SetupWindow and TransferData
    • TPointer and TAPointer safety
    • Function signature changes
    • Obsolete classes and members
    • Obsolete messages
    • Obsolete control libraries
    • Deprecated Borland C++ Class Libraries

---

Usage

Pass "COMPAT=5" to the make file when building the libraries. For example, the following command on a Visual Studio Command Prompt builds the static debug variant of the OWLNext core with enhanced OWL 5 compatibility:

cd %OWLROOT%\source\owlcore
nmake -f vc.mak DEBUG=1 COMPAT=5

If you use OWLMaker, you just select the compatibility mode "OWL 5 API" on the modules page of the OWLMaker Wizard.

When "COMPAT=5" is passed to the make file, the macro OWL5_COMPAT will be defined in the arguments passed to the compiler, i.e. "/D OWL5_COMPAT". In turn, the OWLNext source code has conditional code that checks for the definition of OWL5_COMPAT, and if defined, enables greater compatibility with OWL 5 in many places.

To use the OWL 5 compatibility mode in your application, you have to add OWL5_COMPAT to the preprocessor definitions in the project settings in your IDE, or pass "/D OWL5_COMPAT" explicitly to the compiler, if you use command-line tools. OWLNext uses auto-linking, so you should not have to specify the library variant to link explicitly.

Note: To avoid link conflicts, OWLNext library variants built with OWL5_COMPAT will have the number 5 embedded in the last part of the library name. For example, for the x86-static-debug variant of OWLNext 6.34, built for Visual Studio 2013, the core library name will be "owl-6.34-v12-x86-5dt.lib". For more information, see the OWLNext Library Files Naming Convention.

---

Obsolete compatibility modes

OWLNext is based on OWL 5, and since OWLNext 6.32, the build modes OWL1_COMPAT and OWL2_COMPAT are no longer available. Before migrating your code to OWLNext you should make sure it works well with OWL 5. If you have code based on OWL version 1 or 2, you need to upgrade to OWL 5 before moving to OWLNext. See Upgrading from OWL 1.0.

Since version 8, there are no compatibility modes in OWLNext. So, if you are upgrading from OWL, you should use an earlier version of OWLNext as a stepping stone. See Upgrading from OWL | Recommended step-by-step approach.

---

OWL5_COMPAT build mode

Search the the OWLNext source code for the string "OWL5_COMPAT" to get a complete picture of the effects of enabling this build mode. The following sections give an overview of important changes.

Namespace changes

The core of OWLNext now lives in the "owl" namespace. OWLNext 6.32 renamed the namespace from "OWL" to "owl". A macro for the old namespace name is available in OWL5_COMPAT mode. However, note that OWLNext is strict about namespaces, whether or not you enable compatibility mode. See FAQ for some tips on how to update your code.

Message dispatch and response tables

OWLNext 6.40 introduced a major overhaul of the message dispatch machinery, including a new data structure for response tables.

• TResponseTableEntry is no longer a template.
• TResponseTableEntry::Pmf and its associated type PMF have been removed, since they are no longer needed.
• TEventHandler::TEventInfo::Object is now a void-pointer (previously a pointer to TGeneric).
• The types TAnyPMF and TAnyDispatcher are no longer used and have been removed.
• The DECLARE_SIGNATURE* macros are no longer used and have been removed.
• The NOTIFY_SIG macro is no longer used and has been removed.

In OWL5_COMPAT mode, the old data structure is reinstated, as well as the obsolete types and macros. However, the old implementation is deprecated, so you should not rely on it, as this compatibility may be removed in the future. If your code depends on the old implementation, you should update it.

See Windows Message Dispatch in OWLNext for more information about the new implementation.

Calling sequence for TWindow::SetupWindow and TransferData

In OWL 5, the dialog data transfer function TWindow::TransferData is called at the end of TWindow::SetupWindow. This is unfortunate because SetupWindow is commonly overridden to do custom initialisation of the window. However, if the override calls TWindow::SetupWindow, as is the common idiom, then data is transferred before the custom initialisation can take place. This calling sequence problem has been fixed, so that TransferData is now called after the call to SetupWindow (i.e. not within). See bug ticket "TransferData called before complete setup" [bugs:#102].

In OWL5_COMPAT mode, the old (erroneous) calling sequence is reinstated. Make sure you check your code for dependency on this calling sequence, before turning the compatibility mode off.

TPointer and TAPointer safety

For safety, the constructors for these classes are now explicit, and the classes are non-copyable. In OWL5_COMPAT mode these changes are reverted. Rewrite your code to use std::unique_ptr instead.

Function signature changes

The following (possibly incomplete) list of functions have had their signature changed in OWLNext, due to const-correctness issues etc. In OWL5_COMPAT mode, the old signature is reinstated. You should upgrade your code to use the new signatures.

Note: Beware of changes to the signature of virtual functions. If you use the wrong signature in your override, you may inadvertently and silently create a new virtual function, rather than override the base. To guard against this problem it is recommended to use the override keyword (introduced in C++11).

• EvGetText now returns int and takes int buffer size.
• EvGetTextLength now returns int.
• EvHotKey now have additional parameters uint modifiers and uint vk.
• EvPowerBroadCast now returns TResult for compliancy.
• TBitmap::TBitmap (const BITMAP*); replaced by TBitmap (const BITMAP&).
• TBrush::TBrush (const LOGBRUSH*); replaced by TBrush (const LOGBRUSH&).
• TBrush::GetObject (LOGBRUSH&); replaced by GetObject (), returning LOGBRUSH.
• TCursor::TCursor (const ICONINFO*); replaced by TIcon (const ICONINFO&).
• TCursor::GetIconInfo (ICONINFO*); replaced by GetIconInfo (), returning ICONINFO.
• TFont::TFont (const LOGFONT*); replaced by TFont (const LOGFONT&).
• TFont::GetObject (LOGFONT&); replaced by GetObject (), returning LOGFONT.
• TIcon::TIcon (const ICONINFO*); replaced by TIcon (const ICONINFO&).
• TIcon::GetIconInfo (ICONINFO*); replaced by GetIconInfo (), returning ICONINFO.
• TListViewCtrl::SetBkColor, SetTextBkColor and SetTextColor now takes a TColor, not a COLORREF.
• TListViewCtrl::GetBkColor, GetTextBkColor and GetTextColor now returns TColor, not COLORREF.
• TListViewCtrl::GetOrigin (POINT*); replaced by GetOrigin (TPoint&).
• TListViewCtrl::GetViewRect (RECT*); replaced by GetViewRect (TRect&).
• TListViewCtrl::GetColumn (int index, LVCOLUMN*); replaced by GetColumn (int colNum, TLvColumn&).
• TListViewCtrl::GetItemPosition (int index, POINT*); replaced by GetItemPosition (int index, TPoint&).
• TListViewCtrl::GetItemRect (int index, RECT*, TItemRectType); replaced by GetItemRect (int index, TRect&, TItemRectType).
• TListViewCtrl::FindItem(int startIndex, const TLvFindInfo*); replaced by FindItem(int startIndex, const TLvFindInfo&).
• TPalette::TPalette (const LOGPALETTE*); replaced by TPalette (const LOGPALETTE&).
• TPalette::TPalette (const BITMAPINFO*, uint flags); replaced by TPalette (const BITMAPINFO&, uint flags).
• TPen::TPen (const LOGPEN*); replaced by TPen (const LOGPEN&).
• TPen::GetObject (LOGPEN&); replaced by GetObject (), returning LOGPEN.
• TResId now implicitly converts to LPCTSTR, not LPTSTR, for const-correctness.
• TWindow::GetClassName now returns LPCTSTR, not LPTSTR, for const-correctness.
• TWindow::SetTransferBuffer (void*); now also takes uint size. It also has new overload templates that infer the buffer size from the argument type. See Safe Transfer Buffers.

Obsolete classes and members

The following classes and members are obsolete, but are reinstated in OWL5_COMPAT mode:

• TButtonGadget::TShadowStyle, GetShadowStyle and SetShadowStyle are obsolete.
• TCommandLine::Kind, Token and TokenLen are now private. Use GetToken and GetTokenKind instead.
• TDialog::DoCreate is no longer used. Call PerformCreate instead.
• TDialog::IsModal is replaced by flag TDialog::dfIsModal.
• TDialog::SendDlgItemMsg is replaced by TWindow::SendDlgItemMsg.
• TFile::GetStatus and SetStatus are replaced by TFileName::GetStatus and SetStatus.
• TListViewCtrl::DeleteAnItem is replaced by DeleteItem.
• TPrintDC::DeviceCapabilities is obsolete. Note that the implementation of this function uses an undocumented Win32 function, which may be missing and hence cause application start-up failure on Windows 10 and later [bugs:#342]. Use Win32 DeviceCapabilities instead.
• TTlsContainer::QueryData is replaced by Query.
• TTlsContainer::GetData, operator T*, operator T& and operator -> are all replaced by Get.
• TWindow::ReceiveMessage is now private. Use HandleMessage instead.
• TWindow::TransferBuffer is now private. Use GetTransferBuffer instead.
• Classes TLocalData, TTlsAllocator, TTlsDataManager and TProcessContainer are no longer supported. These are not OWL 5 classes. They were added in OWLNext long ago. They have bugs and are no longer maintained. However, they are reinstated in OWL5_COMPAT mode to minimise disruption to code that rely on them. Rewrite your code to not depend on these classes, as they will be removed in the future.

Obsolete messages

The following messages are obsolete, but are reinstated in OWL5_COMPAT mode:

• WM_CTLCOLOR; this is an obsolete Win16 message. Use the new Win32 messages instead (WM_CTLCOLORBTN etc.). In OWL5_COMPAT mode, EV_WM_CTLCOLOR is implemented by redirecting the new messages to the given handler.
• WM_POWER has been replaced by WM_POWERBROADCAST.
• WM_WININICHANGE has been replaced by WM_SETTINGCHANGE.

Obsolete control libraries

The following legacy libraries are obsolete and no longer supported by default. In OWL5_COMPAT mode, the support is reinstated.

• BWCC (Borland Windows Custom Controls); support can be independently enabled by defining OWL_SUPPORT_BWCC.
• CTL3D (3D Windows Controls); support can be independently enabled by defining OWL_SUPPORT_CTL3D.

Deprecated Borland C++ Class Libraries

The following legacy libraries are deprecated and since OWLNext 7 no longer supported by default. In OWL5_COMPAT mode, the support is reinstated.

• Persistent streams