Mac OS X Porting - Proxy Icon implementation

From Apache OpenOffice Wiki
Jump to: navigation, search

Description: what is a "proxy icon ?

The little icon on the top border of the window :

Aqua proxy icon top window.jpg

The great idea, is to use this icon for drag and drop and other goodies.

In the Finder example below:

  • command-click, control-click or right-click the proxy icon, to present the path to the file

Aqua proxy icon.jpg

If from that menu you select any point in the path, then

  • Finder will come to foreground, with a window to that point.

Here are TextEdit examples:

  • without proxy icon (because document is not saved):

TextEdit noIcon.png

  • with proxy icon (because document was saved):

TextEdit withIcon.png


Implement the feature "proxy icon", in Aqua, on Mac OS X


Expected timeline: October / November 2008

The plan

The new feature will be in the proxyicon4mac cws

Concerned domains

Build :
  • framework
  • sfx2
  • vcl
  • offapi ?
  • (complete me)

Core :
  • framework
  • sfx2
  • vcl


User Interface :
  • new icon (accordingly to the screenshots on this page)
  • new behavior : files can be dragged using the Proxy Icon

Current status

Update: according to Andreas Schlüns (from Framework Project) answer on dev@framework mailing list, the change must be done in framework ( FIXME : framework or sfx2 ? )

Investigating ...


create a doxygen doc of the concerned classes, and start searching a new method/solution

Ideas : we can use .mm files, means objective C and better notifications (document saved, e.g. ) can become very usefull.

Code (works fine ), who builds and works in vcl already. The idea is to create an FSRef using FSMakeFSRefUnicode with the Bundle

    CFBundleRef	appBundle ;
    FSRef	 prefFolder ;

    OSStatus result = FSFindFolder(  kUserDomain,
                            &prefFolder) ;
    appBundle = CFBundleGetMainBundle();

    if ((result == noErr) && (appBundle != NULL))
        CFStringRef bundleID = (CFStringRef) CFBundleGetValueForInfoDictionaryKey
                                (appBundle, kCFBundleIdentifierKey);
        CFMutableStringRef	prefName = CFStringCreateMutableCopy(NULL, 0, bundleID);
        CFStringAppend(prefName, CFSTR(".plist")) ;
        CFIndex nameLength = CFStringGetLength(prefName) ;
        UniChar *buffer = new UniChar[sizeof(UniChar) * nameLength] ;
        CFStringGetCharacters (prefName, CFRangeMake(0, nameLength), buffer) ;
        CFRelease(prefName) ;
        FSRef	prefFile ;
        result = FSMakeFSRefUnicode (&prefFolder, nameLength, buffer, 0, &prefFile);
        delete [] buffer ;

After, just a quick look, the concerned code could be in vcl/aqua/source/window/salframe.cxx :

First idea: create AquaSalFrame::SetProxyIcon (WindowRef inWindow, FSRef * outRef )

We immediately see what we need is the path ( FSRef ) of the concerned file contained in the window, and the pointer on the Window (not a problem)

Other need: check whether the window is a document or not (help, preferences, dialog box .. and so on).

-> ask dev@ or dev@framework for the info

Maybe check whether void AquaSalFrame::SetIcon( USHORT nIcon ) or maybe void AquaSalFrame::SetTitle(const XubString& rTitle) can help

Probable algorithm :

  • Test if the Window is a document (not help or print or dialog box window) ?
    • No : do nothing
    • Yes: ( is a document ):
  • Has the document been already saved ?
    • never saved => do nothing
    • else => set the proxy icon

The probable right function to use is (copied from XCode documentation) :

HIWindowGetProxyFSRef Obtains the FSRef used to determine the proxy icon for a window.

OSStatus HIWindowGetProxyFSRef (
  WindowRef inWindow,
  FSRef * outRef

Parameters inWindow The window whose proxy FSRef is to be obtained.

outRef On exit, the FSRef for the window’s proxy icon.

Return Value A result code. See “Window Manager Result Codes”.

Discussion If the specified window’s proxy icon has been specified using HIWindowSetProxyFSRef or SetWindowProxyAlias, HIWindowGetProxyFSRef returns noErr and a valid FSRef for the window’s proxy icon. If the window has no proxy icon, or if the icon was specified by calling SetWindowProxyCreatorAndType or SetWindowProxyIcon, this function returns an error.

Availability Available in Mac OS X v10.4 and later. Declared In MacWindows.h

Other usefull stuff: in the Aqua File Picker Florian Heckl wrote, are a lot of usefull methods, and we could reuse them, mainly to find a path but not only

static OSStatus setWindowTitleAndProxyFromFSRef( WindowRef window, FSRef *fileRef )
    OSStatus err = noErr;
  HFSUniStr255 name;
  CFStringRef fileName = NULL;
  err = FSGetCatalogInfo( fileRef, 0, NULL, &name, NULL, NULL );
    require_noerr( err, CantGetInfo );
  fileName = CFStringCreateWithCharacters( kCFAllocatorDefault, name.unicode, name.length );
  SetWindowTitleWithCFString( window, fileName );
  HIWindowSetProxyFSRef( window, fileRef );
  SetWindowModified( window, false );

  if( fileName )
    CFRelease( fileName );
  return err;

Links (to be improved):

Handling Carbon Windows and Controls: Basic Window Manipulation: Adding Window Proxy Icons

Sample code (Carbon, can be obsolete)

Proxy Icon search on Apple lists

Google search of for alternative expressions "title bar proxy" or "titlebar proxy"

Apple Human Interface Guidelines: Window Elements "A standard document window may also have … A proxy icon (after a document has been saved)…"

People involved

Name OOo Nickname Role
Eric Bachard ericb2 Development, Documentation
xxxxx xxxxx QA
Graham Perrin grahamperrin User Experience, Documentation
Florian Heckl fheckl Documentation

Ericb 13:03, 30 August 2008 (CEST) 

Personal tools