TweetFollow Us on Twitter

MACINTOSH C
MACINTOSH C: A Hobbyist's Guide To Programming the Mac OS in C
Version 2.3

2000 K. J. Bricknell

Go to Contents

(Chapter 13)

OFFSCREEN GRAPHICS WORLDS, PICTURES, CURSORS, AND ICONS

A link to the associated demonstration program listing is at the bottom of this page



Offscreen Graphics Worlds

Introduction

An offscreen graphics world may be regarded as a virtual screen on which your application can draw a complex image without the user seeing the various steps your application takes before completing the image. The image in an offscreen graphics world is drawn into a part of memory not used by the video device. It therefore remains hidden from the user.

One of the key advantages of using an offscreen graphics ports is that it allows you to improve on-screen drawing speed and visual smoothness. For example, suppose your application draws multiple graphics objects in a window and then needs to update part of that window. If your image is very complex, your application can copy it from an offscreen graphics world to the screen faster than it can repeat all of the steps necessary to draw the image on-screen. At the same time, the inelegant visual effects associated with the time-consuming drawing a large number of separate objects are avoided.

Creating an Offscreen Graphics World

You create an offscreen graphics world with the NewGWorld function. NewGWorld creates a new offscreen colour graphics port, a new offscreen pixel map, and either a new GDevice structure or a link to an existing one. NewGWorld returns a pointer of type GWorldPtr which points to a colour graphics port:

     typedef CGrafPtr GWorldPtr;

When you use NewGWorld, you can specify a pixel depth, a boundary rectangle (which also becomes the port rectangle), a colour table, a GDevice structure, and option flags for memory allocation. Passing 0 as the pixel depth, the window's port rectangle as the offscreen world's boundary rectangle, NULL for both the colour table and the GDevice structure and 0 as the options flags:

  • Provides your application with the default behaviour of NewGWorld.

  • Allows QuickDraw to optimise the CopyBits, CopyMask, and CopyDeepMask functions used to copy the image into the window's port rectangle.

Setting the Colour Graphics Port for an Offscreen Graphics World

Before drawing into the offscreen graphics port, you should save the current colour graphics port and the current device's GDevice structure by calling GetGWorld. The offscreen graphics port should then be made the current port by a call to SetGWorld. After drawing into the offscreen graphics world, you should call SetGWorld to restore the saved colour graphics port as the current colour graphics port.

SetGWorld takes two parameters (port and gdh). If the port parameter is of type CGrafPtr, the current port is set to the port specified in the port parameter and the current device is set to the device specified in the gdh parameter. If the port parameter is of type GWorldPtr, the current port is set to the port specified in the port parameter, the gdh parameter is ignored, and the current device is set to the device attached to the offscreen graphics world.

Preparing to Draw Into an Offscreen Graphics World

After setting the offscreen graphics world as the current port, you should use the GetGWorldPixMap function to get a handle to the offscreen pixel map. This is required as the parameter in a call to the LockPixels function, which you must call before drawing to, or copying from, an offscreen graphics world.

LockPixels prevents the base address of an offscreen pixel image from being moved while you draw into it or copy from it. If the base address for an offscreen pixel image has not been purged by the Memory Manager, or if its base address is not purgeable, LockPixels returns true. If LockPixels returns false, your application should either call the UpdateGWorld function to reallocate the offscreen pixel image and then reconstruct it, or draw directly into an onscreen graphics port.

As a related matter, note that the baseAddr field of the PixMap structure for an offscreen graphics world contains a handle, whereas the baseAddr field for an onscreen pixel map contains a pointer. You must use the GetPixBaseAddr function to obtain a pointer to the PixMap structure for an offscreen graphics world.

Copying an Offscreen Image into a Window

After drawing the image in the offscreen graphics world, your application should call SetGWorld to restore the active window as the current graphics port.

The image is copied from the offscreen graphics world into the window using CopyBits (or, if masking is required, CopyMask or CopyDeepMask). Specify the offscreen graphics world as the source image for CopyBits and specify the window as its destination. Note that CopyBits, CopyMask and CopyDeepMask expect their source and destination parameters to be pointers to bit maps, not pixel maps. Accordingly, you must coerce the offscreen graphic's world's GWorldPtr data type to a data structure of type GrafPtr. Similarly, whenever a colour graphics port is your destination, you must coerce the window's CGrafPtr data type to data type GrafPtr.

As long as you are drawing into an offscreen graphics world or copying an image from it, you must leave its pixel image locked. When you are finished drawing into, and copying from, an offscreen graphics world, call UnlockPixels. Calling UnlockPixels will assist in preventing heap fragmentation.

Updating an Offscreen Graphics World

If, for example, you are using an offscreen graphics world to support the window updating process, you can use UpdateGWorld to carry certain changes affecting the window (for example, resizing, changes to the pixel depth of the screen, or modifications to the colour table) through to the offscreen graphics world. UpdateGWorld allows you to change the pixel depth, boundary rectangle, or colour table for an existing offscreen graphics world without recreating it and redrawing its contents.

Disposing of an Offscreen Graphics World

Call DisposeGWorld when your application no longer needs the offscreen graphics world.

Pictures

Introduction

QuickDraw provides a simple set of functions for recording a collection of its drawing commands and then playing the recording back later. Such a collection of drawing commands, as well as the resulting image, is called a picture. Pictures provide a common medium for the sharing of image data. They make it easier for your application to draw complex images defined in other applications, and vice versa.

When you use OpenCPicture to begin defining a picture, QuickDraw collects your subsequent drawing commands in a data structure of type Picture. By using DrawPicture, you can draw onscreen the picture defined by the instructions stored in the Picture structure.

Picture Format

The OpenCPicture function creates pictures in the extended version 2 format. This format permits your application to specify resolutions for pictures in colour or black-and-white.

Historical Note

During QuickDraw's evolution, three different formats evolved for the data contained in a Picture structure. The extended version 2 format is the latest format. The original format, the version 1 format, was created by the OpenPicture function on machines without Color QuickDraw or whenever the current graphics port was a basic graphics port. Pictures created in this format supported only black-and-white drawing operations at 72 dpi (dots per inch). The version 2 format was created by the OpenPicture function on machines with Color QuickDraw when the current graphics port was a colour graphics port. Pictures created in this format supported colour drawing operations at 72 dpi.

The Picture Structure

The Picture structure is as follows:

     struct Picture
     {
       short  picSize;   // For a version 1 picture: its size.
       Rect   picFrame;  // Bounding rectangle for the picture.
     };
     typedef struct Picture Picture;
     typedef Picture *PicPtr;
     typedef PicPtr *PicHandle;

Field Descriptions

picSize The information in this field is useful only for version 1 pictures, which cannot exceed 32 KB in size. Version 2 and extended version 2 pictures can be larger than 32 KB. To maintain compatibility with the version 1 picture format, the picSize field was not changed for version 2 or extended version 2 picture formats.

You should use the Memory Manager function GetHandleSize to determine the size of a picture in memory, the File Manager function PBGetFInfo to determine the size of a picture in a file of type 'PICT', and the Resource Manager function MaxSizeResource to determine the size of a picture in a resource of type 'PICT'.

picFrame Contains the bounding rectangle for the picture. DrawPicture uses this rectangle to scale the picture when you draw into a differently sized rectangle.
... Compact drawing commands and picture comments constitute the rest of the structure, which is of variable length.

Opcodes: Drawing Commands and Picture Comments

The variable length field in a Picture structure contains data in the form of opcodes, which are values that DrawPicture uses to determine what objects to draw or what mode to change for subsequent drawing.

In addition to compact drawing commands, opcodes can also specify picture comments, which are created using PicComment. A picture comment contains data or commands for special processing by output devices, such as PostScript printers. If your application requires capability beyond that provided by QuickDraw drawing functions, PicComment allows your application to pass data or commands direct to the output device.

You typically use QuickDraw commands when drawing to the screen and picture comments to include special drawing commands for printers only.

'PICT' Files, 'PICT' Resources, and 'PICT' Scrap Format

QuickDraw provides functions for creating and drawing pictures. File Manager and Resource Manager functions are used to read pictures from, and write pictures to, a disk. Scrap Manager functions are used to read pictures from, and write pictures to, the scrap.

See Chapter 18 - Scrap.

A picture can be stored as a 'PICT' resource in the resource fork of any file type. A picture can also be stored in the data fork of a file of type 'PICT'. The data fork of a 'PICT' file contains a 512-byte header that applications can use for their own purposes.

For each application, the Scrap Manager maintains a storage area to hold the last data cut or copied by the user. The area that is available to your application for this purpose is called the scrap. All applications that support copy-and-paste operations read data from, and write data to, the scrap. The 'PICT' scrap format is one of two standard scrap formats. (The other is 'TEXT'.)

The Picture Utilities

In addition to the QuickDraw functions for creating and drawing pictures, system software provides a group of functions called the Picture Utilities for examining the content of pictures. You typically use the Picture Utilities before displaying a picture.

The Picture utilities allow you to gather colour, comment, font, resolution, and other information about pictures. You might use the Picture Utilities, for example, to determine the 256 most-used colours in a picture, and then use the Palette Manager to make those colours available for the window in which the application needs to draw the picture.

Creating Pictures

As previously stated, you use the OpenCPicture function to begin defining a picture. OpenCPicture collects your subsequent drawing commands in a new Picture structure. To complete the collection of drawing (and picture comment) commands which define your picture, call ClosePicture.

You pass information to OpenCPicture in the form of an OpenCPicParams structure:

     struct OpenCPicParams
     {
       Rect   srcRect;    // Optimal bounding rectangle.
       Fixed  hRes;       // Best horizontal resolution.
       Fixed  vRes;       // Best vertical resolution.
       short  version;    // Set to -2.
       short  reserved1;  // (Reserved.  Set to 0.)
       long   reserved2;  // (Reserved.  Set to 0.)
     };
     typedef struct OpenCPicParams OpenCPicParams;

This structure provides a simple mechanism for specifying resolutions when creating images. For example, applications that create pictures from scanned images can specify resolutions higher than 72 dpi.

Clipping Region

You should always use ClipRect to specify a clipping region appropriate to your picture before calling OpenCPicture. If you do not specify a clipping region, OpenCPicture uses the clipping region specified in the current colour graphics port. If this region is very large (as it is when the graphics port is initialised, being set to the size of the coordinate plane by that initialisation) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture scales the clipping region, in which case your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when you draw it. Setting the clipping region equal to the port rectangle of the current graphics port always sets a valid clipping region.

Opening and Drawing Pictures

Using File Manager functions, your application can retrieve pictures saved in 'PICT' files. Using the GetPicture function, your application can retrieve pictures saved in the resource forks of other file types. Using the Scrap Manager function GetScrap, your application can retrieve pictures stored in the scrap.

The demonstration program at Chapter 16 - Files shows how to read pictures from, and save pictures to, files of type 'PICT'.

When the picture is retrieved, you should call DrawPicture to draw the picture. The second parameter taken by DrawPicture is the destination rectangle, which should be specified in coordinates local to the current graphics port. DrawPicture shrinks or stretches the picture as necessary to make it fit into this rectangle.

When you are finished using a picture stored as a 'PICT' resource, you should use the resource Manager function ReleaseResource to release its memory.

Saving Pictures

After creating or changing pictures, your application should allow the user to save them. To save a picture in a 'PICT' file, you should use the appropriate File Manager functions.2 (Remember that the first 512 bytes of a 'PICT' file are reserved for your application's own purposes.) To save pictures in a 'PICT' resource, you should use the appropriate Resource Manager functions. To place a picture in the Scrap (for example, to respond to the user choosing the Copy command to copy a picture to the clipboard), you should use the Scrap Manager function PutScrap.

Gathering Picture Information

GetPictInfo may be used to gather information about a single picture, and GetPixMapInfo may be used to gather colour information about a single pixel map or bit map. Each of these functions returns colour and resolution information in a PictInfo structure. A PictInfo structure can also contain information about the drawing objects, fonts, and comments in a picture.

Cursors

Introduction

A cursor is a 256-pixel image in a 16-by-16 pixel square usually defined in a black-and-white cursor ('CURS') or colour cursor ('crsr') resource.

Cursor Movement, Hot Spot, Visibility, and Shape

Cursor Movement

Whenever the user moves the mouse, the low-level interrupt-driven mouse functions move the cursor to a new location on the screen. Your application does not need to do anything to move the cursor.

Cursor Hot Spot

One point in the cursor's image is designated as the hot spot, which in turn points to a location on the screen. The hot spot is the part of the pointer that must be positioned over a screen object before mouse clicks can have an effect on that object. Fig 1 illustrates two cursors and their hot spot points. Note that the hot spot is a point, not a bit.

(Hot spots)

Cursor Visibility

In general, you should always make the cursor visible to your application, although there are a few cases where the cursor should not be visible. For example, in a text-editing application, the cursor should be made invisible, and the insertion point made to blink, when the user begins entering text. In such cases, the cursor should be made visible again only when the user moves the mouse.

Cursor Shape

Your application should change the shape of the cursor in the following circumstances:

  • To indicate that the user is over a certain area of the screen. For example, when the cursor is in the menu bar, it should usually have an arrow shape. When the user moves the cursor over a text document, your application should change the cursor to the I-beam shape.

  • To provide feedback about the status of the computer system. For example, if an operation will take a second or two, you should provide feedback to the user by changing the cursor to the wristwatch cursor (see Fig 2). If the operation takes several seconds and the user can do nothing in your application but stop the operation, wait until it is completed, or switch to another application, you should display an animated cursor (see below).

    If the operation takes longer than several seconds, you should display a dialog box with a progress indicator. (See Chapter 23 - Miscellany.)

Non-Animated Cursors

System 'CURS' and 'crsr' Resources

The System file in the System Folder contains an number of 'CURS' resources. The following constants represent the 'CURS' resource IDs for the basic cursors shown at Fig 2:

Constant Value Description
iBeamCursor 1 Used in text editing.
crossCursor 2 Often used for manipulating graphics.
plusCursor 3 Often used for selecting fields in an array.
watchCursor 4 Used when a short operation is in progress.

(Cursors)

The Mac OS 8.0 and later System file contains additional 'CURS' resources. The Mac OS 8.5 and later System file contains three 'crsr' resources. The following are the resource IDs for the additional cursors as shown as Fig 3:

Constant Value Description
- -20488 Contextual menu arrow cursor.
- -20487 Alias arrow cursor.
- -20486 Copy arrow cursor.
- -20452 Resize left cursor.
- -20451 Resize right cursor.
- -20450 Resize left/right cursor.
- -20877 Pointing hand cursor.
- -20876 Open hand pointer.
- -20875 Close hand pointer.

(More Cursors)

Custom 'CURS' and 'crsr' Resources

To create custom cursors, you need to define 'CURS' or 'crsr' resources in the resource file of your application.

Changing Cursor Shape

Your application is responsible for setting the initial appearance of the cursor and for changing the appearance of the cursor as appropriate for your application.

To change cursor shape, your application must get a handle to the relevant cursor (either a custom cursor or one of the system cursors shown at Fig 2 and 3) by specifying its resource ID in a call to GetCursor or GetCCursor. GetCursor returns a handle to a Cursor structure. GetCCursor returns a handle to a CCrsr structure. The address of the Cursor or CCrsr structure is then used in a call to SetCursor or SetCCursor to change the cursor shape.

Changing Cursor Shape Theme-Compliant Methodology

Mac OS 8.5 (or, more specifically, Appearance Manager Version 1.1) introduced a new function (SetThemeCursor) for setting the cursor to a version of the specified cursor type that is consistent with the current appearance. You must pass one of the following constants, which are of type ThemeCursor, in the inCursor parameter of SetThemeCursor:

Constant Value Comments
kThemeArrowCursor 0
kThemeCopyArrowCursor 1
kThemeAliasArrowCursor 2
kThemeContextualMenuArrowCursor 3
kThemeIBeamCursor 4
kThemeCrossCursor 5
kThemePlusCursor 6
kThemeWatchCursor 7 Can animate.
kThemeClosedHandCursor 8
kThemeOpenHandCursor 9
kThemePointingHandCursor 10
kThemeCountingUpHandCursor 11 Can animate.
kThemeCountingDownHandCursor 12 Can animate.
kThemeCountingUpAndDownHandCursor 13 Can animate.
kThemeSpinningCursor 14 Can animate.
kThemeResizeLeftCursor 15
kThemeResizeRightCursor 16
kThemeResizeLeftRightCursor 17

Changing Cursor Shape in Response to Mouse-Moved Events

Most applications set the cursor to the I-beam shape when the cursor is inside a text-editing area of a document, and they change the cursor to an arrow when the cursor is inside the scroll bars. Your application can achieve this effect by requesting that the Event Manager report mouse-moved events if the user moves the cursor out of a region you specify in the mouseRgn parameter to the WaitNextEvent function. Then, when a mouse-moved event is detected in your main event loop, you can use SetCursor, SetCCursor, or, for theme-compliant cursors, SetThemeCursor, to change the cursor to the appropriate shape

Note that your application may also have to accommodate the cursor shape changing requirements of modeless dialog boxes with edit text field items.as well as its main windows.

Changing Cursor Shape in Response to Resume Events

Your application also needs to set the cursor shape in response to resume events, normally by setting the arrow cursor.

Hiding Cursors

You can remove the cursor image from the screen using HideCursor. You can hide the cursor temporarily using ObscureCursor or you can hide the cursor in a given rectangle by using ShieldCursor. To display a hidden cursor, use ShowCursor. Note, however, that you do not need to explicitly show the cursor after your application uses ObscureCursor because the cursor automatically reappears when the user moves the mouse again.

Animated Cursors

Theme-Compliant Methodology

Mac OS 8.5 (or, more specifically, Appearance Manager Version 1.1) introduced a new function (SetThemeAnimatedCursor) for animating a version of the specified cursor type that is consistent with the current appearance. You must pass one of the following constants, which are of type ThemeCursor, in the inCursor parameter of SetThemeAnimatedCursor:

Constant Value
kThemeWatchCursor 7
kThemeCountingUpHandCursor 11
kThemeCountingDownHandCursor 12
kThemeCountingUpAndDownHandCursor 13
kThemeSpinningCursor 14

Non-Theme-Compliant Methodology

Non-theme-compliant animated cursors require: a series of 'CURS' (or 'crsr') resources that make up the "frames" of the animation; an 'acur' resource, which collects and orders the 'CURS' frames into a single animation, specifying the IDs of the resources and the sequence for displaying them in the animation.

System 'acur', and 'CURS' Resources

The Mac OS 8.0 and later System file contains an 'acur' resource (ID -6079), together the associated eight 'CURS' resources, for an animated watch cursor. It also contains eight 'CURS' resources (IDs -20701 to -20708) for an animated spinning (beach ball) cursor and six 'CURS' resources (IDs -20709 to -20714) for an animated counting hand cursor.

Custom 'acur' and 'CURS' Resources

Fig 4 shows the structure of a compiled 'acur' resource, and an 'acur' resource and one of its associated 'CURS' resources being created using Resorcerer.

(Creating 'acur' resource)

Creating the Animated Cursor

The following are the steps required to create the animated cursor::

  • If you do not intend to use the system-supplied 'acur' and associated 'CURS' resources:

    • Create a series of 'CURS' resources that make up the "frames" of the animation.

    • Create an 'acur' resource.

  • Load the 'acur' resource into an application-defined structure which replicates the structure of an 'acur' resource, for example:

         typedef struct
         {
           short       numberOfFrames;
           short       whichFrame;
           CursHandle  frame[];
         } animCurs, *animCursPtr, **animCursHandle;
    
    

  • Load the 'CURS' resources using GetCursor and assign handles to the resulting Cursor structures to the elements of the frame field.

  • At the desired interval, call SetCursor to display each cursor, that is, each "frame", in rapid succession, returning to the first frame after the last frame has been displayed.

Icons

Icons and the Finder

As stated at Chapter 9 - Finder Interface, the Finder uses icons to graphically represents objects, such as files and directories, on the desktop. Chapter 9 also introduced the subject of icon families, and stated that your application should provide the Finder with a family of specially designed icons for the application file itself and for each of the document types created by the application.

The provision of a family of icon types for each desktop object, rather than just one icon type, enables the Finder to automatically select the appropriate family member to display depending on the icon size specified by the user and the bit depth of the display device. Chapter 9 described the components of an icon family used by the Finder as follows:

Icon Size (Pixels) Resource in Which Defined
Large black-and-white icon, and mask 32 by 32 Icon list ('ICN#').
Small black-and-white icon, and mask 16 by 16 Small icon list ('ics#')
Mini black-and-white icon, and mask 12 by 16 Mini icon list ('icm#')
Large colour icon with 4 bits of colour data per pixel 32 by 32 Large 4-bit colour icon ('icl4')
Small colour icon with 4 bits of colour data per pixel 16 by 16 Small 4-bit colour icon ('ics4')
Mini colour icon with 4 bits of colour data per pixel 12 by 16 Mini 4-bit colour icon ('icm4')
Large colour icon with 8 bits of colour data per pixel 32 by 32 Large 8-bit colour icon ('icl8')
Small colour icon with 8 bits of colour data per pixel 16 by 16 Small 8-bit colour icon ('ics8')
Mini colour icon with 8 bits of colour data per pixel 12 by 16 Mini 8-bit colour icon ('icm8')

Creating Icon Family Resources Using Resorcerer

Fig 3 at Chapter 9 - Finder Interface shows icon families being created using Resorcerer.

The 'icns' Resource

The 'icns' resource contains all of the data for four icon sizes, thus providing a single source for icon data as opposed to the collection of icon resources ('ics#', 'icl4', 'icm8', etc.) described above. This speeds up icon fetching and simplifies resource management.

Historical Note

The 'icns' resource was introduced with Mac OS 8.5.

The four icon sizes are mini, small, large, and huge, the latter being a new size of 48 by 48 pixels. Four colour depths (1-bit, 4-bit, 8-bit, and 32-bit) and two kind of masks (1-bit and 8-bit) are supported. The deep (8 bit) mask means that masks can have 256 different levels of transparency.

Icon Services checks for an 'icns' resource of the specified ID before it checks for the older resource types ('ics#', 'icl4', 'icm8', etc.) of the same ID. If an 'icns' resource is found, Icon Services obtains all icon data exclusively from that resource.

As of Version 2.2, Resorcerer had no pixel editor for 'icns' resources. However, a command available in the Icon Family editor will take all icons currently being shown and build an 'icns' resource with the same resource ID as those icons. (Choose Build/Update 'icns' from the IconFamily menu.)

Other Icons - Icons, Colour Icons and Small Icons

Other icon types are the icon, colour icon, and small icon. Note that the Finder does not use or display these icon types.

Icon ('ICON')

The icon is defined in an 'ICON' resource, which contains a bit map for a 32-by-32 pixel black-and-white icon. Because it is always displayed on a white background, it does not need a mask.

Colour Icon ('cicn')

The colour icon is defined in a 'cicn' resource, which has a special format which includes a pixel map, a bit map, and a mask. You can use a 'cicn' resource to define a colour icon with a width and height between 8 and 256 pixels. You can also define the bit depth for a colour icon resource.

Small Icon ('SICN')

The small icon is defined in a 'SICN' resource. Small icons are 12 by 16 pixels even though they are stored in a resource as 16-by-16 pixel bitmaps. A 'SICN' resource consists of a list of 16-by-16 pixel bitmaps for black-and-white icons.

Typically, only the Finder and the Standard File Package use small icons.

Icons in Windows, Menus, and Alert and Dialog Boxes

The icons provided by your application for the Finder (or the default system-suppled icons used by the Finder if your application does not provide its own icons) are displayed on the desktop. Your application can also display icons in its menus, dialog boxes and windows.

Icons in Windows

You can display icons of any kind in your windows using the appropriate Icon Utilities functions.

Icons in Menus

The Menu Manager allows you to display icons of resource types 'ICON' (icon) 'cicn' (colour icon), and 'SICN' (small icon) in menu items. The procedure is as follows:

  • Create the icon resource with a resource ID between 257 and 511. Subtract 256 from the resource ID to get a value called the icon number. Specify the icon number in the Icon field of the menu item definition.

  • For an icon ('ICON'), specify 0x1D in the keyboard equivalent field of the menu item definition to indicate to the Menu Manager that the icon should be reduced to fit into a 16-by-16 pixel rectangle. Otherwise, specify a value of 0x00, or a value greater than 0x20, in the keyboard equivalent field to cause the Menu Manager to expand the item's rectangle so as to display the icon at its normal 32-by-32 pixel size. (A value greater than 0x20 in the keyboard equivalent field specifies the item's Command-key equivalent.)

  • For a colour icon ('cicn'), specify 0x00 or a value greater than 0x20 in the keyboard equivalent field. The Menu Manager automatically enlarges the enclosing rectangle of the menu item according to the rectangle specified in the 'cicn' resource. (Colour icons, unlike icons, can be any height or width between 8 and 64 pixels.)

  • For a small icon ('SICN'), specify 0x1E in the keyboard equivalent field. This indicates that the item has an icon defined by a 'SICN' resource. The Menu Manager plots the icon in a 16-by-16 pixel rectangle.
The Menu Manager will then automatically display the icon whenever you display the menu using the MenuSelect function. The Menu Manager first looks for a 'cicn' resource with the resource ID calculated from the icon number and displays that icon if it is found. If a 'cicn' resource is not found and the keyboard equivalent field specifies 0x1E, the Menu Manager looks for a 'SICN' resource with the calculated resource ID. Otherwise, the Menu Manager searches for an 'ICON' resource and plots it in either a 32-by-32 pixel rectangle or a 16-by-16 bit rectangle, depending on the value in the menu item's keyboard equivalent field.

Note that, for the Apple and Application menus, the Menu Manager either automatically reduces the icon to fit within the enclosing rectangle of the menu item or uses the appropriate icon from the application's icon family, such as the 'icl8' resource, if one is available.

Icons in Alert and Dialog Boxes

The Dialog Manager allows you to display icons of resource types 'ICON' (icon) and 'cicn' (colour icon) in alert and dialog boxes. You can display the icon alone or within an image well.

To display the icon alone, the procedure is to define an item of type Icon and provide the resource ID of the icon in the item list ('DITL') resource for the dialog. This will cause the Dialog Manager to automatically display the icon whenever you display the alert or dialog box using Dialog Manager functions.

To display the icon within an image well, include an image well control in the alert or dialog box's item list and assign the resource ID of the icon to the control's minimum value field.

If you provide a colour icon ('cicn') resource with the same resource ID as an icon ('ICON') resource, the Dialog Manager displays the colour icon instead of the black-and-white icon.

Ordinarily, you would use the Alert function (which does not automatically draw a system-supplied alert icon in the alert box), or the StandardAlert function with kAlertPlainAlert passed in the inAlertType parameter, when you wish to display an alert containing your own icon (for example, in your application's About... alert box). If you invoke an alert box using the NoteAlert, CautionAlert, or StopAlert functions, or with the StandardAlert function with an alert type constant of other than kAlertPlainAlert passed in the inAlertType parameter, the Dialog Manager draws the system-supplied black-and-white icon as well as your icon. Since your icon is drawn last, you can obscure the system-suppled icon by positioning your icon at the same coordinates.

Drawing and Manipulating Icons

The Icon Utilities allow your application (and the system software) to draw and manipulate icons of any standard resource type in windows and, subject to the limitations and requirements previously described, in menus and dialog boxes. You need to use Icon Utilities functions only if:

  • You wish to draw icons in your application's windows.

  • You wish to draw icons which are not recognised by the Menu Manager and the Dialog Manager in, respectively, menu items and dialog boxes.

Preamble - Icon Families, Suites, and Caches

Icon Families

You can define individual icons of resource types 'ICON', 'cicn', and 'SICN' that are not part of an icon family and use Icon Utilities functions to draw them as required. However, to display an icon effectively at a variety of sizes and bit depths, you should provide an icon family in the same way that you provide icon families for the Finder. The advantage of providing an icon family is that you can then leave it to functions such as PlotIconID, which are used to draw icons, to automatically determine which icon in the icon family is best suited to the specified destination rectangle and current display bit depth.

Each icon in an icon family shares the same resource ID as other icons in the family but has its own resource type identifying the icon data it contains.

Icon Suites

Some Icon Utilities functions take as a parameter a handle to an icon suite. An icon suite typically consists of one or more handles to icon resources from a single icon family which have been read into memory. The GetIconSuite function may be used to get a handle to an icon suite, which can then be passed to functions such as PlotIconSuite to draw that icon in the icon suite best suited to the destination rectangle and current display bit depth. An icon suite can contain handles to each of the six icon resources that an icon family can contain, or it can contain handles to only a subset of the icon resources in an icon family. For best results, an icon suite should always include a resource of type 'ICN#' in addition to any other large icons you provide and a resource of type 'ics#' in addition to any other small icons you provide.

When you create an icon suite from icon family resources, the associated resource file should remain open while you use Icon Utilities functions.

Icon Cache

An icon cache is like an icon suite except that it also contains a pointer to an application-defined icon getter function and a pointer to data that is associated with the icon suite. You can pass a handle to an icon cache to any of the Icon Utilities functions which accept a handle to an icon suite. An icon cache typically does not contain handles to the icon resources for all icon family members. Instead, if the icon cache does not contain an entry for a specific type of icon in an icon family, the Icon Utilities functions call your application's icon getter function to retrieve the data for that icon type.

Drawing an Icon Directly From a Resource

To draw an icon from an icon family without first creating an icon suite, use the PlotIconID function. PlotIconID determines, from the size of the specified destination rectangle and the current bit depth of the display device, which icon to draw. The icon drawn is as follows:

Destination Rectangle Size Icon Drawn
Width or height greater than or equal to 32. The 32-by-32 pixel icon with the appropriate bit depth.
Less than 32 by 32 pixels and greater than 16 pixels wide or 12 pixels high. The 16-by-16 pixel icon with the appropriate bit depth.
Height less than or equal to 12 pixels or width less than or equal to 16 pixels. The 12-by-16 pixel icon with the appropriate bit depth.

Icon Stretching and Shrinking

Depending on the size of the rectangle, PlotIconID may stretch or shrink the icon to fit. To draw icons without stretching them, PlotIconID requires that the destination rectangle have the same dimensions as one of the standard icons.

Icon Alignment and Transform

In addition to destination rectangle and resource ID parameters, PlotIconID takes alignment and transform parameters. Icon Utilities functions can automatically align an icon within its destination rectangle. (For example, an icon which is taller than it is wide can be aligned to either the right or left of its destination rectangle.) These functions can also transform the appearance of the icon in standard ways analogous to Finder states for icons.

Variables of type IconAlignmentType and IconTransformType should be declared and assigned values representing alignment and transform requirements. Constants, such as kAlignAbsoluteCenter and kTransformNone, are available to specify alignment and transform requirements.

Getting an Icon Suite and Drawing One of Its Icons

The GetIconSuite function, with the constant kSelectorAllAvailableData passed in the third parameter, is used to get all icons from an icon family with a specified resource ID and to collect the handles to the data for each icon into an icon suite. An icon from this suite may then be drawn using PlotIconSuite which, like PlotIconID, takes destination rectangle, alignment and transform parameters and stretches or shrinks the icon if necessary.

Drawing Specific Icons From an Icon Family

If you need to plot a specific icon from an icon family rather than use the Icon Utilities to automatically select a family member, you must first create an icon suite which contains only the icon of the desired resource type together with its corresponding mask. Constants such as kSelectorLarge4Bit (an icon selector mask for an 'icl4' icon) are used as the third parameter of the GetIconSuite call to retrieve the required family member. You can then use PlotIconSuite to plot the icon.

Drawing Icons That Are Not Part of an Icon Family

To draw icons of resource type 'ICON' and 'cicn' in menu items and dialog boxes, and icons of resource type 'SICN' in menu items, you use Menu Manager and Dialog Manager functions such as SetItemIcon and SetDialogItem.

To draw resources of resource type 'ICON', 'cicn', and 'SICN' in your application's windows, you use the following functions:

Resource Type Function to Get Icon Functions to Draw Icon
'ICON' GetIcon PlotIconHandle
PlotIcon
'cicn' GetCIcon PlotCIconHandle
PlotCIcon
'SICN' GetResource PlotSICNHandle

The functions in this list ending in Handle allow you to specify alignment and transforms for the icon.

Manipulating Icons

The GetIconFromSuite function may be used to get a handle to the pixel data for a specific icon from an icon suite. You can then use this handle to manipulate the icon data, for example, to alter its colour or add three-dimensional shading.

The Icon Utilities also include functions which allow you to perform an action on one or more icons in an icon suite and to perform hit testing on icons.



Main Constants, Data Types and Functions - Offscreen Graphics Worlds

Constants

Flags for GWorldFlags Parameter

pixPurgeBit         = 0   Set to make base address for offscreen pixel image purgeable.
noNewDeviceBit      = 1   Set to not create a new GDevice structure for offscreen world.
pixelsPurgeableBit  = 6   Set to make base address for pixel image purgeable.
pixelsLockedBit     = 7   Set to lock base address for offscreen pixel image.

Data Types

typedef CGrafPtr  GWorldPtr;
typedef unsigned long  GWorldFlags;

Functions

Creating, Altering, and Disposing of Offscreen Graphics Worlds

QDErr        NewGWorld(GWorldPtr *offscreenGWorld,short PixelDepth,
             const Rect *boundsRect,CTabHandle cTable,GDHandle aGDevice,
             GWorldFlags flags);
GWorldFlags  UpdateGWorld(GWorldPtr *offscreenGWorld,short pixelDepth,
             const Rect *boundsRect,CTabHandle cTable,GDHandle aGDevice,
             GWorldFlags flags);
void         DisposeGWorld(GWorldPtr offscreenGWorld);

Saving and Restoring Graphics Ports and Offscreen Graphics Worlds

void  GetGWorld(CGrafPtr *port,GDHandle *gdh);
void  SetGWorld(CGrafPtr port,GDHandle gdh);

Managing an Offscreen Graphics World's Pixel Image

PixMapHandle  GetGWorldPixMap(GWorldPtr offscreenGWorld);
Boolean       LockPixels(PixMapHandle pm);
void          UnlockPixels(PixMapHandle pm);
void          AllowPurgePixels(PixMapHandle pm);
void          NoPurgePixels(PixMapHandle pm);
GWorldFlags   GetPixelsState(PixMapHandle pm);
void          SetPixelsState(PixMapHandle pm,GWorldFlags state);
Ptr           GetPixBaseAddr(PixMapHandle pm);
Boolean       PixMap32Bit(PixMapHandle pmHandle);

Main Constants, Data Types and Functions - Pictures

Constants

Verbs for the GetPictInfo, GetPixMapInfo, and NewPictInfo calls

returnColorTable       = 0x0001   Return a ColorTable structure.
returnPalette          = 0x0002   Return a Palette structure.
recordComments         = 0x0004   Return comment information.
recordFontInfo         = 0x0008   Return font information.
suppressBlackAndWhite  = 0x0010   Do not include black and white.

Colour Pick Methods for the GetPictInfo, GetPixMapInfo, and NewPictInfo Calls

systemMethod   = 0   System color pick method.
popularMethod  = 1   Most popular set of colors.
medianMethod   = 2   A good average mix of colors.

Data Types

Picture

struct Picture
{
  short  picSize;  // For a version 1 picture: its size.
  Rect  picFrame;  // Bounding rectangle for the picture
};
typedef struct Picture Picture;
typedef Picture *PicPtr;
typedef PicPtr *PicHandle;

OpenCPicParams

struct OpenCPicParams
{
  Rect   srcRect;     // Optimal bounding rectangle.
  Fixed  hRes;        // Best horizontal resolution.
  Fixed  vRes;        // Best vertical resolution.
  short  version;     // Set to -2
  short  reserved1;   // (Reserved.  Set to 0.)
  long   reserved2;   // (Reserved.  Set to 0.)
};
typedef struct OpenCPicParams OpenCPicParams;

PictInfo

struct  PictInfo
{
  short          version;         // This is always zero, for now.
  long           uniqueColors;    // Number of actual colors in picture(s)/pixmap(s).
  PaletteHandle  thePalette;      // Handle to the palette information.
  CTabHandle     theColorTable;   // Handle to the color table.
  Fixed          hRes;            // Maximum horizontal resolution for all pixmaps.
  Fixed          vRes;            // Maximum vertical resolution for all pixmaps.
  short          depth;           // Maximum depth for all the pixmaps (in picture).
  Rect           sourceRect;      // Picture frame rectangle (contains entire picture).
  long           textCount;       // Total number of text strings in the picture.
  long           lineCount;       // Total number of lines in the picture.
  long           rectCount;       // Total number of rectangles in the picture.
  long           rRectCount;      // Total number of round rectangles in the picture.
  long           ovalCount;       // Total number of ovals in the picture.
  long           arcCount;        // Total number of arcs in the picture.
  long           polyCount;       // Total number of polygons in the picture.
  long           regionCount;     // Total number of regions in the picture.
  long           bitMapCount;     // Total number of bitmaps in the picture.
  long           pixMapCount;     // Total number of pixmaps in the picture.
  long           commentCount;    // Total number of comments in the picture.
  long           uniqueComments;  // The number of unique comments in the picture.
  CommentSpecHandle  commentHandle;   // Handle to all the comment information.
  long               uniqueFonts;     // The number of unique fonts in the picture.
  FontSpecHandle     fontHandle;      // Handle to the FontSpec information.
  Handle             fontNamesHandle; // Handle to the font names.
  long  reserved1;
  long  reserved2;
};
typedef struct PictInfo PictInfo;
typedef PictInfo *PictInfoPtr;
typedef PictInfoPtr *PictInfoHandle;

CommentSpec

struct CommentSpec
{
  short  count; // Number of occurrences of this comment ID.
  short  ID;    // ID for the comment in the picture.
};
typedef struct CommentSpec CommentSpec;
typedef CommentSpec *CommentSpecPtr;
typedef CommentSpecPtr *CommentSpecHandle;

FontSpec

struct FontSpec
{
  short  pictFontID;  // ID of the font in the picture.
  short  sysFontID;   // ID of the same font in the current system file.
  long   size[4];     // Bit array of all the sizes found (1..127) (bit 0 means > 127).
  short  style;       // Combined style of all occurrances of the font.
  long   nameOffset;  // Offset into the fontNamesHdl handle for the font's name.
};
typedef struct FontSpec FontSpec;
typedef FontSpec *FontSpecPtr;
typedef FontSpecPtr *FontSpecHandle;

Functions

Creating and Disposing of Pictures

PicHandle  OpenCPicture(const OpenCPicParams *newHeader);
void       PicComment(short kind,short dataSize,Handle dataHandle);
void       ClosePicture(void);
void       KillPicture(PicHandle myPicture);

Drawing Pictures

void       DrawPicture(PicHandle myPicture,const Rect *dstRect)
PicHandle  GetPicture(Integer picID);

Collecting Picture Information

OSErr  GetPictInfo(PicHandle thePictHandle,PictInfo *thePictInfo,short verb,
       short colorsRequested,short colorPickMethod,short version);
OSErr  GetPixMapInfo(PixMapHandle thePixMapHandle,PictInfo *thePictInfo,short verb,
       short colorsRequested,short colorPickMethod,short version);
OSErr  NewPictInfo(PictInfoID *thePictInfoID,short verb,short colorsRequested,
       short colorPickMethod,short version);
OSErr  RecordPictInfo(PictInfoID thePictInfoID,PicHandle thePictHandle);
OSErr  RecordPixMapInfo(PictInfoID thePictInfoID,PixMapHandle thePixMapHandle);
OSErr  RetrievePictInfo(PictInfoID thePictInfoID,PictInfo *thePictInfo,
       short colorsRequested);
OSErr  DisposPictInfo(PictInfoID thePictInfoID);

Main Constants, Data Types and Functions - Cursors

Constants

iBeamCursor  = 1
crossCursor  = 2
plusCursor   = 3
watchCursor  = 4

Data Types

Cursor

struct Cursor
{
  Bits16  data;
  Bits16  mask;
  Point   hotSpot;
};
typedef struct Cursor Cursor;
typedef Cursor *CursPtr;
typedef CursPtr *CursHandle;

CCrsr

struct CCrsr
{
  short         crsrType;     // Type of cursor.
  PixMapHandle  crsrMap;      // The cursor's pixmap.
  Handle        crsrData;     // Cursor's data.
  Handle        crsrXData;    // Expanded cursor data.
  short         crsrXValid;   // Depth of expanded data (0 if none).
  Handle        crsrXHandle;  // Future use.
  Bits16        crsr1Data;    // One-bit cursor.
  Bits16        crsrMask;     // Cursor's mask.
  Point         crsrHotSpot;  // Cursor's hotspot.
  long          crsrXTable;   // Private.
  long          crsrID;       // Private.
};
typedef struct CCrsr CCrsr;
typedef CCrsr *CCrsrPtr;
typedef CCrsrPtr *CCrsrHandle;

Acur

struct Acur 
{
  short  n;       // Number of cursors (frames).
  short  index;   // (Reserved.)
  short  frame1;  // 'CURS' resource ID for frame #1.
  short  fill1;   // (Recerved.)
  short  frame2;  // 'CURS' resource ID for frame #2.
  short  fill2;   // (Reserved.)
  short  frameN;  // 'CURS' resource ID for frame #n.
  short  fillN;   // (Reserved.)
};
typedef struct Acur acur, *acurPtr, **acurHandle;

Functions

Initialising Cursors

void  InitCursor(void);
void  InitCursorCtl(acurHandle newCursors);

Changing Black-and-White Cursors

CursHandle  GetCursor(short cursorID);
void        SetCursor(const Cursor *crsr);

Changing Colour Cursors

CCrsrHandle  GetCCursor(short crsrID);
void         SetCCursor(CCrsrHandle cCrsr);
void         AllocCursor(void)
void         DisposCCursor(CCrsrHandle cCrsr);
void         DisposeCCursor(CCrsrHandle cCrsr);

Hiding, Showing, and Animating Cursors

void    HideCursor(void);
void    ShowCursor(void);
void    ObscureCursor(void);
void    ShieldCursor(const Rect *shieldRect,Point offsetPt);
void    RotateCursor(long counter);
pascal  void SpinCursor(short increment);

Theme-Compliant Draw State Constants (For Primitives)

kThemeStateDisabled  = 0
kThemeStateActive    = 1
kThemeStatePressed   = 2

Appearance Manager Constants, Data Types and Functions - Cursors

Constants

kThemeArrowCursor                 = 0
kThemeCopyArrowCursor             = 1
kThemeAliasArrowCursor            = 2
kThemeContextualMenuArrowCursor   = 3
kThemeIBeamCursor                 = 4
kThemeCrossCursor                 = 5
kThemePlusCursor                  = 6
kThemeWatchCursor                 = 7   // Can animate
kThemeClosedHandCursor            = 8
kThemeOpenHandCursor              = 9
kThemePointingHandCursor          = 10
kThemeCountingUpHandCursor        = 11  // Can animate
kThemeCountingDownHandCursor      = 12  // Can animate
kThemeCountingUpAndDownHandCursor = 13  // Can animate
kThemeSpinningCursor              = 14  // Can animate
kThemeResizeLeftCursor            = 15
kThemeResizeRightCursor           = 16
kThemeResizeLeftRightCursor       = 17

Data Types

typedef UInt32 ThemeCursor;

Functions

OSStatus  SetThemeCursor(ThemeCursor inCursor);
OSStatus  SetAnimatedThemeCursor(ThemeCursor inCursor,UInt32 inAnimationStep);

Main Constants, Data Types and Functions - Icons

Constants

Types for Icon Families

kLarge1BitMask  = FOUR_CHAR_CODE('ICN#')
kLarge4BitData  = FOUR_CHAR_CODE('icl4')
kLarge8BitData  = FOUR_CHAR_CODE('icl8')
kSmall1BitMask  = FOUR_CHAR_CODE('ics#')
kSmall4BitData  = FOUR_CHAR_CODE('ics4')
kSmall8BitData  = FOUR_CHAR_CODE('ics8')
kMini1BitMask   = FOUR_CHAR_CODE('icm#')
kMini4BitData   = FOUR_CHAR_CODE('icm4')
kMini8BitData   = FOUR_CHAR_CODE('icm8')

IconAlignmentType Values

kAlignNone              = 0x00
kAlignVerticalCenter    = 0x01
kAlignTop               = 0x02
kAlignBottom            = 0x03
kAlignHorizontalCenter  = 0x04
kAlignAbsoluteCenter    = kAlignVerticalCenter | kAlignHorizontalCenter
kAlignCenterTop         = kAlignTop            | kAlignHorizontalCenter
kAlignCenterBottom      = kAlignBottom         | kAlignHorizontalCenter
kAlignLeft              = 0x08,
kAlignCenterLeft        = kAlignVerticalCenter | kAlignLeft
kAlignTopLeft           = kAlignTop            | kAlignLeft
kAlignBottomLeft        = kAlignBottom         | kAlignLeft
kAlignRight             = 0x0C,
kAlignCenterRight       = kAlignVerticalCenter | kAlignRight
kAlignTopRight          = kAlignTop            | kAlignRight
kAlignBottomRight       = kAlignBottom         | kAlignRight

IconTransformType Values

kTransformNone              = 0x00
kTransformDisabled          = 0x01
kTransformOffline           = 0x02
kTransformOpen              = 0x03
kTransformLabel1            = 0x0100
kTransformLabel2            = 0x0200
kTransformLabel3            = 0x0300
kTransformLabel4            = 0x0400
kTransformLabel5            = 0x0500
kTransformLabel6            = 0x0600
kTransformLabel7            = 0x0700
kTransformSelected          = 0x4000
kTransformSelectedDisabled  = kTransformSelected | kTransformDisabled
kTransformSelectedOffline   = kTransformSelected | kTransformOffline
kTransformSelectedOpen      = kTransformSelected | kTransformOpen

IconSelectorValue Masks

kSelectorLarge1Bit     = 0x00000001
kSelectorLarge4Bit     = 0x00000002
kSelectorLarge8Bit     = 0x00000004
kSelectorSmall1Bit     = 0x00000100
kSelectorSmall4Bit     = 0x00000200
kSelectorSmall8Bit     = 0x00000400
kSelectorMini1Bit      = 0x00010000
kSelectorMini4Bit      = 0x00020000
kSelectorMini8Bit      = 0x00040000
kSelectorAllLargeData  = 0x000000FF
kSelectorAllSmallData  = 0x0000FF00
kSelectorAllMiniData   = 0x00FF0000
kSelectorAll1BitData   = kSelectorLarge1Bit | kSelectorSmall1Bit | kSelectorMini1Bit
kSelectorAll4BitData   = kSelectorLarge4Bit | kSelectorSmall4Bit | kSelectorMini4Bit
kSelectorAll8BitData   = kSelectorLarge8Bit | kSelectorSmall8Bit | kSelectorMini8Bit
kSelectorAllAvailableData  = (long)0xFFFFFFFF

Data Types

typedef short   IconAlignmentType;
typedef short   IconTransformType;
typedef UInt32  IconSelectorValue;
typedef Handle  IconSuiteRef;
typedef Handle  IconCacheRef;

CIcon

struct CIcon 
{
  PixMap  iconPMap;         // Icon's pixMap.
  BitMap  iconMask;         // Icon's mask.
  BitMap  iconBMap;         // Icon's bitMap.
  Handle  iconData;         // Icon's data.
  short   iconMaskData[1];  // Icon's mask and BitMap data.
};
typedef struct CIcon CIcon;
typedef CIcon *CIconPtr;
typedef CIconPtr *CIconHandle;

Functions

Drawing Icons From Resources

OSErr  PlotIconID(constRect *theRect,IconAlignmentType align,
       IconTransformType transform,short theResID);
void   PlotIcon(const Rect *theRect,Handle theIcon);
OSErr  PlotIconHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theIcon);
void   PlotCIcon(const Rect *theRect,CIconHandle theIcon);
OSErr  PlotCIconHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,CIconHandle theIcon);
OSErr  PlotSICNHandle(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theSICN);

Getting Icons From Resources Which do Not Belong to an Icon Family

Handle       GetIcon(short iconID); 
CIconHandle  GetCIcon(short iconID);

Disposing of Icons

OSErr  DisposeCIcon(CIconHandle theIcon);

Creating an Icon Suite

OSErr  GetIconSuite(Handle *theIconSuite,short theResID,IconSelectorValue selector);;
OSErr  NewIconSuite(Handle *theIconSuite);
OSErr  AddIconToSuite(Handle theIconData,Handle theSuite,ResType theType);

Getting Icons From an Icon Suite

OSErr  GetIconFromSuite(Handle *theIconData,Handle theSuite,ResType theType);

Drawing Icons From an Icon Suite

OSErr  PlotIconSuite(const Rect *theRect,IconAlignmentType align,
      IconTransformType transform,Handle theIconSuite);

Performing Operations on Icons in an Icon Suite

OSErr  ForEachIconDo(handle theSuite,IconSelectorValue selector, IconActionUPP action,
       void *yourDataPtr);

Disposing of Icon Suites

OSErr  DisposeIconSuite(Handle theIconSuite,Boolean disposeData);

Converting an Icon Mask to a Region

OSErr  IconSuiteToRgn(RgnHandle theRgn,const Rect *iconRect,
       IconAlignmentType align,Handle theIconSuite);
OSErr  IconIDToRegion(RgnHandle theRgn,const Rect *iconRect,
       IconAlignmentType align,short iconID);

Determining Whether a Point or Rectangle is Within an Icon

Boolean  PtInIconSuite(Point testPt,const Rect *iconRect,IconAlignmentType align,
         Handle theIconSuite);
Boolean  PtInIconID(Point testPt,const Rect *iconRect,IconAlignmentType align,
         short iconID);
Boolean  RectInIconSuite(const Rect *testRect,const Rect *iconRect,
         IconAlignmentType align,Handle theIconSuite);
Boolean  RectInIconID(const Rect *testRect,const Rect *iconRect,IconAlignmentType align,
         short iconID);

Working With Icon Caches

OSErr  MakeIconCache(Handle *theHandle,IconGetterProcPtr makeIcon,void *yourDataPtr);
OSErr  LoadIconCache(const Rect *theRect,IconAlignmentType align,
       IconTransformType transform,Handle theIconCache);

Go to Demo

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Stacks 4.0.4 - New way to create pages i...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features Fluid Layout: Stacks lets you build pages... Read more
OmniFocus 3.4.6 - GTD task manager with...
OmniFocus is an organizer app. It uses projects to organize tasks naturally, and then add tags to organize across projects. Easily enter tasks when you’re on the go, and process them when you have... Read more
WiFiSpoof 3.4.8 - Change your WiFi MAC a...
WiFiSpoof quickly and easily allows you to change your WiFi MAC address via hot-key or the system menu bar. Version 3.4.8: Updated copyright "Change Address" button now more appropriately titled "... Read more
MarsEdit 4.3.6 - Quick and convenient bl...
MarsEdit is a blog editor for OS X that makes editing your blog like writing email, with spell-checking, drafts, multiple windows, and even AppleScript support. It works with with most blog services... Read more
Quicken 2019 5.14.0 - Complete personal...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more
Alfred 4.0.8 - Quick launcher for apps a...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more
coconutBattery 3.8.3 - Displays info abo...
With coconutBattery you're always aware of your current battery health. It shows you live information about your battery such as how often it was charged and how is the current maximum capacity in... Read more
BBEdit 13.0.4 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
Microsoft OneNote 16.33 - Free digital n...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Wireshark 3.2.1 - Network protocol analy...
Wireshark is one of the world's foremost network protocol analyzers, and is the standard in many parts of the industry. It is the continuation of a project that started in 1998. Hundreds of... Read more

Latest Forum Discussions

See All

Spiritwish's latest update sees the...
A sizeable update has hit Nexon's MMORPG Spiritwish today. It brings a new game mode, characters and there will also be a special event to celebrate the update with a firework display. [Read more] | Read more »
Maze Machina, a turn-based puzzler from...
The latest game from Arnold Rauers also known as Tiny Touch Tales is now available. You may be familiar with one of his many excellent titles such as Card Crawl, Enyo and Card Thief. His latest endeavour is called Maze Machina and you can grab it... | Read more »
Mario Kart Tour's Ice Tour races to...
Can you believe Mario Kart Tour is already on its 9th tour? The game only launched back in September, and since then it's become increasingly tricky to keep on top of the amount of new content Nintendo is pumping out. [Read more] | Read more »
Apple Arcade: Ranked - Top 50 [Updated 1...
In case you missed it, I am on a quest to rank every Apple Arcade game there is. [Read more] | Read more »
Marvel Future Fight's latest update...
Marvel Future Fight's latest update has added an all-new team of heroes to recruit and do battle with. The 'Warriors of the Sky' include Blue Dragon, War Tiger, Sun Bird, and Shadow Shell. As is the norm, each character comes with their own unique... | Read more »
Klee: Spacetime Cleaners is a fast-paced...
Klee: Spacetime Cleaners is a fast-paced auto-shooter that sports a cute retro aesthetic thathad racked up an impressive 100,000 pre-registers prior to its release. It's available now for both iOS and Android. [Read more] | Read more »
Hearthstone's latest solo adventure...
Blizzard has unveiled a plethora of details about its upcoming expansion for its popular card game Hearthstone. It's called Galakrond's Awakening and will bring the Year of the Dragon storyline to a close. It's available now for pre-purchase ahead... | Read more »
Cultist Simulator's Dancer DLC laun...
Cultist Simulator's Dancer DLC is set to launch for iOS and Android on January 22nd. It revolves around the occult cabaret known as the 'Ecdysis Club', where "the distinction between pleasure and pain is as delicate and essential as the human skin... | Read more »
Death Comes True releases a new characte...
Death Comes True is an FMV murder mystery from Kazutaka Kodaka, the creator of Danganronpa. It sees you playing as an amnesiac young man, called Makoto Karaki, who wakes up in a mysterious hotel to find that he's being hunted for a series of... | Read more »
Epic Seven introduces a new Hero and Art...
The popular MMO Epic Seven has received a new character who is available now in the game. But that's not all, it's also celebrating the start of 2020 by giving all players 1000 Skystone, so long as they play the game between today and 16th January... | Read more »

Price Scanner via MacPrices.net

Weekend Sale! 21″ iMacs for $150 off MSRP at...
Amazon has new 21″ iMacs on sale for $150 off Apple’s MSRP this weekend with prices starting at only $949. Be sure to select Amazon as the seller, rather than a third-party: – 21″ 2.3GHz iMac (... Read more
New Sprint offer: Lease one iPhone XS, get a...
Purchase an Apple iPhone XS at Sprint, and get a second 64GB iPhone XS for free. Requires 2 new lines or 1 upgrade-eligible line and 1 new line. Offer is valid from 1/10/20 to 2/13/20. The fine print... Read more
Price drop! Boost Mobile offers iPhone 7 mode...
Boost Mobile has dropped prices on 2017 Apple iPhone 7 models with phones now available starting at only $199, or $200 off MSRP: – 32GB iPhone 7: $199.99 – 128GB iPhone 7: $349.99 – 32GB iPhone 7... Read more
Looking for a deal on a 13″ MacBook Pro? Try...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
27″ 8-Core iMac Pro on sale today for $4599 a...
B&H Photo has the base 8-Core 3.2GHz 32GB/1TB iMac Pro on sale today for $4599 — $400 off Apple’s MSRP. Overnight shipping is free to many addresses in the US: – 8-Core 3.2GHz 32GB/1TB iMac Pro... Read more
Apple’s 21″ and 27″ iMacs are available for u...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Sale! Get a 10.2″ 32GB WiFi iPad on Walmart’s...
Walmart has new 2019 10.2″ 32GB WiFi iPads on sale for $50 off Apple’s MSRP, only $279. These are the same iPads sold by Apple in their retail and online stores, and be sure to select Walmart as the... Read more
Apple resellers offer 13″ 2.4GHz MacBook Pros...
Apple resellers have 13″ 2.4GHz MacBook Pros on sale today for $200 off Apple’s MSRP, and some are including free overnight delivery. Here are the best deals this week: (1) Amazon has new 2019 13″ 2.... Read more
Apple iPhone 11 models now available at Gazel...
Gazelle is now offering a range of discounted pre-owned unlocked Apple iPhone 11 models starting at $549. iPhones are offered in Fair, Good, and Excellent conditions, and multiple colors are... Read more
2-day iPhone sale: $100 off all Apple iPhones...
Boost Mobile is offering Apple’s new 2019 iPhone 11 and 11 Pro models for $100 off MSRP. Boost is also offering the same $100 discount on new previous-generation iPhone XS, XR, X, 8, and 7 models.... Read more

Jobs Board

*Apple* Mobile App Developer - eiWorkflow So...
…eiWorkflow Solutions, LLC is currently looking for a consultant for the following role. Apple Mobile App Developer Tasks the role will be performing: ? Mobile App Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747681BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000762-Tulsa Promenade-Store **Job Description:** Read more
QA Manager, *Apple* - ViacomCBS (United Sta...
…on over 15 platforms. This role will specifically be responsible for overseeing the Apple QA team, which consists of 3-5 people. This candidate will work with Read more
Geek Squad *Apple* Consultation Professiona...
**756220BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store NUmber or Department:** 000263-Columbia MD-Store Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747039BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000512-Melbourne Beach-Store **Job Description:** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.