REBOL/SDK - Program Customizations

SDK Documentation

Contents

Setting Window Caption

When using the encapsulators the default program window caption can be controlled from the REBOL header object. To change the default window title, add a TITLE string to the ENCAP block.

For example, the REBOL header below will change the default window caption to "Reb-Tool".

REBOL [
    Title: "The Reb-Tool Program"
    Encap: [title "Reb-Tool "]
]

This title will now be part of all windows that are opened by the application. If the window is given a title within its FACE object or as part of calling the VIEW function, that title will follow the title provided by the header above.

Changing the Program Icon (Windows)

On Windows the REBOL encapsulators provide space in their output executable binary files for several icons. These icon formats are supplied:

16x16 16 colors
32x32 16 colors
32x32 256 colors
48x48 256 colors

A variety of programs are available that allow you to modify the appearance of these icons; however, you cannot add or remove icons, and you cannot change these icon formats.

For example, one program, AX Icons from www.axialis.com. provides a nice environment for editing and modifying program icons. You can load the program executable file and copy your icon images from other sources into it.

Another handy program for automating the process of changing icons is ResHacker from Angus Johnson, http://www.users.on.net/johnson/resourcehacker/ This program lets you create small scripts that specify the necessary icon modifications.

Here is an example script that works for REBOL:

[FILENAMES]
Exe=      program.exe
SaveAs=   program.exe

[COMMANDS]
-addoverwrite program.ico, ICONGROUP,REBOL,0

This script will use the icon images found in program.ico to overwrite those found in program.exe.

Handling Program Arguments

Encapsulated programs are free to process their command line arguments. The arguments will be provided in a block that is passed to the program in the system/options object.

args: system/options/args

You could then use normal REBOL code to parse the arguments, such as this example code:

input-file: pick args 1

out-file: select args "-o"

x-mode: found? find args "-x"

This code would parse these command lines:

program file.txt
program file.txt -o file.png
program file.txt -x -o file.png

You might also want to provide the error check:

if any [
    none? input-file
    input-file/1 = #"-"
][
    print "missing input file"
]

Of course, you could also use the REBOL parse command for control over parsing the command line:

input-file: out-file: x-mode: none

parse args [
    any [
        "-o" set out-file string! |
        "-x" (x-mode: true) |
        set input-file string!
    ]
]

The program will also accept a file that is dragged and dropped on its icon (drag and drop mode).

Launching and Restarting

A special function of encapsulated programs allows you to launch additional copies of your program and provide them with command line arguments. This can be handy if you need to start an independent process, such as a sub-application (an editor, for example).

The syntax of the function is:

launch arguments

For example, if you want to launch a second copy of your program to process an action:

launch "-c do-it"

Your program would need to parse the command line as described in the previous section.

If you want to launch yourself then quit (e.g. restart after settings some options), you can use this shortcut:

launch/quit arguments

Including Graphics

It is easy to include graphical images within your encapsulated programs. To do so, include the image within your source code. One way to do this is with the #include preprocessor command:

image1: #include-binary %image1.jpg

This will include the image in its compressed (JPG) format, which is optimal. Then, when your code needs to use the image, you can use a line such as:

img1: load image1

This line will decompress the image (converting it from JPG format to RGB memory format). The image can now be used within your program:

out: layout [
    text "Here's the Image:"
    image img1
]
view out

If you will not be using the image again, you should set the img1 and image1 variables to NONE to allow the image to be garbage collected by the system:

img1: image1: none

You should also set the layout that was created above to NONE:

out: none

Network Settings

If you use networking functions like SMTP (sending email) you will need to provide some network setup information. This can be done either by the developer or by the end user, it is your choice.

Encap no longer cares about the Network option in the REBOL header encap field. If you need this functionality, include the appropriate source code module within your program.

The REBOL/SDK includes the source code to two network setup modules. Both the standard REBOL/Core and the old REBOL/Encap modules are provided.

The REBOL/Core module lets you set the network settings using the set-net function:

set-net [user@example.com mail.example.com ...]

Or, you can directly setup the protocols that you need (see the source to set-net).

The old Encap module works like this:

When the encapsulated script is executed for the first time the user is asked for network settings, and those settings are then saved in a file "network.txt" in the installation directory. When the script is executed again later, REBOL loads the network settings from the "network.txt" file and does not ask the user again.

This setting is preferable if your script uses network protocols, is distributed across a wide range of setups, to many users, and does not have its own dialog to request network settings from the user.