/* File: MacApplication.h Contains: Application-level APIs Version: QuickTime 7.3 Copyright: (c) 2007 (c) 2000-2001 by Apple Computer, Inc., all rights reserved. Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef __MACAPPLICATION__ #define __MACAPPLICATION__ #ifndef __CGCONTEXT__ #include #endif #ifndef __QUICKDRAW__ #include #endif #ifndef __MENUS__ #include #endif #ifndef __HIOBJECT__ #include #endif #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #if PRAGMA_IMPORT #pragma import on #endif /* * Summary: * Controls the presentation of system-provided user interface * elements. * * Discussion: * Note that the system UI mode is a per-process state. Switching * from a process that is suppressing system UI to another process * that is not will cause system UI elements to become visible * automatically. Switching back to the first process will suppress * system UI elements again. */ enum { /* * In this mode, all standard system UI elements are visible. */ kUIModeNormal = 0, /* * In this mode, system UI elements which cover the "content area" of * the screen (the area other than the menubar) are hidden. However, * these elements may automatically show themselves in response to * mouse movements or other user activity; specifically, the Dock * will still show itself automatically when the mouse moves into the * Dock's auto-show region. */ kUIModeContentSuppressed = 1, /* * In this mode, system UI elements which cover the "content area" of * the screen (the area other than the menubar) are hidden. Unlike * kUIModeContentSuppressed, most UI elements will not automatically * show themselves in this mode. */ kUIModeContentHidden = 2, /* * In this mode, all system UI elements, including the menubar, are * hidden. Most system UI elements will not automatically show * themselves in this mode. The application may request that the * menubar automatically show itself while in this mode by passing * the kUIOptionAutoShowMenuBar flag to SetSystemUIMode. */ kUIModeAllHidden = 3 }; typedef UInt32 SystemUIMode; /* * Summary: * Controls optional behavior of system-provided user interface * elements. */ enum { /* * Requests that the menubar automatically show itself when the user * moves the mouse into the screen area that would ordinarily be * occupied by the menubar. Only valid with kUIModeAllHidden. */ kUIOptionAutoShowMenuBar = 1 << 0, /* * Disables all items in the Apple menu. Valid for all modes. */ kUIOptionDisableAppleMenu = 1 << 2, /* * The active application may not be changed while this process is * active. Currently disables the Command-Tab and Command-Shift-Tab * key sequences to switch the active process, and the global window * rotation key sequence selected by the user in the Keyboard * preference pane. SetFrontProcess may still be used to explicitly * switch the active process. Only valid with modes other than * kUIModeNormal. */ kUIOptionDisableProcessSwitch = 1 << 3, /* * The Force Quit window may not be displayed while this process is * active. Currently disables the Command-Option-Escape key sequence * to open the Force Quit window and the Force Quit menu item in the * Apple menu. Only valid with modes other than kUIModeNormal. */ kUIOptionDisableForceQuit = 1 << 4, /* * The current login session may not be terminated while this process * is active. Currently disables the Power key and the Restart, Shut * Down, and Log Out menu items in the Apple menu. Only valid with * modes other than kUIModeNormal. */ kUIOptionDisableSessionTerminate = 1 << 5 }; typedef OptionBits SystemUIOptions; /* * SetSystemUIMode() * * Summary: * Sets the presentation mode for system-provided user interface * elements. * * Discussion: * The presentation mode of an application determines which * system-provided user interface elements are visible on thes * screen. When the frontmost application changes its presentation * mode, a kEventAppSystemUIModeChanged Carbon event is sent to all * applications that have registered for the event. This event is * also sent when an application is activated; it contains the newly * active application's presentation mode. * * Parameters: * * inMode: * The new mode. * * inOptions: * Options controlling how the new mode behaves. * * Result: * An operating system result code. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later * Mac OS X: in version 10.2 and later */ EXTERN_API_C( OSStatus ) SetSystemUIMode( SystemUIMode inMode, SystemUIOptions inOptions); /* * GetSystemUIMode() * * Summary: * Returns the current presentation mode of the application. * * Parameters: * * outMode: * On exit, contains the current mode. You may pass NULL if you * don't need this information. * * outOptions: * On exit, contains the current options for the mode. You may * pass NULL if you don't need this information. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later * Mac OS X: in version 10.2 and later */ EXTERN_API_C( void ) GetSystemUIMode( SystemUIMode * outMode, /* can be NULL */ SystemUIOptions * outOptions); /* can be NULL */ /* * HIApplicationGetCurrent() * * Discussion: * Returns the HIObjectRef of the currently running application * object. This HIObject's EventTargetRef is what will be returned * from GetApplicationEventTarget. * * Result: * The HIObjectRef of the currently running application object. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.2 and later * Mac OS X: in version 10.2 and later */ EXTERN_API_C( HIObjectRef ) HIApplicationGetCurrent(void); /* * SetApplicationDockTileImage() * * Discussion: * Sets the image for the tile in the dock that represents your * application while it is running. If you set the image, it will * NOT revert back to its original image when your application * terminates. You need to manually restore it before quitting. * * Parameters: * * inImage: * The image you wish to have as your tile image. * * Result: * An operating system status code. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( OSStatus ) SetApplicationDockTileImage(CGImageRef inImage); /* * OverlayApplicationDockTileImage() * * Discussion: * Takes the image passed in and composites it on top of the current * image of your application's dock tile. You might do this to put a * standard badge over your application's icon to indicate something * to the user. * * Parameters: * * inImage: * The image you wish to overlay onto your tile image. * * Result: * An operating system status code. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( OSStatus ) OverlayApplicationDockTileImage(CGImageRef inImage); /* * RestoreApplicationDockTileImage() * * Discussion: * Restores the tile for your appliation in the dock to its normal * image (your application icon). You would use this if some overlay * or change of the application icon needed to be removed. * * Result: * An operating system status code. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( OSStatus ) RestoreApplicationDockTileImage(void); /* * BeginCGContextForApplicationDockTile() * * Discussion: * Creates and returns a CGContextRef. You can use this context to * draw into your application's dock tile with Quartz. You **MUST** * call EndCGContextForApplicationDockTile and NOT CGEndContext when * using this API, as it locks your application's tile in the dock. * If you call CGEndContext, the dock will never know you are done * with the tile. * * Result: * An Quartz (Core Graphics) context reference. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGContextRef ) BeginCGContextForApplicationDockTile(void); /* * EndCGContextForApplicationDockTile() * * Discussion: * Ends the CG context for your application tile and frees the lock * on the application dock tile. You **MUST** call this routine and * NOT CGEndContext when using BeginCGContextForApplicationDockTile, * as it locks your application's tile in the dock. If you call * CGEndContext, the dock will never know you are done with the tile. * * Parameters: * * inContext: * The context to end. The context is invalid after this call and * should no longer be used. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) EndCGContextForApplicationDockTile(CGContextRef inContext); /* * BeginQDContextForApplicationDockTile() * * Discussion: * Creates and returns a CGrafPtr for your application's tile in the * dock. You can use this port to draw into your application's dock * tile with Quickdraw. You **MUST** call * EndQDContextForApplicationDockTile and NOT DisposePort when using * this API, as it locks your application's tile in the dock. If you * call DisposePort, the dock will never know you are done with the * tile. * * Result: * A Quickdraw port reference. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGrafPtr ) BeginQDContextForApplicationDockTile(void); /* * EndQDContextForApplicationDockTile() * * Discussion: * Disposes the Quickdraw port for your application tile and frees * the lock on the application dock tile. You **MUST** call this * routine and NOT DisposePort when using * BeginQDContextForApplicationDockTile, else the dock will never * know you are done with the tile. * * Parameters: * * inContext: * The context to end. The context is invalid after this call and * should no longer be used. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) EndQDContextForApplicationDockTile(CGrafPtr inContext); /* * SetApplicationDockTileMenu() * * Summary: * Sets the menu that is displayed by the application's dock tile. * * Discussion: * The Carbon Window Manager and the Dock will always automatically * display a menu containing a list of the application's document * windows. If the application wants to add other additional menu * items, it can use the SetApplicationDockTileMenu API to provide * those items. The items in the specified menu will be combined * with the window title items. This API increments the refcount of * the specified menu. Before the menu is actually displayed, it * will receive kEventMenuPopulate, kEventMenuOpening, and * kEventMenuEnableItems Carbon events, so any event handlers for * these events may update the menu appropriately for the current * state of the application. The application should set a command ID * for each menu item in the dock tile menu, and when that item is * chosen, a kEventCommandProcess Carbon event containing the item's * command ID will be sent to the user focus target. * * Parameters: * * inMenu: * The menu to display, or NULL to remove the current dock tile * menu. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.1 and later * Mac OS X: in version 10.1 and later */ EXTERN_API_C( OSStatus ) SetApplicationDockTileMenu(MenuRef inMenu); /* * GetApplicationDockTileMenu() * * Summary: * Returns the menu that is displayed by the application's dock tile. * * Result: * The application's dock tile menu, or NULL if none. * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.1 and later * Mac OS X: in version 10.1 and later */ EXTERN_API_C( MenuRef ) GetApplicationDockTileMenu(void); /* * CreateCGImageFromPixMaps() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available in CarbonLib 1.x, is available on Mac OS X version 10.0 and later * Mac OS X: in version 10.0 and later */ EXTERN_API_C( OSStatus ) CreateCGImageFromPixMaps( PixMapHandle inImage, PixMapHandle inMask, CGImageRef * outImage); /* * GetApplicationTextEncoding() * * Summary: * Returns the application's primary text encoding. * * Discussion: * The application text encoding is used when you create a * CFStringRef from text stored in Resource Manager resources, which * typically uses one of the Mac encodings such as MacRoman or * MacJapanese. The encoding is determined by: (a) if your app is * bundled, the encoding of the .lproj directory chosen by CFBundle, * (b) else if your plist has a CFBundleDevelopmentRegionKey, the * encoding specified by that key, (c) else if your app has a 'vers' * resource, the encoding for the region field in the 'vers', (d) * else the current localization of the operating system. * * Availability: * Non-Carbon CFM: not available * CarbonLib: in CarbonLib 1.2 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( TextEncoding ) GetApplicationTextEncoding(void); /* * GetApplicationScript() * * Summary: * Returns the application script. * * Discussion: * The application script is used when you need a ScriptCode to pass * to some other API, such as UseThemeFont. * * Availability: * Non-Carbon CFM: not available * CarbonLib: in CarbonLib 1.3 and later * Mac OS X: in version 10.0 and later */ EXTERN_API( ScriptCode ) GetApplicationScript(void); #ifdef PRAGMA_IMPORT_OFF #pragma import off #elif PRAGMA_IMPORT #pragma import reset #endif #ifdef __cplusplus } #endif #endif /* __MACAPPLICATION__ */