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.

Introduction

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 (still buggy in the aqua port)

• SAL_FRAME_STYLE_TOOLWINDOW (kFloatingWindowClass): utility windows like style, colors... (experimental code so not yet committed)

• 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.

Window attributes:

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.

Role of Salframe

SalFrame abstracts any kind of system window.

Functions

• ImplSalCalcFullScreenSize

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.