A Dialog acts as a floating "dialog box" or window, often holding a number
of components for the user to interact with. Some dialogs are meant to appear
only temporarily: alert boxes, file selectors, etc. Others may stay up for
a while: toolboxes, command windows, etc.
If your Dialog will contain one or more Buttons in a reply bar, you may wish
to use the default, closeDialog, cancel, or destructive
properties for some of these buttons.
Dialog Looks
The following looks are supported:
-
0 Default Dialog
-
An unremarkable dialog box
-
1 Tool Dialog
-
Drawn in the style of a tool dialog window, somewhat round and thick
-
2 Fit Note Pad
-
This has a corner folded up on the bottom right and looks as if its sitting
on top of a stack
-
3 Tagged Fit Note
-
This has the bottom right corner folded up
-
4 Open Folder look
-
Has the appearance of a file folder
Dialog Properties
Standard Properties: borderBottom, borderLeft, borderRight, borderTop,
caption, children, class, enabled, height, left, look, numChildren, parent,
proto, sizeHControl, sizeVControl, tile, tileHAlign, tileHInset, tileLayout,
tileSpacing, tileVAlign, tileVInset, top, version, visible, width.
-
enabled:
-
If the Dialog is disabled and holds the system focus, the window itself will
become the system focus.
-
parent:
-
The only valid parent for a Dialog is the null component, also known as "app."
sizeHControl, sizeVControl: Only SIZE_AS_NEEDED and SIZE_AS_SPECIFIED
will be supported. SIZE_AS_NEEDED will only be partially supported: when
the component becomes visible and their height or width is the minimum allowable
value, the component will size itself to a default value.
-
visible:
-
Setting a Dialog visible not only makes it visible, but also brings it to
the front, as if you had invoked the BringToFront( ) action.
-
focus component (must be a child or descendant of the form (or a null
component))
-
This property holds the component that the window will set as the active
system focus when the window becomes active. The property will hold the component
with the system focus as long as the system focus remains within the window.
If the value of the focus property is the null component and the window
is becoming visible or becoming active, then the window will set the system
focus to the first child component that will accept it.
When the system focus is in the window, setting the focus property will also
set the system focus.
Note that a popped-up Popup window, though a child of the window, will not
show up in its focus property. This is because the popped-up Popup is a window
itself, and keeps track of its own focus.
-
type integer (0-5)
-
If the dialog's parent is "app," then this property determines the dialog's
modality and placement relative to other windows. This property cannot be
changed if the dialog is visible.
Dialog Events
-
0 NON_MODAL:
-
Non-modal dialogs are normal windows.
-
1 TOOL_BOX:
-
Toolbox dialogs appear above non-modal windows and also never get the focus
(and so never become active). Children of this type of dialog will never
become the active selection (the user can not copy their data to the clipboard).
-
2 MODAL:
-
Modal windows will not allow keyboard input to be sent to components that
are not either children of the dialog or of "On-top" windows. This means
that attempts to set the focus will fail if the component is not either a
child of the modal window or of an On-top window. Modal windows clear the
input and pop down any Popup windows before becoming active.
-
3 SYS_MODAL:
-
System-modal dialogs behave similarly to Modal floaters, but always appear
above other System-modal windows.
-
4 ON_TOP:
-
"On-top" dialogs behave like Toolbox windows but appear above everything
but Popup windows, and have the special ability to receive input even when
a modal window is active. Because they are like Toolbox windows, they will
never get the focus. Children of this type of dialog will never become the
active selection (the user can not copy their data to the clipboard).
-
5 POPUP:
-
Popup dialogs go away whenever the user clicks on anything inside or outside
them. They also go away whenever a Modal or System-modal window becomes visible.
Children of this type of dialog will never become the active selection (the
user can not copy their data to the clipboard).
_aboutToClose( )
_aboutToClose( self AS dialog )
This event is generated when the Dialog is about to close; i.e., when
visible has changed from one to zero.
Pass:
-
self dialog
-
The Dialog experiencing the event.
_aboutToOpen( )
_aboutToOpen( self AS dialog )
This event is generated when the Dialog is about to appear; i.e., when
visible has changed from zero to one.
Pass:
-
self dialog
-
The Dialog experiencing the event.
_activeChanged( )
_activeChanged( self As dialog, gained AS integer )
This event is generated when a different window becomes an active window--the
non-modal, modal, or system modal dialog that is on top.
Passed:
-
self dialog
-
The component experiencing the event.
-
gained integer
-
If this argument is non-zero, then this dialog has just become an active
window. If this argument is zero, then the dialog is not an active window.
Dialog Actions
BringToFront( )
BringToFront( )
This action causes the Dialog, if it is visible, to come to the front of
the screen, appearing above other dialogs of its priority.
Pass:
Nothing.
The system module contains a Display component, which keeps track of information
about the device's display. An application could create its own Display
component, but it's not clear why this would be useful.
Display Properties
Standard Properties: class, parent, proto, version.
-
height integer
-
This read-only property is the device's display width, as measured in pixels.
-
width integer
-
This read-only property is the device's display height, as measured in pixels.
Display Events
None.
Display Actions
None.
The Draw component allows the NewBASIC programmer access to the lowest level
of graphics functionality in the New Deal operating system. The underlying
implementation of this component is the same human optimized assembly code
in the kernel that powers drawing of the user interface. Draw components
write internally stored and manipulated gstring structures.
Draw Properties
-
data complex
-
This value stors the actual graphics string as a complex. This value can
be passed to other components when setting their .graphic properties.
Draw Events
None.
Draw Actions
start( )
start( ) AS integer
This action begins defining a graphic string object to draw. This must be
the first action sent to a draw component. All subsequent actions are stored
within the draw component until a stop( ) action is recieved.
This action instructs the New Deal subsystem to create an initial gstring.
Pass:
Nothing.
stop( )
stop( ) AS integer
This action stops defining a draw component.
Pass:
Nothing.
rectangle( )
rectangle(left AS integer, top AS integer, right AS integer, bottom
AS integer)
AS integer
This action draws the passed rectangle into the draw component. This rectangle
is filled, according to the currently stored color.
Pass:
-
left
-
The left boundry of the rectangle.
-
top
-
The top boundry of the rectangle.
-
right
-
The right boundry of the rectangle.
-
bottom
-
The bottom boundry of the rectangle.
ellipse( )
ellipse(left as integer, top as integer, right as integer, bottom
as integer) as integer
This action adds the given ellipse to the draw component.
polygon( )
polygon(points as array[][], count as integer) as integer
This action adds the given polygon to the draw component. This action passes
a set of count points within a two dimensional array passed in the points
data.
areacolor( )
areacolor(color as integer) as integer
This action sets the current area color for a draw component. Future filled
components will be drawn using this color.
linecolor( )
linecolor(color as integer) as integer
Thsi action sets the current line color for a draw component. Future drawn
components will be drawn using this color.
moveto( )
moveto(x as integer, y as integer) as integer
This action moves the current cursor position of the draw component to the
given point, based on the upper left corner as the origin (0,0).
lineto( )
drawlineto(x as integer, y as integer) as integer
This action adds a line from the current cursor position to the given point
to the draw component.
text( )
text(text as string) as integer
This action adds text at the current cursor position to the draw component.
font( )
font(font as string, size as integer) as integer
This action sets the current font and point size of the draw component. Fonts
are passed as strings containing their New Deal names. For example. "URW
Roman", etc.
rotate( )
rotate(angle as integer) as integer
This action rotates subsequent operations sent to the draw component by the
given angle.
The Entry component acts a simple one-line text entry.
Entry Looks
The following look is available:
-
0 Default Entry
-
A plain text entry.
Entry Properties
Standard Properties: clipboardable, copyable, deletable, enabled,
focusable, focusState, height, left, look, sizeHControl, sizeVControl, top,
version, visible, width.
-
sizeHControl, sizeVControl:
-
SIZE_AS_NEEDED is only partially supported: when the component becomes visible
and has height or width of zero, the component will re-size
itself to a default value.
-
filter integer (0-)
-
Filter to use when accepting characters. The following filters are supported:
-
0 No filter
-
1 Custom: generate _filterChar( ) events.
-
32 Numeric characters only
-
36 Alphanumeric: alphabetic and numeric characters
-
42 Dashed alphanumeric: alphanumeric and "-"
If you assign a value to this property corresponding to a filter not supported
on the platform, the value will be ignored.
-
maxChars integer (0-250)
-
Use this property to impose a maximum number of characters on the entry's
text. If this property is changed to be less than the current length of the
entry's text, the text will be truncated. If maxChars is zero, then
the string may be up to 1000 characters long.
-
numChars integer (0-maxChars)
-
Number of characters in the current text. This property is read-only; to
change it, change the .text property
-
text string
-
The entry's current text. This string may be up to 1000 characters long.
Entry Events
_entered( )
_entered( self AS entry )
This event is generated when the user is done entering text--when the user,
editing the text, presses the Enter key, the Tab key, or clicks on some other
component.
Pass:
-
self entry
-
The Entry experiencing the event.
_filterChar( )
_filterChar( self AS entry, newChar AS integer, replaceStart AS integer,
replaceEnd AS integer, endOfGroup AS integer ) AS integer
This event is generated when the user enters a character into the text and
the filter property is 1. This event will not catch Enter characters,
which generate the _entered( ) event. If the user pastes a
multiple-character string into the Entry, it will generate one
_filterChar( ) event for each character in the string. The
endOfGroup argument signals that this is the last character of such
a multi-character string.
The event handler should return the Unicode value of the character to insert
in the string, or zero to specify that no character should be inserted at
this time.
Pass:
-
self entry
-
The Entry experiencing the event.
-
newChar integer
-
The Unicode value of the character entered.
-
replaceStart integer (0-numChars)
-
Offset of the start of the range of characters being replaced.
-
replaceEnd integer (replaceStart-numChars)
-
Offset of the end of the range of characters being replaced. If this is the
same as replaceStart, then no characters are being replaced, but this
is the offset of the insertion point.
-
endOfGroup integer (0-1)
-
This argument is one if this character is the last character of a multi-character
insert (or the only character of a single-character insert). It is zero
otherwise.
_focusChanged( )
_focusChanged( self AS entry, oldFocusState AS integer )
This event is generated when the Entry gains or loses the focus--after its
focusState property has changed.
Pass:
-
self entry
-
The Entry gaining or losing the focus.
-
oldFocusState integer
-
Value of the focusState property before the event occurred. To find
out the new value, check the property.
Entry Actions
None.