hpux Man Page: World(3x)

Man Pages

Back to Software Index BORDER=0

Manpage Top Level

World(3X) manual page Table of Contents

Name

World - establish connection to the display

World manages the application’s environment with respect to the X Window System. It establishes a connection to the X server and manages the display. It reads application specific X resources and processes application specific command line options. It also processes a set of predefined command line options described in the "COMMAND LINE OPTIONS" section below.

An InterViews Plus application must create a World object prior to creating any other InterViews Plus objects. This is because world initializes certain display specific variables used by the other classes. If these values are nil when another object is created, it could cause a core dump.

An InterViews Plus application has a class name and an instance name. The class name is passed as the first argument to the World constructor. It is used in setting application X resources, usually in an app-default file of the same name. The instance name can be set in one of several ways:

.
By using the -name command line option. See the COMMAND LINE OPTIONS section.
.
By setting the environment variable RESOURCE_NAME .
.
If not defined in 1. or 2. above, use argv[0] which is the name of the program given to the shell.

It is theoretically possible to create multiple World objects, one for each display attached to a single X server. Attempting this may cause unanticipated results.

Class Hierarchy

World

Constructors

World (const char* classname, int& argc, char** argv, const OptionDesc= nil, const PropertyData= nil)

Creates the world.

Sets the application’s class name to classname. If an app-default file of the same name exists in the X11 library directory under the sub-directory app-defaults, it will be searched for application X resource settings.

The argc and argv arguments are typically passed in from main().

Command Line Options

The World constructor takes an OptionDesc* argument. If non-nil, the OptionDesc* parameter is an array of option descriptors used to parse application-specific command line options.

This struct contains three or four fields depending on the style:

A name used on the command line.

A path specifying the attribute.

A style specifying the location of the value.

A default value (only used for
OptionValueImplicit).

Valid styles are:

OptionPropertyNext

Next arg is an attribute:value pair.

OptionValueNext

Next arg is value.

OptionValueImplicit

Use specified default value.

OptionValueIsArg

Arg is value.

OptionValueAfter

Remainder of arg is value.

The following example demonstrates each option style:

OptionDesc options[] ={
      { "button=", "*quitButton", OptionValueAfter },
      { "-blink", "*blinking", OptionValueImplicit, "Off" },
      { "-f", "*foreground", OptionValueNext },
      { "-x", nil, OptionPropertyNext },
      { "white", "*background", OptionValueIsArg },
      { nil }
};

In our example, if the command lines options are:

% prog button=Quit -blink -f black -x "*title:App" white

The following global X resource settings will be set:

quitButton = Quit

blinking = Off

foreground = black

title = App

background = white

The following command line options are defined, interpreted, and removed
from
argvby InterViews Plus.

-backgroundNext argument sets the background color. -bgSame as-background.-displayNext
argument specifies the target workstation display. -dbufTurns double buffering
on.-explicitSets*keyboardFocusPolicytoexplicit.-foregroundNext argument sets
the foreground color. -fgSame as -foreground.-fontNext argument sets the text
font. -fnSame as-font.-geometryNext argument sets the first top-level interactor’s
position and size. The geometry specification has the form =WxH+XOFF+YOFF.TheXOFFandYOFF
are relative to the top left hand corner of the display. A negative XOFF
(YOFF)specifies the offset of the interactor’s right (bottom) edge from
the right (bottom) side of the screen. -iconicStarts up the first top-level
interactor in iconic form. -nameNext argument sets the instance name of all
top-level interactors that do not have their own instance names. -nodbufTurns
double buffering off.-pointerSets*keyboardFocusPolicytopointer.-reverseSwaps
default foreground and background colors. -rawTurns off the virtual binding
mechanism. SeeVirtualBindings(3X).-rvSame as-reverse.-synchronousForces synchronous
operation with the X Window System. -+synchronousTurns off synchronous operations.-titleNext
argument sets the first top-level interactor’s title bar name. -xrmNext argument
sets an attribute:valueproperty. After interpreting and stripping all known
options fromargv,the Worldconstructor setsargcto the number of uninterpreted
options that remain inargv.Default PropertiesThe World constructor takes
a PropertyData* argument. If non-nil, the PropertyData* parameter is an
array of structures that each contain two string fields: the path specifying
the attribute the value The following example demonstrates the form
of a PropertyData array:

PropertyData properties[] = {
{ "*colorLabel", "Colors: " },
{ "*startValue", "-1" },
{ "*Message*font", "user8x16" }
};

The first two lines create new application specific X resources. These attributes can be set with with X resource mechanism. The third line is setting a default value for an already existing X resource, font.

X resources are searched with the following precedence order:

.
Any application defaults (specified by the PropertyData array).
.
Application defaults from <Xlib>/app-defaults/classname Where <Xlib> is the path to the User defaults, usually in $HOME/.Xdefaults, or in the xrdb database.
.
Command-line arguments. Command-line arguments override user defaults, and both override application defaults.

The following global default properties are defined by InterViews Plus:

PropertyData defpropvalues[] = {
    { "*double_buffered", "on" },
    { "*background", "#ffffff" },
    { "*brush_width", "0" },
    { "*font", "fixed" },
    { "*foreground", "#000000" },
    { "*monochrome", "off" },
    { "*synchronous", "off" },
    { "*highlightColor", "#000000" },
    { "*highlightThickness", "2" },
    { "*keyboardFocusPolicy", "explicit" },
    { "*highlightOnEnter", "off" },
    { "*ignoreVirtualBindings", "off" },
    { nil }
};

Public Operations

virtual int argc() const

Returns the number of arguments remaining in argv after the constructor has removed the ones in which it is interested.

virtual char** argv() const

Returns the argument vector after having been stripped of arguments of interest to the constructor.

virtual const Color* background() const

Returns the default background color associated with the display. If a value for background is defined at the top-level of the property sheet (an application level resource), then it is used. Otherwise, a system default is used.

void Change(Interactor*)

Notifies the world that the interactor size has changed and resizes the interactor. This is called on interactors that have been inserted directly into the world.

virtual const char* classname() const

Returns the class name associated with the world.

static World* current()

Returns the current world. The current world is set when a world is created or an event is received for the display associated with a world.

virtual Display* display() const

Returns a pointer to the current display.

virtual boolean done() const

Returns if the current session is done.

virtual boolean double_buffered() const

Returns if windows on the display should, by default, be double-buffered.

virtual void flush()

Repairs all damaged windows on the display and then send any pending requests to the window system.

void Flush ()

Calls flush() to repair all damaged windows on the display and then send any pending requests to the window system. If you wish to modify the Flush() operation when deriving from world, you would modify the virtual function flush().

virtual const Font* font() const

Returns the default font associated with the display. If a value for Font is defined at the top-level of the property sheet (an application level resource), then it is used. Otherwise, a system default is used.

virtual const Color* foreground() const

Returns the default foreground color associated with the display. If a value for foreground is defined at the top-level of the property sheet (an application level resource), then it is used. Otherwise, a system default is used.

unsigned int Height ()

Returns the height of the screen, in pixels,.

void Insert(Interactor*)

void Insert(Interactor*, IntCoord x, IntCoord y, Alignment = BottomLeft)

Perform the same action as the InsertTopLevel() operation. Provided for backward compatibility with earlier Stanford InterViews releases.

void InsertApplication (Interactor*)

void InsertApplication (Interactor*, IntCoord x, IntCoord y, Alignment = BottomLeft)

Insert an application interactor in the world, with optional <x, y> coordinates relative to the lower left corner of the screen, and optional alignment value. If no <x, y> coordinates are passed, it will default to 0, 0 and an alignment of BottomLeft. See Alignment(3X) for valid alignment values. Window and session managers will consider an application interactor to be the program’s main top-level interactor.

void InsertIcon (Interactor*)

void InsertIcon (Interactor*, IntCoord x, IntCoord y, Alignment = BottomLeft)

Insert an icon interactor into the world, with optional <x, y> coordinates relative to the lower left corner of the screen, and optional alignment value. The interactor is not mapped (not visible) when it is inserted. InsertIcon() is called automatically when a top level interactor is inserted, if the interactor has an icon and the icon has not yet been inserted. See Alignment(3X) for valid alignment values.

void InsertPopup (Interactor*)

void InsertPopup (Interactor*, IntCoord x, IntCoord y, Alignment = BottomLeft)

Insert a popup interactor into the world, with optional <x, y> coordinates relative to the lower left corner of the screen and optional alignment value. The interactor is inserted without any interaction with the window manager. A popup interactor inserted without specific x- and y-coordinates will be centered on the screen, since the user cannot use the window manager’s help in placing the interactor. See Alignment(3X) for valid alignment values.

void InsertToplevel (Interactor, Interactor leader)

void InsertToplevel (Interactor, Interactor leader, IntCoord x, IntCoord y, Alignment = BottomLeft)

Insert a top-level interactor into the world, with optional <x, y> coordinates relative to the lower left corner of the screen and optional alignment value. If the interactor leader is not nil, this informs the window manager that the inserted interactor is part of a group of interactors led by leader. Some window managers may unmap a toplevel interactor when the leader interactor is iconified. See Alignment(3X) for valid alignment values.

void InsertTransient (Interactor, Interactor owner)

void InsertTransient (Interactor, Interactor owner, IntCoord x, IntCoord y, Alignment = BottomLeft)

Insert a transient interactor into the world on behalf of another interactor, with optional <x, y> coordinates relative to the lower left hand corner of the screen and optional alignment value. Some window managers will not decorate the transient interactor (i.e., no resize handles, no title bar etc.) or ask the user to place it. Some window managers may also unmap the transient interactor when its owner interactor is iconified. See Alignment(3X) for valid alignment values.

void Lower(Interactor*)

Lowers the interactor to the bottom of all other interactors.

void Move(Interactor*, IntCoord x, IntCoord y,)

Moves the interactor to a new <x, y> coordinates on the display.

virtual const char* name() const

Returns the instance name associated with the world.

virtual boolean pending() const

Returns whether or not any events are waiting to be read.

virtual boolean property_is_on(const char*) const

Returns whether or not a specific property has been set.

virtual const char* property_value(const char*) const

Returns the value associated with the passed property value.

virtual void quit()

Terminates the run loop, effectively quitting the program when used in conjunction with the default Run() operation.

void Raise(Interactor*)

Raises the interactor to the top of all other interactors.

void Remove(Interactor*)

Removes the interactor from the world.

virtual void RingBell (int volume)

Rings the display bell at volume. The possible value range for the volume is 0 to 100.

virtual void run()

Calls Interactor::Run().

void Run ()

Calls run().

virtual Session* session() const

Returns a pointer to the current Session.

virtual void SetAutoRepeat (boolean)

Turns on (true) or off (false) autorepeat for the keyboard.

virtual void SetFeedback (int thresh, int scale)

Sets the amount of magnification given to users’s movements with the pointing device. The threshold is the minimum distance at which you scale the movement and the scale is the factor by which to magnify the movement.

virtual void SetKeyClick (int volume)

Sets the volume of the audible key click to int volume. The possible range of values is 0 to 100.

virtual void SetScreen (int s)

Sets the current screen to s.

virtual boolean shaped_windows() const

Returns whether or not the display supports nonrectangular windows.

virtual Style* style() const

Returns a pointer to the display Style.

virtual void sync()

Repairs all damaged windows on the display, sends any pending requests to the window system, and waits for an acknowledgement from the window system.

void Sync ()

Calls the repair() operation on all damaged windows on the display, sends any pending requests to the window system, and waits for an acknowledgement from the window system. If you wish to modify the Sync() operation when deriving from World, you would modify the virtual function sync().

unsigned int Width ()

Returns the width, of the screen, in pixels.

Protected Operations

virtual void poll(Event&)

Sets the event to an artificial motion event based on the current pointer position and the state of the buttons and meta-keys.

virtual boolean read(long sec, long usec, Event&)

This routine should not be called by InterViews Plus programs. Reads the next event from the world associated with the event, but does not wait more than sec seconds and usec microseconds. Returns whether or not an event was found in the given time.

virtual void read(Event&)

This routine should not be called by InterViews Plus programs. Reads the next event from the world associated with the event.

virtual void unread(Event&)

This routine should not be called by InterViews Plus programs. Puts the event back on the input queue for the world associated with the event.

X Resources

display:[string]

Sets the workstation display.

double_buffered:[On|Off|True|False]

Indicates whether or not the display should use double buffering. The display hardware may not support this feature.

geometry:[string]

Sets the top level window geometry. See the -geometry option in the "COMMAND LINE OPTIONS" section above.

highlightColor:[color]:

Color of the keyboard traversal location cursor.

highlightThickness:int

Width, in pixels, of the keyboard traversal location cursor.

iconGeometry:[string]

Specifies the location of the top level window’s icon. See -geometry option in the "COMMAND LINE OPTIONS" section above. The parameters to set the dimensions may not be effective.

iconic:[On|Off|True|False]

If true, map the top level window in icon form.

keyboardFocusPolicy:[explicit|pointer]

Sets the keyboard traversal policy for the application. A value of explicit will cause the creation of tab groups and send all keyboard events to the interactor with the location cursor. A value of pointer will send keyboard events to the interactor that has the mouse pointer within its canvas.

//                          World Example
#include <ivplus/box.h>
#include <ivplus/button.h>
#include <ivplus/frame.h>
#include <ivplus/glue.h>
#include <ivplus/message.h>
#include <ivplus/world.h>
// Set a few properties with some default values.
static PropertyData properties[] = {
   {"MyApp*msgstr", "Hello World\n....Bye World!"},
   {"MyApp*font", "8x13"},
   {"MyApp*btnstr", "Push Me"},
   {nil}
};
// Set two command line options "-msgstr" & "-btnstr." The default value is
// given by PropertyData; the user can give the value after specifying
// the option i.e OptionValueNext.
static OptionDesc options[] = {
   {"-msgstr", "MyApp*msgstr", OptionValueNext},
   {"-btnstr", "MyApp*btnstr", OptionValueNext},
   {nil}
};
int main(int argc, char **argv)
{
   // Create the world to get the connection with the display.
   // Use argc, argv as command line options.
   // New options are defined in options array.
   // Default properties are defined in properties array.
   World* world = new World("MyApp", argc, argv, options, properties);
  
   // Create a message with the string as defined in PropertyData.
   Message* msg = new Message(world->GetAttribute("msgstr"));
   // Create a push button.
   PushButton* button = new PushButton(world->GetAttribute("btnstr"),
                                        new ButtonState(0), 1);
  
   // Enclose the message and the push button in a box.
   VBox* appbox = new VBox(new Frame(msg), new VGlue, button);
   // Map the window.
   world->InsertApplication(new Frame(appbox, 1, BevelOut));
   // Enter the event loop.
   world->Run();
   // This program can be invoked with the options:
   // -btnstr "This is Button String" -msgstr "This is \nMessage String"
   return 0;
}

Files

world.h

quitButton	=	Quit
blinking	=	Off
foreground	=	black
title	=	App
background	=	white