To make long entry specs (and data) easier to edit/view in a text editor,
and allow Sloup to minimize heap usage for very long entries, you can use
line continuations. Partial lines should end with a backslash \
Sloup concatenates these together (and provides feedback on the current
status of the "entry len") until it encounters a line without one. It does
slightly special processing for binary data. When splitting a line with \,
make sure your text editor doesn't auto-indent and add extra tabs to
subsequent lines.
For regular data soups, I usually put a line continuation just before a tab, so that the remaining lines for the entry are indented (begin with a tab). See Names20.tab for an example.
For Notes, \ is not used; a paragraph is concatenated until it encounters a ----- (at least 5 -) or BYE! For NOS 2.x, each item in an outlines and checkLists occurs on a separate line.
You can transfer bitmap, PICT, sound and IR (infrared) command resources to the Newton, for example, to include in an application you are building with NewtDevEnv or a book you are creating from HTML with Newt's Cape.
Small bitmaps can be created by hand if you are patient and not binary challenged; a tool like ResEdit on the Mac works pretty well to extract hex strings. If you are a registered user of Newt's Cape, you have access to Newt's Cape Graphic Converter which will produce Sloup-compatible files for PICTs and bitmaps(icons).
Let me know which other tools on Mac or other platforms you find useful so I can share this info (see current tools). Since these binary hex text strings are often long, I almost always use line continuations; in addition to regular line continuations that concatenate the entry as text before processing, Binary Line Continuations are more efficient (and will be illustrated below).
For example, the following example creates 3 identical entries for an "i" graphic that can go in an info button.
Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, width: "int", bitmap: "bitmap"}
REPLACE!name
infoIcon 5 700000007000000000000000F000000070000000700000007000000070000000F8000000
infoIcon2 5 7000000070000000000\
00000F00000007\
0000000700000007000000070000000F8000000
infoIcon3 5 !\
70000000\
70000000\
00000000\
F0000000\
70000000\
70000000\
70000000\
70000000\
F8000000
BYE!
The first line is the name of the soup -- Bitmaps. Since ! occurs, Sloup creates the soup if it doesn't already exist. It also provides an expression that is compiled to create an array of indexes -- it must be at least []. In this example, we want the name slot (first column) to be indexed for direct lookup/faster retrieval by some application -- for example, by Newt, Newt's Cape or BitSound, or Sloup (for replacement).
The second line is the entry description:
The third line (REPLACE!name) is a command to replace an existing bitmap objects with the same name (old entry is removed; new entry is added).
The fourth line is an actual entry, with fields delimited by tabs. infoIcon is the name (since this becomes a symbol, it's generally a good idea to use only alphanumeric and underscore _ characters so that it's easier to access later). width is 5, the bitmap occupies the remainder of the same (long) line.
Before interpreting the bitmap, let's look at two other variations. Depending on the length of the bitmap entry, and the capabilities/limits of your text editor and terminal emulator, you may want lines that are no longer than 72-80 characters.
The next line that creates "infoIcon2" actually consists of 3 lines of text. This line and the next are suffixed with \, regular Line Continuations. Sloup concatenates these three lines together as text before processing it to produce an identical result (except for name) as the first line. This form of line continuation can be used with any tab-delimited text line.
For bitmap or sound lines that are long, I would recommend a slight variation, illustrated by "info icon3". End the final field on the first line with !\ (! precedes \). Sloup converts the subsequent hex data immediately into a binary (rather than a normal) string. This allows much larger resources to be transferred. (The hex text encoding is ~2x the original/eventual binary resource size).
Note: for this to work, the number of hex characters on a line must be even. (Check this with your text editor's "Cursor position" command). Sloup provides feedback on the current status of the "binary len".
Some approximate (current) limits on these three methods:
Here's how to interpret the bitmap string. Each hexadecimal character (0-F) of the bitmap string represents 4 bits; each row is represented by a multiple of 8 characters (32 bits). In the infoIcon example, the width is 5, so each row has 8 characters (even though 27 bits in each row are unused; if width is between 33 and 64, you would need 64 bits, or 16 characters for each row, and so on). For clarity, "infoIcon3" was broken into rows of 8 characters each -- here it is expanded with a binary annotation (omitting trailing zeros):
70000000 // 0111 00... 70000000 // 0111 00... 00000000 // 0000 00... F0000000 // 1111 00... 70000000 // 0111 00... 70000000 // 0111 00... 70000000 // 0111 00... 70000000 // 0111 00... F8000000 // 1111 10...
With some squinting (or filling in squares on graph paper), this should look suspiciously like an "i". Sloup translates this to a soup entry as follows:
{name: infoIcon,
width: 5,
bitmap: {bounds: {left: 0, top: 0, right: 5, bottom: 9}
bits: ...}
}
Later, you could create a picture button, in Newt for example, to use this bitmap as an icon:
{_proto: protoPictureButton,
...
icon: :GetPictAsBits("Bitmaps", "infoIcon"),
}
In Newt's Cape you could access it via a URL:
<IMG SRC="bitmaps/infoIcon" ALT="Info Icon">
How would you create these bitmaps? In addition to creating by hand or using some of the examples that come with Newt, you can use the icon editor in ResEdit (on a Mac), open the hexadecimal editor template, do a Select All and copy (or copy it in segments if > 32K), then paste into a text editor. On Mac or Windows, Newt's Cape users can use Newt's Cape Graphic Converter to convert GIF or (PICT on Mac) or (BMP on Windows) to Bitmap format. On the Newton, you can copy bitmap entries (using Newt) from ROM or existing applications to a soup, and then DUMP! the entries to your desktop, then copy/paste as text into your own .bit file. See latest Sloup tools
You can transfer and create fairly large bitmaps -- largest I have used so far is 230x230 for the dot2dot.nwt example (though generally you might use a PICT for some graphics). For icons and masks in the Extras Drawer, it's recommended that bitmaps be no larger than 32x29.
If the name of a bitmap is suffixed with !, this is interpreted (just like NTK) as a mask. When an icon is highlighted, its region inverts by default. You can specify a different mask via ! (this assumes that the regularly named bitmap already exists, i.e., occurred earlier in the file or transferred separately). This adds a mask field to the existing bitmap soup entry (and does not increment the "Entries" count). Here is an example (pictbuts.bit; I've truncated the lines):
Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, width: "int", bitmap: "bitmap"}
alarm clock 24 0000000000000000000000000000000000000000000000...
alarm clock! 24 0008000001004000000800000880800004000400020010...
light bulb 17 03C000000FF000001C1C00003006000060030000600300...
light bulb! 36 0000000000000000000020100000000000002030000000...
plane 22 60000000580038002600C80011C10C000A42100004B41000050820...
scales 24 0018000000180000001800000000000000180000007E00001F...
BYE!
Exercise for the reader: Name those Bits
WhatIsThis 16 !\ 08000000\ 54000000\ AA000000\ AA000000\ 95000000\ 551C0000\ 4BE20000\ 40030000\ 87050000\ 8A810000\ 80020000\ 400C0000\ 40300000\ 20400000\ 20800000\ 20800000
For NOS 2.1 systems, you can transfer gray scale bitmaps (assuming that you have a tool that creates them). For a 4-gray bitmap, each 2 bits represents a pixel; for 16-grays, 4 bits represents a pixel. You need to include an additional entryspec field bitdepth to indicate the number of bits (no bitDepth or bitDepth: 1 means black and white), and Sloup creates the correct picture structure. These pictures can be included in Newt's Cape books or viewed with BitSound 1.5 (or greater). For example:
...
{name: "string", width: "int", bitdepth: "int", bitmap: "bitmap"}
A PICT is a different data structure from a flat bitmap. A Newton PICT is basically the same as the old Mac PICT1 format (most Mac applications use PICT2, but you could paste into HyperCard as one way to convert to PICT1 first; or use Newt's Cape Graphic Converter).
Transferring a PICT is easier since you don't need to know the width. These can go in the same soup as bitmaps since they have the same basic slot structure, and can be used in the icon slot of a clPictureView. However, since PICTs cannot be used on some MPs in a protoPictureButton or as an application icon in Extras, you may wish to store them in a separate soup. Using Bitmap or PICT in a clPictureView depends on which format is available to you, and which is more compact.
Bitmaps![{structure: 'slot, path: 'name, type: 'symbol},]
{name: 'symbol, bitmap: "picture"}
lightNewt 00C9000000000022001D1101A00082A0008E01000A0...
BYE!
Sounds can also be transferred. However, since even "short" sounds can be rather large, you may run into heap limits on 1.x Newtons. You need to know whether the sound was sampled at a 11KHz or 22KHz sampling rate, which is specified as a real number 11013.2 or 22026.4, respectively.
Sounds![{structure: 'slot, path: 'name, type: 'symbol},] //heavymet.snd
{name: 'symbol, samplingRate: "real", sound: "sound"}
sine 22026.4 F26C000000003FB0FFFFFFE3944F27243D6381...[~14K]
BYE!
Sounds![{structure: 'slot, path: 'name, type: 'symbol},] //soundadv.snd
{name: 'symbol, samplingRate: "real", sound: "sound"}
Boing 11013.2 80808080808080808080808080808080808080...[~15K]
BYE!
To use a sound on the Newton, from NewtDevEnv, you could do:
PlaySound(:GetSound("Sounds","boing"))
You could also embed a sound in a Newt's Cape book by using the :GetSound development method inside META.
The largest sound I've transferred so far is the several-second "dadadada" sound from the False Alarm (falsalrm.nwt) example. This began as a ~31K binary resource on the Mac, extracted via several copy&pastes as ~63K of hex text, and converted into a ~32K soup entry on the Newton. I don't know the internal format of a sound string. It currently represents an uncompressed sample. If you send me pointers to info on sound formats and tools, I'll be glad to propagate to other users.
The Newt BitSound application allows you to display bitmaps/PICTs and play sounds -- both the built-in ROM frames and those in soups.
You can also transfer other resources such as device codes for remote control applications for TVs and VCRs, e.g., for the irremote.nwt and tvpad.nwt examples.
IRCD![{structure: 'slot, path: 'name, type: 'symbol},] // irremote.nwt
{name: 'symbol, resource: "resource"}
RC5Play0 !\
706C79300000035200000001000000200000008000000012000000010000000200000001\
...
Again, I don't know the internal format of these strings -- but they can copied/pasted directly from ResEdit. In Newt (assuming you have platform functions installed), e.g.,
:SendRemoteControlCode(data,:GetNamedResource("IRCD", "RC5Play0",'resource),1)
You can also create other binary types using the binary: prefix in an entrySpec. For example, to dump a package named ReStartPkg, you could do:
Package
{packageName: "ReStartPkg", packageEntry: "binary:packageEntry"}
DUMP!
To install a package named ReStartPkg, you could do:
Package
{packageName: "ReStartPkg", packageEntry: "binary:packageEntry"}
ReStartPkg !\
7061636B616765307878787800000000000000010000004A004A001600000F7000000000\
...
BYE!
If you have many and/or large files, bitmap, PICT, sound or other resources, you may wish to consider registering for Sloup (or Newt) so that you can get other versions which allow faster connections and faster resource conversion.