Accessing the Interfaces directly/de

From Free Pascal wiki

Deutsch (de) | English (en) | português (pt)

This page describes how to write access the underlying widgetset used by lazarus directly (zum Beispiel: das Windows API, oder GTK, oder Qt, etc). One should always try to avoid relying on widgetset specials. This document is here for both people improving the widgetsets and for people writing components that really need to access the widgets directly.


Every TWinControl has a Handle, and the LCL does not need to know, what a Handle is. The meaning of the Handle is totally up to the interface:

  • under GTK a Handle is often a PGtkWidget
  • under Windows a Handle is often a HWnd.
  • under Carbon a Handle is often a object descendant of TCarbonWidget.
  • under Qt, a Handle is often a pointer to a object descendent of TQtWidget.

Details pro Widgetset


Handles on Qt are mostly pointers to objects. Every time a control is created, a helper object is also created and both are connected. The helper object is necessary to receive events from Qt. After receiving a event it will send it to the LCL.

Most of those objects are descendents from TQtWidget as declared below:

 { TQtWidget }

 TQtWidget = class(TObject)
   Widget: QWidgetH;
   LCLObject: TWinControl;
   function  GetContainerWidget: QWidgetH; virtual;

Notice the two variables they all contain:

  • Widget - This is a connect to the Qt object for this Widget
  • LCLObject - Is a bridge with the LCL object it is linked to.

And also this method:

  • GetContrainerWidget() - When you wish to create a new widget and set it's parent, don't set it to Widget. Set it to GetContrainerWidget() instead. This happens because forms have 2 widgets. The main form widget, and also a container widget, where all child controls should be put to ensure that the size of the menu is handled automatically. Most other controls will have just one widget, but by using this function you avoid surprises in case the implementation of a control changes.


Handles on Carbon are very similar to Qt ones. The helper classes are descended from abstract class TCarbonWidget.

 { TCarbonWidget }

 TCarbonWidget = class(TObject)
   Widget: Pointer;
   LCLObject: TWinControl;

Notice the two variables they all contain:

  • Widget - This is a connect to the Carbon object for this Widget: ControlRef (TCarbonControl descendants) or WindowRef (TCarbonWindow descendants).
  • LCLObject - Is a bridge with the LCL object it is linked to.


Handles on Win32 or WinCE are almost always the same as their relative win api handles,For example handle of tmenu is HMENU,handle of TBrush is HBRUSH,so you can easily use them and pass them to windows apis.

List of Handles on various LCL classes


  • Win32, WinCE: HFONT
  • Qt: Ein TQtFont Objekt von qtprivate.pas
  • Carbon: Ein TCarbonFont Objekt von carbondef.pp


  • Win32, WinCE: HDC
  • Gtk: Ein TDeviceContext Objekt von gtkdef.pp
    • You can get a drawable, for example with: TDeviceContext(MyCanvas.Handle).Drawable
  • Qt: Ein TQtDeviceContext Objekt von qtprivate.pas
  • Carbon: Ein TCarbonDeviceContext Objekt von carbondef.pp
    • The native handle can be accessed with TCarbonDeviceContext(MyCanvas.Handle).CGContext of type CGContextRef


  • Win32, WinCE: HBRUSH
  • Qt: Ein TQtBrush Objekt von qtprivate.pas
  • Carbon: Ein TCarbonBrush Objekt von carbondef.pp


  • Win32, WinCE: HBITMAP
  • Gtk: PGDIObject (definiert in Unit GtkDef)
  • Qt: Ein TQtImage Objekt von qtobjects.pas unit
  • Carbon: Ein TCarbonBitmap Objekt von carbondef.pp

You can access this on Gtk using:

  GDIObject: PGDIObject;
  Bitmap: TBitmap;
  AImage: PGtkWidget;

  GDIObject := PgdiObject(Bitmap.Handle);

  AImage := gtk_image_new_from_pixmap(GDIObject^.GDIPixmapObject,


  gtk_container_add(GTK_CONTAINER(MyForm.Handle), AImage);


  • Win32, WinCE: it´s a HWND, a native window handle
  • Gtk: It´s a pointer to a structure.
  • Qt: The Handle is a pointer to a object from the TQtMainWindow class declared at qtwidgets.pas.
    • To have access to the QMainWindow Qt object it represents do: TQtMainWindow(Handle).Widget
    • To have access to the container widget of the form, do: TQtMainWindow(Handle).GetContrainerWidget
  • Carbon: TCarbonWindow from carbonprivate.pp

TMenu, TMainMenu, TMenuItem und TPopUpMenu

  • Win32, WinCE : HMENU
  • Qt: TMainMenu ist ein Zeiger auf ein TQtMenuBar Objekt. TPopUpMenu ist ein TQtMenu Objekt. TMenuItem can either be a TQtAction if it represents a clickable item or a separator or a TQtMenu if it is an item that has submenus.
  • Carbon: TMenuItem is a TCarbonMenu object, TMenu (TMainMenu and TPopupMenu) is represented by its root menu item