# Status of Orpheus Port

### Contents

What's New
Introduction
Installation
Platforms Tested
Examples
Porting Philosophy
Usage Notes
Limitations
Status of Individual Controls
To Do
Other Resources

### What's New

- 20090921 release (0.2.2):
  - Lazarus 0.9.27 eliminated the Ctl3D property, breaking Orpheus, which uses Ctl3D in several controls. This release restores the Ctl3D property so Orpheus can again be compiled with Lazarus.
  - The status table below has been updated for all widgetsets. In some cases Orpheus controls have improved with general improvements and bug fixes in the LCL and underlying widgetset code; in a few cases, however, Orpheus controls perform worse than they did previously, probably due to side-effects from LCL changes.

- 20081229 release (0.2.1):
  - Adds TOvcCalendar.
  - Updated results of testing for Lazarus 0.9.26. GTK2 widgetset now working better.

- 20080720 release (0.2.0):
  - Recent change in the Lazarus LCL broke Orpheus TOvcTable on Windows. This release works around that change.
  - Numerous bugs fixed and workarounds found. See To Do list.
  - Batch/script files are now included for compiling all test apps at once.

- 20080316 release (0.1.9):
  - Recent changes in the Lazarus LCL broke Orpheus compilation. This release can now be compiled.

- 20080301 release (0.1.8):
  - Recent changes in the Lazarus LCL broke all Orpheus property editors and example programs. This release fixes those problems.

- 20070903 release (0.1.7):
  - Recent changes in the Lazarus LCL broke Orpheus compilation. This release can now be compiled.
  - Recent improvements in the Lazarus Qt widgetset add basic functionality for several Orpheus controls (see table below). However, GTK2 widgetset does not work as well as it used to.

- 20070704 release (0.1.6):
  - 3 new example programs have been added for demonstrating TOvcSpinner, TOvcSimpleField, TOvcTCSimpleField and TO32TCSimpleField. Note that the TestSimpField and TestTblEdits examples are intended primarily for Windows at this time since TOvcSimpleField and TOvcTCSimpleField are not yet working on other widgetsets (see table below).
  - Fix improves functionality of TO32TCFlexEdit validation.

- 20070630 release (0.1.5):
  - Most of the Orpheus controls now work with the Lazarus Carbon widgetset.

- 20070425 release (0.1.4):
  - Recent changes to Lazarus LCL broke compilation of Orpheus. This release can now be compiled with the latest LCL.

- 20070401 release (0.1.3):
  - Improvements to TO32FlexEdit on Windows.

- 20070317 note:
  - Recent improvements in the Lazarus Carbon widgetset add basic functionality for several Orpheus controls on OS X (see table below).

- 20070211 note:
  - Recent improvements in Lazarus fix display of custom cursor when sizing and moving columns and rows at runtime in TOvcTable.

- 20070204 release (0.1.2):
  - Workarounds found for recent Lazarus changes that broke TOvcTable Columns and Rows editors.
  - Workaround found for recent FPC 2.1.1 change that broke compilation of ovcvlb.pas.

- 20070128 release (0.1.1):
  - An example program that demos the TO32FlexEdit control has been added even though validation doesn't work with LCL (see "To Do" list below). If you have Delphi you can compile the example to see how validation is supposed to work.
  - Recent changes in Lazarus on Windows appear to have broken both the Columns and Rows design-time property editors for the TOvcTable control. The property editors still work with OS X. Stay tuned...
  - Custom cursors are now visible when resizing table columns at runtime on Windows. However, cursor also disappears sometimes. Stay tuned on this one too...

- 20070127 note:
  - Recent improvements in the Lazarus Qt widgetset make a couple of Orpheus controls work better with Qt.

- 20070115 note:
  - In addition to downloading the .zip file (see link below), you can now also obtain the Orpheus ported source using Subversion:

    svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/orpheus [local_dir]

- 20070114 note:
  - Controls have now been tested with GTK2 widgetset (see table below).

- 20070107 release (0.1.0):
  - TOvcVirtualListBox control added.
  - Installation no longer registers TOvcSimpleField and TOvcTCSimpleField controls (see myovcreg.pas) on non-Windows platforms since these two controls don't work on other platforms and crash Lazarus IDE if added to a form on those platforms.

### Introduction

These notes describe the status of the OrphPort Project, an attempt to port a subset of TurboPower's Orpheus controls to Lazarus and Free Pascal. At this time, several enhanced label controls and most of the table (grid) controls have been ported. Some of the controls work quite well on multiple platforms; others need more work or await better support by the Lazarus LCL or by specific widgetsets before they are fully functional. The table below gives the status of individual controls. You are encouraged to work on improving these controls (see To Do list). Please send your bug reports, suggestions and patches to:

MacPgmr (at) fastermac (dot) net

Note: You can also post to the "Ported from Delphi/Kylix" section of the Lazarus forum if you want your bug reports and suggestions to be seen by the entire Lazarus community.

The ported source code is here: http://web.fastermac.net/~MacPgmr/OrphPort/downloads

You can now also obtain the Orpheus ported source using Subversion:

svn co https://lazarus-ccr.svn.sourceforge.net/svnroot/lazarus-ccr/components/orpheus [local_dir]

The original Orpheus 4.06 source code that this port was based on is here: http://sourceforge.net/projects/tporpheus (although you don't need this for Lazarus)

TurboPower's 1,392-page Orpheus User's Manual is also available from the Source Forge site.

Note that the ported source remains under the original MPL 1.1 license.

### Installation

1. Unzip the ported source files into their own folder.
2. Start Lazarus.
3. Optionally, choose File | New | Application to make sure Lazarus doesn't mess up the currently open project.
4. Choose Package | Open package file and select orpheus.lpk.
5. Click Compile to make sure your version of Lazarus can compile the Orpheus units.
6. Click Install and click Yes when prompted to rebuild the Lazarus IDE.
7. After rebuilding is finished, restart Lazarus if it didn't restart automatically. The installed Orpheus controls will be on the Orpheus tab of the component palette.

Important! If you don't have write access to the folder where Lazarus is installed, you may have problems rebuilding the Lazarus IDE with older versions of Lazarus. However, if you have a relatively new version of Lazarus, it will compile itself to the ~/.lazarus/bin folder if you don't have write access to the Lazarus install folder. After rebuilding, be sure to start ~/.lazarus/bin/lazarus, not the installed Lazarus.

### Platforms Tested

Platform | OS Version | Library Versions | Widgetsets Tested | Lazarus Version Tested
--- | --- | --- | --- | ---
Windows | XP SP2 |  | win32 | 0.9.28 RC with FPC 2.2.4
OS X | 10.4.11 (Tiger) on PowerPC | gtk: 1.2.0.9.1 gtk2: 2.14.7 qt: 4.5.2 | gtk, gtk2, carbon, qt | 0.9.28 RC with FPC 2.2.4
OS X | 10.5.8 (Leopard) on Intel |  | carbon | 0.9.28 RC with FPC 2.2.4
Linux | --not tested-- |  |  |

### Examples

The source for several small test applications is included which demonstrates most of the ported controls. Open each test app's .lpi file and compile it once Orpheus has been installed in Lazarus. Folders for the test apps are located in the tests folder in your Orpheus folder, as follows:

- TestTable - demos TOvcTable and various table cell controls (column headers, row labels, string, memo, check box, combo box, bitmap).
- TestURL - demos TOvcURL
- TestRLbl - demos TOvcRotatedLabel
- TestLabel - demos TOvcLabel
- TestVLB - demos TOvcVirtualListBox
- TestSpinner - demos TOvcSpinner
- TestFlexEdit - demos TO32FlexEdit validation
- TestSimpField - demos TOvcSimpleField validation (Windows only for now)
- TestTblEdits - demos TOvcTCString, TOvcTCSimpleField validation and TO32TCFlexEdit validation (Windows only for now)
- TestCalendar - demos TOvcCalendar

To see the TOvcSpinner control in action, try out the table's Rows and Columns property editors with the TestTable app.

Note: The TestTable app uses the included .bmp files to demo the TOvcTCBitMap control. These bitmap files are not needed to rebuild the Lazarus IDE since they're in the ovcreg.lrs resource file, but they are included for completeness.

Tip: The necessary files for compiling the test apps with Delphi are also included (.dof, .dfm, .bdsproj). If you have Delphi you can compile the apps to see exactly how the Orpheus controls are supposed to look and behave. Note that with the free Turbo Delphi Explorer you can't install Orpheus (a limitation of the free version). However, you can still compile the test apps, as follows:

- Start Turbo Delphi Explorer and open the test app's .bdsproj file.
- Click Ignore All to proceed when Delphi encounters the unrecognized Orpheus controls.
- Choose File | Close and click Cancel to close the main form.
- Choose Project | Options and make sure the Search path in Directories/Conditionals points to your Orpheus folder.
- Choose Project | Compile to compile the test app.

### Porting Philosophy

- All changes to the original source code were made via conditional compiling (IFDEF's). Thus the ported source retains full Delphi compatibility. An added benefit is that you can see what the original code was, something that is often lost with ported code.
- A compatibility unit, MyMisc, was added to fill in gaps in the Lazarus LCL and provide other compatibility routines.
- Orpheus functions written in assembly were "Pascal-ized" so the ported code could be compiled on non-Intel platforms.
- For now, the Lazarus package (orpheus.lpk) compiles the source with range, overflow and stack checking turned on. This revealed several apparently harmless bugs in the TurboPower code, which have been fixed. To find these and other minor bugs, grep the source for "TurboPower bug".
- In general, no other significant changes or "improvements" were made to the source. An exception is the o32tcflx unit, where a few additions were made to correct apparent omissions or inconsistencies.
- A note on comments: Comments added to the ported source are generally marked with "//". However, the "o32" units (developed later than other units by TurboPower) already included some "//" comments. With these units, you can tell the added comments by their context (near IFDEF's, for example).

### Usage Notes

1. When you first add an Orpheus control to a form, Lazarus will add the Orpheus unit to the uses section of your main source file (.lpr). This pulls in a great deal of code that you don't need. Delete the Orpheus unit from the uses section to reduce the size of your executable file. <==Fixed in 0.2.2 release.

2. The TOvcSimpleField and TOvcTCSimpleField controls originally did not work at all on non-Windows widgetsets, although they now have some functionality. For now, don't use these controls in cross-platform applications. Just opening a form that has a TOvcSimpleField or TOvcTCSimpleField control on it may crash non-Windows versions of Lazarus. Use the TO32FlexEdit and TO32TCFlexEdit controls in place of TOvcSimpleField and TOvcTCSimpleField controls in cross-platform applications.

3. To display the TOvcLabel's Style Manager property editor in the Lazarus IDE, right-click on the TOvcLabel control (Apple key+click on Mac). You can also change Style Manager properties via the CustomSettings in the Object Inspector. Also, with GTK, the default clNone Color displays a black background, so be sure to set ParentColor to True or select a different Color.

4. An added benefit of the Orpheus TOvcSpinner control is that it is available for Delphi too, unlike the LCL TSpinEdit, which has no equivalent in the Delphi VCL.

### Limitations

1. The TO32FlexEdit and TO32TCFlexEdit controls include code for displaying an optional button within the text editing area. However, this TBitBtn-within- a-TEdit has not been supported by the LCL, so the code has been IFDEF'd out for now. Beginning with Lazarus 0.9.27, this code appears to work okay with the win32 and carbon widgetsets. To enable the button code, see the comments above the ButtonOkay define in o32flxed.pas.

2. Widgetsets generally implement LCL controls by creating native controls that correspond to the LCL controls (text edit, check box, etc.). However, Orpheus builds its TOvcSimpleField control from TCustomControl, rather than descending from an existing edit control such as TCustomEdit. In general, TOvcSimpleField and TOvcTCSimpleField have not worked very well on non-Windows widgetsets.

3. The GTK widgetset does not support TOvcRotatedLabel, apparently because the GetTextMetrics function is not fully implemented on that widgetset.

4. The Carbon widgetset has a few minor limitations as of Lazarus 0.9.26 that affect some of the Orpheus controls. Setting the BorderStyle property does nothing with Carbon in custom controls such as TOvcVirtualListBox, TOvcCalendar and TOvcTable. Also, since the Carbon widgetset does not implement the bvLowered bevel style, changing the focus of a TOvcCalendar control does not change the look of the currently selected date as it should (the date remains bvRaised, which actually looks lowered with the Carbon widgetset).

5. Differences between Delphi VCL and Lazarus LCL affect some Orpheus controls. For example, VCL messages like CM_ENTER and CM_EXIT are not supported in the LCL. In a couple places, the ported code uses LM_SETFOCUS and LM_KILLFOCUS messages to obtain some functionality. Similarly, the lack of LCL support for the CM_CTL3DCHANGED message means that changing the Ctl3D property in Lazarus for controls such as TOvcCalendar may not update the control's design (reloading the form will show the correct design). Finally, some properties are True by default in Delphi but False in Lazarus, meaning forms converted from Delphi may not look quite the same for properties with default values until you explicitly set the properties in Lazarus or in your code.

### Status of Individual Controls

Control | VCL / LCL ancestor | Description | Issues / To-do | win32 | gtk | gtk2 | carbon | qt
--- | --- | --- | --- | --- | --- | --- | --- | ---
TOvcRotatedLabel | TGraphicControl | Rotated text | gtk widgetset doesn't support | Working | Not working | Partial | Working | Working
TOvcLabel | TGraphicControl | Fancy shading, color and highlighting | Property editor still needs work | Working | Working | Working | Working | Working
TOvcURL | TCustomLabel | Looks and acts like HTML hyperlink |  | Working | Working | Working | Working | Partial
TOvcSpinner | TCustomControl | Can associate with a TEdit; 8 different styles |  | Working | Working | Working | Working | Crashes
TOvcVirtualListBox | TCustomControl | Header row, variable width tabs, huge number of rows |  | Working | Working | Working | Working | Partial
TOvcCalendar | TCustomControl | Calendar control |  | Working | Working | Working | Working | Partial
TOvcSimpleField | TCustomControl | Edit control with validation |  | Working | Partial | Partial | Partial | Partial
TO32FlexEdit | TCustomEdit | Edit control with validation | gtk and qt used to work better | Working | Partial | Working | Working | Partial
TOvcTable | TCustomControl | Full-featured grid control | See "To Do" list; 0.9.26 didn't crash | Working | Crashes | Crashes | Partial | Freezes
TOvcTCColHead | TComponent | Table column headings |  | Working | Working | Working | Working | Working
TOvcTCRowHead | TComponent | Table row headings |  | Working | Working | Working | Working | Working
TOvcTCString | TComponent (edits with TEdit) | Table cell for editing strings |  | Working | Working | Working | Working | Partial
TOvcTCSimpleField | TComponent (edits with TOvcSimpleField) | Table cell for editing strings, with validation |  | Working | Partial | Partial | Partial | Partial
TOvcTCMemo | TComponent (edits with TMemo) | Table cell for editing memo text |  | Working | Working | Working | Working | Partial
TOvcTCCheckBox | TComponent (edits with TCustomControl) | Table cell for check box |  | Working | Working | Working | Working | Partial
TOvcTCComboBox | TComponent (edits with TComboBox) | Table cell for combo box | Dropdown problem w/o XP manifest | Working | Not working | Not working | Working | Partial
TOvcTCBitmap | TComponent | Table cell for displaying bitmap |  | Working | Working | Working | Not working | Partial
TOvcTCGlyph | TComponent | Table cell for cycling thru glyphs |  | Working? | Working? | Working? | ? | ?
TOvcTCIcon | TComponent | Table cell for displaying icon |  | Working? | Working? | Working? | ? | ?
TO32TCFlexEdit | TComponent (edits with TO32FlexEdit) | Table cell for editing strings, with validation |  | Working | Working | Working | Working | Partial
TOvcController | TComponent | Key-to-command translator | Property editor uses TTabSet | ? | ? | ? | ? | ?

Notes:
(1) "Working" means control is basically functional. "Partial" means control compiles, installs in IDE and displays at run-time, but doesn't function correctly. "Not working" means control compiles and installs in IDE but doesn't display correctly. "Widgetset doesn't support" means the widgetset currently does not provide the support needed for the control.
(2) TOvcSimpleField and TOvcTable require a TOvcController on form. However, TO32FlexEdit doesn't need TOvcController.

### To Do

- TOvcLabel
  - Figure out why TOvcColorComboBox controls in Style Manager property editor don't work on Windows.
  - Figure out why Color's default value (clNone) displays black background with GTK. Workaround for now is to set TOvcLabel's ParentColor to True in Object Inspector or select a different Color.
- TOvcVirtualListBox
  - Fix scrolling problems on Windows (not repainted right) and other platforms (scrolls too many with each click of arrow). <==Fixed in 0.2.0 release.
  - Figure out why double-click doesn't work on GTK. <==Fixed.
- TO32FlexEdit
  - Figure out why, on Windows, presence of XP manifest prevents setting Text. <==Appears to be fixed with 20070401 Lazarus.
  - Come up with workaround for LCL's lack of MakeObjectInstance for making callback function from method. Without this, control's validation is not performed. <==Workaround in 0.1.3 release fixes this on win32 widgetset. <==Partial workaround in 0.2.0 release for other widgetsets is to call SendMessage(TO32FlexEdit(Sender).Handle, OM_VALIDATE, 0, 0); in OnExit handler. See TestFlexEdit example.
  - Can't tab out of control on Windows with win32 widgetset (tabbing works with qt widgetset on Windows though). <==Fixed in 0.1.3 release.
- TOvcTable
  - Custom cursors not visible when sizing and moving columns and rows. Determine whether this is an LCL limitation. <==Recently fixed in Lazarus for Windows.
  - Sizing and moving columns and rows doesn't work at all with GTK or Carbon. Determine whether this is a GTK/Carbon limitation.
  - Table scroll bar "thumb" extends entire length of scrollbar with GTK. <==Fixed in 0.2.0 release.
  - Figure out how to move edit cell to stay with its row when scrolling table (non-Windows only).
  - Figure out why scrolling table with keyboard doesn't repaint table with Carbon. Possibly related to TestTable issue with Carbon where selecting a .bmp in the combo box cell doesn't display the bitmap in the next column until form is resized.
- TOvcTCComboBox
  - Figure out why, on Windows, won't drop down without presence of XP manifest.
- TO32TCFlexEdit
  - Need a way of setting OnValidationError handler (an apparent omission since TO32FlexEdit has it). <==Workaround in 0.2.0 release is to set TO32TCFlexEditEditor(Sender).OnValidationError in UserValidation handler.
- TOvcSimpleField and TOvcTCSimpleField
  - Recent improvements in GTK and Carbon widgetsets mean these controls no longer crash programs when they're used. However, they don't yet work as edit controls. Determine whether this means more improvement in widgetsets is needed. (Use TO32FlexEdit and TO32TCFlexExit in the meantime.)
- TOvcTCBitMap
  - This previously worked, but changes to Lazarus LCL now cause it to crash when cell gets focus (win32 only). <==Fixed in 0.2.0 release.
- TOvcController
  - Rewrite ovccmdp0.pas property editor to use TTabControl instead of TTabSet (not part of LCL).

### Other Resources

Status of Lazarus widgetsets:

http://wiki.lazarus.freepascal.org/Roadmap

OS X tips for Lazarus:

http://wiki.lazarus.freepascal.org/OS_X_Programming_Tips

Last updated: Sept. 21, 2009