Mac OS X Porting salframe
Work in progress... (don't hesitate to signal and correct errors)
This page is intended to describe the salframe API in the mac native port of OpenOffice. Salframe is the "window" part of vcl in OOo.
The SalFrame class is the native representation of windows. It corresponds to the Window class located in the general part of VCL (vcl/source/window/window.cxx, window2.cxx and window3.cxx). The window class is an abstract representation of windows which then calls the native salframe to manipulate native windows, doing things like creating the window, showing/hidding it, changing its title, its menu, handling events.... As the SalFrame class manipulates native objects (windows), it is purely virtual in the platform independent part of VCL: there is no implementation of it in vcl/source, but you can find its definition in vcl/inc/salframe.hxx. Its native implementations are called AquaSalFrame for native MacOS X, WinSalFrame for MS Windows, X11SalFrame for Unix systems, and GtkSalFrame for GTK implementation under unix systems.
In this article, we will concentrate on its MacOS X implementation but some explanations will still be valid for other implementations.
Properties of an AquaSalFrame
Firstly, we will see some properties of an AquaSalFrame:
CarbonWindowRef mrWindow; // Window handle AquaSalGraphics* mpGraphics; // current frame graphics AquaSalFrame* mpNextFrame; // pointer to next frame AquaSalFrame* mpParent; // pointer to parent frame void* mpInst; // instance handle for callback SystemEnvData maSysData; // system data long mnWidth; // client width in pixels long mnHeight; // client height in pixels int mnMinWidth; // min. client width in pixels int mnMinHeight; // min. client height in pixels int mnMaxWidth; // max. client width in pixels int mnMaxHeight; // max. client height in pixels Rect maFullScreenRect; // old window size when in FullScreen WindowAttributes maFullScreenAttr; // old window attributes when in FullScreen BOOL mbGraphics; // is Graphics used? BOOL mbFullScreen; // is Window in FullScreen? AquaSalInstance* mpSalInstance; TSMDocumentID maTsmDocumentId; SalExtTextInputEvent maInputEvent; // preedit text BOOL mbSheetDialog; //is the window a sheet dialog? (not yet committed)
mrWindow is a pointer to the "physical" aqua window. It is of Carbon type whereas almost all the other attributes are of primitive types (int, BOOL, ...) or VCL types (AquaSalFrame, AquaSalGraphics).
How does it works?
Now we will concentrate on how this class works: When a new "logical" window is created in the platform independent part of VCL, a new XXXXSalframe (where XXXX stands for Aqua, Win, X11 or Gtk) is created with some flags to know what type of window we should create. The XXXXSalframe constructor is called and then the CreateNewSystemWindow (void AquaSalFrame::CreateNewSystemWindow(CarbonWindowRef pParent, ULONG nSalFrameStyle)). This function creates the "physical" native window but don't shows it. The window will be visible when the AquaSalFrame::Show function will be called (void AquaSalFrame::Show(BOOL bVisible, BOOL bNoActivate)).
Creation of new windows
The CreateNewSystemWindow function creates the new "physical" window. Different types of windows with different attributes are created depending on the flags passed in parameters (ULONG nSalFrameStyle) of the function:
Types of windows:
- SAL_FRAME_STYLE_FLOAT (corresponds to the kFloatingWindowClass in Carbon): windows without decoration, for specific usages. Can have very different appearances.
- SAL_FRAME_STYLE_OWNERDRAWDECORATION (kToolbarWindowClass)
- SAL_FRAME_STYLE_TOOLTIP (kHelpWindowClass): Shows tooltips
- SAL_FRAME_STYLE_TOOLWINDOW (kFloatingWindowClass): utility windows like style, colors...
- SAL_FRAME_STYLE_DEFAULT (kDocumentWindowClass): main windows
- SAL_FRAME_STYLE_CHILD: Not implemented in the mac port.
- SAL_FRAME_STYLE_INTRO: window containing the splashscreen
In an experimental patch, i added new flags for dialog windows. Indeed, in native implementations of VCL, there's only one flag for dialog windows: SAL_FRAME_STYLE_DIALOG, altough in the platform independent part of VCL (see vcl/source/window/window.cxx and vcl/inc/wintypes.hxx) there are many different flags: WINDOW_DIALOG, WINDOW_TABDIALOG, WINDOW_MODALDIALOG, WINDOW_MODELESSDIALOG, WINDOW_MESSBOX, WINDOW_INFOBOX, WINDOW_WARNINGBOX, WINDOW_ERRORBOX, WINDOW_QUERYBOX. So i added new flags which correspond to these flags, to the native part of VCL. These new flags haven't been committed yet
- SAL_FRAME_STYLE_MESSBOX, SAL_FRAME_STYLE_QUERYBOX, SAL_FRAME_STYLE_INFOBOX, SAL_FRAME_STYLE_MODAL_DIALOG (kSheetWindowClass): Sheet dialogs
- For the other flags, a default window is created.
The parameter flag ULONG nSalFrameStyle of the CreateNewSystemWindow function has not only informations on the type of window to create, but also on some attributes.
- SAL_FRAME_STYLE_CLOSEABLE: the window has a close box
- SAL_FRAME_STYLE_SIZEABLE: the window has a resize grip on its bottom right corner, and can be resized
- SAL_FRAME_STYLE_MOVEABLE: not directly used in the macport.
The last step to create a new window is to register the event handlers, with the InstallAndRegisterEventHandler function.
Here's a list of all the events which are registered during the creation of the window:
- HandleTSMEvent (or HandleKeyboardEvent in older versions)
Role of Salframe
SalFrame abstracts any kind of system window.
What can and what cannot Salframe
static void ImplSalCalcFullScreenSize( const AquaSalFrame* pFrame, Rect* pSize )
Locale function which calculate the full active screen size. (Multi-Display is currently not yet implemented, that's why pframe not used here)
Take the Main Display ID from CoreVideo function (CGDirectDisplayID () ), and defines a CGRect named "rect" which size of this Display (usage of CGDisplayBounds(DisplayID)) to take the full positive size). Then, it stores these positive integers (use of static_cast<int> to have some signed integer) into psize, with origin on the top left.