GEOS SDK TechDocs
|
| 
4.2 The Process Object
| 
4.4 Code and Message Handlers
As stated earlier, the bulk of the Hello World application consists of User Interface objects. These objects are defined just after the Process object in your application's code, and they are given certain attributes and instance data. Once they have been defined, in general you will not have to bother with them again.
UI objects are arranged into resources. Each resource is allocated a block on the global heap when the program is launched; therefore, resources should be kept to reasonable sizes (2K-6K) whenever possible.
The application object resides within its own resource so the application takes up very little memory when iconified (minimized). Menus for complex applications are usually put in a menu resource. Most other UI gadgetry is put in a resource called "Interface" (though this name is not required).
Every application must have an application object, an instance of the class
GenApplicationClass
. The application object handles and manages many application-related things such as dispatching input sent by the input manager to the application. The application object must be the top-level generic object in every application. The name of the application object is also stated in the geode parameters file line
appobj
(see The Hello World Parameters File
).
Hello World's Application Object shows Hello World's application object definition. The comments in the code are extensive and explain the purpose of each line.
Code Display 2-4 Hello World's Application Object
This display is part of hello3.goc and follows the previous display directly.
/* * Application Object * The very top-level generic object of an application MUST be a GenApplication * object. The hello3.gp file contains an "appobj" statement which indicates * that this "HelloApp" object is in fact the top-level UI object. * This object should be in its own resource so it takes up very little memory * when minimized. Note that the name of the resource may be whatever you choose; * it does not have to be AppResource. */
@start AppResource; /* Begin definition of objects in AppResource. */
@object GenApplicationClass HelloApp = {
GI_comp = @HelloPrimary;
/* The GI_comp attribute lists the generic children
* of the object. The HelloApp object has just one
* child, the primary window of the application. */
gcnList(MANUFACTURER_ID_GEOWORKS, GAGCNLT_WINDOWS) = @HelloPrimary; /* This GCN list determines which of the application's * window objects must be made visible when the * application first starts up. */ }
@end AppResource /* End definition of objects in AppResource. */
Every application must have a primary window object of class
GenPrimaryClass
. This object will draw and manage the primary window and will work with the UI and the geometry manager to arrange all the children of the window properly. It will also automatically put up the system-controlled gadgets (such as the system window menu, the minimize/maximize buttons, and the Express menu).
The Hello World primary window has only two children, one of which is a menu. The other is the view object, which occupies the remaining space within the primary. The view object, as stated earlier, automatically handles all scrolling and clipping of documents. Its scrollable area is eight and a half inches by eleven inches. A description of what the view window does and how it interacts with the Process object to draw the text is given in The Scrolling View and Drawing the Text
.
Hello World's Primary and View Objects shows the definition and attributes of each of these two objects. See the illustration above for a diagram of the two objects implemented under the OSF/Motif specification.
Code Display 2-5 Hello World's Primary and View Objects
This display is part of hello3.goc and directly follows the previous display.
@start Interface; /* This resource is for miscellaneous UI objects. */
@object GenPrimaryClass HelloPrimary = {
GI_visMoniker = "Hello World Sample Application";
/* This title will appear at the top of the primary
* window as the name of the application. */
GI_comp = @HelloView, @HelloMenu; /* This window has two children, the GenView object * and the GenInteraction menu object. */
/* For simplicity, this application is not given an icon. Therefore, we must
* prevent the user from being able to minimize the application. This is
* done by applying the following attribute to the GenPrimary object. Note that
* GenPrimaryClass is a subclass of GenDisplayClass, in which this attribute
* is actually defined. */
ATTR_GEN_DISPLAY_NOT_MINIMIZABLE;
/* The following hint allows the primary window object to size itself
* according to its children (the view object). */
HINT_SIZE_WINDOW_AS_DESIRED;
/*
* When the specific UI permits, let's not show the menu bar on
* startup. Some applications would find the extra space this leaves
* helpful, in particular on the small screens of pen-based devices,
* though for this simple application it doesn't really matter.
*/
ATTR_GEN_DISPLAY_MENU_BAR_POPPED_OUT;
HINT_DISPLAY_MENU_BAR_HIDDEN_ON_STARTUP;
}
/* GenView object * This GenView object creates a window where the application can display portions * of a document as necessary. We want it to be scrollable, so the specific UI * (OSF/Motif) will create scroll bars which the user can interact with. Whenever a * portion of the window needs to be redrawn, the GenView object will invalidate * a portion of the window, causing a MSG_META_EXPOSED to be sent to the * application. The application will draw the document into the window. The * window keeps track of a mask which is used to clip the application's * drawing operations so only the invalid portion of the window is drawn. */
@object GenViewClass HelloView = {
GVI_horizAttrs = @default | GVDA_SCROLLABLE | GVDA_NO_LARGER_THAN_CONTENT;
/* This makes the View scrollable in the
* horizontal dimension and keeps it from
* growing larger than our document. */
GVI_vertAttrs = @default | GVDA_SCROLLABLE | GVDA_NO_LARGER_THAN_CONTENT; /* This makes the View scrollable in the * vertical dimension and keeps it from * growing larger than our document. */
GVI_docBounds = { 0, 0, 72*17/2, 72*11 };
/* This sets the document size (scrollable
* bounds) of the GenView. */
GVI_content = process; /* This sets the output of the View--where it will * send its MSG_META_EXPOSEDs--to be the * application's Process object. */
/* * This view will not take text input, so specify that no floating * keyboard should come up. Otherwise, we would get a floating * keyboard by default on pen-based systems. */ ATTR_GEN_VIEW_DOES_NOT_ACCEPT_TEXT_INPUT; }
@end Interface /* End definition of objects in this resource. */
The Hello World program has one menu, called "Menu", located in the primary window's menu bar. Menus are instances of
GenInteractionClass
with the GIV_POPUP attribute set in the
GII_visibility
field. The moniker of the menu object appears on the menu bar (see The Hello World Menu
for the definition of Hello World's menu).
The menu should have one child for each of its entries. In Hello World, the only child is the dialog box, whose moniker appears as the text of the menu item that brings up the box.
Code Display 2-6 The Hello World Menu
/This display is part of hello3.goc and follows the previous display directly.
/* HelloMenu Menu * Menus are of GenInteractionClass. The moniker of a menu is used to show the menu * on the primary's menu bar (thus, "Menu" will show up in Hello World's menu bar). * Each of the menu's children (in the GI_comp field) will be an entry or a * collection of entries in the menu. To separate a menu from a dialog * box GenInteraction, you must apply the visibility GIV_POPUP. A dialog box will * have the visibility GIV_DIALOG. */
@start MenuResource;
@object GenInteractionClass HelloMenu = {
GI_visMoniker = 'M', "Menu"; /* The moniker of the menu is used in
* the primary window's menu bar. */
GI_comp = @HelloColorBox; /* The only child of the menu (the only * item in the menu) is the dialog box. */
GII_visibility = GIV_POPUP; /* This attribute designates the GenInteraction * as a menu or a submenu. */ }
@end MenuResource;
The Hello World Dialog Box and Its Triggers shows the code for the dialog box and its triggers.
Dialog boxes in GEOS may be of
GenInteractionClass
, or dialogs may be called up and instantiated during execution with kernel routines. Hello World uses a GenInteraction in order to have a "floating" dialog box that may be retained and moved around the screen.
When a dialog box is brought up by a menu item, the moniker of the dialog box object will be used as the text of the menu item. Thus, the word "Color" will appear both at the top of the dialog box and in the menu.
Children of a dialog box are arranged by the geometry manager. In general, children will be arranged top to bottom (or left to right, depending on the specific UI) as they are defined. Thus, the two triggers will appear "Blue" first and "Gold" second (on bottom). The dialog box will automatically size itself to fit all its children properly. Dialog boxes, unlike windows, are generally not resizable.
Each of the triggers will appear as a simple button big enough to hold its moniker. Each trigger, when pressed, sends a specified message to a specified object. The Blue trigger sends
MSG_HELLO_CHANGE_TO_BLUE
to the application's Process object, and the Gold trigger sends the message
MSG_HELLO_CHANGE_TO_GOLD
to the Process object. These messages are placed in the Process object's message queue and require no return values.
Code Display 2-7 The Hello World Dialog Box and Its Triggers
This display is part of hello3.goc and follows the previous display directly.
/* HelloColorBox Dialog Box * Dialog boxes are of GenInteractionClass. The moniker of the dialog box will * appear at the top as the box's title. Additionally, if the GenInteraction * is a child of a menu interaction, the moniker will also serve as the text that * appears in the menu item that brings up the dialog box. The dialog will * automatically size itself to be large enough to hold all its children. Thus, * this dialog will be small (with just two children, each a trigger with a short * moniker). */
@object GenInteractionClass HelloColorBox = {
GI_visMoniker = 'C', "Color"; /* The moniker will be displayed both as the
* dialog's title and as the menu item that
* brings the dialog up. */
GI_comp = @HelloBlueTrigger, @HelloGoldTrigger; /* The two triggers are the only gadgets * in the dialog box. */
GII_visibility = GIV_DIALOG; /* In order for this interaction to be * a dialog box, this attribute must be set. */ }
/* GenTriggers * Buttons are implemented by GenTriggerClass. When a trigger is pushed by the user * (clicked on with the mouse), it will send the specified message to the specified * output object. In both cases below, the trigger will send an application-defined * message to the application's Process object. A trigger's moniker is displayed * within the trigger. In this case, both are text, but any graphics could be used * instead to create graphical triggers easily. (E.g. a blue flag and a gold flag * rather than the words "Blue" and "Gold.") */
@object GenTriggerClass HelloBlueTrigger = {
GI_visMoniker = 'B', "Blue"; /* The 'B' indicates the keyboard navigation
* character for this trigger. */
GTI_destination = process; /* Send the message to the Process object. */
GTI_actionMsg = MSG_HELLO_CHANGE_TO_BLUE; /* Send this message. */
}
@object GenTriggerClass HelloGoldTrigger = {
GI_visMoniker = 'G', "Gold"; /* The 'G' indicates the keyboard navigation
* character for this trigger. */
GTI_destination = process; /* Send the message to the Process object. */
GTI_actionMsg = MSG_HELLO_CHANGE_TO_GOLD; /* Send this message. */
}
GEOS SDK TechDocs
|
| 4.2 The Process Object
| 4.4 Code and Message Handlers