http://www.newton-inc.com/dev/techinfo/qa/qa.htmnil 'noBackdrop
slot to the base view will stop an application from becoming a
backdrop application.
viewIdleScript. In general, applications
should release the CPU now and then so the OS can do clean up
operations.
self", you can speed things up by doing the lookup
explicitly once before executing the loop, and using the call
statement to execute the function within the body of the loop. f1 := {myFn: func() 42};
f2 := {_parent: f1};
f3 := {_parent: f2};
f4 := {_parent: f3};
f5 := {_parent: f4};
f5.test1 := func ()
for i:=1 to 2000 do call myFn with ();
f5.test2 := func() begin
local fn := myFn;
for i:=1 to 2000 do call fn with ();
end
/* executes with a noticeable delay */
f5:test1();
/* executes noticeably faster */
f5:test2();
Note for MacOS programmers: this trick is analogous to the MacOS
programming technique of using GetTrapAddress to get
a trap's real address and calling it directly to avoid the
overhead of trap dispatch.
2+3 will
be replaced with 5 by the compiler.) In the meantime,
you need to write your code as clearly as possible without relying
too heavily on the ordering of functions inside expressions.kDebugMode constant in
your project and have in your application a statement conditioned
by the value of kDebugMode, the NTK compiler removes
the entire if/then statement from your application code when the
value of kDebugMode is NIL.constant kDebugMode := true; // define in Project Data
if kDebugMode then Print(...); // in application code
When you change the value of the kDebugMode constant
to NIL, then the compiler strips out the entire if/then statement.
if getroot().|MyBaseView:MySIG| then
begin
getroot().|MyBaseView:MySIG|:TestThisView();
local s := getroot().|MyBaseView:MySIG|.BlahSize;
end;installScript, then in the
viewSetupFormScript for the application's base view.
In your case, you can do some math on the frame returned from
GetAppParams to see if the screen is large enough to
support your application.Notify to tell the user why your
application cannot run.viewBounds so it does not
appear, useRelBounds(-10, -10, 0, 0) so the view will be
off-screen.viewChildren and
stepChildren slots to NIL.AddDeferredSend(self, 'Close, nil) to
close the view.
protoCloseBox or
protoLargeCloseBox then your close box will
automatically hide itself if your application is the backdrop
application. If you also use newtStatusBar as your
status bar proto, the appropriate buttons will shift to fill the
gap left by the missing close box. Note that you do not have to
use the NewtApp framework to use the newtStatusBar
proto.Close and
Hide methods so your application cannot be
closed.GetUserConfig('blessedApp).viewChangedScript for the view will be called
each time the user does something to modify the view. For
keyboards, this means the script is called each time the user taps
a key. This is the only notification that is provided to indicate
the view contents have changed.viewQuitScript or other custom code to explicitly
notify the target that the keyboard is going away, but we do not
recommend this. (There may be a hardware keyboard attached, a
system keyboard may be open, or the user may be writing into your
view. It is a mistake to assume that the only way to modify your
view is through your own keyboard.)viewIdleScript (or call it from the
viewIdleScript.) In the
viewChangedScript, if the 'text slot has
changed, use :SetupIdle(<delay>) to arrange for
the viewIdleScript to be called in a little
while.:SetupIdle(<delay>) happens again before the
first delay goes by (perhaps because the user typed another key,)
the idle script will be called after the new delay. The older one
is ignored. SetupIdle resets the timer each time it's
called.viewIdleScript return
NIL so it won't be called repeatedly.GetRoot():BlessApp(appSymbol) will close
the current backdrop application and open the new backdrop
application if necessary. Note that appSymbol must be
a valid application symbol of a current installed and active
application. BlessApp does NOT verify that an
application can become the backdrop (for instance, it doesn't
check the 'noBackdrop flag for an application). For
this reason, BlessApp must only be used on your own
applications. See the Newton DTS Q&A, "How to Prevent an
Application from Becoming a Backdrop" for more information about
the 'noBackdrop flag.BlessApp from within a part's
installScript or removeScript. If you
want to do something like this, use a delayed call to use
BlessApp.stepChildren slot of the base
view of the template file. If both the exported and importing
template have children, they will both have a
stepChildren slot. The result is that the
stepChildren slot of the importing prototemplate is
masking the one in the exported proto. The instantiated view does
not collect all the children from the entire proto chain (though
NTK does do this at compile time for user proto templates).stepChildren is to add a
viewSetupChildrenScript to either your exported proto
template or the importer that collects all of the
stepChildren into a runtime stepChildren
array.// AFTER setting up stepChildren, views which "import" this proto
// must call inherited:?viewSetupChildrenScript();
exporter.viewSetupChildrenScript := func()
begin
// get the current value of the "extra" kids
// ...unless the importer added NO kids, in which case, these are OURS
local extraKids := stepChildren;
local items := clone(extraKids);
local kids;
local whichFrame := self;
while (whichFrame) do
begin
// get kids, but NOT using inheritance
kids := GetSlot(whichFrame, 'stepChildren);
// copy any extra stepChildren (but if NO extra kids are defined, don't copy twice!)
if kids and kids <> extraKids then
ArrayMunger(items, 0, 0, kids, 0, nil);
// go deeper into the _proto chain (or set whichFrame to nil)
whichFrame := whichFrame._proto;
end;
stepChildren := items;
end;
Note that you will have similar problems with declared children.
If you have declared children you will also need to collect the
stepAllocateContext slot.
GetRoot().buttons.soft will be non-nil
if there is a "soft" button bar, that is, the button bar is
located on the drawable screen. GetRoot():LocalBox()
returns the rectangle that encloses the screen and the
tablet. GetAppParams() returns information about the
useful area of the screen, excluding the soft or hard button bar.
Used together, this information will allow you to implement any
combination of button bar disabling and/or button bar
obscuring.KillStdButtonBar. That API is designed for use when
you want to actually remove the button bar so you can replace it -
probably with a floating slip. It is a fairly expensive call and
does a lot of things you don't need if all you want to do is take
over the screen. We recommend avoiding that call if possible.) local params := GetAppParams();
if GetRoot().Buttons.soft then
self.viewBounds := OffsetRect(UnionRect(params.appArea, params.buttonBarBounds),
-params.appAreaGlobalLeft, -params.appAreaGlobalTop)
else
self.viewBounds := params.appArea;
If the goal is to to prevent users from accessing the buttons,
then the button bar should be obscured regardless of whether or
not it is on the LCD screen. On units with a hard button bar, you
must take into account the fact that part of the base view will be
off-screen. (For instance, don't place your close box under the
silk-screened buttons.) A simple way to accomplish this is by
having a child view whose bounds are the appArea and
locating the rest of the application within that child.
Note that on some Newton devices (for instance, the eMate 300),
the buttons are not located in a view at all. On these devices,
covering the entire tablet does not prevent the user from
accessing the buttons (for instance, opening up the Extras
Drawer).
Below is some sample code you can add to your base view's
viewSetupFormScript to cover the entire tablet:
local params := GetAppParams();
self.viewBounds := GetRoot():LocalBox();
if params.appAreaGlobalLeft then
self.viewBounds := OffsetRect(self.viewBounds, -params.appAreaGlobalLeft, -params.appAreaGlobalTop);
'string. Next, you need to use the global
function BinaryMunger to munge an empty string into
the VBO. This will properly prepare the binary object to be used
as a NewtonScript string.StrMunger as often
as needed to copy new string data into the VBO. Here is a code
example:// Prepare a VBO to be the string
local myString := GetDefaultStore():NewVBO( 'string, Length("") );
BinaryMunger( myString, 0, nil, "", 0, nil );
StrMunger( myString, StrLen( myString ), nil, "My new string", 0, nil );
// Repeat with more data if necessary...
Note that unlike the C language's stdio library
function, the NewtonScript StrLen function does not
need to traverse the string to determine the string length, so you
probably don't need to worry about performance hits from its
usage.
Not all NewtonScript routines will necessarily "preserve" the VBO
nature of large strings. For instance, if you concatenate strings
using the Stringer global function or the & or
&& operators, the result is currently a non-VBO string. Be
aware that if you accidentally create a very large non-VBO string,
the code may throw a "out of NewtonScript heap memory"
evt.ex.outofmem exception.
clEditView every time some change is made, typing is
very slow. So, when should it be saved?AddDelayedCall or
AddDelayedSend can be used. The OS also provides
AddProcrastinatedSend and
AddProcrastinatedCall, which more or less implement
the timer-resetting feature for you.viewIdleScript. The
viewIdleScript is preferred over
AddProcrastinatedCall/Send because of better
management of the event queue by the OS. When you call
SetupIdle to start an idle timer, any existing idle
timer is reset. Procrastinated calls/sends aren't currently
implemented by resetting an existing timer, but rather by creating
a delayed event which fires for each call and then checking a flag
when the timer expires to see if it's the last one.target frame, which is usually a soup entry. The
entry layer implements StartFlush to start the timer,
and EndFlush is called when the timer expires and
which should ensure that the data is saved to the soup.StartFlush equivalent could be implemented
something like this: StartFlush: func()
begin
self.entryDirty := TRUE;
:SetupIdle(5000); // 5 second delay
end;
Your viewIdleScript would look something like
this:
viewIdleScript: func()
begin
:EndFlush();
nil; // return NIL to stop the idler until next StartFlush
end;
And your EndFlush equivalent would look something
like this:
EndFlush: func()
if self.entryDirty then
begin
// getting data from editView may not
// be necessary at this point
myEntry.editViewData :=
<editView/self>.viewChildren;
EntryChangeXmit(myEntry, kAppSymbol);
self.entryDirty := nil;
end;
Implementing EndFlush as a separate method rather
than just putting the contents in the viewIdleScript
makes it easy to call the method from the
viewQuitScript or viewPostQuitScript, to
guarantee that changes are saved when the view is closed. (The
viewIdleScript may not have been called if the user
makes a change then immediately taps the close box or overview or
whatever.)
DoNotInstall function. This function is called when
the package containing the part is activated for the first time as
a result of downloading to the unit, putting away to the Extras
Drawer, or installation with API functions such as
SuckPackageFromBinary or
SuckPackageFromEndpoint. The function is not called
when the package is installed as a result of card insertion,
resetting the unit, or moving the package from one store to
another using the Extras Drawer filing. This function is
incorrectly mentioned in the Newton Programmer's Guide and Newton
Programmer's Reference as DoNotInstallScript. The
proper name of the function is simply
DoNotInstall.nil, the entire package will not
be installed on the device. This provides a convenient way to
prevent installation on devices that do not support your package.
It's considered bad form to simply fail to install and provide no
notification to the user. We recommend at least using
GetRoot():Notify(...) to display a message explaining
why you are not installing.EnsureInternal anything this
function leaves behind to avoid the "Grip of Death" problems (the
error with the alert "The package 'MyApp' still needs the card you
removed...").SetPartFrameSlot. For example, to create a package
that will not install on any unit after the year 2000 (because the
world will have ended anyway), do the following: SetPartFrameSlot('DoNotInstall, func()
if Time() >= 50492160 then
begin
GetRoot():Notify(kNotifyAlert, "Millenial",
"This application, and all existence, has expired.");
true; // return non-nil to prevent install
end);
Note that this does nothing to prevent packages that were
installed before the year 2000 from continuing to function.
Because this script executes only when a package is first
installed on a given device, it may be used to set a flag that can
be used by other parts of your application to do things like
suggest user registration, go into demo mode, show some extra
help, etc. It's probably not appropriate as a way to initialize
user preferences or create initial data. Operations like that are
best done by checking each time the package is installed or
launched, and initializing then if it hasn't been done. This is
the case because a user may install your package on a card, then
remove that card from one machine and insert it into a different
machine that has not previously been used with your application.
The part's InstallScript will execute in this case,
but the part's DoNotInstall function will not.
SetPartFrameSlot('labels, '_extensions); InstallScript
part method.InstallScript for a form/application part only
takes one argument, whereas the InstallScript of an
auto part takes two arguments.InstallScript of a form/application part is
EnsureInternal'ed, an auto part's
InstallScript is not.
DeletionScript to my part, it
doesn't get called when the user scrubs the package. Why is
DeletionScript not called?DeletionScript to your part. The
DeletionScript must be defined in a manner different
from the part's InstallScript or
RemoveScript. You must explicitly set the
DeletionScript slot in your part frame using NTK's
SetPartFrameSlot global function. Here is an
example:SetPartFrameSlot('DeletionScript, func() print("Howdy!")
);SetPartFrameSlot for
any part slot other than InstallScript or
RemoveScript.protoFormulasPanel for RegFormulas, but
there does not appear to be such a template.protoFloatNGo as your base and add your formula
elements to it. The only requirements are:overview slot that contains the
text to show in the formula's overview.viewbounds.bottom must be the height of your
panel.protoTitle whose title
slot is the name of the formula panel.RegPrefs
function.protoPrefsRollItem is
incomplete. You must define an overview slot which is
the text to show in the overview mode. You can optionally define
an icon slot which is an icon for the title in the
non-overview mode (a title icon). Note that title icons are much
smaller than normal icons.
SetEntryAlarm calendar message, but the alarm is not
set.SetEntryAlarm will not find
events. You need to use a new Calendar API called
SetEventAlarm. This function is provided in the
Newton 2.0 Platform File. See the Platform File Notes for more
information.AddLayout method requires
that the symbol in the layout is internal. This bug will be fixed
in a future ROM. To work around this, do the following:local newLayout := {_proto: GetLayout("A Test Layout")};
newLayout.symbol := EnsureInternal (newLayout.symbol);
GetRoot().cardfile:AddLayout(newLayout);
CircleDistance which takes two longitude/latitude
pairs and the units to use in reporting the distance, and
CircleDistance returns the distance between the two
points. NTK may give a warning about "Unknown global
function 'CircleDistance'". This warning can be safely
ignored so long as you're writing a package for a Newton 2.0 OS
device.CircleDistance (firstLong, firstLat, secondLong,
secondLat, units)CircleDistance rounds the distance
to the nearest ten miles or ten kilometers.firstLong: The longitude for the first point on the
Earth.firstLat: The latitude for the first point on the
Earth.secondLong: The longitude for the second point on the
Earth.secondLat: The latitude for the second point on the
Earth.units: A symbol specifying the units in which the
distance will be calculated. Currently the options are
'miles or 'kilometers.NewCity. Check the section
titled "Using the Time Zone Application" in the Built-In
Applications and System Data chapter of the Newton Programmer's
Guide for information on how to convert a longitude or latitude in
degrees, minutes & seconds to an integer for
CircleDistance.
GetExtraIcons result in an
undefined Query method exception. How can I fix
this?GetExtraIcons. The code is not checking if the store
has any extras information on it, so the Query
message is getting sent to a NIL soup. The result is
the exception.GetExtraIcons: try
GetExtraIcons(...)
// do whatever you need to do here
onexception |evt.ex.fr.intrp;type.ref.frame| do
begin
// check for a problem calling the Query function
if currentException().data.errorCode = -48809 AND
currentException().data.symbol = 'Query then
begin
// no extras drawer info on the store
end ;
else
// a real error has occured, so let system handle it
ReThrow() ;
end ;bcCustomFields returns the labels and values of the
custom fields used in the entry. Is there a way to get a list of
all the custom fields the user has defined?'customFields to the names soup
method GetInfo. This will return a frame of all the
custom fields the user has defined. Each slot in this frame will
have a frame with a 'label slot. Each
'label slot will be a string specified by the user.
Here is an example:
GetStores()[0]:GetSoup(ROM_CardFileSoupName):GetInfo('customFields)
{custom1: {label: "Customer Label"},
custom2: {label: "Another label"}}
owner slot, the value of
which is a frame. This slot is removed from the entry before it is
sent to another Newton device. You can add slots to this frame to
store them, but keep them from being sent. Be sure to append your
developer signature to any slot names you add to the
owner frame.MakeTextNote doesn't work
if Notes is closed.MakeTextNote to create the data,
then add it to the soup entry using soup:AddXmit or
uSoup:AddToStoreXmit (or one of the other soup
functions.)MakeTextNote always creates a frame with all the
correct data that the Notes application requires. If the 2nd
paramater (addit) is TRUE, it will add that frame to
the Notes soup and show the note on the screen. If addIt is
NIL, then the frame is returned. newNote := GetRoot().paperroll:MakeTextNote("Here is a sample note", nil);
GetUnionSoup("Notes"):AddToDefaultStoreXmit(newNote, '|appSym:SIG|)
tapAction slot but it does not
work. What is missing?tapAction slot if it
does not find a 'text slot in the
partFrame as well. The 'text slot
contains the name that will be displayed in the Extras drawer.tapAction to
a your part frame (in other words, your autopart): DefineGlobalConstant('kTapActionFn,
func()
begin
// your code goes here!
end);
// part MUST have a text slot for tapAction to be used
// text slot is the name seen by the user in Extras
SetPartFrameSlot('text, kAppName) ;
SetPartFrameSlot('tapAction, kTapActionFn) ;
GetAppPrefs to get the prefs
for that application for read-only purposes. Only the documented
slots in that frame should be accessed. Other slots are neither
documented nor supported, and their behavior may change. You
should also check to ensure that the Home Page application exists
on a particular unit before using any features. For example, here
is a code snippet that evaluates to an array of user names, or NIL
if the unit does not support multiple users or is not in
multi-user mode. if GetRoot().HomePage then
begin
local prefs := GetAppPrefs('HomePage, '{});
if prefs.users and prefs.kMultipleUsers then
foreach item in prefs.users collect item.name;
end;
The Home Page preferences frame contains the following slots that
may be accessed read only:
kMultipleUsers: non-nil if multi-user mode is
enabled
kRequirePassword non-nil if passwords required in
multi-user mode
kDisallowNewUsers non-nil if new users can't be
created at login
users array of user frames or NIL.
A user frame contains the following slot that you may use as
read-only data:
name a string, the user-visible user's name
Keep in mind that new users could be created or existing users
names may be changed at any time, and there is no notification
when this happens. If necessary, you should check the set of users
when your application launches. It is unlikely that new users will
be created, deleted, or renamed while an application is open,
unless this happens as a result of a new user being created at
login. In this case, registering for change in the user
configuration frame with RegUserConfigChange and
watching for the 'kCurrentUser slot to change will
let you catch changes to the current set of multi-user names.
RegAuxButton, I get a -48204
error. Why am I getting this error? try
RegAuxButton( kAppSymbol, {destApp: 'newtWorks, ...} );
onexception |evt.ex.fr| do
nil;AddEntryFromStationery. For
instance: if GetRoot().NewtWorks then
GetRoot().NewtWorks:AddEntryFromStationery(stationerySym);
If you want to create a new entry with data already in it, use the
Newton Works method AdoptEntryFromStationery. To
create a new entry, you must add the basic Newton Works soup entry
slots and then any stationery-specific slots:
(1) Create a frame with the basic Newton Works soup entry slots as
shown below:
class: Class of the item. For instance, for Draw
documents, use the symbol 'drawPaper
version: Integer, the current version of the
entry
title: String which is the document title
timeStamp: Creation date of the entry
realModTime: Date the entry was most recently
modified
(2) Add the stationery-specific slots:
"Draw" Stationery Additional Slots
saveData: a frame with the following slots:
shapes: Required. An array of a single item, a
picture as returned by the global function
MakePict.
selection: [], // the empty array
styles: nil,
Warning: the above information describes only how to create a new
Draw document. See the Q&A "Reading/Modifying Newton Works
Data" for information on reading information from a Draw document.
Slots in the saveData slot of Draw documents already
in Newton Works should be treated as read-only. (Do not try to
modify these data structures in any way.)
"Paper" Stationery Additional Slots
SaveData: the object returned from
protoTXView:Externalize(). See the Newton 2.1 OS
documentation for information about Externalize().
Note that this data must be from a protoTXView that
uses VBOs (it uses the protoTXView:SetStore(...)
method), or Newton Works can run out of NewtonScript memory when
editing the document.
hiliteRange: frame with the document's hilite range
(see the protoTXView documentation for details)
margins: a frame with slots 'top,
'left, 'bottom, 'right,
which are the document's margins in pixels. The frame can also
optionally have the slots 'userTop,
'userLeft, 'userBottom, and
'userRight that will contain numbers (integer or
real) with the margin sizes translated to user units (inches or
centimeters.) If the userXXX slots are missing or
nil, they will be calculated from the pixel
values.
(3) Use code like the following to add the entry to the soup:
if GetRoot().NewtWorks then
GetRoot().NewtWorks:AdoptEntryFromStationery(theEntry, stationerySym, GetDefaultStore());
NewtApplication:AdoptEntryFromStationery(...)
method.
class: Class of the item. For instance, for Draw
documents, use the symbol 'drawPaperversion: Integer, the current version of the
entrytitle: String which is the document titletimeStamp: Creation date of the entryrealModTime: Date the entry was most recently
modifiedsaveData that contains the following slots:shapes: This is an array of shapes in the
document.styles: An array of all styles contained in the
shapes array.selection: An array containing integer indexes into
the shapes array, indicating the currently selected shapes.shapes slot is represented as an array of
style/shape pairs, as returned by
drawApp:GetContents(). Each "shape" can be another
array of shape and style pairs, representing grouping of shapes
(these grouping can continue, so subarrays can have sub-subarrays,
etc). If the shapes array contains exactly one item (its length is
1) and the class of the item is 'picture, it is a
picture that has been created/imported but not yet viewed in
Newton Works. If this is the case, the individual shapes cannot be
read, but the picture is the same format as the return value of
the global function MakePict.saveData slot of Draw documents
already in Newton Works should be treated as read-only. Do not try
to modify these data structures in any way. Manipulating them can
result in serious user problems.
ShowFoundItem method
of the Works base view only as shown below.
ShowFoundItem is generally intended for internal use
by the application itself. However, it provides handy access for
navigating to a particular soup entry, so Works supports using it
for this purpose only. Do not attempt to use
ShowFoundItem to do more than simply bring up an
entry in the Works application.ShowFoundItem may be
difficult to specify because Works can use stationery provided by
3rd parties, which may have special requirements for the finder.
In Works, the stationery is responsible for adding data to the
finder when a find is performed, and so the stationery may rely on
that data being present when ShowFoundItem is later
used. For all the stationery types that exist at the time this
Q&A was written, a minimal finder frame of {findWords:
[""]} is sufficient to allow the stationery to show the
item. Please note that this is NOT a fully specified finder,
however it is sufficient for the FindSoupExcerpt
method, which is used widely. A full finder frame which
accomplishes the same thing might look like this: {owner: GetRoot().NewtWorks,
findType: 'text,
findWords: [""],
items: [{_proto: theEntry, title: "None"}]}
For Works stationery developers, we recommend not making any
assumptions about the contents of the finder frame when
implementing your ViewDef's ShowFoundItem method.
(Note that ShowFoundItem is a Works-specific
requirement of stationery. Generic ViewDefs do not require a
ShowFoundItem method.)
Here is an inspector example of navigating Works to one of each
existing stationery. The example assumes a new untitled document
of each type exists. (You'll want to have your own code that finds
the appropriate Works soup entry to open.)
// make sure Works is open
GetRoot().NewtWorks:Open();
// find an entry
s := GetUnionSoup("NewtWorks");
theEntry := s:Query({text: "Untitled Paper"}):Entry();
// show it
GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});
// the rest of them
theEntry := s:Query({text: "Untitled Drawing"}):Entry();
GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});
theEntry := s:Query({text: "Untitled Calculations"}):Entry();
GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});
theEntry := s:Query({text: "Untitled Spreadsheet"}):Entry();
GetRoot().NewtWorks:ShowFoundItem(e, {findWords: [""]});
// cleanup
theEntry := s := nil;MakeTextNote function.protoTXView. Use the protoTXView methods
to add data to that view. When done, use the
Externalize method to get the data in a form suitable
for saving in the Works soup.protoTXView, it's imperative
that you call the SetStore method so that the data is
created on the user store rather than the NS heap. Different
formats are used for store-backed and heap-backed
protoTXViews, and the type of backing is carried into
the Externalized data. As a result, failure to use
SetStore would cause you to create a Works document
that was not backed by the user store and which could eventually
result in out-of-memory errors when the user added sufficient data
to the document.SetStore in the viewSetupFormScript
and AdoptEntryFromStationery, or the intial text
specified in the 2nd paramater to Replace. (Notably,
you may wish to provide styles for the text, see the Newton 2.1 OS
documentation on the protoTXView method
Replace.) // create and populate a dummy protoTXView
local textView := BuildContext(
{
_proto: protoTXView,
viewBounds: SetBounds(0, 0, 0, 0),
viewFlags: 0,
ReorientToScreen: ROM_DefRotateFunc,
viewSetupFormScript: func() begin
inherited:?viewSetupFormScript();
self:SetStore(GetDefaultStore());
end,
});
textView:Open();
textView:Replace({first: 0, last: 0}, {text: "Some initial text"}, nil);
// get the data in an external form for the Works soup
local saveData := textView:Externalize();
textView:Close();
// Create a new Works document from the data
GetRoot().NewtWorks:AdoptEntryFromStationery(
{
title: "Initial Title",
saveData: saveData,
hiliteRange: {first: 0, last: 0},
margins: {top: 72, left: 72, right: 72, bottom: 72},
}, 'paper, GetDefaultStore());
UnRegStamps method, my registered stamps do not get
unregistered. What is going wrong?UnRegStamps method that causes stamps to remain
registered. Use the following code to unregister your stamps:local viewDef := GetViewDefs( 'drawPaper ).default;
if viewDef then
begin
// Call UnregStamps conditionally. If the Draw application is not
// installed, GetViewDefs will return the "Missing Stationery"
// stationery.
viewDef:?UnregStamps( kStampRegistrySymbol );
local registry := GetViewDefs( 'drawPaper ).StampListRegistry;
if registry AND HasSlot( registry, kStampRegistrySymbol ) then
RemoveSlot( registry, kStampRegistrySymbol );
end;
Note that calling the UnRegStamps method is required
for future compatibility.
protoAZTabs or protoAZVertTabs?SetLetter method of the AZTab
protos:protoAZTabs.SetLetter(newLetter, NIL)
pickLetterScript message.
// set myProtoAZTabs to the letter "C"
myProtoAZTabs:SetLetter($c, nil) ;
protoAZVertTabs.SetLetter...
see protoAZTabs.SetLetter
protoSoupOverview:HitItem(...)? I want to call the
inherited method and use the return value to determine what action
the system performed.ProtoSoupOverview:HitItem(...) returns nil if it
handled the tap and non-nil if it didn't handle the
tap (the opposite meaning of the return value of
protoOverview's HitItem method).protoSoupOverview's HitItem is just like
protoOverview's HitItem method; this is
a mistake in the documentation.ROM_UpArrowBitmap in my
application, and now my app appears partially invisible in the
Newton 2.1 OS. What's wrong?ROM_UpArrowBitmap and the other
directional arrow constants were not intended to be supported, and
the value of the magic pointer has changed in Newton 2.1 OS. The
change was made to better implement the (documented and supported)
scrolling protos such as protoUpDownScroller.ROM_UpArrowBitmap is named in the NTK Platform File
defs file, and had mistakenly been mentioned in some public
documentation from Apple, so you may have thought this was
supported. If you have a reference to one of these magic pointers
in the icon slot of a clPictureView,
you'd have gotten an arrow graphic on the 2.0 and earlier releases
of the OS, but on the Newton 2.1 OS, the changed value is not
acceptable to the view system as a graphic. The result is that
drawing is aborted when the OS tries to render the view with the
arrow graphic, and views that would normally be drawn after the
bad view will also fail to render, producing what appear to be
invisible views that are otherwise functional.protoTXView-based view as a
descendent of a draggable view. When I drag the view, the
protoTXView-based view still draws its contents at
the original coordinates. What is going wrong?protoTXView prototype does not correctly
update its draw origin coordinates when moved. To work around this
bug, you must close the protoTXView-based view and
re-open it.protoTXView-based view, you will
need to externalize the data so that you can restore the data when
you reopen the view. To do this, call the Externalize
method and store the return value somewhere (perhaps in the parent
of the protoTXView). When you reopen the view, call
the Internalize method with the stored return value
of the call to Externalize.FrameDirty see
changes to nested frames?FrameDirty is fooled by changes to
bytes within binary objects. Since strings are implemented as
binary objects, this means that FrameDirty will not
see changes to individual characters in a string. Since
clParagraphViews try (as much as possible) to work by
manipulating the characters in the string rather than by creating
a new string, this means that FrameDirty can be
easily fooled by normal editing of string data.s := GetStores()[0]:CreateSoup("Test:DTS", []);
e := s:Add({slot: 'value, string: "A test entry", nested: {slot: 'notherValue}})
#4410B69 {slot: value,
String: "A test entry",
nested: {slot: notherValue},
_uniqueID: 0}
FrameDirty(e)
#2 NIL
e.string[0] := $a; // modify the string w/out changing its reference
FrameDirty(e)
#2 NIL
EntryChange(e);
e.string := "A new string"; // change the string reference
FrameDirty(e)
#1A TRUE
EntryChange(e);
e.nested.slot := 'newValue; // nested change, FrameDirty is deep.
FrameDirty(e)
#1A TRUE
s:RemoveFromStore() // cleanup.evt.ex.fr.store exceptions. These limits
are for the encoded form that the data takes when written to a
soup, which varies from the object's size in the NS heap.EntryFlushXMit and EntryChangeXMit?EntryFlushXMit and EntryChangeXMit is
what will be done with the entry after the flush or change._proto slots. The result is that the data will be
written to the store, and a cached frame will exist. Often, this
is exactly what is desired because the entry is still needed since
it will soon be accessed or modified.EntryFlushXMit is a better option; it writes the data
to the soup without creating the cached entry.AddXMit or
EntryChangeXMit. If the entry will not soon be used
again (so it doesn't need to take up heap space with the cached
frame), then use AddFlushedXmit or
EntryFlushXMit.while entry do
begin
entry.fooCount := entry.fooCount + 1;
// nil appSymbol passed so don't broadcast
EntryFlushXMit(entry, nil);
entry := cursor:Next();
end; // Could broadcast now
foreach x in kInitialData do // if new, may not need broadcast
soup:AddFlushedXmit(Clone(x), nil);
soupDef mechanism and putting the long name
(typically without appended signature) in the
'userName slot of that data structure.
WhichEnd cursor method returns the symbols
'begin or 'end, depending on where the
cursor is in a soup. Why does NTK complain when I try to check for
these symbols?if myCursor:WhichEnd() = '|begin| then
:WeAreAtBeginning();
EntryChange on the modified entry I get a -48022
error. What is wrong?ClearVBOCache while modifying VBOs. You can
also work around the problem by putting the VBO in a soup entry
and using EntryChangeXmit or
EntryFlushXmit.ClearVBOCache takes a reference to a VBO as an
argument, and moves the dirty pages for a given VBO to the store,
freeing up the system memory. Note that this function does not
commit the changes to the VBO, while EntryChangeXmit
and EntryFlushXmit do commit the changes.ClearVBOCache. For example, modifying 32K of
contiguous data, or a single byte in 32 different pages of one
VBO, or even a single byte in 32 different VBOs all modify 32
total pages of VBO data. Don't do this too often, though. Calling
ClearVBOCache repeatedly for modifications to the
same page of a VBO or when there are only a few modified pages
will needlessly slow the machine.Stats() is called: gc(); stats();
soup:AddToDefaultStoreXmit({ foo : "a test string"}, '|bar:SIG|);
gc(); stats();
soup:AddToDefaultStoreXmit({ foo : "another test string"}, '|bar:SIG|);
gc(); stats();
A: There is no leak. What's actually going on is that the Xmit
versions of the soup methods do their broadcasting in deferred
actions. That's good, because it means that broadcast handlers
that might throw or have other side effects won't break your code.
A little bit of heap memory is used to keep track of the deferred
action and its arguments. This memory is released after the
deferred action executes, which is typically immediately after
control returns to the top level.
If you select all the test code in the NTK Inspector and press the
Enter key, NTK compiles the entire selection and executes it as a
single operations, so control doesn't return to the top level
(thus allowing the deferred actions to execute) until after the
last operation. The deferred action created by each call to the
Xmitting function will still be pending, so the space won't have
been released yet, and stats reflect this. If the example is
executed one line at a time, you'll see that no memory is actually
leaked.
If you pass nil for the changeSym
argument to the Xmit functions, no notification occurs and the
deferred action is not created. Normally, this is a bad idea,
since you want other applications to know about your soup changes.
However, Xmit notification may not be necessary for specialized
applications that use only their own application soups and do not
publish information about reading/writing soup data for
extensibility.
If you are modifying a very large number of entries (for instance,
creating a new soup of thousands of entries), you might pass
nil for the changeSym to void immediate
notification. Afterwards, use the XmitSoupChange
global function with the 'whatThe symbol. (See the
documentation for XmitSoupChange for more
information.)
CDPipeInit, it
returns a -28102 error (Communication tool not found). I've
checked that the tool is installed properly, and the DIL sample
application works fine. What's wrong?CSTR.rsrc" to your project
and see if that fixes things.
SetupPortMenu
function in SoupDrink.c for an example.
FDget function return error
-28801 (Out of heap memory) or -28706 (Invalid parameter)? I don't
think I'm out of memory, and I don't always get this error code so
my parameters must be right. What is wrong?A:={first: {left:3, right: 30, top:10, bottom:90}};
A.second := A.first; // triggers the problem
B:={first: {left:3, right: 30, top:10, bottom:90}};
B.second := clone(B.first); // cloning avoids the problem
C:={first: {left:3, right: 30, top:10, bottom:90, foo: nil}};
C.second := C.first; // no problem since C.foo exists
D:={first: {left:3, right: 30, top:10, bottom:1000}};
D.second := D.first; // no problem since D.bottom is >255
To work around this problem, you can clone the frame (as in frame
"B") or add another slot to the frame (as in frame "C") or ensure
that the values are not between 0 and 255 (frame "D").
Note: this has been fixed in the 1.0.2 Windows DILs.
CDPipeListen, but it never seems to be called. What
is going wrong?CDPipeListen, the callback
function never gets called in Windows applications. You will have
to use a synchronous listen, then wait for the state of the DIL
pipe to change before accepting the connection. The following code
shows how to properly accept a connection.anErr = CDPipeListen( gOurPipe, kDefaultTimeout, NULL, 0 );
if (!anErr)
{
// This code doesn't need to be executed on MacOS, but
// is currently required for Windows. We need to loop,
// waiting for the connection state to change to
// kCDIL_ConnectPending.
endTime = (GetTickCount()/1000) + 30; // to timeout in 30 seconds
while ((GetTickCount()/1000) < endTime )
{
if (CDGetPipeState( gOurPipe ) == kCDIL_ConnectPending) {
anErr = CDPipeAccept( gOurPipe );
break;
} else
CDIdle( gOurPipe );
}
}
Note: this has been fixed in the Windows DILs 1.0.2.
.chain command.
SetLCDContrast,
to do just that. However, changing the contrast with no end user
control is not considered a good user-interface practice.ScaleShape?MungeBitmap,
it sometimes shifts the data. How can I rotate left correctly?MungeBitmap using
these operations: 'flipHorizontal,
'flipVertical, and 'rotateRight.
('rotateRight three times will work as well, but it
is less efficient bacause flips are faster than rotates.)MakeBitmap and copy data into the bitmap.GetPICTAsBits). If you want to create bitmaps
dynamically at compile time, you can create a simple bitmap object
with the following format.{
bounds: <bounds frame>,
bits: <raw bitmap data>,
mask: <raw bitmap data for mask - optional>
}
Binary object <raw bitmap data> - class 'bits
bytes data-type descr
0-3 long ignored
4-5 word #bytes per row of the bitmap data
(must be a multiple of 4)
6-7 word ignored
8-15 bitmap rectangle - portion of bits to use--see IM I
8-9 word top
10-11 word left
12-13 word bottom
14-15 word right
16-* bits pixel data, 1 for "on" pixel, 0 for off
The bitmap rectangle and bounds slot must be in agreement
regarding the size of the bitmap.
MakeBitmap Shapes
If you want to create bitmap data at run time or extract bitmap
data from a bitmap created with the MakeBitmap global
function, use the GetShapeInfo function to get the
bitmap and other slots required to interpret the meaning of the
bitmap created by MakeBitmap.
Warning: the following information applies only to bitmaps
of depth 1 (black and white bitmaps) created by your application
with MakeBitmap. Do not rely on GetShapeInfo
or the following slots for images created by other applications,
images stored in the Newton ROM, images created with functions
other than MakeBitmap, nor images with a depth other
than 1.
If you created a bitmap using MakeBitmap of
depth 1, the return value of
GetShapeInfo contains frame with information you can
use to interpret the bitmap data.
This frame includes a bits slot referencing the
bitmap data for the bitmap. This bitmap data can be manipulated at
run time (or copied for non-Newton use), using other slots in the
return value of GetShapeInfo to interpret the bitmap
binary object: scanOffset, bitsBounds,
and rowBytes. For instance, the first bit of the
image created with MakeBitmap can be obtained with
code like:
bitmapInfo := GetShapeInfo(theBitmap);
firstByte := ExtractByte(bitmapInfo.bits, bitmapInfo.scanOffset);
firstBit := firstByte >> 7; // 1 or 0, representing on or off
Note that rowBytes will always be 32-bit aligned. For
instance, for a bitmap with a bitsBounds having width
33 pixels, rowBytes will be 8 to indicate 8 bytes
offsets per horizontal line and 31 bits of unused data at the end
of every horizontal line.
view:LockScreen(nil) message forces an "immediate update".
How is this different from calling RefreshViews?DrawShape) the system normally renders the shape on
the screen immediately. :LockScreen(true) provides a
way to "batch up" the screen updates for multiple drawing calls.
Sending :LockScreen(nil) "unplugs" the temporary
block that has been placed on the screen updater, causing all the
batched drawing changes to be rendered on the LCD.RefreshViews tells the system to execute the commands
needed to draw every view that has a dirty region. You can think
of it as working at a level "above" the screen lock routines. When
you send the message Dirty, it does not immediately
cause the system to redraw the dirtied view, instead it adds the
view to the dirty area for later redrawing.SetValue, call RefreshViews (and not see
an update) draw a few shapes, and then, when you unlock the
screen, the refreshes to the dirty regions and your shapes will
all appear at once.LockScreen and RefreshViews:LockScreen(nil) result in a
RefreshViews?LockScreen(true) just stops the hardware screen
from updating from the offscreen buffer.
LockScreen(nil) releases that lock which usually
causes the hardware screen to update soon thereafter.SetValues draw
into the offscreen buffer?SetValue doesn't draw. Otherwise, see 1.RefreshViews?vfFillWhite and
kRGB_0 but neither seems to work. How do I draw white
text?textPattern slot in the style frame to make the text
black (kRGB_Black) and set the
transferMode to modeBic.kRGB_Gray1 for something that is as close
to white as you can get.modeOr - Replaces pixels under the non-white part of
the source image with source pixels. If the source pixel is white,
the destination pixel is unchanged.modeXor - Inverts pixels under the non-white part of
the source image. Destination pixels under the white part of the
source image are unchanged. This actually XORs the values in the
source and destination pixels. For example, for destination of 0xA
(75% grey), source 0x0 (white) produces result 0xA (unchanged).
Source 0xF (black), produces result 0x5 (25% grey, or inverted).
Source pixels of other values have less utility. For example,
source 0x5 (25% grey) produces result 0xF (black), while source
0xA (75% grey) produces result 0x0 (white), and source 0x3 (50%
grey) produces result 0x9 (slightly less than 75% grey).modeBic - Erases screen pixels under the non-white
part of the source image, making them all white. Destination
pixels under the white part of the source image are unchanged.
This actually, does a bitwise NOT, so it is really only useful
when source pixels are either 0 (white) or 0xF (black). With other
values, weird things happen, For example, destination 0xF with
source 0xA produces result 0x5. Destination 0x0 with source 0xA
produces result 0x0. Destination 0x3 with source 0xA produces
result 0x1.modeNotCopy - Replaces screen pixels under the black
part of the source image with white pixels. Screen pixels under
the white part of the source image are made black.modeNotOr - Screen pixels under the black part of the
source image are unchanged. Screen pixels under the white part of
the source image are made black.modeNotXor - Screen pixels under the black part of
the source image are unchanged. Screen pixels under the white part
of the source image are inverted.
GrayShrink doing what I want it to
when I use it with relatively small bitmaps?GrayShrink was designed for rendering relatively
large images such as received faxes into a moderately large part
of a Newton display. It works by setting a flag in the bitmap that
tells the imager to gather multiple bits from the source bitmap
and turn them into a single gray pixel when drawing through a
reducing transform.GrayShrink will
not modify the bitmap. The end result will be a transformed
(shrunk) image with the same bit depth as the original. That is,
the shrinking will still happen, but the graying won't.GrayShrink will not work with read-only bitmaps (it
is unable to set the flag.) The result will still be a transformed
(shrunk) image, but pixels will not be combined to gray. There is
no way to clear the flag once it has been set. After
GrayShrink has modified a bitmap, drawing it to the
screen through any scaling transform that reduces the image will
produce a pixel combined gray result.GrayShrink pixel gathering algorithm produces an
anomaly along the righthand side of the reduced image. When
rendering large bitmaps into a reasonably large destination, this
is generally uunnoticeable. However, when used with small source
bitmaps or when rendering into a small area, several columns along
the right side of the result may not be drawn, and the anomaly is
easily seen. We recommend using GrayShrink and the
'drawGrayScaled setting for
protoImageView only for large source images such as
incoming faxes or scanned data.
MungeBitmap to flip or rotate a
grayscale image, it gets corrupted. What's wrong?MungeBitmap does not properly handle bitmaps with
a depth greater than 1. You can work around this problem by using
kMungeBitmapFunc, which has the same calling
conventions and return value as MungeBitmap.
kMungeBitmapFunc is provided in the Newton 2.1
Platform file, version 1.2b1 or later.MungeBitmap with the
'rotateLeft, 'rotateRight, or
'flipHorizontal options will trigger the bug. The
'rotate180 and 'flipVertical arguments
to MungeBitmap work correctly with deeper
bitmaps.TextBounds and
StrFontWidth, but those values may be too small to
fit.:LocalBox() to find out) and
use center justification in a style frame passed to
:DrawShape(...).
cookie := OpenRemoteControl();
CloseRemoteControl(cookie);
OpenRemoteControl. Always returns nil.
cookie is invalid after this call returns.
SendRemoteControlCode(cookie, command, count);
OpenRemoteControl, this function sends the remote
control command (see below for format of data). The command is
sent count times. count must be at least 1. Returns after the
command has been sent (or after the last loop for count
> 1). (see diagram)
Each command code has the following structure:
struct IRCodeWord {
unsigned long name;
unsigned long timeBase;
unsigned long leadIn;
unsigned long repeat;
unsigned long leadOut;
unsigned long count;
unsigned long transitions[];
};
name
timeBase in microseconds; sets the bit time base
leadIn duration in timeBase units of the lead bit
cell
repeat duration in timeBase units of the last bit
cell for loop commands
leadOut duration timeBase units of the last bit cell
for non-loop commands
count one-based count of transitions following
transitions[ ] array of transition durations in
timeBase units
See Remote.¹, Sony.r, RC5.r, and RemoteTypes.r files for examples.
The .rsrc files have templates for ResEdit editing of the Philips
and Sony resources. See Remote IR Sample code for more
details.
Things To Know Before You Burn The Midnight Oil:
If the Newton goes to sleep, the IR circuits are powered down,
and any subsequent sends will fail. If you want to override this,
you need to have a powerOffhandler close the remote connection,
and when Newton wakes up the application could re-open the
connection.
If two applications are concurrently trying to use the IR port
(beaming and remote control use for instance), this will cause a
conflict.
Sample Code
The Remote IR Sample is part of the DTS Sample code
distribution, you should find it on AppleLink and on the Internet
ftp server (ftp.apple.com).
By way of a quick summary: the sample has an array of picker
elements with the resource definitions bound to the index (ircode
inside the application base view).
You specify the constant that is an index to the array, get the
resource using the NTK function GetNamedResource and
when you send data, use the constant as the resource used.
OpenRemoteControl is called in
viewSetupFormscript, and closeRemoteControl
is called in viewQuitScript. Note that these
are methods, not global functions; same is true of
SendRemoteControlCode.
More Information
Consult the IR samples available on ftp.apple.com (Internet) and
on the Newton Developer CD-ROMs.
byteCount slot of your input spec to the
minimum packet size. In your input script, call
Partial to read in the entire packet, and then call
FlushInput to empty everything out for your next
receive completion.partialScripts with
partialFrequencies. Call the Ticks
global function if necessary to determine the exact execution time
of a partialScript.Instantiate, Bind or
Connect touch the hardware?{
type: 'service,
label: kCMSAsyncSerial,
opCode: opSetRequired
}
<see diagram section A>
The CommManager task creates the appropriate CommTool task(s) and
replies to the communications service request. Each CommTool task
initializes itself . In response to the Bind request
the CommTool acquires access to any physical hardware it controls,
such as powering up the device. The endpoint is ready-to-go.
<see diagram section B>
An endpoint may use multiple CommTool tasks, but there will be a
single NewtonScript endpoint reference for them.
When the endpoint requests a connection, the CommTool interacts
wih the physical hardware (or a lower level CommTool) as necessary
to complete the connection, depending on the type of
communications service. For example, ADSP will use the endpoint
address frame to perform an NBP lookup and connection request. MNP
will negotiate protocol specifications such as compression and
error correction.
<see diagram section C>
The CommTool completes the connection and replies to the
connection request. Note that if this is done asynchronously, the
Newt task continues execution, giving the user an option to abort
the connection request.
<see diagram section D>
Disconnect functions similarly to
Connect, moving the endpoint into a disconnected
state. Unbind releases any hardware controlled by the
CommTool. Dispose deallocates the CommTool task.
kMacRomanEncoding is the default
encoding system for strings on most Newtons, you can specify it
explicitly by adding one of the following encoding slots to your
endpoint:encoding: kMacRomanEncoding; // Unicode<->Mac translation
encoding: ; // Unicode<->Sharp
Wizard translationkShiftJISEncoding
encoding: ; //
Unicode<->Japanese ShiftJIS translation
For kMacRomanEncoding, the upper 128 characters of
the MacOS character encoding are sparse-mapped to/from their
corresponding unicode equivalents. The map table can be found in
Appendix B of the NewtonScript Programming Language reference. The
upper-bit translation matrix is as follows:
short gASCIIToUnicode[128] = {
0x00C4, 0x00C5, 0x00C7, 0x00C9, 0x00D1, 0x00D6, 0x00DC, 0x00E1,
0x00E0, 0x00E2, 0x00E4, 0x00E3, 0x00E5, 0x00E7, 0x00E9, 0x00E8,
0x00EA, 0x00EB, 0x00ED, 0x00EC, 0x00EE, 0x00EF, 0x00F1, 0x00F3,
0x00F2, 0x00F4, 0x00F6, 0x00F5, 0x00FA, 0x00F9, 0x00FB, 0x00FC,
0x2020, 0x00B0, 0x00A2, 0x00A3, 0x00A7, 0x2022, 0x00B6, 0x00DF,
0x00AE, 0x00A9, 0x2122, 0x00B4, 0x00A8, 0x2260, 0x00C6, 0x00D8,
0x221E, 0x00B1, 0x2264, 0x2265, 0x00A5, 0x00B5, 0x2202, 0x2211,
0x220F, 0x03C0, 0x222B, 0x00AA, 0x00BA, 0x2126, 0x00E6, 0x00F8,
0x00BF, 0x00A1, 0x00AC, 0x221A, 0x0192, 0x2248, 0x2206, 0x00AB,
0x00BB, 0x2026, 0x00A0, 0x00C0, 0x00C3, 0x00D5, 0x0152, 0x0153,
0x2013, 0x2014, 0x201C, 0x201D, 0x2018, 0x2019, 0x00F7, 0x25CA,
0x00FF, 0x0178, 0x2044, 0x00A4, 0x2039, 0x203A, 0xFB01, 0xFB02,
0x2021, 0x00B7, 0x201A, 0x201E, 0x2030, 0x00C2, 0x00CA, 0x00C1,
0x00CB, 0x00C8, 0x00CD, 0x00CE, 0x00CF, 0x00CC, 0x00D3, 0x00D4,
0xF7FF, 0x00D2, 0x00DA, 0x00DB, 0x00D9, 0x0131, 0x02C6, 0x02DC,
0x00AF, 0x02D8, 0x02D9, 0x02DA, 0x00B8, 0x02DD, 0x02DB, 0x02C7
};
Connect and Listen methods of
protoBasicEndpoint?nil before attempting to
access the array, while others assume they will always be passed
an array of options. Some also assume that the array will always
contain at least one element. ep:Connect([nil], nil); data := [....];
for item := 0 to Length(data) - 1 do
ep:Output(data[ item ], nil, nil);
protoBasicEndpoint performs a function
synchronously, it creates a special kind of "sub-task" to perform
the interprocess call to the comm tool task. The sub-task causes
the main NewtonScript task to suspend execution until the sub-task
receives the "operation completed" response from the comm tool
task, at which time the sub-task returns control to the main
NewtonScript task, and execution continues.
The sub-task, however, is not disposed of until control returns to
the main NewtonScript event loop. In effect, each and every
synchronous call is allocating memory and task execution time
until control is returned to the main NewtonScript event loop! For
a small number of sucessive synchronous operations, this is
fine.
A fully asynchronous implementation, on the other hand, is faster,
uses less machine resources, allows the user to interact at any
point in the loop, and is generally very easy to implement. The
above loop can be rewritten as follows:
ep.fData := [....];
ep.fIndex := 0;
ep.fOutSpec := {
async: true,
completionScript:
func(ep, options, error)
if ep.fIndex >= Length(ep.fData) - 1 then
// indicate we're done
else
ep:Output(ep.fData[ ep.fIndex := ep.fIndex + 1 ],
nil, ep.fOutSpec )
};
ep:Output(ep.fData[ ep.fIndex ], nil, ep.fOutSpec );
Of course, you should always catch and handle any errors that may
occur within the loop (completionScript) and exit
gracefully. Such code is left as an excercise for the reader.
XON/XOFF flow control can be set
with the kCMOInputFlowControlParms and
kCMOOutputFlowControlParms options. In the case of
hardware handshaking (RTS/CTS) you should use the
following options:{ label: kCMOInputFlowControlParms,
type: 'option,
opCode: opSetRequired,
data: { arglist: [
kDefaultXonChar,
kDefaultXoffChar,
NIL,
TRUE,
0,
0, ],
typelist: ['struct,
'byte,
'byte,
'boolean,
'boolean,
'boolean,
'boolean, ],
},
},
{ label: kCMOOutputFlowControlParms,
type: 'option,
opCode: opSetRequired,
data: { arglist: [
kDefaultXonChar,
kDefaultXoffChar,
NIL,
TRUE,
0,
0, ],
typelist: ['struct,
'byte,
'byte,
'boolean,
'boolean,
'boolean,
'boolean, ],
},
}
MakeModemOption call.MakeModemOption when setting up options to intiailize
an endpoint. So you would call MakeModemOption to get
your initial option array, then add your own custom options after
that. MakeModemOption will return correct options
based on the user settings for ignore DialTone, use PC Card Modem,
etc.
inputSpec of form
'string. When its inputScript triggers,
I switch to an input form of 'binary. When the binary
inputScript triggers, the first few bytes of the data
are garbage, and sometimes the inputScript doesn't
trigger at all. The same behavior occurs when switching to the
'frame input form. Why?endSequence and filter processing.byteCount, or end-of-packet (EOP)
detection failure.{
type: 'option,
label: kCMOSerialHWChipLoc,
opCode: opSetRequired,
form: 'template,
result: nil,
data: {
argList: [kHWLocPCMCIASlot1, 0], // or kHWLocPCMCIASlot2
typeList: ['struct, ['array, 'char, 4], 'uLong]
}
}
If you are using Newton Internet Enabler (NIE) endpoints, you can
use a PC Card Modem instead of a serial PC Card, but you do not
have to add any special endpoint options. NIE will handle this
automatically, provided you correctly set up your modem in the
Modem preferences in the Prefs application.
This should allow your endpoint code to use the PC Card (serial
card or modem card) instead of the built-in serial port. Connect
the NTK Inspector to the built-in serial port as you normally
would. If you are using an AppleTalk endpoint, you can
simultaneously use the NTK inspector connected via AppleTalk.
'char fields in the endpoint option is preventing the
correct flow control characters from being set in the serial
driver. The solution is to use the 'byte symbol
rather than the 'char symbol for these fields, thus
avoiding the Unicode-to-ASCII conversion that would normally take
place. The Newton Programmer's Guide is incorrect; the correct
option frames are as follows:{ label: kCMOInputFlowControlParms,
type: 'option,
opCode: opSetRequired,
result: nil,
form: 'template,
data: {
arglist: [
unicodeDC1, // xonChar
unicodeDC3, // xoffChar
true, // useSoftFlowControl
nil, // useHardFlowControl
0, // not needed; returned
0, ], // not needed; returned
typelist: ['struct,
'byte, // XON character
'byte, // XOFF character
'boolean, // software flow control
'boolean, // hardware flow control
'boolean, // hardware flow blocked
'boolean, ], }, }, // software flow blocked
{ label: kCMOOutputFlowControlParms,
type: 'option,
opCode: opSetRequired,
result: nil,
form: 'template,
data: {
arglist: [
unicodeDC1, // xonChar
unicodeDC3, // xoffChar
true, // useSoftFlowControl
nil, // useHardFlowControl
0, // not needed; returned
0, ], // not needed; returned
typelist: ['struct,
'byte, // XON character
'byte, // XOFF character
'boolean, // software flow control
'boolean, // hardware flow control
'boolean, // hardware flow blocked
'boolean, ], }, }, // software flow blocked
Baud rate 9600
Data bits 8
Stop bits 1
Parity Odd
2 Hardware Restrictions
The IR hardware used in the Sharp Wizard series (as well as
Newtons and other devices) requires a brief stablizing period when
switching from transmitting mode to receiving mode. Specifically,
it is not possible to receive data for two milliseconds after
transmitting. Therefore, all devices should wait three
milliseconds after completion of a receive before
transmitting.
3 Packet Structure
There are two kinds of Packets: "Packet I" and "Packet II".
Because the IR unit is unstable at the start of a data
transmission, DUMMY (5 bytes of null code (0x00)) and
START ID (0x96) begin both packet types. At least two
null bytes must be processed by the receiver as DUMMY
before the START ID of a packet is considered. After
this (DUMMY, START ID) sequence the PACKET
ID is transmitted. Code 0x82 is the packet ID
for a PACKET I transmission, and code 0x81 is the
packet ID for a PACKET II transmission.
3.1 Packet I
This packet type is used to transmit the following control
messages:
3.1.1 Request to send ENQ (0x05)
3.1.2 Clear to send SYN (0x16)
3.1.3 Completion of receiving data ACK (0x06)
3.1.4 Failed to receive data NAK (0x15)
3.1.5 Interruption of receiving data CAN (0x18)
The format of this packet type is as follows:
Byte length Set value in transmission Detection method in reception
DUMMY 5 0x00 * 5 Only 2 bytes are detected when received.
START ID 1 0x96
PACKET ID 1 0x82
DATA 1 above mentioned data
Packet I example:
DUMMY START ID PACKET ID DATA
0x00, 0x00, 0x00, 0x00 0x96 0x82 0x05
3.2 Packet II
This packet type is used to transmit data. The maximum amount
of data that may be transmitted in one packet is 512 bytes. If
more than 512 bytes are to be transmitted, they are sent as
several consecutive 512-byte packets. The last packet need not be
padded if it is less than 512 bytes and is distinguished by a
BLOCK NO value of 0xFFFF.
The format of this packet type is as follows:
Byte length Set value in transmission Detection method in reception
DUMMY 5 0x00 * 5 Only 2 bytes are detected.
START ID 1 0x96
PACKET ID 1 0x81
VERSION 1 0x10 Judge only bits 7-4
BLOCK NO 2 (L/H) 0x0001 ~ 0xFFFF
CTRL CODE 1 0x01 Don't judge
DEV CODE 1 0x40 Don't judge
ID CODE 1 0xFE Don't judge
DLENGTH 2 (L/H) 0x0001 ~ 0x0200
DATA 1 ~ 512
CHKSUM 2 (L/H)
BLOCK NO in last block must be set to
0xFFFF.
CHKSUM is the two-byte sum of all of the data bytes
of DATA where any overflow or carry is discarded
immediately.
Send all two-byte integers lower byte first and upper byte
second.
Packet II example:
DUMMY START ID PACKET ID VERSION BLOCK NO CTRL CODE
0x00, 0x00, 0x00, 0x00 0x96 0x81 0x10 Low High 0x01
DEV CODE ID CODE DLENGTH data CHECKSUM
0x40 0xFE Low High ???? Low High
4 Protocol
Data will be divided into several blocks of up to 512 bytes
each. These blocks are transmitted using type I and II packets as
follows:
4.1 Transmission Protocol
4.1.1 The initiating device (A) begins a session by sending an
ENQ (type I) packet. The receiving device (B) will
acknowledge the ENQ by transmitting a
SYN packet.
4.1.2 When (A) receives a SYN packet, it goes to step
4.1.4 below.
4.1.3 When (A) receives a CAN packet, or when 6
minutes have elapsed without a SYN packet reply to an
ENQ packet, (A) terminates the session. If (A)
receives any other packet, no packet, or an incomplete packet, it
begins sending ENQ packets every 0.5 seconds.
4.1.4 When (A) receives a SYN packet, it transmits a
single type II data packet, then awaits an ACK packet
from (B).
4.1.5 When (A) receives an ACK packet, the
transmission is considered successful.
4.1.6 If no ACK packet is received within 1 second
from completion of step 4.1.4, or if any other packet is received,
(A) goes to step 4.1.1 and transmits the data again.
Retransmission is attempted once. The session is terminated if the
second transmission is unsuccessful.
4.2 Reception Protocol
4.2.1 The receiving device (B) begins a session by waiting for an
ENQ (type I) packet. If no ENQ packet is
received after 6 minutes (B) terminates the session.
4.2.2 When (B) receives an ENQ packet, (B) transmits
either a SYN packet to continue the session or a
CAN packet to terminate the session.
4.2.3 When (B) receives a valid type II packet (for example, the
checksum and all header fields appear to be correct), (B)
transmits an ACK packet.
4.2.4 If one or more header fields of the data packet are not
correct, or if the time between data bytes is more than 1 second,
(B) goes to step 4.2.1 and does not transmit the ACK
packet (this will cause (A) to retransmit the packet after a one
second delay).
4.2.5 If the header fields of the data packet appear to be correct
but the checksum is incorrect, (B) transmits a NAK
packet (this will cause (A) to retransmit the packet
immediately).
Because of the restriction in hardware mentioned in item 2 above,
it is not possible to receive data for two milliseconds after a
data transmission. Please wait three milliseconds before
transmitting a response to the other device.
(see diagram)
AddProcrastinatedCall or
AddProcrastinatedSend repeatedly with the same symbol
from my input specification's InputScript method
sometimes causes an out of memory exception on pre-Newton 2.1
devices. What's going wrong?InputScript, it may not be executed until a much
later time. Due to a bug in the way procrastinated actions with
the same symbol are queued, it's possible to queue so many events
that you run out of NewtonScript heap memory. This bug is fixed in
the Newton 2.1 OS.AddDelayedCall or AddDelayedSend
in place of a procrastinated action.'time slot of the event frame passed to an endpoint's
EventHandler is in ticks. After some experimentation,
I've discovered that it is not in ticks. What is this time
value?0x3FFFFFFF, or
-536870912 decimal. Therefore, the time value will
start counting at zero, count up to 536870911, wrap
to -536870912 then start to count back up to
536870911.
Ground (4) -> Ground (4) (also connect to connectors' shrouds)
Transmit+ (6) -> Receive+ (8)
Transmit- (3) -> Receive- (5)
Receive+ (8) -> Transmit+ (6)
Receive- (5) -> Transmit- (3)
Data Term Ready (1) -> Clear To Send (2)
Clear To Send (2) -> Data Term Ready (1)
You should use twisted pairs for 6/3, 8/5, and 1/2, to improve
signal quality and reduce attenuation, especially in long cables.
You can use side-by-side pairs, as in telephone hookup cable, for
short cable runs.
Remember that because RS-422 uses a differential signal for
transmit and receive, you always need two transmit and two receive
pairs, and a break of either wire will cause communications in
that direction to fail. The advantage, however, is significantly
longer and more reliable cable runs than RS-232.
If you don't use hardware flow control, you can eliminate the 1/2
pair, but that's not recommended unless you know this cable will
be used only in software flow control situations.
Q: What's the pin mapping on the Newton-to-PC (DIN-to-DB9)
cable?
A: Here it is:
Note that the pin numbers shown are as defined above.
PC (DB9) Newton (DIN)
========================
1 1
2 3
3 5
4 7,2
5 4,8
6 1
7 N/C
8 N/C
9 N/C
N/C=not connected.
Apple MessagePad 100: 50 mA
Apple MessagePad 110: ~160 mA
Apple MessagePad 120: ~300 mA
Apple MessagePad 130: ~300 mA (with backlight off)
Apple MessagePad 130: (with backlight on, the maximum has not been characterized)
SafeRemovePackage().SuckPackageFromEndpoint(), or the
store method SuckPackageFromBinary() depending on
where the package is coming from.SafeRemovePackage until after you verify
(most likely with a deferred call) that the
SuckPackageFromEndpoint or
SuckPackageFromBinary has succeeded.SafeRemovePackage from
a function that's in the target package. You'll need to create a
small function which does nothing but remove the old package, and
then TotalClone that small function before executing it via a
deferred call. Otherwise you'd be chopping your package's legs out
from under itself, causing no end of havoc!installscript performs whatever checks are necessary,
and then conditionally calls SuckPackageFromBinary,
providing the binary object which holds the real package..pkg file that NTK produces into an
object in the NewtonScript environment in NTK. On Windows NTK,
LoadDataFile does this. On Macintosh NTK, the easiest
thing to do is use a utility such as Clipboard Magician to copy
the data from the .pkg file into a resource, then use
GetNamedResource to get the data in your installer
package. GetNamedResource and
LoadDataFile are documented in the Newton Toolkit
User's Guide. The MonacoTest sample code is a working example of a
package installer that uses this technique.func(pkgRef)
begin
local thelen:=extractword(pkgRef,26) div 2 -1;
local s:=" ";
while strlen(s)<thelen do
s:=s&s;
s:=substr(s,0,thelen);
BinaryMunger(s, 0, thelen*2, pkgRef,
52+(extractlong(pkgRef,48)*32)+extractword(pkgRef,24), thelen*2);
s;
end
Pin 1 HSKo /DTR
Pin 2 HSKi /CTS
Pin 3 TxD- /TD
Pin 4 GND Signal ground connected to both logic and chassis ground.
Pin 5 RxD- /RD
Pin 6 TxD+ (see below)
Pin 7 GPi General purpose input received at SCC's DCD pin.
Pin 8 RxD+ (see below)
Pin 9 Power out 5V@100ma. This pin only exists on the eMate 300 and the Newton Serial Adapter.
All inputs are:
Ri 12K ohms
minimum Vih 0.2v, Vil -0.2V
maximum tolerance Vih 15V, Vil -15V
All outputs are:
Rl 450 ohms
minimum Voh 3.6V, Vol -3.6V
maximum Voh 5.5V, Vol -5.5V
No more than 40mA total can be drawn from all pins on the serial
port. Pins 3 & 6 tri-state when SCC's /RTS is not
asserted.
The EIA RS-422 standard modulates its data signal against an
inverted (negative) copy of the same signal on another wire
(twisted pairs 3/6 & 5/8 above). This differential signal is
compatable with older RS-232 standards by converting to EIA
standard RS-423, which involves grounding the positive side of the
RS-422 receiver, and leaving the positive side of the RS-422
transmitter unconnected. Doing so, however, limits the usable
cable distance to approximately 50 feet, and is somewhat less
reliable.
The MessagePad 120 and the MessagePad 130 use a Linear Technology
LTC902 serial line driver. This part drives +5/-5 nominally for
the RS422 signals, and you can use just one half to interconnect
with RS232 compatible signal levels.
The MessagePad 2000 and the eMate 300 use a Linear Technology
LTC1323 serial line driver. This part drives +5/-5 nominally for
the RS422 signals, and you can use just one half to interconnect
with RS232 compatible signal levels.
CalibrateTablet
to open the "Align Pen" view. CalibrateTablet takes
no arguments, and does not return until the user has finished the
calibration.CalibrateTablet automatically saves the new
calibration information for you.
StringToDateFrame and StringToTime don't
seem to work. StringToDateFrame returns a frame with
NIL for all the time & day slots, and StringToTime
returns NIL.StringToDateFrame and
StringToTime: PrepareStringForDateTime := func (str)
begin // str is just a time string, nothing else belongs
local newStr := clone (str);
local tf:= GetLocale().timeFormat;
local startMin := StrPos (str, tf.timeSepStr1, 0);
local startSec := StrPos (str, tf.timeSepStr2, startMin+1);
// If a time seperator for seconds, then strip out seconds
if startSec then
begin
local skipSecSep := startSec + StrLen (tf.timeSepStr2);
local remainderStr := SubStr (
str, skipSecSep, StrLen (str) - skipSecSep);
local appendStr := StringFilter (
remainderStr, "1234567890", 'rejectBeginning);
newStr := SubStr (str, 0, startSec) & appendStr;
end;
return newStr;
end;GetDateStringSpec formats the supplied date elements
in reverse order. Is this is a bug?GetDateStringSpec uses the elements in reverse order,
although some functions that use dateStringSpecs may not observe
the order defined by the dateStringSpec. For instance, some
functions may use the elements of the dateStringSpec, but use the
element ordering defined by the locale bundle. GetDateStringSpec([[kElementYear, kFormatNumeric],[kElementMonth,
kFormatNumeric],[kElementDay, kFormatNumeric] ]); prefsView and place a reference to the template for
your preferences slip there (probably using the NTK
GetLayout function.) When the user selects "Prefs"
from the Info button in your application, the NewtApp framework
will create and open a view based on the template in the
prefsView slot.theApp
in the preferences view. Use this reference to call the
application's GetAppPreferences method. This method
will return a frame containing your application's preferences.
GetAppPreferences is a method provided by NewtApp and
should not be overidden.'|Pref1:SIG|) or create a slot in the
preferences frame using your developer signature and save all
preferences in that frame. This will guarantee that you don't
overwrite slots used by the NewtApp framework. preferencesSlip.viewSetupFormScript := func()
begin
prefs := theApp:GetAppPreferences();
if NOT HasSlot(prefs, kAppSymbol) then
prefs.(kAppSymbol) := {myPref1: nil, myPref2: nil};
end;
To save the preferences, call the application's
SaveAppState method:
preferencesSlip.viewQuitScript := func()
theApp:SaveAppState(); // save prefs
NewtApp currently provides one built-in preference for where to
save new items. In the preferences frame there will be a slot
called internalStore. Setting this slot to true
will force the NewtApp framework to save all new items on
the internal store.
aboutInfo. Place a
frame in that slot with the following slots: {tagLine: "", // A tagline for your application
version: "", // The version number for the application
copyright: "", // Copyright information
trademarks: "", // Trademark information
}
The information found in this frame will be displayed by the
NewtApp framework when the user selects "About" from the Info
button's popup. See the picture below for an example of what the
user will see.
Alternatively, you can create your own About view. If you do this,
create a slot in your application's base view called
aboutView containing a reference to a template for
your about view (probably using the NTK GetLayout
function.) A view will be created from that template and opened
when the user selects "About" from the Info button's popup.
NewtSoup continues to get the
FillNewSoup message, even when the soup already
exists. Am I doing something wrong?FillNewSoup message needs
to be sent. Check the "Setting the UserVisible Name With NewtSoup"
Q&A for more details and a description of how to work around
the problem.
RegUnionSoup?newtSoup called
MakeSoup which you can override. The
MakeSoup method is responsible for calling
RegUnionSoup (or otherwise making a soup) and then
calling the FillNewSoup method if the soup is
new/empty.MakeSoup is called normally as part of initializing
the newtSoup object. Here is a sample
MakeSoup method that will use a newly defined slot
(from the newtSoup based template) for the user
name.MakeSoup method. In
particular, MakeSoup is used by the
newtSoup implementation to initialize the object, so
it needs to set up other internal slots. It's vital that the
'appSymbol slot in the message context be set to the
passed argument, and that the 'theSoup slot be set to
the soup or unionSoup that MakeSoup creates or gets.
(Recall that RegUnionSoup returns the union soup,
whether it previously existed or not.)GetSoupList method of union soups used in this
code snippet returns an array with the member soups. It should be
considered documented and supported. A newly created union will
have no members, so FillNewSoup should be called.
This is an improvement over the default MakeSoup
method, which always calls FillNewSoup if the soup on
the internal store is empty.'userName slot, which is looked up in the current
context. As with soupName, soupDescr,
etc, you should set a new userName slot in the frame
in the allSoups frame in the newtApplication
template. MakeSoup: func(appSymbol)
begin
self.appSymbol := appSymbol; // just do it...
self.theSoup := RegUnionSoup(appSymbol, {
name: soupName,
userName: userName,
ownerApp: appSymbol,
userDescr: soupDescr,
indexes: soupIndices,
});
if Length(theSoup:GetSoupList()) = 0 then
:FillNewSoup();
end;
allSoups frame, and then cause the
application to refresh. The cursor that controls the sort order
for the layout is built from the masterSoupSlot slot.
Both the default and the overview layouts have a
masterSoupSlot which points back to the relevant
allSoups slot in the app base view.newtAppBase.allSoups &
newtAppBase.allSoups.mySoup are writeable. (Since the
frames reside in the package, they are in protected memory.)newtAppBase.allSoups.mySoup:SetupCursor()
to create a new cursor using the new query spec.newtAppBase:RedoChildren() to display
the items in the new sort order. if IsReadOnly (newtAppBase.allSoups) then
newtAppBase.allSoups := {_proto: newtAppBase.allSoups};
if IsReadOnly (newtAppBase.allSoups.mySoup) then
newtAppBase.allSoups.mySoup :={
_proto: newtAppBase.allSoups.mySoup};
newtAppBase.allSoups.mySoup.soupQuery :=
{indexpath: newKey}; // new sort order!
newtAppBase.allSoups.mySoup:SetupCursor();
newtAppBase:RedoChildren();newtApplication method NewtInstallScript
is normally called in the part's InstallScript
function. One thing the NewtInstallScript does is
register the viewDefs in the NewtApp base view
allViewDefs slot using the global function
RegisterViewDef.RegisterViewDef requires that the data
definition symbol be internal. If the symbol is on the card, then
when the NewtRemoveScript tries to unregister the
viewDef a reference to data on the card is encountered and the
above error message will be shown. This bug will be fixed in a
future ROM.InstallScript before calling
NewtInstallScript: local mainLayout := partFrame.theForm;
if mainLayout.allViewDefs then
foreach dataDefSym,viewDefsFrame in mainLayout.allViewDefs do
foreach viewDef in viewDefsFrame do
RegisterViewDef (
viewDef, EnsureInternal (dataDefSym) );
partFrame.removeFrame :=
mainLayout:NewtInstallScript(mainLayout);
RegisterViewDef
more than once with the same view definition.
RegisterViewDef will do nothing (and return NIL) if
the template is already registered.
newtLabelInputLines (and their variants) use to
accomplish their work.'flavor slot
of the newtLabelInputLine set of protos, which acts
as a translator between the target data frame (or more typically a
slot in that frame) and the text field which is visible to the
user. For example, it's the filter for
newtDateInputLines which translates the
time-in-minutes value to a string for display, and translates the
string into a time-in-minutes for the target data.newtFilter or one of the other specialized filters
described in Chapter 4 of the Newton Programmer's Guide.newtLabelInputLine is opened, a new filter
object is instantiated from the template found in the
'flavor slot for that input line. The instantiated
filter can then be found in the filter slot of the
view itself. The _parent slot of the instantiated
filter will be set to the input line itself, which allows methods
in the filter to get data from the current environment.inputLine part of the
field, and the rest are methods which you can override or call as
appropriate.recFlagsprotoLableInputLine. This
provides the 'viewFlags settings for the
inputLine part of the proto -- the field the user
interacts with.recTextFlags'textFlags settings for the
inputLine part of the proto.recConfig'recConfig settings for the
inputLine part of the proto.dictionaries'dictionaries slot used in recognition,
Provides custom dictionaries if vCustomDictionaries
is on in the recFlags slot.PathToText()inputLine needs to be updated. The
function should read data out of the appropriate slot in the
'target data frame (usually specified in the
'path slot) and return a user-visible string form of
that data. For example, for numbers the function might look like
func() NumberStr(target.(path))TextToPath(str)inputLine value changes. The result
will be written into the appropriate slot in the
'target data frame. The string argument is the one
the user has modified from the inputLine part of the
proto. For example, for numbers the function might look like
func(str) if StrFilled(str) then
StringToNumber(str)Picker()PickActionScript message. If the picker is
cancelled, send a PickCancelledScript message.labelCommands
array.PickActionScript( newValue )Picker method. If you override this method be sure to
call the inherited PickActionScript method.PickCancelledScript()Picker
method. If you override this method be sure to call the inherited
PickCancelledScript method.InitFilter()inputLine
that uses this filter is first opened. This method can be used to
get data from the current environment (for example, the
'path slot of the inputLine) and adjust
other settings as appropriate.
newtApplication slot called
helpManual. You should store a reference to your help
book in this slot.viewHelpTopic which you
can use to dynamically change the location the help book is opened
to. This slot should store the name of the topic to open to.newtEditView or
newtROEditView, I cannot scroll through all the text
of a large note. After a few pages it stops scrolling. What is
going wrong?newtEditView and newtROEditView
have a default scroll height of 2,000 pixels. To work around this
limitation, you will need to add a slot called
noteSize to your newt(RO)editView. This
slot should hold an array of two elements. The first element is
the scroll width. If you do not want horizontal scrolling, the
scroll width should equal the view width. The second element is
the scrollHeight.noteSize slot that you would use
to create a newt(RO)EditView with a scroll height of
20,000 pixels. {
_proto: newtEditView,
noteSize: [viewWidth, 20000],
...
}
newtApp-based application which does
not use stationery. If I set the forceNewEntry slot
to nil in my layout and open the application with a
nil target, I can still see the entry view. How can I
avoid this?newtApp framework will not open the stationery if a
target does not exist.
newtEntry(Roll/Page)Header proto has a
PopIt method which opens the header. You will need to
override the StatScript of your
newtNewStationeryButton and send the header a
PopIt message. Because PopIt is not
defined prior to Newton 2.1 OS, you will need to check for its
existence before calling it. Here is a code example: newtNewStationeryButton. StatScript: func( theStat )
begin
// Keep a copy of the inherited return value for use below
local result := inherited:?StatScript( theStat );
// Pass self as a parameter for the closure. This gives us a reference
// to the application so we can get the entry view.
AddDeferredCall( func( context )
begin
local entryView := context:GetTargetView();
// This code assumes that your header is declared to the entry
// view with the name theHeaderView
if entryView.theHeaderView.popIt then
entryView.theHeaderView:Popit( true );
end,
[self] );
result;
end;'default in its
symbol slot. To change this behavior at run-time, you
will need to override the StatScript method of your
newtNewStationeryButton.StatScript method, you will set two slots in
your application. The first slot is the
preferredViewDef slot in your application's base
view. The second is the viewDef slot of the current
layout. Both of these slots should be set to the symbol of the
viewDef that you want displayed. For instance, you might have the
following StatScript:StatScript := func( theStat )
begin
preferredViewDef := 'myNewDefaultStationery;
layout.viewDef:= 'myNewDefaultStationery;
// Make sure we call the inherited method
inherited:?StatScript( theStat );
end;
Note: you must not modify either the application's
preferredViewDef slot or the layout's
viewDef slot at any other time. Doing so could cause
your application to not work on future versions of the Newton OS.
newtEntryPageHeader which is declared
to my newtLayout view. Each time I change entries in
my application, the header does not get properly updated. What's
going wrong?newtApplication views, they
need to be declared to their parent. Declaring
newtApplication views to a grandparent can cause
undefined behavior.overviewTargetClass slot to your
application (or any other layout that is a descendent of your
newtOverLayout). Set this slot's value to be the
symbol that represents your data class (for example,
'|myData:SIG|), which must match the data class you
use when registering your print format. The NewtApp overview will
use overviewTargetClass instead of the default
overview class ('newtOverview) supplied by
newtOverLayout.usesCursors slot to true indicating that
it will use the value target as a multiple item target and it will
iterate over it using GetTargetCursor(target). For an
example of a print format that can handle multiple items, see the
MultiRoute DTS sample.'newtOverview) , see the Q&A "Limitations with
NewtOverview Data Class".prefsCache slot of your NewtApp-based
application. This slot is defined in your application's base view
by the NewtApp framework. This frame will be saved to the system
soup when the application closes.prefsCache frame, you must use
your registered signature to avoid conflicting with slots that the
framework may use. You can name each of your preferences with your
signature, or we recommend adding a subframe in a slot named with
your signature. For instance, you might have the following
code:prefsCache.('|MyPrefs:MySIG|) := {pref1: 1, pref2:
2};newtCheckAllButton (@872) which you can
use. This proto sends the CheckAll method to the
layout. In Newton 2.1 OS, newtOverLayouts have two
new methods, CheckAll and UncheckAll,
which implement this behavior. However, none of this is present in
Newton 2.0 OS .CheckAll and UncheckAll methods for your
overview layout (or any other layout you wish to implement check
all for.)protoCheckAllButton. These
samples implement an earlier (and less useful) flavor of Check
All. The old samples check all the items which are currently
visible in the overview, while the Newton 2.1 OS checks all the
items that are present in the currently selected folder/card
filter. "Checkbook" (version 8 or later) or "WhoOwesWhom" (version
3 or later) will reflect the Newton 2.1 behavior.protoCheckAllButton from the older sample code, since
that gives the correct look and button bounds, and modify it as
follows:buttonClickScript should look
something like this: func()
if newtAppBase.currentLayout = 'overView then
begin
if layout.checkAllPrimed then
layout:UnCheckAll()
else
layout:CheckAll();
layout.checkAllPrimed := NOT layout.checkAllPrimed;
end;
The overview layout's CheckAll and UncheckAll methods should look
something like this:
CheckAll:
func()
begin
local curse := dataCursor:Clone();
curse:Reset();
hilitedIndex := nil;
selected := MapCursor(curse, func(e) MakeEntryAlias(e));
AddUndoSend(layout, 'UnCheckAll, []);
layout:DoRetarget();
end;
UncheckAll:
func()
begin
hilitedIndex := nil;
selected := nil;
layout:DoRetarget();
end
Note that these methods make use of two undocumented slots:
hilitedIndex and selected.
hilitedIndex is used internally by
newtOverLayout to track the tapped item. You may set
it to NIL (as above) to clear the value, but do not
set it to some other value or rely on its current value.
selected contains an array of aliases to soup entries
representing the currently selected items, and will be used by the
routing and filing buttons for processing entries. It is important
to clear hilitedIndex when modifying the
selected array in any way.
The resulting CheckAll button should be included in the
menuRightButtons array for the status bar. The older
sample code puts it on the left, however user interface
discussions as part of the Newton 2.1 OS effort resulted in the
decision to place the button on the right.
newtApplication. allLayouts: {
default: GetLayout("default.t"),
overview: GetLayout("Overview.t"),
}
allSoups: {
mySoup: {
_proto: newtSoup,
soupName: "SoupName:SIG",
soupIndices: [],
soupQuery: {} } }
title: kAppName
newtClockFolderTab or
newtFolderTab as a child of the
newtApp.
5) Draw a newtStatusBar as a child of the
newtApp.
6) For the newtStatusBar set the following slots:
menuLeftButtons: [newtInfoButton]
menuRightButtons: [newtActionButton, newtFilingButton]
"main.t" and add it
to the project.
Create the default view:
1) Create another layout file.
2) Draw a newtLayout in the new layout file.
3) Add a viewJustify slot to the newtLayout
and set it to parentRelativeFull horizontal
and vertical.
4) Set the viewBounds of the newtLayout
to:
{top: 20, // leave room for the folder tab
bottom: -25, // leave room for the status bar
left: 0,
right: 0}
newtEntryView as a child of the
newtLayout.
6) Add a viewJustify slot and set it to
parentRelativeFull horizontal and vertical (necessary
only until platform file is updated).
7) Set the viewBounds of the newtEntryView to:
{top: 0, bottom: 0, right: 0, left: 0};
For example:
a) Draw a newtLabelInputLine as a child of the
newtEntryView.
b) Set the following slots:
label: "My Label"
path: 'myTextSlot
newtLabelNumInputLine as a child of
the newtEntryView.
d) Set the following slots:
label: "Number"
path: 'myNumberSlot
"default.t" and add
it to the project. Move it so that it is compiled before the main
layout (use the Process Earlier menu item).
Add Overview support
1) Create another layout file.
2) Draw a newtOverLayout in the new layout file.
3) Add the Abstract slot to the
newtOverLayout, for example:
Abstract := func(item, bbox )
begin
local t := item.myTextSlot & ",";
if item.myNumberSlot then
t := t && NumberStr(item.myNumberSlot);
MakeText(t, bbox.left+18, bbox.top,
bbox.right, bbox.bottom - 18);
end;
Add InstallScript and RemoveScript
1) Create a text file and add the following to it:
InstallScript := func(partFrame) begin
partFrame.removeFrame :=
(partFrame.theForm):NewtInstallScript(partFrame.theForm);
end;
RemoveScript := func(partFrame) begin
(partFrame.removeFrame):
NewtRemoveScript(partFrame.removeFrame);
end;
callbackID parameter to the
RegSoupChange global function. If you also use your
application's symbol as the callbackID parameter, you
will overwrite the NewtApp framework's registration. There are two
ways to work around this problem.callbackID symbol in your call to
RegSoupChange.NewtSoupChangedNotify method is called. It is passed
the same four parameters as the callback function parameter of
RegSoupChange.NewtSoupChangedNotify method,
be sure to call the inherited method. application:NewtSoupChangedNotify(theName, appSym, changeType, changeData)
begin
// Do your stuff here
inherited:?NewtSoupChangedNotify( theName, appSym, changeType, changeData );
end;packed)
to prevent aligning of the fields by the compiler. I tried to use
the keyword and got an error. How can I ensure that a structure is
packed?__packed, which is probably worth a try. Using this
directive may cause the compiler to stop with an internal error in
some circumstances, so be prepared. You should ensure that the
structure produced has the correct alignment by using the C
sizeof and offsetof functions, since
this directive does introduce a compiler dependency. Accessing
elements in __packed structures can be considerably
less efficient than using non-packed structures: use them only
when necessary. For example: __packed struct T { char c; int i; };
__packed directive, it would be 8 bytes wide and the
integer field would begin 4 bytes from the structure start, so
that it was word aligned.
We believe the internal error in the compiler can be avoided by
taking the sizeof the structure before using it. An easy way to do
this is to add a dummy function right after the structure is
declared. For example:
inline void dummyT() { (void)sizeof(T); }
Primitive types can also be declared __packed, which
means that the compiler will not make assumptions about the
alignment of pointers to them. That is, if you know an int starts
two bytes into a word-aligned data structure, the wrong thing will
happen if you simply cast the pointer to int.
Instead, you can used an unaligned int type. This
generates considerably less efficient code than is needed for
working with aligned values, but it's still more efficient that
trying to extract the proper bytes and shift/add them into an
integer youself. For example:
typedef __packed int UNALIGNED_INT;
int IntAt(UNALIGNED_INT* p) { return *p; }
This directive does not work properly with bitfield specifiers.
For example:
__packed struct Foo {
unsigned flag1 : 1;
unsigned flag2 : 1;
unsigned data1 : 6;
unsigned short data2;
}
will not produce what you expect. Instead, avoid the bitfield
specifiers and take advantage of C++ inline functions to access
the partial bytes:
__packed struct Foo {
char stuff;
unsigned short data2;
int Flag1() { return (stuff & 0x80) != 0; }
int Flag2() { return (stuff & 0x40) != 0; }
int Data1() { return stuff & 0x3F; }
int Data2() { return data2; }
};
inline void dummyFoo() { (void)sizeof(Foo); }
The result is a 3-byte wide data structure with the bitfields
easily accessible.
__packed directive. ProtocolGen does
not make use of structure sizes, so it's OK to NOP out the
__packed keyword for that tool. Here's an easy way to
do that:
#ifdef PROTOCOLGEN
#define __packed
#endif
AfterScript to set the
appropriate slot in the view to point to the ROM based PICT
(assuming that the constant for the PICT is defined in the NTK
definitions file AND documented in the Newton Programmers Guide).
Use something like this in the AfterScript:thisView.icon := ROM_RouteDeleteIcon;protoStaticText text
slot that is in one linked layout window from a button that is in
another linked layout window. I tried to allow access to the base
view from both linked layouts, but this didn't help. I even tried
to allow access from the base view to both layouts, but this
didn't help, either. What should I do?textThatChanges
which a child of a view called changingContainer and
is declared to changingContainer with the name
textThatChanges. ChangingContainer is
the base view for a layout which is linked into the main layout,
and the link (in the main layout) is declared as
changingContainerLink. Code in the main layout can
change the text of the textThatChange view like
so: SetValue(containerLink.whatToDo, 'text, "Turn and face the...")
To do the equivalent of the declare yourself:
1) In the viewSetupFormScript script of the
'buttonThatChanges button, set the value of the base
view's slot 'theTextView to self, as in
the following code fragment:
func()
begin
base.theTextView := self;
end
buttonClickScript script of the
'buttonThatSetsText button, use the global function
SetValue to store new text in the text slot of the
'buttonThatChanges button, as in the following code
fragment:
func()
begin
SetValue(base.theTextView, 'text, "Now something happened!");
end
base. In your application, you may access your
base view in a different way.
StrCompare can return
different results at compile time than it does at run time. What
gives?StrCompare on an given Newton unit. Here is one
such function for English releases of the Newton OS (which assumes
strings using only page 0 of the unicode table):constant kNSortTable := '[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24, 25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46, 47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68, 69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90, 91,92,93,94,95,96,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80, 81,82,83,84,85,86,87,88,89,90,97,98,99,100,101,102,103,104,105,106, 107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122, 123,124,125,126,127,128,129,130,131,132,133,161,157,135,136,165, 149,138,137,143,141,152,159,158,144,140,170,134,146,147,148,142, 150,138,168,171,151,153,160,153,154,155,156,174,174,174,174,65, 65,145,67,175,69,175,175,176,176,176,176,162,78,177,177,177,79, 79,164,79,178,178,178,85,166,167,139,65,65,65,65,65,65,145,67,69, 69,69,69,73,73,73,73,169,78,79,79,79,79,79,163,79,85,85,85,85,172, 173,89];
// function to compare strings (only page 0 characters)
// with the same order as the Newton ROM does.
DefConst('kNewtonStrCompare, func(s1, s2)
begin
local l1 := StrLen(s1);
local l2 := StrLen(s2);
local l := Min(l1, l2);
local i := 0;
while i < l and
(r := kNSortTable[ord(s1[i])] - kNSortTable[ord(s2[i])]) = 0 do
i := i + 1;
if i = l then
l1-l2
else
r;
end);
call func(theFrame) begin
local i := 0;
foreach slot, value in theFrame do begin
print(i && ': && slot);
i := i + 1;
end
end with (<the reordered frame>)
Main Build time
heap size (+/- 0.5 sec)
1250K Main heap ran out of memory...
1275K 32.7 sec
1300K 26.4 sec
1400K 22.3 sec
1500K 19.2 sec
1600K 17.5 sec
2000K 16.0 sec
3000K 15.2 sec
Experiment with Main heap size by measuring build time until you
find a reasonable compromise between build time and memory
requirements for your particular project.
If you are curious about GC activity, do the following:
1) Add the following line to your GlobalData file (in
the NTK folder) and restart NTK:
protoEditor:DefineKey({key: 65}, 'EvaluateSelection);
GlobalData file.
2) Type VerboseGC(TRUE) in the Inspector window,
select, and hit the keypad-period key. Each time the GC kicks in,
a line will be displayed in the Inspector window. By watching the
frequency of GCs, you can get some idea of how your main heap is
being used.
3) Use VerboseGC(FALSE) to turn this feature off.
Please note that VerboseGC is available only in the
NTK build-time environment. The function does not exist on the
Newton device itself. It should be used only for debugging and
optimization.
Build Heap
The Build heap holds your package frame data during the last
part of the build. Its size is set through the Toolkit Preference
dialog. Changes take effect immediately.
The Build heap is allocated only when the Build Package command is
issued. It is released as soon as the resulting file is written to
disk. As a result Build heap allocation is a recurring issue.
The rule of thumb is to set the Build heap to the size of your
package (on the MacOS computer hard disk, not on the Newton
device). If the Build heap is insufficient, NTK will tell you
so.
There is nothing to be gained by setting the Build heap larger
than necessary.
NTK first attempts to allocate the Build heap from MultiFinder
memory. If that fails, NTK tries to allocate the Build heap from
NTK's partition.
To verify that you have enough memory for the Build heap you need
to look at the "About This Macintosh" dialog in the Finder
application just prior to issuing the build command.
1) If the "Largest Unused Block" exceeds the Build heap requested
size, the Build heap will be allocated from MultiFinder
memory.
2) If 1 failed and NTK's partition bar shows enough free memory to
accommodate the request, the Build heap will be allocated in NTK's
partition.
3) If both 1 and 2 failed, the build will fail. Try to increase
MultiFinder free memory by quitting any other open application, or
increase the free memory in NTK's partition by closing some or all
of NTK's open windows. Then try building again.
To prevent fragmentation of MultiFinder memory launch NTK first,
and DocViewer, ResEdit, etc. afterwards. Whenever possible, quit
those other applications in the reverse order .
Note: You can use Balloon help to see how much memory an
application is actually using. Simply select the Show Balloons
menu item and position the cursor on the application partition bar
in the About Macintosh dialog. This feature is missing from
PowerPC-based MacOS computers.
NTK Partition Size
For NTK 1.6 the rule of thumb for the "smallest useful"
partition size for small projects is:
(3500K + Main heap size) for a 680x0 MacOS computer
(5500K + Main heap size) for a PowerPC MacOS computer with Virtual
Memory off.
These rules do not include space for the Build heap.
The "smallest useful" partition size is defined by the following
example: Using NTK default Main and Build heaps, open the
Checkbook sample. Open one browser and one layout window for each
file in the project, connect the Inspector, build and download.
Perform a global search on "Check" (case insensitive) producing
slightly more than 200 matches. Double click on several of these
matches displayed in the search results window. Build and download
again.
For serious work, increase the partition size by at least 256K for
small projects, more for large ones. If you routinely perform
global searches that produces many matches, see the next
section.
On a PowerPC-based MacOS computer with Virtual Memory on, NTK's
2.7 Meg of code (the exact number is shown in the Finder Info
dialog) stays on the hard disk, reducing memory requirements at
the expense of performance.
if x = 1 then
dosomething
else
if x = 2 then
doSomethingElse
else
if x = 3 then
doYetAnotherThing
else
if x = 4 then
doOneMoreThing
else
if x = 5 then
doSomethingSimple
else
if x = 6 then
doThatThing
else
if x = 7 then
doThisThing
else // x = 8
doTheOtherThing
if x <= 4 then
if x <= 2 then
if x = 1 then
doSomething
else // x = 2
doSomethingElse
else
if x = 3 then
doYetAnotherThing
else // x = 4
doOneMoreThing
else
if x <= 6 then
if x = 5 then
doSomethingSimple
else // x = 6
doThatThing
else
if x = 7 then
doThisThing
else // x = 8
doTheOtherThing;
Use an array of functions with integer selectors
Replace a long if-then-else statement with an array of
functions. The code is more compact and readable. For a large set
of alternatives, the faster direct lookup should compensate for
the extra function call. This approach is most useful for a
contiguous range of selector values (e.g., 11 to 65). It can
accommodate a few "holes" (for example, 11 to 32, 34 to 56, 58 to
65). It is not practical for non-contiguous selectors (e.g., 31,
77, 256, 1038...)
For example, the following code:
if x = 1 then
dosuchandsuch;
else
if x = 2 then
dosomethingelse;
else
if x = 3 then
andsoon;
cmdArray := [func() dosuchandsuch,
func() dosomethingelse,
func() andsoon];
call cmdArray[x] with ();
Use a frame of functions with symbols for selectors
This alternative provides the flexibility of using symbols for
selecting the outcome.
For example, the following code:
if x = 'foo then
dosuchandsuch;
else
if x = 'bar then
dosomethingelse;
else
if x = 'baz then
andsoon;
...can be rewritten like this:
cmdFrame := {foo: func() dosuchandsuch,
bar: func() dosomethingelse,
baz: func() andsoon};
call cmdFrame.(x) with ();
Open the Newton Toolkit application with ResEdit.
Double-click on the "mem!" resource icon
Double-click on resource ID 1000 named "Additional
NTK Memory Requirements"
Change the fifth (and last) value. This is an hexadecimal number.
In NTK 1.6, you should see "0001 8000" which is
98304 bytes (or 96k) to add to the total
stack size. For example, to increase this value to
128k = 131072 bytes change the
hexadecimal value to "0002 0000".
DeclareUnit, before
it's used (imported or exported.) See the docs on
DeclareUnit below for details.DefineUnit and specify the NS
objects that are exported.UnitReference (or UR for short.)DeclareUnit(unitName, majorVersion, minorVersion, memberIndexes)
unitName
majorVersion - integer - major version number of the
unit
minorVersion - integer - minor version number of the
unit
memberIndexes - frame - unit member name/index pairs
(slot/value)
return value - unspecified
DeclareUnit before
it's used (imported or exported.) The declaration maps the member
names to their indexes. A typical declaration looks like:
DeclareUnit('|FastFourierTransforms:MathMagiks|, 1, 0, {
ProtoGraph: 0,
ProtoDataSet: 1,
});
Typically, the declarations for a unit are provided in a file,
such as "FastFourierTransforms.unit", that is added to an NTK
project (similar to .h files in C.)
When resolving imports, the name and major version specified by
the importer and exporter must match exactly. The minor version
does not have to match exactly. If there are units differing only
in minor version, the one with the largest minor version is
used.
Typically, the first version of a unit will have major version 1
and minor version 0. As bug fixes releases are made, the minor
version is incremented. If a major (incompatible) change is made,
then the major version number is incremented.
Note: When a unit is modified, the indexes of the existing members
must remain the same. In other words, adding new members is safe
as long as the indexes of the existing members don't change. If
you change a member's index it will be incompatible with any
existing clients (until they're recompiled with the new
declaration.)
DefineUnit(unitName, members)
unitName
members - frame - unit member name/value pairs
(slot/value)
return value - unspecified
DefineUnit exports a unit and specifies the value of
each member. Immediates and symbols are not allowed as member
values. A typical definition looks like:
DefineUnit('|FastFourierTransforms:MathMagiks|, {
ProtoGraph: GetLayout("foo.layout"),
ProtoDataSet: { ... },
});
A unit must be declared before it's defined. The declaration used
when exporting a unit with n members must contain
n slots with indexes 0..n-1. The
definition must specify a value for every declared member (this is
important.)
UnitReference(unitName, memberName)
UR(unitName, memberName)
unitName
memberName - symbol - name of a member of unit
return value - a reference to the specified member
To use a unit member call UnitReference (UR
for short) with the unit and member name.
The unit name 'ROM can be used to refer to obects in
the base ROM. For example:
UR('ROM, 'ProtoLabelInputLine).
Note: references to objects in the base ROM are sometimes called
"magic pointers" and have traditionally been provided in NTK by
constants like ProtoLabelInputLine or
ROM_SystemSoupName.
In Newton 2.0 OS, there may also be packages in the ROM. These ROM
packages may provide units. Their members are referenced just like
any other unit, using UR, the unitName, and the
memberName. This is the mechanism by which licensees can provide
product-specific functionality.
AliasUnit(alias, unitName)
alias
unitName - symbol - name of a unit
return value - unspecified
AliasUnit provides a way to specify an alternate name
for a unit. Since unit names must be unique, they tend to be long
and cumbersome. For example:
AliasUnit('FFT, '|FastFourierTransforms:MathMagiks|);
...so that you could write:
local data := UR('FFT, 'ProtoDataSet):New(points);
...instead of:
local data := UR('|FastFourierTransforms:MathMagiks|,
'ProtoDataSet):New(points);
AliasUnitSubset(alias, unitName, memberNames)
alias
unitName - symbol - name of a unit
memberNames - array of symbols - list of unit member
names
return value - unspecified
AliasUnitSubset is similar to AliasUnit,
except that it additionally specifies a subset of the units
members which can be used. This helps restrict code to using only
certain members of a unit.
Unit Part Frame Methods
These methods can optionally be defined in a part frame to handle
units becoming unavailable.
RemovalApproval(unitName, majorVersion, minorVersion)
unitName
majorVersion - integer - major version number of the
unit
minorVersion - integer - minor version number of the
unit
return value - nil or string
This message is sent to a part frame when an imported unit is
about to be deactivated. It may a return a string to be shown to
the user as a warning about the consequences of deactivating the
package in use. For example:
"This operation will cause your connection to fooWorld to be dropped."
Note: do not assume that the user is removing the package. Other
operations such as moving a package between stores also cause
package deactivation.
This message is only a warning. The user may decide to proceed and
suffer the consequences. If the user proceeds, the
ImportDisabled message (see below) will be sent.
If the removing the unit is not a problem (for example, your
application is closed), then RemovalApproval can
return nil and the user will not be bothered.
ImportDisabled(unitName, majorVersion, minorVersion)
unitName
majorVersion - integer - major version number of the
unit
minorVersion - integer - minor version number of the
unit
return value - unspecified
This message is sent to a part frame after an imported unit has
been deactivated. The part should deal with the situation as
gracefully as possible. For example, use alternative data or put
up a Notify and/or close your application.
Unit-Related Glue Functions
These functions are available in the Newton 2.0 Platform file.
MissingImports(pkgRef)
nil or an array of frames (see
below)
glue name - kMissingImportsFunc
MissingImports lists the units used by the specified
package that are not currently available. MissingImports
returns either nil, indicating there are no missing units,
or an an array of frames of the form:
{
name: symbol - name of unit desired
major: integer - major version number
minor: integer - minor version number
<other slots undocumented>
}
mySoup:Query({words: "pizza"}) don't sucessfully find the
entries. Why?SetClass(SetLength("\u<hex data>"),
theLength), theClass) in Windows NTK , the binary object is
not what I expect. It seems to be byte-swapped. How can I create
binary objects with data in them in Windows NTK?MakeBinaryFromHex() function; it handles the
byte-swapping issues properly. This function is defined by the
platform file, and only runs at build-time -- it doesn't exist on
the Newton device. You may need to get a newer platform file
because this function was added after Windows NTK 1.6 shipped.
myEncloser := {
importantSlot: 42,
GetImportantSlot := func()
return importantSlot,
nestedSlot := {
myInternalValue: 99,
getTheValue := func()
begin
local foo;
foo := :GetImportantSlot(); // WON'T WORK; can't find function
foo := myEncloser:GetImportantSlot(); // MAY WORK
importantSlot := 12; // WON'T WORK; will create new slot in nestedSlot
myEncloser.importantSlot := 12; // MAY WORK
end
}
};
myEncloser.nestedSlot:GetTheValue();
_parent or _proto slot that
references the enclosing frame. Nesting the frame is not strictly
necessary in this case, only the _proto or
_parent references are used.
MyFrame:= {}; theSlotName := "Slot_1";
At this point is there a way to then create the following?...
MyFrame.Slot_1
A: The function Intern takes a string and returns a
symbol. There is also a mechanism called path expressions (see the
NewtonScript Reference), that allows you to specify an expression
or variable to evaluate, in order to get the slot name. You can
use these things to access the slots you want:
MyFrame := {x: 4};
theXSlotString := "x" ;
MyFrame.(Intern(theXSlotString)) := 6
theSlotName := "Slot_1";
MyFrame.(Intern(theSlotName)) := 7;
// myFrame is now {x: 6, Slot_1: 7} call func()
begin
local s,v;
local root := GetRoot();
local base := root.|YourApp:YourSIG|; // name of app
local prot := base._proto;
foreach s,v in base do
begin
if v and v <> root AND v <> base AND v <> prot then
begin
Write ("Slot:" && s & ", Value: ");
Print(v);
end;
end;
end with ()
TrueSize can also be a
valuable tool to determine the heap used by your applications. See
the NTK User Guide for more information about
TrueSize.
thrower: func(x) begin
if x then
throw('|evt.ex.msg;my.exception|, "Some error occurred");
end;
returner: func(x) begin
if x then
return -1; // some random error code,
0; // nil, true, whatever.
end;
local s;
for i := 1 to kIterations do
try
call thrower with (nil);
onexception |evt.ex.msg;my.exception| do
s := CurrentException().data.message;
Code to check the return value and handle an error:
local result;
local s;
for i := 1 to kIterations do
if (result := call returner with (nil)) < 0 then
s := ErrorMessageTable[-result];
Running the above loops 1000 times took about 45 ticks for the
exception loop, and about 15 ticks for the check the return value
loop. From this you might conclude that exception handling is a
waste of time. However, you can often write better code if you use
exceptions. A large part of the time spent in the loop is setting
up the exception handler. Since we commonly want to stop
processing when exceptions occur, we can rewrite the function to
set up the exception handler once, like this:
local s;
try
for i := 1 to kIterations do
call thrower with (nil);
onexception |evt.ex.msg;my.exception| do
s := CurrentException().data.message;
This code takes only 11 ticks for 1000 iterations, an improvement
over the return value case, where we'd have to check the result
after each call to the function and stop the loop if an error
occurred.
Running the same loops, but passing TRUE instead of
NIL so the "error" occurs every time was interesting.
The return value loop takes about 60 ticks, mostly due to the time
needed to look up the error message. The exception loop takes a
whopping 850 ticks, mostly because of the overhead in the
CurrentException() call.
With exceptions, you can handle the error at any level up the call
chain, without having to worry about each function checking for
and returning error results for every sub-function it uses. This
will produce code that performs much better, and will be easier to
maintain as well.
With exceptions, you do not have to worry about the return value
for successful function completion. It is occasionally very
difficult to write functions that both have a return value and
generate an error code. The C/C++ solution is to pass a pointer to
a variable that is modified with what should otherwise be the
return value of the function, which is a technique best
avoided.
As in the above example, you can attach data to exceptions, so
there's no need to maintain an error code to string (or whatever)
mapping table, which is another boon to maintainability. (You can
still use string constants and so on to aid localization efforts.
Just put the constant in the throw call.)
Finally, every time an exception occurs you have an opportunity to
intercept it with the NTK inspector. This is also a boon to
debugging, because you know something about what's going wrong,
and you can set the breakOnThrows global to stop your
code and look at why there's a problem. With result codes you have
a tougher time setting break points. With a good debugger it could
be argued that you can set conditional break points on the "check
the return value" code, but even when you do this you'll have lost
the stack frame of the function that actually had the problem.
With exceptions and breakOnThrows, all the local
context at the time the exception occurred is still available for
you to look at, which is an immense aid.
Conclusion: Use exceptions. The only good reason not to would be
if your error handler is very local and if you expect it to be
used a lot, and if that's true you should consider rewriting the
function.
PrimClassOf will return an object's primitive
type.String. A string object contains a 12-byte header
plus the Unicode strings plus a null termination character. Note
that Unicode characters are two-byte values. Here's an
example: "Hello World!"
Rich Strings
Rich strings extend the string object class by embedding ink
information within the object. Within the unicode, a special
character kInkChar is used to mark the position of an
ink word. The ink data is stored after the null termination
character. Ink size varies depending on stroke complexity.
Array Objects
Array objects have an object header (12 bytes) and additional
four bytes per element which hold either the immediate value or a
reference to a referenced object. To calculate the total space
used by an array, you need to take into account the memory used by
any referenced objects in the array.
Here's an example:
[12, $a, "Hello World!", "foo"]
Frame Objects
We have two kinds of frames: frames that don't have a shared
map object; and frames that do have a shared map object. We take
the simple case first (no shared map object).
The frame is maintained as two array-like objects. One, called the
frame map, contains the slot names, and the other contains the
actual slot values. A frame map has one entry per symbol, plus one
additional 4 -byte value.
The frame map uses a minimum of 16 bytes. If we add the frame's
object header to this, the minimal size of a frame is 28 bytes.
Each slot adds 8 bytes to the storage used by the frame (two array
entries.) Here's an example:
{Slot1: 42, Slot2: "hello"}
Multiple similar frames (having the same slots) could share a
frame map. This will save space, reducing the space used per frame
(for many frames all sharing the same map) to the same as used for
an array with the same number of slots. (If just a few frames
share the frame map, we need to take into account the amortized
map size that the frames share. So the total space for N frames
sharing a map is N*28 bytes of header per frame, plus the size of
the frame map, plus the size of the values for the N frames.
Here's an example of a frame that could share a map with the
previous example:
{Slot1: 56, Slot2: "world"}
When do frames share maps?
1. When a frame is cloned, both the copy and the original frame
will share the map of the original frame. A trick to make use of
this is to create a common template frame, and clone this template
when duplicate frames are needed.
2. Two frames created from the same frame constructor (that is,
the same line of NewtonScript code) will share a frame map. This
is a reason to use RelBounds to create the
viewBounds frame, and it means there will be a single
viewBounds frame map in the part produced.
Note: These figures are for objects in their run-time
state, ready for fast access. Objects in transit or in storage
(packages) are compressed into smaller stream formats. Different
formats are used (and different sizes apply) to objects stored in
soups and to objects being streamed over a communications
protocol.
if value.path = '|name.first| then ... // WRONG
'|name.first|
is not a path expression, it is a symbol with an escaped period. A
proper path expression is either 'name.first or
[pathExpr: 'name, 'first]. The vertical bars escape
everything between them to be a single NewtonScript symbol.
The test value.path = 'name.first will always fail,
because path expressions are deep objects (essentially arrays) the
equal comparison will compare references rather than contents. You
will have to write your own code to deeply compare path
expressions.
This code is further complicated by the fact that symbols are
allowed in place of path expressions that contain only one
element, but the two syntaxes produce different NewtonScript
objects with different meanings. That is, 'name = [pathExpr:
'name] will always fail, as the objects are different.
A general test is probably unnecessary in most circumstances,
since you will be able to make assumptions about what you are
looking for. For example, here is some code that will check if a
given path value from a soup index is equivalent to
'name.first:
if ClassOf(value.path) = 'pathExpr and Length(value.path) = 2
and value.path[0] = 'name and value.path[1] = 'first then ...
...
local myFunc := func(...) ...;
local futureSoupEntries := Array(10, nil);
for i := 0 to 9 do
futureSoupEntries[i] := {
someSlots: ...,
aFunction: myFunc,
};
...
Functions constructed within another function, as in your example,
will have this enclosing lexical scope, which is the locals and
parameters of the function currently being executed, plus the
message context (self) when the function is created. Depending on
the size of this function and how it's constructed, this could be
very large. (Self might be the application's base view, for
example.)
A TotalClone is made during the process of adding an
entry to a soup, and this includes the function body, lexical
scopes, and message context bound up within any functions in the
frame. All this can take up a lot of space.
If you create the function at compile time (perhaps with
DefConst('kMyFunc, func(...) ...)) it will not have
the lexically enclosing scope, and the message context at compile
time is defined to be an empty frame, and so cloning such a
function will take less space. You can use the constant
kMyFunc within the initializer for the frame, and
each frame will still reference the same function body.
(Additionally, the symbol kMyFunc will not be
included in the package, since it is only needed at compile
time.)
If the soup entries are only useful when your package is
installed, you might consider instead replacing the function body
with a symbol when you write the entry to the soup. When the entry
is read from the soup, replace the symbol with the function
itself, or use a _proto based scheme instead. Each
soup entry will necessarily contain a complete copy of the
function, but if you can guarantee that the function body will
always be available within your application's package, it might be
unnecessarily redundant to store a copy with each soup entry.
TrueSize to get the size of a soup
entry I get results like 24K or even 40K for the size. That can't
be right. What's going on?TrueSize "knows" about the underlying
implementation of soup entries. A soup entry is really a special
object (a fault block) that contains information about how to get
an entry and can contain a cached entry frame. In the information
about how to get an entry, there is a reference to the soup, and
various caches in a soup contain references to the cursors, the
store, and other (large) NewtonScript objects. TrueSize
is reporting the space taken up by all of these objects.
(Note: calling TrueSize on a soup entry will force
the entry to be faulted in, even if it was not previously taking
up space in the NewtonScript heap.)TrueSize is not very useful when
trying to find out how much space the cached frame for an entry is
using. A good way to find the space used for a cached entry frame
is to call gc(); stats(); record the result, then
call EntryUndoChanges(entry); gc(); stats(). The
difference between the two free space reports will be the space
used by the cached frame for a given entry.EntryUndoChanges(entry) will cause any cached frame
to be removed and the entry to return to the unfaulted state. Gc()
then collects the space previouly used by the cached entry
frame.TrueSize breakdown of the types of
objects used, you can Clone the entry and call
TrueSize on the copy. This works because the copy is
not a fault block, and so it does not reference the
soups/cursors/stores.
Floor and Ceiling
seem broken. For instance, Floor(12.2900 * 10000)
returns 122899, not 122900. What's going on?Floor or
Ceiling. This happens because of the way floating
point numbers are stored, and the limitation is common to many
real number representations. In the same way that 1/3 cannot
accurately be represented in a finite number of digits in base 10
(it is .3333333333...), likewise 1/10 cannot be exactly
represented as a fractional part in base 2. Because number
printers typically round to a small number of significant digits,
you don't normally notice this. The NTK inspector, for example,
displays only 5 significant figures in floating point numbers.
However, if you display the number with enough precision, you'll
see the representation error, where the real is actually slightly
larger or smaller than the intended value.FormattedNumberStr(0.1, "%.18f") ->
"0.100000000000000010" FormattedNumberStr(0.3, "%.18f") -> "0.299999999999999990"
The functions Floor and Ceiling are
strict, and do not attempt to take this error into account. In the
example, 12.29 is actually
12.2899999999999990, which multiplied by
10000 is 122,899.999999999990. The
largest integer less than this number (Floor) is
correctly 122899.
There are usually ways to work around this problem, depending on
what you are trying to accomplish. To convert a floating point
number to an integer, use RIntToL, which rounds to
the nearest integer avoiding the problems caused with round-off
error and Floor or Ceiling.
RIntToL(x) produces the same result that
Floor(Round(x)) would produce.
RIntToL(12.29*10000) -> 122900
If you need to format a number for display, use a formatting
function such as FormattedNumberStr. These functions
typically round to the nearest displayable value. To display 2
decimal digits, use "%.2f":
FormattedNumberStr(12.29, "%.2f") -> "12.29"
If you're working with fixed point numbers such as dollar amounts,
consider using integers instead of reals. By representing the
value in pennies (or mils, or whatever) you can avoid the
imprecision of reals. For example, represent $29.95
as the integer 2995 or 29950, then
divide by 100 or 1000 to display the
number. If you do this, keep in mind that there is a maximum
representable integer value, 0x1FFFFFFF or
536870911, which is sufficient to track over 5
million dollars as pennies, but can't go much over that.
If you really need to find the greatest integer less than a
certain number and can't tolerate how Floor deals
with round off errors, you'll need to do some extra work keeping
track of the precision of the number and the magnitude of the
round off error. It's worthwhile to read a good numeric methods
reference. Floating point numbers in NewtonScript are represented
by IEEE 64-bit reals, which are accurate to around 15 decimal
digits. The function NextAfterD provides a handy way
to see how 'close together' floating point numbers are.
FormattedNumberStr(NextAfterD(0.3, kInfinity), "%.18f");
-> "0.300000000000000040"
http://gemma.apple.com/dev/techsupport/insidemac/PPCNumerics/PPCNumerics-2.html
Briefly, numbers are represented by 1 bit of sign ("on" is
negative), 11 bits of exponent, and 52 bits of fractional part.
The exponent bits are stored in excess 0x3FF, that is, 0x3FF is
the representation for 0, values greater than 0x3FF are positive
exponents, and values less than 0x3FF are negative exponents. The
52 bits of fractional part actually provide 53 bits of accuracy,
because the initial 1 bit is dropped.
For example, suppose that we want to convert 9 97/128 into IEEE 64
bit format:
1) convert to base 2
1001.1100001
2) shift number to the form of 1.yyyyyy * 2^Z
1.0011100001 * 2^3
3) add 0x3FF (excess 0x3FF) to exponent field, convert to
binary.
3+0x3FF = 0x402 = 100 0000 0010
4) now put the numbers together, using only the fractional part of
the number represented above, in the form of yyyyyy
0 10000000010
0011100001000000000000000000000000000000000000000000
in hex representation, this is 0x4023840000000000
5) Just to verify, try it: StrHexDump(9+97/128, 16) ->
"4023840000000000"
The IEEE standard also allows for non-normal numbers. Here are the
exceptions:
infinity e = 7FF, f = 0 (+ or - depending on sign bit)
NaN e = 7FF, f <> 0 (also overflow, error, etc.)
zero e = 0, f = 0 (+ or -, depending on sign bit)
subnormal e = 0, f <> 0 (these are less precise numbers,
smaller than the smallest normal number)
Note that there is more than one not a number value. In fact,
there are quite a large number. The IEEE spec assigns meaning to
various NaN values, as well as defining signalling and quiet NaNs.
NewtonScript does not distinguish between NaN values. One NaN is
as good as another.
In NewtonScript, real numbers are 8-byte binary objects of class
'real. In addition to the NewtonScript floating point
literal syntax, you can use the compile time function
MakeBinaryFromHex to construct real numbers, and you
must use this style for custom NaN values. The most recent
platform files for Newton 2.0 and Newton 2.1 provide constants for
negative zero (kNegativeZero), positive and negative
infinity (kInfinity, kNegativeInfinity),
and a canonical NaN (kNaN).
MakeBinaryFromHex("4023840000000000", 'real) -> 9.7578125
// = 9+97/128
protoSoupOverview?HitItem that gets called
whenever an item is tapped. The method is defined by the overview
and you should call the inherited one. Also note that
HitItem gets called regardless of where in the line a
tap occurs. If the tap occurs in the checkbox, you should do
nothing, otherwise you should do something.protoSoupOverview. So, you can find the actual soup
entry by cloning the cursor and moving it.HitItem method. If the item
is selected (the checkbox is not tapped) then the code will set an
inherited cursor (called myCursor) to the entry that
was tapped on:func(itemIndex, x, y)
begin
// MUST call the inherited method for bookeeping
inherited:HitItem(itemIndex, x, y);
if x > selectIndent then
begin
// get a temporary cursor based on the cursor used
// by soup overview
local tCursor := cursor:Clone();
// move it to the selected item
tCursor:Move(itemIndex) ;
// move the inherited cursor to the selected entry
myCursor:Goto(tCursor:Entry());
// usually you will close the overview and switch to
// some other view
self:Close();
end;
// otherwise, just let them check/uncheck
// which is the default behavior
endprotoSoupOverview?protoSoupOverview. You can
draw one in a viewDrawScript as follows: // setup a cached shape for efficiency
mySoupOverview.cachedLine := nil;
mySoupOverview.viewSetupDoneScript := func()
begin
inherited:?viewSetupDoneScript();
local bounds := :LocalBox();
cachedLine := MakeRect(selectIndent - 2, 0,
selectIndent - 1, bounds.bottom);
end;
mySoupOverview.viewDrawScript := func()
begin
// MUST call inherited script
inherited:?viewDrawScript();
:DrawShape(cachedLine,
{penPattern: vfNone, fillPattern: vfGray});
end;ValidationFrame to
validate and edit entries in a protoListPicker. When
I edit certains slots I get an error that a path failed. All the
failures occur on items that are nested frames in my soup entry.
What is going on?validationFrame in your pickerDef,
even if you have no nested entries. Instead, you can provide your
own validation mechanism and editors:Validate method in your picker
definitionOpenEditor method in your picker
definitionpickerDef.Validate(nameRef, pathArray)
nameRef
pathArray - array of paths to validate in the
nameRef
returns an array of paths that failed, or an empty array
Validate each path in pathArray in the given nameRef.
Accumulate a list of paths that are not valid and return them.
The following example assumes that pickerDef.ValidateName
and pickerDef.ValidatePager have been
implemented:
pickerDef.Validate := func(nameRef, pathArray)
begin
// keep track of any paths that fail
local failedPaths := [];
foreach index, path in pathArray do
begin
if path = 'name then
begin
// check if name validation fails
if NOT :ValidateName(nameRef) then
// if so, add it to array of failures
AddArraySlot(failedPaths, path);
end;
else begin
if NOT :ValidatePager(nameRef) then
AddArraySlot(failedPaths, path);
end;
end;
// return failed paths or empty array
failedPaths;
end;
pickerDef.OpenEditor(tapInfo, context, why)
OpenDefaultEditor. However, you need to use this
instead of DefaultOpenEditor.
pickerDef.OpenEditor := func(tapInfo, context, why)
begin
local valid = :Validate(tapInfo.nameRef, tapInfo.editPaths) ;
if (Length(valid) > 0) then
// if not valid, open the editor
// NOTE: returns the edit slip that is opened
GetLayout("editor.t"):new(tapInfo.nameRef,
tapInfo.editPaths, why, self, 'EditDone, context);
else
begin
// the item is valid, so just toggle the selection
context:Tapped('toggle);
nil; // Return <nil>.
end;..
end;
New method that will open the editor and return the
associated View.
The editor can be designed to fit your data. However, we suggest
that you use a protoFloatNGo that is a child of the
root view created with the BuildContext function. You
are also likely to need a callback to the pickderDef so it can
appropriately update the edited or new item. Finally, your editor
will need to update your data soup uing an "Xmit" soup method so
that the listPicker will update.
In the OpenEditor example above, the last three
arguments are used by the editor to send a callback to the
pickerDef from the viewQuitScript. The design of the
callback function is up to you, here is an example:
pickerDef.EditDone := func(nameRef, context)
begin
local valid = :Validate(tapInfo.nameRef, tapInfo.editPaths) ;
if (Length(valid) > 0) then
begin
// Something failed. Try and revert back to original
if NOT :ValidatePager(nameRef) AND
self.('[pathExpr: savedPagerValue, nameRef]) = nameRef then
nameRef.pager := savedPagerValue.pager;
context:Tapped(nil); // Remove the checkmark
end;
else
// The nameRef is valid, so select it.
context:Tapped('select);
// Clear the saved value for next time.
savedPagerValue := nil;
end;fixedHeight slot. When I bring up the
picker, it is not tall enough to display all the items. Worse, I
cannot scroll to the extra items. What is going on?fixedHeight slot is used for two separate
things. Any given pick item can use the fixedHeight
slot to specify a different height. This works fine.fixedHeight slot of the
first pick item (in other words, pickItems[0]) if it
exists. It is as if the following code executes:local itemHeight := kDefaultItemHeight;
if pickItems[0].fixedHeight then
itemHeight := pickItems[0].fixedHeight;
local totalHeight := itemHeight * Length(pickItems);
pickItems array has a
fixedHeight slot that is sufficiently large to make
scrolling work correctly. This may be fixed in future revisions of
the NewtonOS.
Note that there will be similar problems if your pick items
contain icons. The system will use the default height unless you
specify a fixedHeight slot in your first item. The
default height is not tall enough for most icons. In other words,
if you have icons in your pick items, you must have a
fixedHeight slot in the first item that is set to the
height of your icon.
protoTextList
but they do not appear. How do I get columns?protoTextList is based on a
simple text view which does not support tabs. If you want
scrolling selectable columns you can use shapes to represent the
rows. If you need finer control, use the LayoutTable
view method.
protoNumberPicker for
input. (or) I have used protoNumberPicker and have
encountered a bug/misfeature/problem. What should I use?protoNumberPicker has several instabilities and
bugs. We recommend that you use the DTS sample code
"protoNumberPicker_TDS". It provides all of the features of
protoNumberPicker with none of the bugs. It also
provides additional functionality that is not in
protoNumberPicker. See the sample code for more
detail.protoListPicker, protoPeoplePicker,
protoPeoplePopup, or
protoAddressPicker?protoListPicker. That means that the particular class
of nameRef you use must include single selection. In general, this
requires creating your own subclass of the particular name
reference class.protoListPicker
variant will view. That data definition will include the
singleSelect slot. As an example, suppose you want to
use a protoPeoplePopup that just picks individual
people. You could use the following code to bring up a
protoPeoplePopup that only allowed selecting one
individual at one time: // register the modified data definition
RegDataDef('|nameref.people.single:SIG|,
{_proto: GetDataDefs('|nameRef.people|), singleSelect: true});
// then pop the thing
protoPeoplePopup:New('|nameref.people.single:SIG|,[],self,[]);
// sometime later
UnRegDataDef('|nameref.people.single:SIG|);
protoListPickers and
classes, create the appropriate subclass. For example, a transport
that uses protoAddressPicker for emails might create
a subclass of '|nameRef.email| and put that subclass
symbol in the class slot of the
protoAddressPicker.
Since many people are likely to do this, you may cut down on code
in your installScript and removeScript
by registering your dataDef only for the duration of the
picker. That would mean registering the class just before you pop
the picker and unregistering after the picker has closed. You can
use the pickActionScript and pickCanceledScript
methods to be notified when to unregister the dataDef.
protoListPicker?viewFont slot
in the protoListPicker itself and have that work
(just like you can set viewLineSpacing slot now). In
the meantime, you need a piece of workaround code. Warning: you
must set the viewFont of the listPicker AND include this
workaround code in the viewSetupDoneScript:func()
begin
if listBase exists and listBase then
SetValue(listBase, 'viewFont, viewFont) ;
inherited:?viewSetupDoneScript();
end;
viewFont slot of the
listBase view to the viewFont of the
protoListPicker. You cannot rely on the listbase view
always being there, hence the test for its existence.
Note that you can use the same code to modify the
lineHeight slot of the listPicker. Just substitute
lineHeight for viewFont in the code
snippet. The one caveat is that the lineHeight must
be at least 13 pixels.
selected array
of a protoListPicker, it throws a -48402
error. How do I preselect items?protoSoupOverview?selected slot:selected - Required. Initially set to
nil; it is modified by protoSoupOverview
as the user selects and deselects overview items.nil or the
empty array if there is no selection. For example: [[alias: NIL, 66282812, 84, "Names"],
[alias: NIL, 66282812, 85, "Names"]]protoTextList after it
is displayed. I add an item and scroll to highlight that item.
However, the state of the scroll arrows does not correctly get
updated. Sometimes it will indicate that there are more items to
scroll when it is really at the end of the list.protoTextList
to reset the scroll distance when you update the listItems array.
The workaround is to always scroll the list to the top before
calling SetupList when you add items. Then you can
scroll the list to where you want it. Note that this workaround is
safe to use in Newton 2.1 OS as well. In other words, if you are
adding items to a protoTextList, use this workaround
unless your application is Newton 2.1 OS-specific. This method
will add a single item to the protoTextList, set the
highlighted item to the new item and scroll if required. It will
also make sure the item is unique. AddListItem := func(newItem)
begin
// Insert the item if not already in Array
local index := BInsert(listItems, item, '|str<|, nil, true);
// item must be in the array and index will point to the item.
if NOT index then
begin
:Notify(kNotifyAlert, kAppName, "Duplicate entry.");
return nil;
end;
// workaround a bug in 2.0 that causes the
// scroll arrows to get out of sync
// do this by scrolling to the top
:DoScrollScript(-viewOriginY) ;
self:SetUpList();
// Setting the selection slot will highlight the item
selection := index;
// scroll to show the new item
if index >= viewLines then
:DoScrollScript((index - viewLines + 1) * lineHeight) ;
self:RedoChildren();
return true;
end ;
protoPicker that I reuse in my
application. Sometimes the picker will be blank when I open it.
What's happening?ProtoPicker does not correctly reset the
viewOriginY slot if you display a list that requires
scrolling, and then display one that does not require scrolling.
The solution is to manually reset the viewOriginY
slot to 0 if you dynamically change the contents of the picker.
protoPeoplePicker
displayed names as "last, first", but in Newton 2.1 OS it displays
"first last". How can I make protoPeoplePicker
display the original way?nameRefDataDef for people that will display the name
in "last, first" format. The good news is that this workaround
will work on both Newton 2.0 and Newton 2.1. The basic steps
are:nameRefDataDef that
does the right thingdataClass slot
of your peoplePicker // create a unique symbol for the the data def
DefineGlobalConstant('kMyDataDefSym,
Intern("nameRef.people.lastFirst:" & kAppSymbol)) ;
DefineGlobalConstant('kMyGetFunc,
func(item, fieldPath, format)
begin
// if this is a person, not a company, modify stuff
local entry := EntryFromObj(item) ;
if fieldPath = 'name AND format = 'text AND entry AND
IsFrame(entry) AND ClassOf(entry) = 'person then
begin
local nameFrame := entry.name ;
if nameFrame AND nameFrame.first AND nameFrame.last then
return nameFrame.last & ", " & nameFrame.first ;
else
return inherited:Get(item, fieldPath, format) ;
end
else
return inherited:Get(item, fieldPath, format) ;
end
) ;
Put this code into the viewSetupFormScript of the
base view of your application:
// register my modified people data def
RegDataDef(kMyDataDefSym, {_proto: GetDataDefs('|nameRef.people|),
Get: kMyGetFunc}) ;
Put this code into the viewQuitScript of the base
view of your application:
// unregister my modified people data def
UnRegDataDef(kMyDataDefSym) ;
Use the kMyDataDefSym constant as the value for the
dataClass slot of your protoPeoplePicker
or protoPeoplePopup
protoCountryTextPicker or default state for
protoUSstatesTextPicker?'default to the params frame. The slot
must contain the name of the country
(protoCountryTextPicker) or state
(protoUSstatesTextPicker) as a string. For example,
if you wanted the protoCountryTextPicker to default
to Canada, you could do the following in the
viewSetupFormScript: // get a writeable copy of the params frame
self.params := Clone(params);
params.default := "Canada";RegGlobalKeyboard function.
GetUserSettings,
SetDefaultUserSettings and SetUserSettings
allow you to manipulate recognition-related user preference
data. These functions can allow an application to keep and manage
recognition settings for multiple users. These functions only
manage information about the recognition settings, and no other
user preference settings. GetUserSettings()
SetUserSettings. Do not modify the frame this
function returns. Do not rely on any values, as the frame may
change in future releases.
SetDefaultUserSettings()
SetUserSettings(savedSettings)
GetUserSettings.
Sets user preferences for recognition as specified.
local correctView := GetRoot().correct;
if correctView and (GetCaretBox() or GetHiliteOffsets()) then
correctView:Open();
GetKeyView as a test to make sure a
correctable view was the key view. With the changes to the OS with
the Newton 2.1 release that allow any view to be a key view, this
is no longer a reliable test. The corrector will fail to open
(generating a -48204 "bad path" error) if the key view does not
support the caret or a selection. Calling GetCaretBox
and GetHiliteOffsets is a more reliable test to see
if a correctable view is available.
GetNamedResource(..., 'picture) routine,
you can use PICT resources to be drawn in clPictureViews. MacOS
PICT resources often contain multiple opcodes (instructions). For
single-opcode PICTs, compression is done for the whole picture.
You can check Inside Macintosh documentation for
specifications of the PICT format. If you are using very large
bitmaps which you will print, you should use PICT resources
composed of many smaller 'bitmap copy' opcodes because they will
print much faster and more reliably on PostScript printers. This
is because very large PICT opcodes printed to LaserWriters must be
decompressed on the printer. The printer's decompression buffer is
sometimes too small if the opcodes represent large bitmaps. Check
your MacOS graphics application documentation for more information
on segmenting your large PICTs into smaller pieces. For some
applications, you might have two versions of the PICTs, one for
displaying (using GetPictAsBits for faster screen
drawing), and a large tiled PICT for printing.MonacoTest". That includes a font which will print
as the monospaced Courier font.target variable
(it will contain the "body" of the data sent; don't use
fields.body). Note that if mulitiple items are sent,
the value of target will change as the print format
iterates over the list. Try to put the real "data" for the routing
in the target using the view method
GetTargetInfo.GetRoot().(yourAppSymbol).theSlot.OpenRoutingSlip. Create a
new item with the transport's NewItem method and add
routing information such as the recipient information in the
toRef slot. For the call slip, the transport symbol
will be '|phoneHome:Newton|, but this approach will
work for other transports. (For transports other than the call
transports, you will also provide the data to route in the
item.body slot.)toRef slot in the item frame should contain an
array of recipients in the form of nameRefs, which are the objects
returned from protoPeoplePicker and other
protoListPicker-based choosers. Each nameRef can be
created from one of two forms: a cardfile soup entry, or just a
frame of data with minimal slots. (The required slots vary
depending on the transport. For instance, the current call
transport requires only phone, name, and country.) entry := myCursor:Entry();
2. Create your own pseudo-entry:
entry := {
phone:"408 555 1234",
name: {first: "Glagly", last: "Wigout"},
country: "UK",
};
Make the entry into a "nameRef" using the nameRef's registered
datadef -- an object which describes how to manipulate nameRefs of
a specific class. Note that every transport stores its preferred
nameRef class symbol in its transport.addressingClass
slot. (Examples are '|nameRef.phone| and
'|nameRef.email|).
local class := '|nameRef.phone|;
local nameRef := GetDataDefs(class):MakeNameRef(myData, class);
Setting up the targetInfo Frame
Your GetTargetInfo view method should return a
targetInfo frame, consisting of target
and targetView slots. Alternatively, you can
create a frame consisting of these slots and pass it to
OpenRoutingSlip. As a workaround to a ROM bug, you
must also supply an appSymbol slot in the
targetInfo frame containing your appSymbol. Note that
targetInfo.target could be a multiple item target
(see the CreateTargetCursor documentation for more
info.)
Opening The Slip
You can use OpenRoutingSlip to open the slip after
setting up slots such as toRef and cc
within the item. You can use code such as the
following:
/* example using Call Transport */
local item, entry, class, nameRef;
// just for testing, get an Name...
entry := GetUnionSoup("Names"):Query(nil):Entry();
item := TransportNotify('|phoneHome:Newton|, 'NewItem, [nil]);
if item = 'noTransport or not item then
return 'noTransport;
class := '|nameRef.phone|;
nameRef := GetDataDefs(class):MakeNameRef(entry, class);
item.toRef := [nameRef];
targetInfo := {
targetView: getroot(),
target: {}/* for non-CALL transports, add your data here! */,
appsymbol: kAppSymbol
};
// returns view (succeeded), or fails: nil or 'skipErrorMessage
OpenRoutingSlip(item, targetInfo);
CreateTargetCursor function.GetTargetInfo
method like: func(reason)
begin
local t := CreateTargetCursor(kDataClassSymbol, myItemArray);
local tv := base; // the targetView
return {target: t, targetView: tv};
end;
The first argument to CreateTargetCursor is used as
the class of the target, which is used to determine what formats
and transports are available. You must register formats on that
data class symbol in your part's InstallScript
function.
The item array passed to CreateTargetCursor can
contain any items, including soup entries or soup entry aliases.
If you include soup entry aliases, they will automatically be
resolved when accessing items using the GetTargetCursor
function.
Print formats that have their usesCursors slot set to
nil will automatically print items on separate pages
-- print formats must use the target variable to image the current
item. To print multiple items, set the format usesCursors
slot to true and use
GetTargetCursor(target, nil) to navigate through the
items.
If either the format (the usesCursors slot) or the
transport (the allowsBodyCursors slot) does not
support cursors, the system will automatically split the items
into separate Out Box items.
protoPrintFormat:viewSetupFormScript()?viewSetupFormScript.self:LocalBox() and get the correct page size. Note
that you cannot rely on the
protoPrintFormat.viewBounds slot value. To position
subviews within the print format centered or "full" width or
height, use view justifications like centered, right, and full, or
use theEnclosingView:LocalBox() to determine the
exact size of the enclosing view.
CreateTargetCursor('newtOverview, myItemArray) in my
application to simplify my code which handles overviews. Why would
my print format throw an exception when I use this method?'newtOverview
symbol as your data class with CreateTargetCursor.
The biggest limitation is that it requires you to support exactly
the set of of datatypes: ['frame, 'text, 'view]. In
other words, you must register a protoFrameFormat (by
default, it handles 'frame and 'text
dataTypes) and a protoPrintFormat. However, there are
two other limitations not mentioned in the final documentation:
the system does not guarantee that it will call your print
format's formatInitScript method or a format's
SetupItem method.viewSetupFormScript (or other code in the print
format) assumed that the formatInitScript has been
called, it could cause errors and/or exceptions. The workaround to
this would be to set a flag in the formatInitScript;
if it was not set at the beginning of
viewSetupFormScript, send your format the
formatInitScript message. Other problems could occur
with SetupItem, but you'd probably not see any errors
or exceptions until you tried to beam/mail a frame to another
device and then tried to Put Away the item.CreateTargetCursor to prepare a "multiple item
target", you may be able to use this special
'newtOverview symbol as your data class. If your
application prints every item on separate pages (in other words,
not multiple items on one page) and you want to split beam and
mail items into separate items in the Out Box, this might be
useful to you. For more information, see the Newton Programmers
Guide (not reference) in the Routing chapter "Using the Built-in
Overview Data Class" section and the "Move It!" article in the
Newton Technology Journal 2.02. Also, check out the MultiRoute DTS
sample.
'frame
dataTypes. Why is Beam available in my Action picker in Newton 2.1
OS?'text dataType. If any routing formats for your data
supports text export (a format.dataTypes array
includes 'text), Beam will be available.
Unfortunately, there is a bug in current Newton 2.1 OS devices
such that Beam does not convert the target to text before sending
it. Transports that support sending text should use the
kItemToTextFunc function (in the Newton 2.x platform
files), and that function calls the format's
TextScript to convert the item to text. Since Beam
does not do this, this gives the appearance that the item is being
sent as 'frame, a dataType that may not be supported
by your application's routing formats.'frame datatype. In your
routing format, add 'frame to the
dataTypes slot. This will allow all
'frame transports, including mail transports that can
send attachments, to send mail with your application. This will
allow your application to avoid text-specific bugs in Beam. For
the best user interface, we recommend that you write stationery
for your data so that users can view the item in the In Box or Out
Box. See the Newton Programmers Guide and Reference for more
information about writing and registering stationery. Note that
you can test your application with Put Away, using the built-in
Beam transport as well as the DTS sample "Archive Transport".format:SetupItem(...) method. If you don't
support overviews or other mechanisms that use multiple item
targets, change item.body to be a new frame of the
form {text: "the converted item to text", class:
'text}. Note that this format should not also support the
'frame dataType because you are destructively
modifying the item.SetupItem method is called. You can use the code like
the following in your SetupItem format after calling
the inherited method:// get a 'cursor' to iterate over the items.
// Note: this still returns a 'cursor' even if item.body wasn't real
local cursor := GetTargetCursor(item.body, nil);
local newArray := [];
local entry := cursor:entry();
while (entry) do
begin
// convert item to text in whatever way you normally do it...
// For instance, you might call your format's textscript...
entry := {
text: "blah blah" && entry.a && entry.b,
class: 'text
};
AddArraySlot(newArray, entry);
entry := cursor:Next();
end;
item.body := CreateTargetCursor(classof(item.body), newArray);
// remember to return 'item' from SetupItem
item
'frame data by hiding the data in extra slots in
item.body. If you did that, the item would be much
larger than necessary to route 'frame data, and will
not be Put Away properly because the 'class slot is
set to 'text, not your original data class). If you
actually want to support 'text and
'frame dataTypes, use a single
protoFrameFormat with dataTypes ['frame, 'text]
and do not convert the item.body as
illustrated above. (This is actually recommendation #1 above).
Note that 'text stationery must be registered in
order to view the item in the In Box and Out Box. Such stationery
is not necessarily installed on the receiving device. Some mail
transport packages may have installed 'text
stationery, but you may choose not to rely on this. If you are
interested in writing text stationery, see the DTS sample
"MinMail" and the Newton Programmers Guide and Reference for more
information about writing and registering stationery.
:LocalBox() in its
viewSetupFormScript,
viewSetupChildrenScript, or
viewSetupDoneScript. This is only accurate during the
current print job to the printer or fax driver. You cannot
determine this size during Print/Fax preview, nor during the print
format's formatInitScript, nor in your application's
on-screen views.formatInitScript can accurately determine the page
height. This special format method was designed to allow
time-intensive code to execute before the print job begins. For
instance, fax timeouts might be less likely if some data were
processed before fax connection. However, there is no supported
API to find the actual final printable area that you will have
when the system opens the print format view and sends the
viewSetupFormScript message. Although you may be
tempted to access undocumented slots which contain information
about printer and page settings, this is both unsupported and
results in unreliable bounds. (For instance, the undocumented fax
cover page information affects the printable area but it's not
stored in the printer nor page size structures.)paperSize and paperSizes. You cannot use
these to reliably determine the printable area, nor can you create
new paperSizes. See the Newton Programmer's Reference
for more details.:LocalBox() in the print format
viewSetupFormScript,
viewSetupChildrenScript, or
viewSetupDoneScript. (Or, use the print format
pageHeight and pageWidth slots in
viewSetupChildrenScript or later.) Also, add new
child views with appropriate center/full/right/relative
justification to take advantage of varying page sizes. This will
allow your application to work with any paper size, in any
printer, and in any locale.
modeXOR and modeNot will
not work.modeBic) for drawing
the text.userName slot. This
slot contains a string that will show up in the alert sound
picker.RegSound(soundSymbol, alertSoundFrame)
soundSymbol
alertSoundFrame - see above
Registers the sound in alertSoundFrame with the alert
sound picker.
UnRegSound(soundSymbol)
soundSymbol
Unregisters the sound frame that was registered with the symbol
specified by soundSymbol.
SoundList()
{item:
soundName, soundSymbol: theSoundSymbol}
GetRegisteredSound(soundSymbol)
soundSymbol
Returns a sound frame that can be passed to the sound playing
functions (for example, the global function
PlaySound). soundSymbol is the symbol
used to register the sound.
height slot, flush
the data, and then do a re-target. For instance, you might have
the following method in your stationery: DoResize: func( newHeight )
begin
target.height := newHeight;
:FlushData();
:DoRetarget();
end;
RegisterViewDef on
Newton 2.0 OS, I get the "grip of death" alert ("The package
'MyApp' still needs the card you removed...") when the card the
viewDef is on is removed. I don't get the grip of death alert when
using Newton 2.1 OS. How can I keep the grip of death alert from
appearing?EnsureInternal the
second argument to the RegisterViewDef global
function. The RegisterViewDef global function was
changed in Newton 2.1 OS to automatically
EnsureInternal the second argument.EnsureInternal-ing something that has been
EnsureInternal-ed is a very fast operation so you
don't need to worry about checking which platform you are running
on.
ROM_compatibleFinder in Newton 2.0,
the overview of found items contains checkboxes for each item,
allowing the user to attempt to route the found items. Since my
found items are not soup items, various exceptions are thrown. How
can I prevent the checkboxes?SelectItem slot to
the result frame, set to nil. AddArraySlot(results,
{_proto: ROM_compatibleFinder,
owner: self,
title: mytitle,
SelectItem: nil, // prevents checkboxes
items: myresults});
Delete to
behave correctly, or as complex as replacing GetTarget
and adding appropriate layouts. See the Newton DTS Q&A
"Creating Custom Finders" for more information.
ROM_soupFinder is not appropriate, but
ROM_compatibleFinder seems to throw many exceptions.
Which should I use?soupFinder based item you could do
something like:DefConst('kMySoupFinder, {
_proto: ROM_soupFinder,
Delete: func()
begin
print("About to delete " & Length(selected) && "items") ;
inherited:Delete() ;
end,
}) ;
Most of these routines are only callable by your code. They should
not be overwritten. Those routines that can be safely overriden
are specified.
Some of methods and slots are common to both types of finders:
finder.selected
finder:Count()
finder:ReSync()
finder:ShowFoundItem(item)
overview's items array.
finder:ShowOrdinalItem(ordinal)
'first - the first found item
'prev - the previous item
'next - the next item
<an-integer> - display the nth item based on
the integer.
Under no circumstances should you call or override:
finder:MakeFoundItem
finder:AddFoundItems
ROM_SoupFinder
SoupFinder has the following methods and slots:
All the documented items from the simple use of soupFinder as
documented in the Newton Programmer's Guide 2.0.
soupFinder:Reset()
should use the ReSync method to reset a finder.
soupFinder:ZeroOneOrMore()
for more than one entry.
soupFinder:ShowEntry(entry)
opening the application and moving it to that item.
This does not close the findOverview.
soupFinder:SelectItem(item)
If this method is set to nil in the soupFinder proto,
items will not have a checkbox in front of them (not
selectable).
soupFinder:IsSelected(item)
soupFinder:ForEachSelected(callback)
soupFinder:FileAndMove(labelsChanged, newLabel,
storeChanged, newStore)
newLabel is the new label if and only if
labelsChanged is true.is the new store if and only if
newStore storeChanged
is true.
Developers can override this, though they may want to call the
inherited routine to do that actual work. Note that
FileAndMove can be called even if no items are
selected. If you override this method you MUST check if there are
selected items by doing:
if selected then
// do the work
soupFinder:FileAs(labels)
soupFinder:MoveTo(newStore)
soupFinder:Delete()
Developer can override. Note: if you override this, the crumple
effect will
still happen. There is no way to prevent the ability to delete the
items or
prevent the crumple effect at this time.
soupFinder:GetTarget()
The following methods should not be called or modified:
soupFinder.MakeFoundItem
soupFinder.AddFoundItems
ROM_CompatibleFinder
compatibleFinder:ShowFakeEntry(index)
index'th item from the found items.
Note that items will likely be an array of the found items.
ShowFakeEntry should behave just like
ShowFoundItem. In other words, it should open the
application then send a ShowFoundItem to the
application.
compatibleFinder:ConvertToSoupEntry(item)
The following methods are defined to be the same as the
soupFinder:
FileAs, MoveTo, Delete, IsSelected, SelectItem,
ForEachSelected, GetTarget, FileAndMove
Note that this causes problems in some cases: most notably, the
ForEachSelected call is expected to return an array
of soup entries. The chances are you will need to override most of
those methods. See soupFinder for a description of
what the methods are supposed to do.
nil value in the frame returned by the
BatteryStatus global function. How do I interpret
these values?nil is returned if the underlying
hardware cannot determine the correct information. Some hardware
is limited in the amount of information that it can return. Future
hardware may fill in more slots with authoritative non-nil
values.AddFolder and
RemoveFolder to modify the folder set for a given
application.AddFolder(newFolderStr, appSymbol)
newFolderStr
appSymbol - symbol, application for local folder
result - symbol, the folder symbol of the newly added
folder.
AddFolder takes a folder name and creates a new
folder for the application.
AddFolder returns the symbol representing the tag
value for the new folder. Please note that the symbol may be
different from the value returned by using Intern()
on the string. In particular, folder names with non-ASCII folders
are supported. If a folder with the name already exists, the
symbol for the pre-existing folder is returned and a new folder is
not created.
There is a limit on the number of unique folders an application
can support. If the limit is exceeded, AddFolder
returns NIL and a new folder is not added. With the
Newton 2.0 OS, the current limit is twelve global folders and
twelve local folders.
RemoveFolder(folderSym, appSymbol)
folderSym
appSymbol - symbol, the application for which to
remove the folder
result - undefined; do not rely on the return value
of this function.
RemoveFolder can be used to remove a folder from the
available list for an application. If items exist in a folder that
is removed, the only way users can see the items is by selecting
"All Items" from the folder list.
protoStatusTemplate-based view
and am trying to rename the primary button through the
protoStatusTemplate's setup frame. After doing this,
I get an exception when I tap on the renamed button. What am I
doing wrong?protoStatusTemplate which will cause the primary
button to function incorrectly if you do not include a
buttonClickScript in the setup frame.primary slot of the
values frame of the setup, the primary button uses the
text slot and the buttonClickScript slot
of that frame to initalize itself. Unfortunately, it does not
check to see if either of those slots exist before trying to use
them. The result is that an exception is thrown when you tap the
button.buttonClickScript to the primary frame. From that
method you will typically call your base view's
CancelRequest method.// Add a buttonClickScript method which just calls the application's CancelRequest method.
local viewSetValues := {
primary:
{
text: "Stop",
buttonClickScript: func() GetRoot().(kAppSymbol):CancelRequest('userCancel)
}
};
local viewSet := {
appSymbol: kAppSymbol,
name: "The Name",
values: viewSetValues
};
// Setup the status template
statusView:ViewSet( viewSet );protoPhoneExpando
under Newton 2.0 OS. Something is going wrong in the
setup1 method. Is this a known bug?protoPhoneExpando (and
the entire expando user interface) have been deprecated in the
Newton 2.0 OS, and are only supported for backward compatibility.
If possible, you should redesign your application to avoid the
expandos.setup1 and setup2 messages to the
template in the lines array. These methods in
protoPhoneExpando rely on information that isn't
created until the view is actually opened.labelCommands
slot in the template which has an array of one element,
that element being the label you want to appear in the phone line.
For example: labelCommands: ["phone"].protoPhoneExpando
doesn't use the phoneIndex feature. If it
does, you'll have problems that are harder to work around.
clEditView, and
clEditViews can contain pictures (in addition to ink,
polygons, and text) in the Newton 2.0 OS.'viewChildren slot of a clEditView to
create editable items. 'para templates are text and
ink text, 'poly templates are drawings and sketch
ink, and 'pict templates are images.clEditView, you need to create
an appropriate template and then add it to the
viewChildren array (and open the view or call
RedoChildren) or use the AddView method
to add it to an existing view (then Dirty the view.)
See the item "Adding Editable Text to a clEditView" elsewhere in
the Q&As for details.'pict items needs to contain these
slots:viewStationery: Must have the symbol 'pict
viewBounds: A bounds frame, like
RelBounds(0,0,40,40)
icon: A bitmap frame, see clPictureView
docsclPictureView
view class.
clParagraphView
that's inside a smaller view and be able to scroll back and forth.
When I try this, it always wraps at the bounds of the parent. How
can I create a horizontal scrolling text view?clEditView, leaving
the rest of it off screen and unselectable.viewBounds of the
clParagraphView are modified during creation of the
view so that the view's right edge is aligned with the parent's
right edge. After that, wrapping is automatic.viewFlag vReadOnly is set, 2) making
sure vCalculateBounds and
vGesturesAllowed, are off, and 3) not using
tabs or styles. Lightweight text views
are not editable, but you can use SetValue to change
their text slots dynamically.clParagraphView or if
tabs or styles are required, there is another workaround. The code
to check for clipping only looks one or two levels up the parent
chain, so you could nest the paragraph in a couple of otherwise
useless views which were large enough to prevent clipping, and let
the clipping happen several layers up the parent chain.clParagraphView view class:viewKeyDownScript message is sent when a key is
pressed.viewKeyUpScript message is sent when a key is
released.ViewKeyUpScript and ViewKeyDownScript
are currently called using parent inheritance. Do not rely
on this behavior: it may change in future ROMs.nil. The default action for ViewKeyDownScript
is usually to insert the character into the paragraph.
(There may be other default actions in the future.) If you return
a non-nil value, the default action will not occur.vSingleKeyStrokes flag in the
textFlags slot of your view for the system to send
the ViewKeyDownScript or ViewKeyUpScript
message for every key stroke. If you do not specify
vSingleKeyStrokes, keyboard input may be dropped if a
lot of key strokes are coming in. ViewKeyDownScript(char, flags)
char The character that was entered on the keyboard.
Note that if a modifier key is the only key pressed (for example,
the Shift key), this value will be 0.
flags An integer that specifies which modifier keys
were pressed, the unmodified key value, and the keycode. The
modifier key constants are shown in the section "Keyboard Modifier
Keys".
ViewKeyUpScript
ViewKeyUpScript(char, flags)
char The character that was entered on the keyboard.
Note that if a modifier key is the only key pressed (for example,
the Shift key), this value will be 0.
flags An integer that specifies which modifier keys
were pressed, the unmodified key value, and the keycode. The
modifier key constants are shown in the section "Keyboard Modifier
Keys".
Keyboard Flags Integer
Bits Description
0 to 7 The keycode.
8 to 23 Original keycode. The 16-bit character that would result
if none of the
modifier keys were pressed.
24 Indicates that the key was from an on-screen keyboard.
(kIsSoftKeyboard)
25 Indicates that the Command key was in effect.
(kCommandModifier)
26 Indicates that the Shift key was in effect.
(kShiftModifier)
27 Indicates that the Caps Lock key was in effect.
(kCapsLockModifier)
28 Indicates that the Option key was in effect.
(kOptionsModifier)
29 Indicates that the Control key was in effect.
(kControlModifier)
Keyboard Modifier Keys
You use the keyboard modifier key constants to determine which
modifier keys were in effect when a keyboard event occurs.
Constant Value
kIsSoftKeyboard (1 << 24)
kCommandModifier (1 << 25)
kShiftModifier (1 << 26)
kCapsLockModifier (1 << 27)
kOptionsModifier (1 << 28)
kControlModifier (1 << 29)
protoKeyboard-based keyboard to be
open at the same time as other keyboards. When my keyboard opens,
it seems like any other keyboard closes. How do I keep multiple
keyboards open?protoKeyboard-based view opens, it closes
the last-opened protoKeyboard-based view. However,
you need not use protoKeyboard.protoDragger) and use the
RegisterOpenKeyboard view message to register the
keyboard with the system. Using RegisterOpenKeyboard
will ensure that the caret is set up properly and allows you to
track the caret changes with the
viewCaretChangedScript view message if desired.protoKeyboardButton-based keyboard list. Is this
possible?protoKeyboardButton has a method called
SetKeyboardList that lets you do this.
SetKeyboardList takes two arguments. The first
argument is an array of keyboard symbols to add to the list. The
second argument is an array of keyboard symbols to remove from the
list. Note that the keyboard symbols of the built-in keyboards are
listed on pages pages 8-26 and 8-27 of the Newton Programmer's
Guide.keyboardSymbol.preallocatedContext slot with the symbol of the
keyboarduserName slot with the name that will appear in
the protoKeyboardButton popupkeyboardSymbol slot with your keyboard's
symbolpreallocatedContext slot and the
keyboardSymbol slot must be the same symbol. Note
that the keyboardSymbol slot is required, but the
preallocatedContext slot is additionally necessary to
avoid exceptions on devices prior to Newton 2.1 OS.viewSetupDoneScript of the
protoKeyboardButton-based view, send the button a
SetKeyboardList message with your keyboard's symbol.
For instance, you might have the following
viewSetupDoneScript:viewSetupDoneScript: func()
begin
:SetKeyboardList( [kMyKeyboardSymbol], nil );
// Be sure to call the inherited viewSetupDoneScript method!
inherited:?viewSetupDoneScript();
end;
If you want to dynamically change the keyboard list, you can also
override the buttonClickScript. You must first call
SetKeyboardList, then call the inherited
buttonClickScript.
All additions and subtractions are removed from the list when your
protoKeyboardButton-based view is closed.
ViewIntoBitmap, or
the global function GetPointsArray, or a set of
functions from the Recognition chapter, particularly
GetStroke and GetStrokePointsArray.clKeyboardView also finds the smallest
key unit specified in the keyboard and uses this to constrain the
final horizontal size. It calculates a minimal pixel size for the
keyboard and makes sure that the final keyboard size is an
integral multiple of this value. For example, if the smallest size
is 10 pixels, then the final keyboard can be 10 pixels or 20
pixels, but not 15 pixels. If the view is 15 pixels, the keyboard
will be 10 pixels. m = w * (1/s)
m - minimal size
w - width of the longest keyboard row in key units
s - numeric equivelent for smallest keyboard unit specified in the keyboard:
(keyHUnit = 1, keyHHalf = 0.5, keyHQuarter = 0.25, keyHEighth = 0.125)
For the built-in ASCII keyboard in current ROMs, the longest row
is 14 key units, the smallest key unit used is
keyHQuarter, so the minimal width for the ASCII
keyboard is:
m = 14 * (1 / 0.25) = 14 * 4 = 56 pixels.
The keyboard will always be an integral multiple of 56 pixels in
width. Note that 224 pixels is exactly 4 * 56. By changing the
width to 223, the keyboard now becomes 168 pixels wide.
_DoCloseButton method to your application's base
view. The _DoCloseButton method is called when a
keyboard equivalent is used to close a view. This method takes no
arguments and must return true if you handled the
close, or return nil to let the system continue to
search for a close box in other applications.BuildContext. This guarantees that it will be
searched for a close box before your application is searched.
keyCommand if all I have is
the keyMessage symbol?MatchKeyMessage
that will do what you want. However, the documentation was
inadvertently left out of the current version of the Newton
Programmers Guide for Newton 2.1 OS. The documentation should
be: MatchKeyMessage(startView, keyMessage)
Finds the keyCommand frame for the specified message
starting with the specified view.
startView - The view from which to start searching
for the message
keyMessage - A symbol for the command message that
will be searched for. This must be the same message that is
specified in the keyMessage slot of the
keyCommand frame
return value - Either nil or a
keyCommand frame
The MatchKeyMessage function searches for the message
using the same lookup rules that are used when the system handles
a key command.
protoTransportHeader-based view?addedHeight slot.
The height of the transport header will be increased by this
amount.viewSetupFormScript
method of your protoTransportHeader view. This
works around a bug with protoTransportHeader:
self.stepChildren := SetUnion( self._proto.stepChildren,
self._proto._proto.stepChildren, true );
Finally, use NTK as you normally would to create the child
views.
nil for the
sendPrefs, outboxPrefs, or
inboxPrefs slots in my transport preferences
template, opening the slip throws -48204. What is going wrong?sendPrefs, outboxPrefs, or
inboxPrefs in your preferences dialog to set those
slot to nil. Due to a bug in the cooresponding views
for those preference items, -48204 is thrown when an attempt is
made to open the views. This will be fixed in a future ROM.
protoAddressPicker from
remembering the last people picked?protoAddressPicker has a slot called
useMemory that was left out of the documentation. If
this slot is set to nil, the memory mechanism will be
disabled.
RemoveTempItems when items are selected, the
ReceiveRequest message sometimes has bogus request
arguments (for instance, the cause is set to
'remote). Is this a known bug?RemoveTempItems. The
call to RemoveTempItems does not clear out the cache
of selected items correctly. This will be fixed in a future
version of the Newton OS.'remote, assume that the cause slot is actually
'user and act accordingly. If you receive a request
with its 'cause slot set to 'remote and
your transport's communications channel is connected then perform
the appropriate action for receiving remote items.ItemCompleted. Why is this problem
occuring?ItemCompleted. To work
around this, you should check to make sure the folder exists
before calling ItemCompleted. If it does not exist,
then set the transport's 'outboxFiling preference to
nil. Here is a code example:// This code assumes that the current receiver (self) is your transport
if NOT GetFolderStr( :GetConfig( 'outboxFiling ) ) then
:SetConfig( 'outboxFiling, nil );inboxFiling is nil.AutoPutAway method. Second, the
transport configuration slot 'dontAutoPutAway must be
set to nil (or not be present). This configuration
slot is new to Newton 2.1 OS and must contain the value nil or the
value 'never. If nil, items will be put
away automatically provided the application defined by the item's
appSymbol slot has the AutoPutAway
method. If 'never, items will not be automatically
put away regardless of whether the application defined by the
item's appSymbol slot implements the
AutoPutaway method.sprintf-like function for formatting numbers called
FormattedNumberStr. The Newton Programmer's Guide 2.0
First Edition (beta) says this function is no longer supported.
How do I format my numbers?FormattedNumberStr. Here
is the FormattedNumberStrAPI that is supported.
FormattedNumberStr should be considered to have
undefined results if passed arguments other than those specified
here.FormattedNumberStr(number, formatString)
number A real number.
formatString A string specifying how the number
should be formatted.
This function works similar to the C function
sprintf. The formatString specifies how
the real number should be formatted; that is, whether to use
decimal or exponential notation and how many places to include
after the decimal point. It accepts the following format
specifiers:
%f Use decimal notation (such as
"123,456.789000").
%e Use exponential notation (such as
"1.234568e+05").
%E Use exponential notation (such as
"1.234568E+05").
You can also specify a period followed by a number after the %
symbol to indicate how many places to show following the decimal
point. ("%.3f" yields "123,456.789" for
example.)
Note: FormattedNumberStr uses the current values of
GetLocale().numberFormat to get the separator and
decimal characters and settings. The example strings above are for
the US English locale.
Known Problems
Other specifiers
Do not use other formatStrings. Previous
releases of the documentation listed %g and
%G as supported specifiers. The behavior of these
specifiers has changed with the Newton 2.0 OS. Given the
similarities to the sprintf function, it may occur to
you to try other sprintf formatting characters. Specifiers other
than above have an undefined result and should be considered
undocumented and unsupported.
Large numbers
FormattedNumberStr does not work properly for
numbers larger than 1.0e24. If the number is very
large the function can cause the Newton device to hang.
Small numbers or long numbers
If more than 15 characters of output would be generated, for
example because you are using %f with large number or
a large number of digits following the decimal,
FormattedNumberStr has undefined results, and can
cause the Newton device to hang.
Rounding
FormattedNumberStr does not guarantee which
direction it will round. In the Newton 2.0 OS, it rounds half
cases down rather than up or to an even digit. If you need a
precisely rounded number you should use the math functions
Ceiling, Floor, NearbyInt,
or Round with suitable math.
Trailing decimals
In early releases of the Newton 1.0 OS, there was a bug in
FormattedNumberStr that caused a trailing decimal
character to be added when zero decimal positions was specified.
That is, FormattedNumberStr(3.0, "%.0f") resulted in
"3." not "3". To properly test for and
remove this unwanted extra character you must be sure to use the
character specified in the Locale settings and not assume the
decimal character will be a period.
Gestalt
function as follows:// define this somewhere in your project
// until the platform file defines it (not in 1.2d2)
constant kGestalt_BackLight := '[0x02000007, [struct, boolean], 1];
local isBacklight := Gestalt(kGestalt_BackLight);
if isBacklight AND isBacklight[0] then
// has a backlight
else
// has not got one
To find the current state of the backlight, use the following
function:
BackLightStatus()
Changing backlight status
To turn the backlight on or off, use:
BackLight(state)
state - nil (turn backlight off) or non-nil (turn backlight
on)
StrPos global function to search for a ':' character,
it finds other characters such as '.' or ';'. Isn't that a bug?
How can I reliably search for these characters in any locale?StrPos and many of the other
string functions are case insensitive - they treat upper and
lowercase letters as being identical. In other languages,
characters such as accented letters may be considered as different
cases of the base letter, so they are treated as identical as
well. In the Newton OS model, the concepts 'same case' and 'same
position in the sorting order' are not distinguished, so all cases
of a letter will sort to the same position. Going backwards, all
characters that sort identically are considered to be different
cases of the same letter. Well, in the Swedish sort order, many
punctuation characters are defined to sort to the same place, and
so the case insensitive functions in the Newton device treat the
characters as identical. Many special and punctuation characters
are grouped this way, but perhaps the most surprising set is ?
¡ : , . ; ¿ and !, which all sort to the same position
and so are treated as identical in Swedish by StrPos
and other case insensitive functions.CharPos function instead of
StrPos.
'gmt
slot of a city entry, which can be gotten with the
GetCityEntry global function. See the "Built In Apps
and System Data" chapter of the Newton Programmers Guide for
details. Note that the docs incorrectly say the gmt
slot contains the offset in minutes, when it is actually specified
in seconds. The current location is available in the
'location slot of the user configuration frame. Use
GetUserConfig('location) to access it. The global
function LocalTime can be used to convert a time to
the local time in a distant city.LocalTime to compute the delta
between the current city and the GMT city, then add the delta to
the given GMT time. LocalTime can be used directly to
go the other way--getting the GMT time from the local time.LocalTime(time,
where)time - a time in minutes in the local (Newton
device) zone, for example as returned from the Time
functionwhere - a city entry, as returned from
GetCityEntryresult - a time in minutes in the where
city, adjusted as necessary for time zone and daylight
savings.LocalTime tells you the local time for the distant
city, given a time in the current city. For example, to find out
the time in Tokyo: Date(LocalTime(time(), GetCityEntry("Tokyo")[0]))
#C427171 {year: 1997, month: 2, Date: 22, dayOfWeek: 6,
hour: 8, minute: 1, second: 0, daysInMonth: 28}
Because the Newton OS doesn't have time zones, it can't keep track
of daylight savings time by changing zones (for example, from
Pacific Standard Time to Pacific Daylight Time). Instead, it uses
a bunch of rules that tell it when to set the time ahead or back,
and by how much. The global function DSTOffset can be
used to find out how much these daylight savings time rules have
adjusted a given time for a given city.
DSTOffset(time,
where)
time - a time in minutes in the where city
where - a city entry, as returned from
GetCityEntry
result - an integer, number of minutes that
daylight savings adjusted that time in that city.
DSTOffset tells you what the daylight savings
component is of a given time in a given location. This component
would need to be subtracted from the result of the global function
Time to get a non-daylight-adjusted time for the
current location.
// it's currently 2:52 PM on 3/4/97, no DST adjustment
DSTOffset(Time(), GetCityEntry("Cupertino")[0]);
#0 0
// but during the summer, DST causes the clocks to "spring forward" an hour.
DSTOffset(StringToDate("6/6/97 12:34"), GetCityEntry("Cupertino")[0]);
#F0 60
Sqrt with a negative number on the
Newton, or use Compile in the NTK Inspector, I get a
strange result. However, if I just type sqrt(-2) into
the listener I get a different strange result. What's going
on? call compile("sqrt(-2)") with ()
#4412F2D -1.79769e+308
sqrt(-2)
#440DE05 1.00000e+999
A: There is a floating point library bug in Sqrt on
the Newton OS. When passed a negative number, the large positive
value is returned instead of a not-a-number value. You can work
around it using Pow(x, 0.5) instead of
Sqrt(x) if there is no way to guarantee that the
value passed to Sqrt is non-negative, or simply check
and see if the argument is less than 0 and return a not-a-number
constant.
The reason sqrt(-2) works differently when you type
it into the NTK Inspector is because of a compiler process known
as constant folding. Sqrt can be evaluated at compile
time if you pass it a constant argument. So what's really
happening is that NTK is evaluating the Sqrt function
during the compile phase and passing the resulting floating point
number (or rather, not-a-number) to the Newton device where it's
promptly returned. An NTK real number formatting limitation
displays non-a-number values and infinities as
1.00000e+999 rather than as some other string. You
can use IsNAN to determine if a real number is a
not-a-number value.
You can avoid constant folding and force evaluation on the Newton
device by using a variable. For instance:
x := -2;
y := sqrt(x);
#C4335B1 -1.79769e+308
Also, note that FormattedNumberStr does not properly
handle not-a-number values. (it returns "Number too small.")
ExtractByte
or ExtractWord or possibly ExtractLong
to get the bytes out in integer form, then do something with them.
However, keep in mind that NewtonScript integers are only 30 bits
wide, whereas the serial number is 64 bits wide, so you'll never
be able to put all the information contained in the serial number
into a single integer. (3 integers would be required.)SetClass to change it's class to 'real,
which would effectively "cast" the 8-byte object to a real number.
This is a bad idea, because real numbers are interpreted using
bitfields with special meanings, and it's possible for two real
numbers to have different binary representations and still
evaluate as equal using the '=' operator. (Any two not-a-number
values will do this.)StrHexDump is the
best way to format the serial number object for humans to read. If
you want to break it up to make it more easily readable, you could
do something like this: local s := StrHexDump(call ROM_GetSerialNumber with (), 2);
StrReplace(s, " ", "-", 3);
"0000-0000-0154-8423 "
ModalConfirm slip,
because your code is paused waiting for the result. You can,
however, remove an AsyncConfirm slip. The return
value from AsyncConfirm (which is documented in the
Newton Programmer's Guide as "unspecified") is actually a
reference to the confirm view. Sending that view a
Close message dismisses the slip. The callback
function will not be called if this slip is removed in this way,
so make sure your program handles that case.clEditView
(the children paragraph, polygon, and picture views containing
text, shapes, and ink) to a soup and restore it later?viewChildren array for the
clEditView, probably in the
viewQuitScript. To restore, assign the array from the
soup to the viewChildren slot, either at
viewSetupFormScript or
viewSetupChildrenScript time; or later followed by
RedoChildren.viewChildren array. (For example, text has optional
slots for fonts and tabs, shapes have optional slots for pen
width, and new optional slots may be added in future versions.)
Saving the whole array also allows you to gracefully handle
templates in the viewChildren array that don't have
an ink, points, or text slot. In the future, there may be children
that represent other data types.
clEditView?
If I drag out a clParagraphView child in NTK, the
text is not selectable even if I turn on
vGesturesAllowed.clEditViews have special requirements. To create a
text child of a clEditView that can be selected and
modified by the user (as if it had been created by the user) you
need to do the following: textTemplate := {
viewStationery: 'para,
viewBounds: RelBounds(20, 20, 100, 20),
text: "Demo Text",
};
AddView(self, textTemplate);
AddView), because the clEditView expects
to be able to modify the contents as the user edits this item. The
template (textTemplate above) should also be created
at run time, because the clEditView adds some slots
to this template when creating the view. (Specifically it fills in
the _proto slot based on the
viewStationery value. The _proto slot
will be set to protoParagraph) If you try to create
too much at compile time, you will get -48214 (object is read
only) errors when opening the edit view.
The minimum requirements for the template are a
viewStationery of 'para, a
text slot, and a viewBounds slot. You
can also set viewFont, styles,
tabs, and other slots to make the text look as you
would like.
TieViews, do I simply remove the appropriate slots
from the viewTie array?viewChangedScript
to be called. This can happen without calling
SetValue, for example, when the user writes into a
view that has recognition enabled, the
viewChangedScript will get called.UntieViews function, and call it if it exists, but if
it does not, removing the pair of elements from the tied view's
viewTie array is fine.
FilterDialog and ModalDialog. (See the
Q&A "FilterDialog and ModalDialog Limitations" for important
information on those methods.)
clParagraphView's
viewIdleScript is fired off automatically. (For
example, an operation which results in the creation or changing of
a keyboard's input focus within the view will trigger the
viewIdleScript.) Why does this happen and what can I do about
it?clParagraphView class internally uses the idle
event mechanism to implement some of its features. Unfortunately,
any viewIdleScripts provided by developers also
execute when the system idle events are processed. Only the
"heavyweight" views do this, "lightweight" paragraph views (in
other words, simple static text views) do not.viewIdleScript. You can either
accept the extra idle script calls, or use another
non-clParagraphView based view to implement your idle
functions.theView:FilterDialog(), the part of the screen that
was not covered by the theView no longer accepts any
pen input. theView is a protoFloatNGo.
Is there some trick?FilterDialog and
ModalDialog when used to open views that are not
immediate children of the root view. At this point we're not sure
if we'll be able to fix the problem.FilterDialog or ModalDialog
to open more than one non-child-of-root view at a time.
Opening more than one at a time with either of these messages
causes the state information from the first to be overwritten with
the state information from the second. The result will be a
failure to exit the modality when the views are closed.FilterDialog.BuildContext.
This is the best solution because it avoids awkward situations
when the child of an application is system-modal. (Application
subviews should normally be only application-modal.)ModalDialog message instead of
FilterDialog. ModalDialog does not have
the child-of-root bug. (FilterDialog is preferred,
since it uses fewer system resources and is faster.)view:FilterDialog();
if view.modalState then
begin
local childOfRoot := view;
while childOfRoot:Parent() <> GetRoot() do
childOfRoot := childOfRoot:Parent();
childOfRoot.modalState := view.modalState;
end;
FilterDialog message to is not an immediate child of
the root. You can probably improve the efficiency in your
applications, since the root child is ususally your application's
base view, which is a "well known" view. That is, you may be able
to re-write the code as follows:
view:FilterDialog();
if view.modalState then
base.modalState := view.modalState; {left: -30, top: <top>, right: 0, bottom: <bottom>}
and the following view justification:
vjParentRightH + vjLeftRatio
DragAndDrop
message to a view, the bitmap for the pre-drag state is cached.
Once the drag loop starts, you can not update that cached bitmap.
When you "scroll" the view (probably using
RefreshViews), you update the screen, but the cached
bitmap is still there and is used by the DragAndDrop
routine to update the screen as the dragged item is moved.
ModalConfirm and
AsyncConfirm, the 2.0 Newton Programmer's Reference
says you may pass three types of things as the buttonList
argument: a symbol ('okCancel or
'yesNo), and array of strings, or an array of frames
with 'value and 'text slots.'okCancelDefaultOk,
'okCancelDefaultCancel,
'yesNoDefaultYes, and 'yesNoDefaultNo.
They do the obvious thing, setting the default key as specified
and the close key to Cancel or No if those aren't the default.
However, using these symbols on a Newton 2.0 OS device will result
in the "OK" and "Cancel" buttons always being displayed, even if
you specify 'yesNoDefaultYes or
'yesNoDefaultNo.buttonList
argument allows an additional slot, called 'keyValue.
Supported values for this slot are the symbols
'default and 'close, or NIL/not present.
'default makes the button the default key, and
'close makes the button activate with the close key.
Any other value will cause a problem in the current Newton 2.1
implementation. The keyValue slot is ignored on the
Newton 2.0 OS.'yesNoDefaultYes and 'yesNoDefaultNo
symbols if you intend to run on both Newton 2.0 and 2.1 devices.
Instead, use one of these specifiers: '[{text: "Yes", value: TRUE, keyValue: default}, {text: "No", value: NIL, keyValue: close}]
'[{text: "Yes", value: TRUE}, {text: "No", value: NIL, keyValue: default}]
ROM_DefRotateFunc. When I rotate the screen the
base view rotates properly, but the linked view closes. Do I need
to add a ReorientToScreen slot to the linked
view?ReorientToScreen slot in the view tells the OS that
this view is OK, so the slot is used first as a token ("magic
cookie") to tell the OS that this view knows about rotation. Later
during the rotation operation, the ReorientToScreen
message is sent to your application's base view and to other views
that are immediate children of the root view. That method then
performs its second function, which is to completely handle
resizing the view and its children for the new screen size. (Even
views which are small enough so that no resizing is necessary need
a ReorientToScreen method. That method may need to
move the base view to ensure that it remains on-screen after
rotation.)ROM_DefRotateFunc for this
script, since it fills the magic cookie requirement and handles
resizing for most views. ROM_DefRotateFunc is very
simple: it send a close and then an open message to the view.
Since well-written applications take screen size into account when
they open, this works fine in most cases. However, applications
that keep track of internal state that isn't preserved when the
app is closed can't use ROM_DefRotateFunc, because
when the app reopens on the rotated screen, it will look
different. Opening a linked subview is one example of this; it
doesn't usually make sense to remember that a slip is open, since
it's usually closed when your application is closed.ReorientToScreen method to your linked views
wouldn't help; since they are descendents of your base view and
not children of the root view, the OS wouldn't handle these views.
(It's up to your application to keep its kids under control.) You
could change your application so that it kept track of whether the
linked views were open or closed, and restored them to the same
state when it was reopened. However, this might be confusing to
users who closed your app and then opened it again much later.ReorientToScreen method, which either resizes the
views so they fit on the new screen, or which closes and reopens
the views such that the floaters also re-open. By using the
ReorientToScreen message to handle the special case,
you get to do something different during rotation versus during
opening at the user request (for example, after tapping on the
Extras icon.)BuildContext also must be handled
carefully during rotation. Because they are themselves children of
the root view, they'll each need their own
ReorientToScreen method or the screen may not be
rotatable when they are open or they won't reopen after rotation.
If you use ROM_DefRotateFunc, the slip itself will be
closed and reopened, and care may need to be taken to ensure the
slip properly handles being reopened, and that its connection to
its controlling application is not lost.protoTXView text engine in
Newton 2.1 OS. How can I get text, styles, pictures, etc. out of
the object returned by protoTXView's
Externalize method without either a) instantiating a
protoTXView or b) digging in the data structure?protoTXView produces. The data structures
in that object are not documented or supported. You may be tempted
to do this anyway, since it looks as though the data structure is
obvious. Don't, it isn't. ProtoTXView actually uses
several different data formats depending on the complexity and
storage destination for the data.protoTXView to get at the data. Here's one way: local textView := BuildContext(
{
_proto: protoTXView,
viewBounds: SetBounds(0, 0, 0, 0),
viewFlags: 0,
ReorientToScreen: ROM_DefRotateFunc,
});
textView:Open();
textView:Internalize(myExternalizedData);
protoTXView APIs to
get the data from the textView object. Don't forget
to clean up with textView:Close() when you're
done.
protoTXView data stored in a soup entry, for example
to get the text for sending in email?protoTXView method
GetRangeData always allocates its storage from the
NewtonScript heap, so you will need to copy the data into a
destination VBO in chunks. Here's some code to do that. (This code
uses a 4K block size, you may wish to adjust that as necessary,
add error checking, etc.) StringFilter is used to
remove the protoTXView graphic indicator. constant kChunkSize := 0x1000; // 4K chunks
local start := 0;
local theText := GetDefaultStore():NewVBO('string, length(""));
// make VBO into a proper string
BinaryMunger(theText,0,nil, "", 0, nil);
while numChars-start > kChunkSize do
// strip out graphics characters
StrMunger(theText,start, nil,
StringFilter(
textView:GetRangeData(
{
first: start,
last: start := start + kChunkSize
}, 'text),
"\u2206\u", 'rejectAll),
0, nil);
// copy remainder
if start < numChars then
StrMunger(theText,start,nil,
StringFilter(
textView:GetRangeData(
{first: start, last: numChars}, 'text),
"\u2206\u", 'rejectAll),
0, nil);
// theText now holds plain text from the protoTXView
ClearVBOCache as mentioned in the Q&A, "How to
Avoid Resets When Using VBOs". If you are having problems with
large VBOs during code like that mentioned above, see that Q&A
for more information.
clParagraphView and
would like to find the current position of the caret within that
view so that I can scroll to it. Is there a way to do this?clParagraphView method called
caretRelativeToVisibleRect that you can use.'inbox, 'top, 'left,
'bottom, 'right, or nil.
Below is a list of what each return value signifies.paragraphView:CaretRelativeToVisibleRect( visibleBox
)'inbox The caret is positioned inside the visible
region.'top The caret is above the visible region.'bottom The caret is below the visible region.'left The caret is to the left of the visible
region.'right The caret is to the right of the visible
region.nil The view has no caret.protoUpDownScroller on an Apple
MessagePad 2000 , tapping on the scroller once calls the
viewScroll2DScript two or three times. Shouldn't the
scroller call the script only once per tap?viewScroll2DScript once per tap, but rather calls it
repeatedly while the pen is held down over the scroll arrow. This
is normal scroller behavior, and has in fact been there all along.
with the MP2000, the processor is so much faster that it can chug
through many scroll operations before the pen is released.while not StrokeDone(unit) do
targetView:viewScroll2dscript(....)". If it takes even 1
tick for the StrokeDone function to report true, it's
possible that the viewScroll2DScript might have been
called more than once.viewScroll2DScript. Use the global function
Sleep for this, as that call will yeild the
NewtonScript task and let other parts of the OS work (or sleep the
processor, saving battery power.) constant kMaxScrollSpeed := 60; // ticks
viewScroll2DScript: func(...)
begin
local t := ticks();
... // do scrolling stuff
RefreshViews(); // show scrolled result
Sleep(MAX(kMaxScrollSpeed - (ticks() - t), 0));
end;
The above code should have the unit scrolling at a fairly
consistent one-scroll-per-second unless the time it takes to do
the scrolling stuff is more than 1 second, in which case it'll
just go as fast as it can. The drawback to this approach is that
the script will always delay for at least a second, so if for
example the user taps the up arrow then the down arrow in less
than a second, there will seem to be a delay between the up scroll
and down scroll that would not necessarily need to be there.
You could certainly be more clever with your delays by counting
ticks and watching the count paramater to your scroll script. This
might even result in a better performing delay. However, it's
probably not worth the effort it would take to implement this. The
one-scroll-per-second approach works well, is simple, and it's
unlikely that the user will ever notice the small extra delay.
(Don't try to do one-scroll-every-5-seconds using this method
though, your users may quickly grow annoyed at the extra
delay!)