++Builder provides an icon for console-mode applications. It’s a nice icon (see Figure A), but at first glance it looks too much like the C++Builder icon. I can’t count the number of times I’ve accidentally clicked on the wrong icon in the Taskbar. Another problem is that if you have two or more console-mode applications running at the same time, they all use the same default icon.

Figure A The default console-mode icon.

This article provides a tutorial on customizing the icons of console-mode applications. In addition, I talk about creating transparent pixels in a customized icon and creating 16×16-pixel icons using the Borland Image Editor. 

 

What to do

If you’ve done any significant Windows or VCL programming using C++Builder, you probably know about the “Load Icon” button on the Applications panel on the project options screen. Unfortunately, for console-mode applications, that button is grayed out.

To change the icon for a console-mode application, first load its resource file into Image Editor, make the changes and then save the modified resource file. The new icon will be incorporated into the executable after the resource file has been re-added to the project or the Borland C++Builder IDE has been restarted. 

 

Where to start

Let's say your console-mode application is called ConsoleApp. The first step is to open the Project Manager view as shown in Figure B.

Figure B A typical console-mode application contains a resource file (.res), a Borland Project File (.bpf) and, of course, the C++ source file.

        By default, the resource file is located in the same directory as your console-mode application. For the ConsoleApp project in Figure B, the resource file you need to open is called ConsoleApp.RES. Open the resource file using Borland’s Image Editor.

 

3-2-1… Launch the Image Editor

There are two places where you can find Image Editor:

 

1.       In the Borland C++Builder 6 program menu (via “Start | Programs | Borland C++Builder 6 | Image Editor”).

2.       In the C++Builder IDE; choose the “Tools” menu and then choose “Image Editor”.

 

Open the resource file

In Image Editor, select “File | Open” and then navigate to the .RES file for your console-mode application.

 

Open the icon

In a default console-mode application’s resource file, the icon in the resource file is called MAINICON. To open the MAINICON icon, expand the Icon tree branch and double-click on MAINICON(see Figure C).

Figure C The icon editing window contains a pixel editor on the left side and a full-size icon on the right side. Transparent pixels (the blue-green pixels) surround the buildings.

The double-click will open the icon editing window (Figure D) in Image Editor. The icon editing window has two parts: a pixel editor in the left-hand panel and a full-size icon in the right-hand panel. The default console-mode icon is a 32×32 pixel, 16-color icon.

Figure D A default console-mode application resource file contains an icon called MAINICON.

 

Opening your inner artist

The vertical toolbar on the left side of Image Editor’s main window contains all of your graphics-editing tools. Even though Image Editor doesn’t have all of the features of a high-priced graphics-editing application, you can still make some pretty amazing icons easily and quickly.

 

Icon basics

Every pixel in an icon can either be colored or it can be transparent. Image Editor displays transparent pixels using a dark teal (blue-green) color. In the default Borland-supplied icon, the pixels surrounding the buildings are all transparent pixels.

 

Bulk erase

If you’re like me and you like starting with a blank slate, the first thing you’ll want to do is delete all of the colored pixels. As a novice, I clicked on the eraser tool and started erasing colored pixels. This was painfully slow because it changed only one pixel at a time.

        Next, I tried the Eye Dropper tool and clicked on one of the transparent pixels. I then used the Fill tool (it looks like a pouring paint bucket) to erase large sections of the same color. This was better than using the Eraser tool but it still left lots of scattered pixels of different colors.

        Finally, I tried the Brush tool. That was what I needed. Because I had previously picked a transparent pixel with the Eye Dropper tool, I was able to use the Brush tool to quickly erase large sections of the palette.

        Later, I discovered I could left-click on the red “S” near the color palette (Figure E). This is the same as picking a transparent pixel using the Eye Dropper tool and it’s handy if the icon doesn’t have any transparent pixels.

Figure E Click on the red swooping “S” in the color palette to create transparent pixels in the pixel editor.

 

Saving

When you're done customizing your icon, you'll notice on the “File” menu that the “Save” and “Save As” menu choices are grayed-out. To save the icon, you first need to click on the resource window (Figure C); you'll then be able to save the icon (and the resource file).

 

Seeing your icon

If you go back to C++Builder and then build and execute your application, you'll be disappointed to see the old icon. Even if you force the application to build, you'll still see the old icon! The linker apparently caches the .RES file. There are two ways to force a changed resource file to be incorporated into an executable:

 

1.       Remove the resource file from the project and then add it back again.

2.       Close the Borland IDE and launch it again.

 

Creating 16x16-pixel icons

The Windows Taskbar and the application’s title bar typically use 16×16-pixel icons. If the only icon available is a 32×32-pixel icon, Windows will shrink its size to 16×16 pixels. Sometimes the 32×32-pixel icon doesn't render well when it's shrunk to 16×16. Likewise, if the resource file defines only a 16x16-pixel icon, it might have a “jagged” (aliased) look when it’s rendered as a 32×32-pixel icon. It’s therefore a good idea to include both 16×16-pixel and 32×32-pixel icons in your resource file.

On the icon editing window in Image Editor (shown in Figure D), click on the “New” button to add a 16×16-pixel icon to the resource. The Icon Properties window will appear.

Choose the 16×16 (small icon) size and then click “OK.” A new, empty 16×16-pixel icon is displayed in the icon editing window. You can easily switch back and forth between the icons by clicking on the combo box in the icon editing window (see Figure D).

Installing a resource file (.RES) that contains a 16×16-pixel icon is the same as installing it with a 32×32-pixel icon:

 

1.       Save the resource file.

2.       Remove the resource file from the project.

3.       Add it back into the project.

4.       Build or make the application.

 

Making it easier

After you’ve erased all of the pixels from an icon, save the resource file in an easy-to-find location (I chose the icons/ directory in the C++Builder root directory).

        The next time you need to customize an icon, launch Image Editor and open the empty resource file that you previously saved. You can safely overwrite the .RES file in your project but you’ll still need to use the remove/add trick to make the linker realize that the .RES file has been changed.

 

Conclusion

Custom icons help to differentiate your console-mode applications at runtime and when they are picked from Windows Explorer. Creating a custom icon is easy. When you’re ready to distribute your executable, the Borland C++ compiler incorporates the icon resource into the executable so you don’t need to provide any other files.

 

Contact Curtis at curtis@decompile.com.

 

 colleague at my office and I were working on a project recently that entailed processing groups of files. Each small group of files was handled the same way, namely, dragging the file-names from a directory window to the window that did the processing. He said “Golly, if I know what files I want the program to work on ahead of time, why can’t I just tell the program what I want it to do when it starts? Why do I have to load the GUI (Graphical User Interface) each time?” Good question indeed. What he was really asking about was the traditional user command line interface. This allows a user to pass parameters to a program as the program begins.

        In the pre-Windows days, command lines were routinely used at the console. Computer users used to type something like

 

myprogram param1 param2

 

in a command console window (which used to be the entire screen!) in order to start the program “myprogram.exe” with the two parameters “param1” and “param2.” 

        In the Windows of today, users simply use the mouse to select icons which launch the desired programs. Often, they then need to type additional information in the window or click buttons in the window. However, even Windows retains, in an elegant fashion, the traditional command line which passes information to a program as it starts. Command lines continue to be useful, even in a windowed environment.

 

The basics of argc and argv

In C and in C++, the start of a program is a function called main() with a prototype of

 

int main ( int argc, char *argv[] )

 

which returns an integer to the operating system when the program ends. The first parameter, argc, is the count of the number of parameters passed to the program. The second parameter, argv, is an array of null-terminated strings which denote the command-line literals. The number of strings (the dimension of argv[]) is argc. The first string, argv[0], is the full path-name to the called function.

        For the earlier example, argc would be three, and we would have something like:

 

argv[0] = "C:\MYPROGRAM"

argv[1] = "param1"

argv[2] = "param2"

 

The scope of the values argc and argv is only inside of the main() function:

 

int main ( int argc, char *argv[] )

{

  // argc and *argv[] scope only in here

}

 

If you try to use argc and argv outside of main(), a compile-time error will result.

 

Builder’s version of the command line

With the exception of a pure console application, the days of main() are long gone. Builder developers seldom see a main() function. However, the command line parameters are still there—they have simply evolved. Their new names are _argc and _argv (see also [1]).

        These names are the same as before with the addition of leading underscores. The scope of the two parameters is global to a C++Builder project. They are available everywhere, not just inside of main().

        This brings us to a demonstration project. In building and executing the demonstration program associated with this article, one will observe the following: With no command line parameters, the value _argc will be one as shown in the top edit box of Figure A. The bottom edit box will show that _argc is available in subroutines—a major improvement over the old argc!

Figure A First demo showing values of argc and argv in Form1.

        The memo box is filled with the strings from _argv by using the following code:

 

for (int i = 0; i < _argc; i++)

   {

   Memo1->Lines->Append(_argv[i]);

   }

 

By starting the program, there is no command line and there are no command-line arguments other than _argv[0], which is the full path name of the executable program.

        Pressing the “Show Form2” button yields the output shown in Figure B. Notice that _argc and _argv are truly global in the project.

Figure B First demo showing values of argc and argv in Form2.

 

Four ways to use the command line in Windows

The above is a Windows application. Despite the frequent use of icons and toolbars, there are four ways [2] to instead use a command line in Windows.

        The first way is inside of the Builder IDE. Choosing “Run | Parameters” from the main menu allows the developer to type in command-line parameters into the Run Parameters dialog shown in Figure C.

Figure C Specifying parameters via the Run Parameters dialog.

        The second way is to enter the command-line parameters after the executable name in a console window as shown in Figure D.

Figure D Specifying parameter via the command line.

        The third way is to enter the parameters into the “Open” edit box from the Windows “Start | Run” menu; this approach is demonstrated in Figure E. Again, enclose the path to the executable in double quotes.

Figure E Specifying parameters via the Windows Run dialog.

The fourth way is to enter the command-line parameters into the “Target” edit box of a shortcut properties window as shown in Figure F. Simply create a shortcut to the executable, and then edit the “Target” box. Notice that the full path name for the executable is in double quote marks. Do not enclose the individual parameters in the same set of quotes or Windows will protest that it cannot find the file.

Figure F Specifying parameters via a shortcut’s properties.

 

Some Final Comments

It is the case that the _argc and _argv parameters are available as soon as the project starts. This is where the information in the constructor of the main form is used.

        It is difficult to find a reference to Windows command lines, but the rules are fairly simple:

 

1.       The file-name is enclosed in double quotation marks.

2.       Individual parameters after the double-quote-delimited file-name are simply separated by white space (spaces or tabs).

3.       A multiple-word string must be enclosed in double quotes.

 

A simple example of all three rules is:

 

“aFile.exe” param1 “param2 string with spaces” param3

 

Builder command-line parameters work well in applications repetitively. Command-line parameters available in an application are often much easier on the user than refilling edit boxes.

 

Contact Don at trundlar@cox.net. 

 

References

1.       See also the ParamStr() and ParamCount() VCL functions in the BCB help files.

2.       A fifth method of specifying command-line parameters is to drop a file directly onto the executable; see also “Secondary Desktops” later in this issue.