Mac OS X Implementing HIView

Contributors

Eric Bachard[ericb]

Sébastien Plisson [plipli]

Introduction

[DRAFT] : means, not yet working, work in progress ...

HIObject is a common base class for all user interface objects and all menus, windows, controls, toolbars, and so on, are subclasses of HIObject.

HIView is an object-oriented view system subclassed from HIObject. All controls are implemented as HIView objects ("views"). You can easily subclass HIView classes, making it easy to implement custom controls. Over time the HIView API will replace the current Control Manager. See [HIView intro]

The main idea behind HIView is to superpose plans, to create any view, using compositing possibilities of Quartz Graphical Engine.

The final result is the superposition of all plans, following simple rules like :

- The last plan is always drawn on the previous one ;
- Some plans can  be declared visible, or not, very easely.

This page is part of [Native Controls Implementation] and the objective is to use HIView for HIComboboxes or other HI* controls.

Our objective is to bind vcl controls with HI* controls, from Carbon API.

e.g. : implement HICombobox as one control only.

The generic implementation, under tests (and not fully working), uses :

In progress :
- plipli : HIFramework integration : compiled, to be cleaned up before testing delivery to mac@porting ; - ericb/ismael : salnativewidget - create and bind native controls (HIViews) (ericb) and HIWindow (ismael);

Note : we "or"- ed kWindowCompositingAttribute in nWindowAttributes, to see compositing effects. [FIXME] : investigate, because use this attribute causes refresh issues

Reengineer Events handling (plipli)

Main files : salframe.cxx, salframe.h, aquavclevents.hxx

Description :

In OOo, the class SalFrame defines the object containing : - a window - other objects related to window management system

AquaSalFrame is the native implementation of VCL Salframe.

VCL / AQUA traces deductions (ericb)

1)

Technical principles

1) OO ask to VCL / native implementation code to draw controls (ie DrawNativeControl) or images or text

2) For controls, native implementation code create objects but do not draw them For images and text, native code draw objects to context (from QDBegin) or context from HiView event

3) When HIView events are received by event handler, especially kEventControlDraw, native code should draw controls to context given by the event

4) Native code call needsDisplay functions to tell Quartz which zone to update

Current code implementation

Events for HIView

Two sorts of events are needed:

• for objects (ClasskEventClassHIObject ) :

kEventHIObjectConstruct

kEventHIObjectInitialize

kEventHIObjectDestruct

• for controls themselves ( Class kEventClassControl ) :

kEventControlDraw 

kEventControlInitialize

kEventControlHitTest

kEventControlGetPartRegion

Current implementation : see vcl/aqua/aquavclevents.hxx for more informations about the syntax.

Install Event Handler

Now we have to install event Handler, inside AquaSalFrame::CreateNewSystemWindow() :

InstallEventHandler (
                           GetControlEventTarget (mhView),
                           NewEventHandlerUPP (HandleHIViewEvent),
                           GetEventTypeCount (cHIViewEvent),
                           cHIViewEvent,
                           (void*)mhView, // note the use of the pointer 
                           NULL
                           );

The HI* Event Handler

The Handler is OSStatus type, and is used when events are detected.

e.g. : we created HandleHIViewEvent()

using GetEventParameter, itself using the parameters described in Apple documentation.

Code sample :

OSStatus HandleHIViewEvent(EventHandlerCallRef inHandlerCallRef, EventRef inEvent, void* inUserData)
{ 
    //lock
    ImplSalYieldMutexAcquire();
    
    
    OSStatus status = noErr;
    
    // we use mrContext, global and seen from everywhere 
    CGContextRef mrContext; 
    
    // create HIRect, contianing the control bounds ( in local coordinates) 
    HIRect bounds;  

    status = GetEventParameter (inEvent, 
                                kEventParamCGContextRef, 
                                typeCGContextRef, 
                                NULL, 
                                sizeof (CGContextRef), 
                                NULL, 
                                &mrContext); 

    // not used, but usefull
    //require_noerr(status, CantGetGraphicsContext); // 2
    
   
    // We need to know the bounds containing the current control 
    HIViewGetBounds ((HIViewRef) inUserData, &bounds); 

    // not used, but usefull
    //require_noerr(status, CantGetBoundingRectangle);

    // unlock 
    ImplSalYieldMutexRelease();
    
    return status;  
} 

HIView use in AquaSalFrame::CreateNewSystemWindow()

Code sample :

   
    //  TEST HIVIew part 
    // Set mrContentView with HIView Content ViewRef
  
        HIRect myViewRect;
        myViewRect.origin.x = aContentRect.left; 
        myViewRect.origin.y = aContentRect.right; 
        myViewRect.size.width = aContentRect.right-aContentRect.left; 
        myViewRect.size.height = aContentRect.bottom-aContentRect.top; 
        OSStatus errval;
        errval = HIViewFindByID(HIViewGetRoot(mrWindow), kHIViewWindowContentID, &mrContentView); 

        // make the view visible                        
        HIViewSetVisible (mrContentView, true); 
        
        // set the frame
        HIViewSetFrame (mrContentView, &myViewRect);

        // Activate content view and children
        HIViewSetActivated (mrContentView,true);

Controls

[FIXME]

Example : HICombobox

-> code located in vcl/aqua/source/gdi/salnativewidgets.cxx , where all NWF are defined

1) declare CTRL_COMBOBOX control as "true" in isNativeControlSupported()

2) get the control region in getNativeControlRegion()

3) add CTRL_COMBOBOX case in drawNativeControl()

Code sample for the last part (Warning : not yet working !! ) :

 switch( nType )
    {
            
        case CTRL_COMBOBOX:
        if ( ( nPart==PART_BUTTON_DOWN) ||  (nPart==PART_SUB_EDIT) || (nPart==PART_ENTIRE_CONTROL) || (nPart==HAS_BACKGROUND_TEXTURE))

        .... (other code ) 

                    HIViewRef myCombo;
                                        
                    HIRect rc2;
                    
                    rc2.origin.x = rControlRegion.GetBoundRect().Left();
                    rc2.origin.y = rControlRegion.GetBoundRect().Top();
                    rc2.size.width = rControlRegion.GetBoundRect().GetWidth();
                    rc2.size.height = rControlRegion.GetBoundRect().GetHeight();
                    
                    HIComboBoxCreate ( &rc2 , NULL, NULL, NULL, kHIComboBoxStandardAttributes, &myCombo);
                    
                    HIViewSetVisible ( myCombo, true);
                    HIViewAddSubview (mrView, myCombo); 
                    
                    HIViewSetNeedsDisplay (myCombo, true);                   
                    
                    printf ("rc2.origin.x %.0f  \n rc2.origin.y %.0f \n rc2.size.width %.0f \n rc2.size.height %.0f \n", 
                    rc2.origin.x, rc2.origin.y, rc2.size.width , rc2.size.height );
                                        
                    //HIViewSetActivated (myCombo,true);

                     .....  (other code )

Usefull Links

References

[Introducing HIView]

OverView : [HIToolbox]

HIVIew : [reference] [or .pdf format]

[Upgrading to HIToolbox]

Code sample

Build a big toy with all controls included : All controls + code around

High Level Toolbox, HIServices Release Notes : HIToolbox