Carbon interface internals

From Lazarus-ccr

Jump to: navigation, search

Deutsch (de) English (en) Français (fr)

Contents

[edit] Introduction

This page gives an overview of the LCL Carbon interface for Mac OS X and will help new developers.

For installation and creating a first Carbon application refer to Carbon Interface.

[edit] Other Interfaces

[edit] Platform specific Tips

[edit] Interfaces Development Articles

[edit] Documentation about Carbon

  • Free Pascal's Carbon API unit is FPCMacOSAll.pas in /usr/local/share/fpcsrc/packages/extra/univint.

[edit] Carbon interface development basics

  • Target Mac OS X version is 10.4
  • Avoid using obsolete or deprecated APIs and functions (e. g. QuickDraw vs. Quartz 2D)
  • Use object approach
  • Check Carbon calls result with OSError function
  • Assume UTF-8 encoded strings between LCL and Carbon widgetset (for future Lazarus Unicode support)

[edit] What is already working ?

Working components in the Carbon interface

[edit] What needs to be done next?

See Bug Tracker Carbon open issues

[edit] Carbon IDE Bugs

Item Note Dependencies Responsible
'...' buttons in dialogsNow they are too large I think
OK/CancelMany dialogs have non-Mac check-X glyphs
Menu barToo wide for 1024x768 display resolution
Lazarus menuHelp About and app prefs (Environment options) should be accessible here
MenusMany missing or non-standard menu shortcuts:

File New should be Cmd+N
File Save As should be Shift+Cmd+S
File Quit should be Cmd+Q
Search Find should be Cmd+F
Search Find Next should be Cmd+G
Search Find Previous should be Shift+Cmd+G
(Goto line and Procedure List need to be reassigned)
Option+Cmd+F does not bring up Search Results
F11 behaves weird!

See Bug Tracker Carbon IDE open issues

[edit] Implementation Details

[edit] Keyboard

  • Apple Command key is mapped to ssCtrl per Apple Guidelines
  • Apple Control key is mapped to ssMeta
  • Apple Option key is mapped to its inscription, i.e. ssAlt
  • Virtual key codes mapping is not reliable (depends on keyboard language layout!)

[edit] Application

  • Title: You cannot change it at runtime. You have to set it in Application Bundle.
  • OnDropFiles event is fired when file is dropped on application dock icon or opened via Finder if is associated. You have to enable this event in Application Bundle.

[edit] Drawing and measuring text precisely in parts

If you want to draw (via TextOut, TextRect) or measure (via TextWidth, TextHeight) text divided into various parts and rely it will be displayed same each time not depending on its division, you have to disable some default typographic features (like kerning, fractional positioning, ...) of Canvas. You can choose one of the following:

  • CarbonWidgetSet.SetTextFractional(Canvas, False); // from CarbonInt unit
  • TCarbonCustomControl(CustomControl.Handle).TextFractional := False; // from CarbonPrivate unit
  • TCarbonDeviceContext(Canvas.Handle)..TextFractional := False; // from CarbonCanvas unit

[edit] Screenshot taking

The only possible efficient way of taking a screenshot on Mac OS X is using OpenGL. Apple provides a demonstration function which returns a CGImageRef with the screenshot. This function was converted to Pascal and is available on the glgrab.pas unit on the carbon interface directory. This function requires the Apple-specific parts of the Apple OpenGL headers, and those aren't yet on the FPC Packages, so they were translated and are located on lazarus/lcl/interfaces/carbon/opengl.pas until they are released on a stable Free Pascal.

After obtaining a CGImageRef, the next step to implement the RawImage_fromDevice method is obtaining a local copy of it's pixel data. It isn't possible to directly access the bytes of a CGImageRef, so the image needs to be drawn to a CGContextRef which uses a memory area allocated by us as buffer. This method has the great advantage of converting from the internal format of the screenshot bytes to the very convenient ARGB, 32-bits depth, 8-bits per channel format that is default to LCL.

[edit] Compatibility issues

These are things that will probably never be solved.

[edit] Mouse.CursorPos changing does not generate mouse (move) events

[edit] Release mouse capture is not supported

[edit] Command line parameters

Because Carbon applications are executed via Application Bundle, command line parameters are not passed. You have to use OnDropFiles event to detect openning associated files.

[edit] Shortcuts indication is not supported

[edit] Drawing on Canvas outside OnPaint event is not supported

[edit] Drawing on screen device context is not supported

[edit] TCustomControl.Color of clBtnFace makes its background transparent

[edit] TWinControl.Font fsStrikeOut is not supported

[edit] TForm

  • Icon is not supported
  • ShowInTaskbar is not supported

[edit] TEdit.PasswordChar different then default is not supported

[edit] TMemo.WordWrap when is disabled, does not allow to scroll text horizontally

[edit] TListBox.Columns is not supported

[edit] TComboBox

  • OnDropDown is called when set focus
  • OnCloseUp is called when released focus
  • DroppedDown does not show drop down list when style is csDropDownList
  • DropDownCount is not supported
  • Style: csSimple, csOwnerDrawFixed and csOwnerDrawVariable are not supported

[edit] TPanel.Bevelxxx: bvLowered and bvSpace are not supported

[edit] TBitBtn.Spacing is not supported

[edit] TTrackBar

  • LineSize is not supported
  • ScalePos is not supported
  • TickMarks are not supported

[edit] TProgressBar

  • BarShowText is not supported
  • Smooth is not supported
  • Step is not supported

[edit] TColorDialog.Title is not supported

[edit] How to add a new control

For example TButton.

TButton is defined in lcl/buttons.pp. This is the platform independent part of the LCL, which is used by the normal LCL programmer.

Its widgetset class is in lcl/widgetset/wsbuttons.pp. This is the platform independent base for all widgetsets (carbon, gtk, win32, ...).

Its Carbon interface class is in lcl/interfaces/carbon/carbonwsbuttons.pp: 

 TCarbonWSButton = class(TWSButton)
 private
 protected
 public
   class function  CreateHandle(const AWinControl: TWinControl; const AParams: TCreateParams): TLCLIntfHandle; override;
 end;

Every WS class that actually implements something must be registered. See the initialization section at the end of the carbonwsXXX.pp unit: 

 RegisterWSComponent(TCustomButton, TCarbonWSButton);

TCarbonWSButton overrides CreateHandle to create a Carbon button helper class called TCarbonButton in carbonprivate.pp, which really creates the button control in the Carbon and installs event handlers.

Retrieved from "http://wiki.lazarus.freepascal.org/Carbon_interface_internals"