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

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.