Figure 26-0

Display 26-0

SwatDisplay 26-0

Table 26-0
Figure 26-1 Hierarchy of System Objects

The GenApplication maintains a set of links to the GenScreen objects; this is 
distinct from the generic tree headed by the GenSystem. Every GenScreen is 
the parent of a Visible tree; its children are all GenFields displayed on that 
screen.
26Generic System Classes

Revision:  l

The Generic System Objects (GenSystem, GenScreen, and GenField) act as 
the root objects in the GEOS UI. Every application you create will be in a 
generic tree headed by these objects; however, you will rarely need to interact 
with these objects. 

The system objects are created by GEOS automatically; you will never need 
to declare instances of these objects within your code. Whenever an 
application object is instantiated, the system automatically attaches it to the 
generic and visible trees headed by these objects.

This chapter is meant to show you how these objects work within the GEOS 
system, what capabilities they automatically provide for you, and what 
information they contain that may aid in debugging efforts.

	26.1	The System Objects

The GenSystem, GenScreen, and GenField objects work to create a platform 
for your application to run upon. You will never create these objects, and you 
might never need to communicate with them. Nevertheless, some 
applications will want to send messages to these objects. Also, while you are 
debugging code, you may find it useful to examine the instance data of these 
objects (though you may never change this data). For these reasons, the 
objects are fully documented here.

When GEOS starts up, it creates a single GenSystem object. This object is the 
top-most object of a generic tree which contains all GenApplication objects. It 
also maintains a separate tree which contains the GenScreen objects. 
Whenever GEOS is running, there will be exactly one GenSystem object. All 
generic objects which are displayed on any screen will belong to the generic 
tree headed by the GenSystem. (See Figure 26-1.)

GEOS creates a GenScreen for every screen being used by the system. Each 
screen is the head of a Visible tree. (GEOS currently does not support multiple 
screens on a single system; however, future versions may support multiple 
screens.)

GEOS can provide several different environments, all of which may be 
running simultaneously on a single machine. For example, Geoworks 
Ensemble provides "Beginner," "Intermediate," and "Advanced" rooms. Each 
of these environments is represented by a GenField object. Each GenField 
object is a generic child of the GenSystem. It is also a Visible child of the 
appropriate GenScreen.

Every Application object is the child of a GenField. When an application is 
started, its GenApplication is automatically attached to the appropriate 
GenField, which is generally the GenField which was active when the 
application was started. An application may transfer itself to a different 
GenField; this will have the effect of moving the application to a different 
GEOS environment.

	26.2	The GenSystem Object


Whenever GEOS is running, there is a single GenSystem object. This object 
is the head of the generic tree which contains all generic objects being 
displayed on any screen. (There may be other generic object trees which are 
not connected to the GenSystem; however, these objects will have no user 
interface. For example, every GenDocumentGroup is the head of a separate 
generic object tree.)

	26.2.1	GenSystem Features

The GenSystem object has many responsibilities. Most of these are of no 
interest to the application. There are a few which applications will want to 
know about:

u	The GenSystem is the head of the generic tree which contains all generic 
objects which are usable on any screen. This makes it a useful reference 
point when searching through generic objects during debugging.

u	The GenSystem keeps track of the specific UI under which GEOS is 
running.

u	The GenSystem keeps track of the default GenScreen object. Whenever 
a new GenField is created, it is made a visible child of that GenScreen.

u	The GenSystem keeps track of the default GenField object. Whenever an 
application is started, the application object will be made a generic child 
of the default GenField.

The GenSystem is also used as a convenient point to alter such system-wide 
features as the mouse pointer image, system modality, and the layering of 
windows. 

	26.2.2	GenSystem Instance Data

GenSystemClass instance data is internal and should never be set or 
altered by your application. It is provided here for reference, in case you need 
to examine the data during debugging. However, your code should not 
examine the data directly; instead, it should use the messages described in 
section 26.2.3 on page 1457 to examine these fields.

GenSystem itself should also never be subclassed and instances of the class 
may not be statically defined, nor instantiated by applications or libraries 
other than the UI library itself.

Code Display 26-1 GenSystem Instance Data

/* Never access or alter these instance data fields.
 * They are for internal use only. */

@instance Handle			GSYI_specificUI;
@instance Handle			GSYI_defaultUI;
@instance optr			GSYI_defaultScreen;
@instance optr			GSYI_defaultField;
@instance @composite			GSYI_screenComp;



GSYI_specificUI stores the handle of the specific UI in use by this system 
object. By default, this specific UI will also be the same specific UI used by all 
applications underneath this system object. 

GSYI_defaultUI stores the handle of the default specific UI to use for the next 
loaded application. This may be overridden by a GenField (though this is 
rare). For all intents and purposes, GSYI_defaultUI will be the same as 
GSYI_specificUI.

GSYI_defaultScreen stores an optr of a GenScreen. By default, new GenField 
objects will be made visible children of this GenScreen.

GSYI_defaultField stores the optr of a GenField. By default, new application 
objects will be made generic children of this GenField. This may be 
overridden with MSG_GEN_APP_ADD_TO_PARENT, though normal 
applications will not do this.

GSYI_screenComp stores the optr of the first GenScreen object child. The 
GenSystem is the head of two object trees. One is a visible tree containing all 
GenScreen objects; the other is a generic tree containing all application 
objects (and their generic children). The generic tree is specified by GI_comp, 
as usual.

	26.2.3	GenSystem Basics

MSG_GEN_SYSTEM_GET_DEFAULT_SCREEN, 
MSG_GEN_SYSTEM_GET_DEFAULT_FIELD, 
MSG_GEN_SYSTEM_SET_DEFAULT_FIELD

Some of the GenSystemClass instance data can be examined or changed 
with messages. Applications may find out the current default screen or 
default field with MSG_GEN_SYSTEM_GET_DEFAULT_SCREEN and 
MSG_GEN_SYSTEM_GET_DEFAULT_FIELD, respectively. Applications may 
also set the default field with MSG_GEN_SYSTEM_SET_DEFAULT_FIELD. 
(Only the system may set the default screen.)

You may retrieve the optr of the current default GenScreen object in use by 
the system with MSG_GEN_SYSTEM_GET_DEFAULT_SCREEN. You may not 
change the system's screen object, however.

You may also retrieve the optr of the current default GenField object that 
GenApplications will be attached to when loaded with 
MSG_GEN_SYSTEM_GET_DEFAULT_FIELD. 

n	MSG_GEN_SYSTEM_GET_DEFAULT_SCREEN



optr	MSG_GEN_SYSTEM_GET_DEFAULT_SCREEN();

This message returns the optr of the default GenScreen. By default, any 
GenFields will be made visible children of this GenScreen.

Source:	Unrestricted.

Destination:	The GenSystem object.

Parameters:	None.

Return:	The optr of the current default GenScreen object (GSYI_defaultScreen).

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_GET_DEFAULT_FIELD



optr	MSG_GEN_SYSTEM_GET_DEFAULT_FIELD();

This message returns the optr of the default GenField. By default, new 
applications will be made generic children of this GenField.

Source:	Unrestricted.

Destination:	The GenSystem object.

Parameters:	None.

Return:	The optr of the current default GenField object (GSYI_defaultField).

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_SET_DEFAULT_FIELD



void	MSG_GEN_SYSTEM_SET_DEFAULT_FIELD(

	optr	defaultField);

This message changes the default GenField for the GenSystem. By default, 
new applications will be made generic children of this GenField.

Source:	Unrestricted.

Destination:	The GenSystem object.

Parameters:	optr	The optr of the new default GenField object.

Return:	Nothing.

Interception:	Not intercepted.

	26.2.4	Advanced GenSystem Usage

MSG_GEN_SYSTEM_SET_PTR_IMAGE, 
MSG_GEN_SYSTEM_NOTIFY_SYS_MODAL_WIN_CHANGE, 
MSG_GEN_SYSTEM_MARK_BUSY, MSG_GEN_SYSTEM_MARK_NOT_BUSY, 
MSG_GEN_SYSTEM_BRING_GEODE_TO_TOP, 
MSG_GEN_SYSTEM_LOWER_GEODE_TO_BOTTOM

You may alter the pointer image in use at the system level with 
MSG_GEN_SYSTEM_SET_PTR_IMAGE. Pass this message the PointerDef 
image to use and the PointerImageLevel for the pointer image to 
represent.

MSG_GEN_SYSTEM_NOTIFY_SYS_MODAL_WIN_CHANGE is sent to the 
GenSystem whenever it needs to check the status of any system-modal 
windows. This message is called by the UI whenever it needs to check this 
information. The message looks for the top window on the screen residing at 
a window priority of WIN_PRIO_MODAL within a window layer of 
LAYER_PRIO_MODAL; it then re-directs input to the owning geode's input 
object. If no system modal window is up, input returns along its normal flow 
pattern.

MSG_GEN_SYSTEM_BRING_GEODE_TO_TOP raises a geode's layer to the top, 
giving the application the focus and target (if it is focusable and/or 
targetable). Applications will not generally send this message; instead, they 
will send MSG_GEN_BRING_TO_TOP to the application object, and its handler 
will send MSG_GEN_SYSTEM_BRING_GEODE_TO_TOP to the GenSystem.

MSG_GEN_SYSTEM_LOWER_GEODE_TO_BOTTOM lowers a geode's layer to 
the bottom, releases the focus and target from the application (if it had 
them), and then determines the most suitable geode to grant the focus and 
target exclusives to. Again, applications will not generally send this message; 
instead, they will send MSG_GEN_LOWER_TO_BOTTOM to the application 
object, and its handler will send 
MSG_GEN_SYSTEM_LOWER_GEODE_TO_BOTTOM to the GenSystem.

n	MSG_GEN_SYSTEM_SET_PTR_IMAGE



 void	MSG_GEN_SYSTEM_SET_PTR_IMAGE(

	optr		ptrImage,

	PtrImageLevel 		level);

This message alters the system-wide pointer image. 

Source:	Unrestricted.

Destination:	The GenSystem object.

Parameters:	optr	A pointer to a PointerDef structure.

level	The PtrImageLevel to use. 

Return:	Nothing.

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_NOTIFY_SYS_MODAL_WIN_CHANGE



 void	MSG_GEN_SYSTEM_NOTIFY_SYS_MODAL_WIN_CHANGE();

This message is sent to the system object by the UI when it needs to check 
the status of any system modal windows.

Source:	The UI. You should not send this message yourself.

Destination:	The GenSystem object.

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_MARK_BUSY



 void	MSG_GEN_SYSTEM_MARK_BUSY();

This message is called by the GenField or GenApplication object while an 
application is being launched but is not yet on screen. While marked busy, 
the UI will continue to allow mouse events through. Each message sent to the 
system object needs a MSG_GEN_SYSTEM_MARK_NOT_BUSY to undo its 
busy state. Therefore, if multiple MSG_GEN_SYSTEM_MARK_BUSY messages 
are sent, an equal number of the MSG_GEN_SYSTEM_MARK_NOT_BUSY 
messages need to be sent to take down the busy cursor.

Source:	The UI. You should not send this message yourself.

Destination:	The GenSystem object.

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_MARK_NOT_BUSY



 void	MSG_GEN_SYSTEM_MARK_NOT_BUSY();

This message is called by the GenField or GenApplication object when an 
application no longer needs to mark an application busy that has been 
brought on-screen.

Source:	The UI. You should not send this message yourself.

Destination:	The GenSystem object.

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_BRING_GEODE_TO_TOP



void	MSG_GEN_SYSTEM_BRING_GEODE_TO_TOP(

	word		geode,

	word		layerID,

	Handle		parentWindow);

This message raises a geode's window layer to the top and gives that geode 
the focus and target (if the geode if focusable/targetable). This message is 
called from within the UI to implement "autoraise," the automatic raising of 
a geode and the transferring of the focus and target when clicked upon. This 
message is also called by the GenApplication's handler for 
MSG_GEN_BRING_TO_TOP.

Source:	Usually the specific UI, in response to an autoraise, or in response to 
MSG_GEN_BRING_TO_TOP.

Destination:	The GenSystem object.

Parameters:	geode	GeodeHandle of the application.

layerID	LayerID of window.

parentWindow	Handle of the parent window to bring to top.

Return:	Nothing.

Interception:	Not intercepted.

n	MSG_GEN_SYSTEM_LOWER_GEODE_TO_BOTTOM



void	MSG_GEN_SYSTEM_LOWER_GEODE_TO_BOTTOM(

	word		geode,

	word		layerID,

	Handle		parentWindow);

This message lowers a geode's window layer to the bottom, releases any focus 
and target exclusives, and assigns new focus and target exclusives to the 
most suitable remaining geode. This message is called by the 
GenApplication's handler for MSG_GEN_LOWER_TO_BOTTOM.

Source:	Usually in response to MSG_GEN_LOWER_TO_BOTTOM.

Destination:	The GenSystem object.

Parameters:	geode	GeodeHandle of the application.

layerID	LayerID of the window.

parentWindow	Handle of the parent window to lower to the 
bottom.

Return:	Nothing.

Interception:	Generally not intercepted.

	26.3	The GenScreen Object


The GenScreen object is an abstract representation of the video screen in use 
by the system. Its visible bounds are the bounds of the associated screen's 
video driver.

Currently, only one screen may be in use at a time, so there will be only one 
GenScreen at any time. (In the future, multiple screens may be supported.) 
Every visible component of your system will therefore be associated with a 
single GenScreen object. 

	26.3.1	GenScreen Instance Data

GenScreenClass instance data is internal and should never be set or 
altered by your application. It is provided here for reference, in case you need 
to examine the data during debugging.

@instance Handle			GSCI_videoDriver;

GSCI_videoDriver stores the handle of the current video driver in use by the 
system. This video driver will be used in building the visible tree beneath this 
object. You should never set this video driver yourself.

	26.4	GenField Objects


The GenField object sets the generic field in which all GenApplications 
attached below it will reside. There may be several GenFields at the same 
time; each provides a distinct environment for applications. For example, in 
Geoworks Ensemble, the Beginner, Intermediate, and Advanced Rooms are 
GenFields.

	26.4.1	GenField Features

GenField objects perform many functions. All of these functions are 
transparent to the application; indeed, most applications can ignore the 
GenField's existence. Among other things, the GenField does the following:

u	It provides a field on which to display windows and other independent UI 
objects (such as icons, detached menus, etc.).

u	It sets the complexity level (novice, advanced, etc.) for all applications 
under it.

u	It manages the Express menu (if one is present).

	26.4.2	GenField Instance Data

GenFieldClass instance data is internal and should never be set or altered 
by your application. It is provided here for reference, in case you need to 
examine the data during debugging.

Code Display 26-2 GenField Instance Data

/* All of these instance fields are internal. They are listed and described here 
 * for background information only. */

@instance GenFieldFlags			GFI_flags = 0;

typedef ByteFlags GenFieldFlags;
#define GFF_DETACHING				0x80
#define GFF_LOAD_BITMAP				0x40
#define GFF_RESTORING_APPS				0x20
#define GFF_NEEDS_WORKSPACE_MENU				0x10

@instance optr			GFI_visParent = 0;
@instance byte			GFI_numDetachedApps = 0;
@instance byte			GFI_numRestartedApps = 0;
@instance byte			GFI_numAttachingApps = 0;
@instance ChunkHandle			GFI_apps = 0;
@instance ChunkHandle			GFI_processes = 0;
@instance ChunkHandle			GFI_genApplications = 0;
@instance byte			GFI_numAppsToCheck = 0;
@instance optr			GFI_notificationDestination = 0;



GFI_flags stores the GenFieldFlags of the GenField object. These flags are 
for internal bookkeeping purposes.

GFI_visParent stores the optr of the GenScreen object that acts as this 
GenField's visible parent. This is typically set just before setting the 
GenField GS_USABLE (although it may be left to the specific UI to fill in.) 
During MSG_META_DETACH, this field is cleared; it may not be saved to a 
state file.

GFI_numDetachedApps stores the number of applications that were detached 
by the system upon MSG_META_DETACH. These applications and their 
associated state data will be saved to the GFI_apps chunk so that they will be 
brought up in their previous state.

GFI_numRestartedApps stores the number of applications that have been 
restarted from state files upon MSG_META_ATTACH. These restarted 
applications should reflect the applications detached during the previous 
system shutdown.

GFI_numAttachingApps stores the number of applications currently trying to 
attach to the system. The system keeps track of these applications in case the 
system must shutdown during an application's attach cycle.

GFI_apps stores a chunk array of AppInstanceReference structures. This 
data is used on MSG_META_ATTACH to bring up applications to their 
previous state.

GFI_processes similarly stores a chunk array of processes in progress under 
this GenField. This chunk array is saved to state so that these processes may 
continue when GEOS is restarted.

GFI_genApplications stores the number of GenApplications currently 
launched within the GenField. This data is not saved to state.

GFI_numAppsToCheck stores the number of applications the UI must check 
with before shutting down.

GFI_notificationDestination stores the object that should receive the Field's 
notification messages (MSG_META_FIELD_NOTIFY_DETACH, 
MSG_META_FIELD_NOTIFY_NO_FOCUS, 
MSG_META_FIELD_NOTIFY_START_LANUCHER_ERROR).

	26.4.2.1	GenField Messages

GenFieldClass provides a variety of messages to communicate with the 
system object and applications. Most of these messages are internal, and 
those that are not internal are rarely needed. You may in rare cases find it 
useful to subclass GenField objects, in which case you may need to intercept 
some of the following messages.

		Background Bitmaps

MSG_GEN_FIELD_RESET_BG, MSG_GEN_FIELD_ENABLE_BITMAP

The GenField object may have a bitmap attached to it, to display in the field 
below the applications.

		Field Start-up and Shutdown

MSG_GEN_FIELD_EXIT_TO_DOS, MSG_GEN_FIELD_ABOUT_TO_CLOSE, 
MSG_GEN_FIELD_NO_APPS_RESTORED, 
MSG_GEN_FIELD_OPEN_WINDOW_LIST, 
MSG_GEN_FIELD_GET_TOP_GEN_APPLICATION, 
MSG_GEN_FIELD_GET_LAUNCH_MODEL

MSG_GEN_FIELD_EXIT_TO_DOS is sent when the field should exit the system 
and return to the DOS prompt. This message is sent to the GenField object so 
that fields may intercept it and perform their own shutdown maintenance. 
You should only intercept this if you create a custom GenField.

MSG_GEN_FIELD_ABOUT_TO_CLOSE is sent by a GenField environment 
application (such as Welcome) to tell the field that it is about to be closed. If 
`quitOnClose' is set in the field's .INI file, the GenField will attempt to quit all 
applications running in that GenField. Otherwise, the GenField does 
nothing; it waits until all open applications are exited, at which point 
MSG_META_FIELD_NOTIFY_NO_FOCUS will be sent to the GenField.

MSG_GEN_FIELD_NO_APPS_RESTORED is sent to the GenField object when 
the Field has been restarted to inform it that no applications have been 
restarted from the state file.

MSG_GEN_FIELD_OPEN_WINDOW_LIST is sent to the GenField to bring up a 
window list dialog. Certain specific UIs (such as Presentation Manager) 
support this. Other specific UIs may ignore this message.

MSG_GEN_FIELD_GET_TOP_GEN_APPLICATION returns the top (visual) 
GenApplication for the GenField sent this message. 
MSG_GEN_FIELD_GET_LAUNCH_MODEL retrieves the UILaunchModel in 
use for this field.

n	MSG_GEN_FIELD_EXIT_TO_DOS



void	MSG_GEN_FIELD_EXIT_TO_DOS();

This message requests the GenField to exit the system and return to DOS. 
The message is sent to the GenField so that custom fields (such as Welcome) 
can intercept the message and react accordingly by initiating shutdown 
procedures.

Source:	Usually the UI.

Destination:	GenField object.

Interception:	May be intercepted if you have a custom GenField object that needs to 
perform certain shutdown procedures before exiting to DOS (such as 
shutting down applications).

n	MSG_GEN_FIELD_ABOUT_TO_CLOSE



void	MSG_GEN_FIELD_ABOUT_TO_CLOSE();

This message is sent by an environment application (like Welcome) to inform 
a GenField that it is about to be closed. The GenField then has the option of 
quitting any applications or waiting until the applications themselves are 
closed by the user. If `quitOnClose' is set the GenField's .INI file category, 
then the GenField will quit all open applications. Otherwise, it will ignore 
the request to quit.

Source:	Unrestricted, though usually an environment application resident on 
top of a GenField object.

Destination:	The GenField object.

Interception:	May be intercepted if you have a custom GenField.

n	MSG_GEN_FIELD_NO_APPS_RESTORED



void	MSG_GEN_FIELD_NO_APPS_RESTORED();

This message serves as notification that no processes have been restarted 
from the state file.

Source:	The kernel

Destination:	GenField object

Interception:	May be intercepted to support custom behavior for a custom GenField 
object.

n	MSG_GEN_FIELD_OPEN_WINDOW_LIST



void	MSG_GEN_FIELD_OPEN_WINDOW_LIST();

This message may be sent by any object that wishes to bring up a GenField's 
window list dialog (if available).

Source:	Unrestricted.

Destination:	GenField object under a specific UI that supports window list dialogs.

Interception:	Generally not intercepted.

n	MSG_GEN_FIELD_GET_TOP_GEN_APPLICATION



optr	MSG_GEN_FIELD_GET_TOP_GEN_APPLICATION();

This message returns the GenField's top application object.

Source:	Unrestricted.

Destination:	GenField object.

Return:	optr of top visual GenApplication object.

Interception:	Generally not intercepted.

n	MSG_GEN_FIELD_GET_LAUNCH_MODEL



word	MSG_GEN_FIELD_GET_LAUNCH_MODEL();

This message returns the GenField's UILaunchModel in use.

Source:	Unrestricted.

Destination:	GenField object.

Return:	UILaunchModel in use by the GenField.

Interception:	Generally not intercepted.
