Percival Help File

Percival Help File

Copyright © 2007 Jay Reynolds Freeman, all rights reserved.
Personal Web Site:


Table of Contents:


Welcome to the help file for Percival, a special-purpose pixel-oriented image editor for the Apple Macintosh™. Percival was written by me, Jay Reynolds Freeman. By all means Email me about it if you wish.

Percival was named after one of my cats, "Percival", now deceased. (I regularly name programs that I write after my cats.)

"Percival" is also an annoyingly cute acronym: Pixel Editor for the Repair and Customization of Icons, when Vector Applications Lose.

Cute or not, that acronym describes Percival concisely. In a little more detail, Percival is a rather minimalist image editor that does just one specialized thing well enough that some people may find it useful: Percival allows pixel-by-pixel touch-up and minor alteration of images that are 128 by 128 pixels in size, or smaller. Images that are 128 by 128 pixels are a standard size used for Macintosh icons. Thus Macintosh developers may find occasional use for Percival.

In particular, Percival is NOT:

Percival is designed to work paw-in-glove with several applications that Apple provides with its "XCode" software package for developers, notably "Icon Composer" and "Pixie". "Icon Composer" can create icons out of many different kinds of images, though it provides no way to edit images. "Pixie" allows a magnified view of the pixels in any image, or anywhere on the Macintosh display. As I write these words, "Icon Composer" and "Pixie" are both part of the current version of XCode, which is XCode 2.4.1.

Note in particular that Percival does not actually create icon image files. The TIFF files that Percival writes are, however, suitable input for "Icon Composer", which does create icon image files.

Apple's "Preview" application is also a useful adjunct to Percival. Among the many features of "Preview" is the ability to read an image from a file that uses one image format and write that image to a file that uses a different image format. Thus in effect you can use "Preview" to change, for example, TIFF files into PNG files. As I write these words, "Preview" is bundled with OS X.

It would be possible to use Percival to create an entire icon from scratch, but anyone who does so must have way more free time than I do: Icons are almost certainly better prepared from images made with fancier software, or perhaps from images obtained with a camera. I expect Percival to be very useful for touching them up, though.

Percival has a "pour color" command that does what the "paint bucket" tool does on many other image editors. This capability may be useful for substantial modification of icons with large blocks of pixels that are all exactly the same color.

Percival is shareware: You are welcome to use Percival for free, forever, and to pass out free copies of it to anybody else. If you should at some time wish to make a shareware donation for Percival, use my PayPal&trade account or send a check by hard-copy mail to

Jay Reynolds Freeman
Post Office Box 60628
Palo Alto, CA, 94306-0628
U. S. A.

PayPal will need my EMail address:

How much to donate is your choice, and I certainly do not insist, request, or expect that you do so.

Getting Started:

System Requirements:

Percival is a stand-alone application for the Apple Macintosh&trade. It is Universal Binary&trade, and thus should run on any Macintosh with either an Intel microprocessor such as the Core Duo&trade, or one of the older PowerPC&trade microprocessors. Percival requires the Apple OS X operating system, version 10.4 or later. Its memory and disc requirements are minimal: The program occupies only a few hundred Kilobytes on disk, and can run usefully in several Megabytes of memory. (Percival uses lots of memory to save copies of the image you are working on for the "Undo" command.)

It is possible that Percival will run on versions of OS X that are earlier than 10.4; possibly as early as 10.2. Unfortunately, I have not tested the program with earlier versions of OS X.


A Percival installation comprises just the "Percival" application itself -- there are no extra files. The Percival distribution may contain some extra items, including a copy of this HTML file, a "README" file, and perhaps some interesting or useful examples of icons, but all you really need is the program. (By the way, in case you obtained this help file as a separate download, the "Percival Help" menu item, in Percival's "Help" menu, will call up this file from within the program -- you don't need a separate copy.)

"Installation" is simply the act of putting the application wherever you like. Possibly it should end up in your Applications folder, but that choice is up to you.

There is nothing to register, no activation codes required, and no enhanced versions available for a price. The shareware product, "Percival", is all there is.

You are welcome to make as many backup copies of Percival as you wish, and to give free copies of it to anyone.


Most people consider it ill-advised to run an unknown application -- like Percival -- without special precautions, because it might contain code to do something malicious. If I had deliberately written a malicious program, I certainly wouldn't tell you, at least, not until it was way too late. What's more, if you are a suspicious type -- and in today's Internet and computing environment, you should be! -- there is nothing I can do or say to convince you that I have not put some ill-intended code into Percival. Actually, I suppose it might help if I told you where I live, but I myself am a suspicious type, so I am not going to do that.

Besides, my house is a mess.

It might be useful to remember that Apple's OS X operating system is based on Unix: If you have moderate Unix experience, you might know that Unix is pretty good about keeping one user from messing with other users' data. Thus you might create a special, "dummy", user account, just for testing Percival, with access to nothing other than Percival and any images you may be using. If you know how to do that, good. If not, perhaps you should seek advice from a Unix-knowledgeable and trustworthy friend. (You shouldn't rely on me to provide the details; for all you know I am a computer criminal who might deliberately tell you something that didn't work and thereby set you up for disaster.)

Furthermore, one thing I worry about -- something every software developer worries about -- is that some third party will modify my code to be malicious, or create a malicious program with the same name and appearance as mine, and produce nefarious results thereby. I have no way to avoid this problem.

Starting Percival:

Just click on the Percival icon, and away you go. The easiest way to load an image file for editing is to drag the file to the small empty square area part way up the left side of the Percival window, the one with the label, "Drag an Image File Here".

Interacting With Percival:

Percival provides one main window, one button, a color well, and a small handful of menu items. There is one other general way of interacting with Percival that may be of particular use: Percival makes considerable use of "tooltips" -- the brief text descriptions that pop up when the cursor is positioned over particular areas of the screen. You can learn something about almost any visible feature of Percival by moving the cursor over it and waiting for the tooltip to appear.

The Percival Window:

Percival has only one window, and you can only edit one image at a time.

The Magnified Image Pane:

When Percival starts running, a large square pane, set somewhat right of center, fills most of the Percival window. That pane is where a four-times-enlarged view of the image you are editing will appear. Each pixel in the original image will appear as a four-by-four square of pixels in the enlarged image. That's almost too tiny to work with, but if the big image were much larger, it wouldn't all fit on the display of some Macintoshes.

The Normal-Size Image Pane:

There is also a much smaller square pane not quite half way up the left side of the Percival window, with the label "Drag an Image File Here". That smaller pane will hold a full-size view of the image you are editing, and as the label suggests, you can load an image for editing by dragging the image file into the smaller pane. (You can also load images by commands in the File Menu.)

The Miniature Image Panes:

When you load an image, copies of it will appear in both of the panes just mentioned. Furthermore, three additional images will appear in a horizontal row just above the full-sized image. One will be half-size, one will be quarter-size, and the last one will be one-eighth size. These images allow you to get a sense of what an icon will look like when the Macintosh operating system software resizes it. The panes for the miniaturized images will not be visible until you load an image.

Selecting Part Of An Image:

You edit the image in the Magnified Image Pane by selecting part of it and then doing something to what you have selected. The modifications will show up in all five differently-sized copies of the image.

There are two ways to select part of the image.

The Color Well:

The color well near the lower left corner of the Percival window works in the standard way, with one exception: The feature that allows you to drag a color to the place where it will be used, can only be used to fill the current selection with color. That is, no matter where in the big square you try to drag the color to, it will end up in the current selection. (If you try to drag the color to a place outside the big square, it won't go anywhere at all.) I set the color well up to work that way because the four-by-four squares that are used to represent pixels of the full-sized image are so small that it might otherwise be hard to tell where the color was going; the selection provides a well-defined and easily visible target.

You may also change colors in the image you are editing by using the "Pour Color" and "Set Color" items of the Edit Menu, discussed later herein.

The "Use Transparent Color" Button:

The button near the lower-left corner of the Percival window, labeled "Use Transparent Color", is a short-cut for setting the color in the color well to completely transparent. You could do the same thing by clicking on the color well to bring up a color panel, then fiddling around with the controls on the panel. The button just does it faster.

This button does not change anything in the image you are editing. It only changes the color in the color well.

Menu Items:

The Percival Menu:

The items in the Percival menu are pretty much Apple standards. Only two require special discussion for Percival:

By the way, Percival has no "Preferences" menu item: The program is so simple that I couldn't think of any preferences you might want to set.

The File Menu:

The File Menu items have to do with your interactions with Percival in the Percival window, and they are all quite conventional: "Open...", "Save", "Save As...", and "Revert" do pretty much what they do in most applications for the Macintosh, with pretty much the usual warnings if you are about to lose work or overwrite an existing file.

Two things deserve special mention:

The Edit Menu:

The Edit Menu contains a few fairly standard items, and a few which are less conventional. None of the items in the Edit Menu will work until you have loaded an image. Until then, there is nothing to be edited.

The Window Menu:

The Window Menu contains only fairly standard Macintosh menu items.

The Help Menu:

The one item in the Help Menu opens up an HTML help file which probably looks suspiciously like the one you are now reading ...

Tips and Hints:


What's New:

This section describes what is new in Percival since the previous release. I omit cosmetic improvements, minor changes in documentation and minor changes in displays.

Items are listed in more or less the order in which I dealt with them.

Since this is the first release, it's all new!

What Used to be New:

This section describes changes in Percival between its first release and the last one before what is now current. I omit cosmetic improvements, minor changes in documentation and minor changes in displays.

Items are listed in more or less the order in which I dealt with them.

Since this is the first release, there isn't anything that used to be new; it's all new!

What Might be New in the Future:

Besides fixing bugs and making internal improvements, my wish list for the future of Percival includes the following items, which are not necessarily in the order in which I might get around to doing them:

The future probably does not hold:

Miscellaneous Information:

I wrote Percival because I needed it, and stopped adding functionality when it would do what I wanted to do. Improvements and enhancements will likely also be things for which I have a use.

I have only written three or four stand-alone Macintosh applications, and Percival is the first one that allows editing images. Notwithstanding, it came up and ran in usefully in less than three days, by which I mean that three days after start of project I was able to perform the icon-editing task which had inspired me to write Percival in the first place. That speaks very well of the quality of Apple's "XCode" development environment. (The last stand-alone Macintosh application that I completed before Percival was an implementation of the Scheme Programming language called "Wraith Scheme" -- see my website for details -- that I have been fussing with off and on for twenty years, so my track record for average development speed is probably still a bit below average.)

It took about another week to polish things up and take care of the details well enough for Percival to be released as shareware. I could have added more features -- there seems to be no end to the list of possible features for an image editor -- but I have seen far too many software development projects succumb to one or another of the disastrous consequences of creeping featurism, so I decided to stop right there and release Percival 1.0. The first release has a rather minimal feature set, but it does a more than sufficient job at what I wanted it to do, so I hope others will find it useful.

Percival is written as a "Cocoa" application in a mixture of Objective C and C++, with a user interface developed with Apple's "Interface Builder" application. The program makes as much use as I could manage of Apple's enormous, Byzantine, and very useful, class library. Percival contains about 1500 lines of code.



The following excuses may help explain flaws or omissions in Percival:

Infrequently Asked Questions:

Thanks To:

-- Jay Reynolds Freeman, February, 2007