Documentation: The FXWindow Class

Documentation: The FXWindow Class [Remove Frame]

The FXWindow class manages a window on the screen. FXWindow is the base class of all FOX GUI widgets such as buttons and sliders, in other words, all widgets are ultimately derived from FXWindow. All windows are organized into a so called widget tree; at the root of this widget tree is the root window which is a special window which represents the entire screen. Top level or shell windows are children of the root window; they're special because top level windows, such as the main window and dialog box, are positioned and resized directly by the user. Layout manager windows are composite windows which may have zero or more children, possibly including other layout managers. Layout managers position their child-windows according to certain layout patterns and layout flags. Child windows or simple windows are windows which do not themselves have any children. Child windows are usually simple controls such as buttons and sliders.

Navigating The Widget Tree

As each window is positioned somewhere in the widget tree, each window maintains some information about where in the tree it is; this information can be obtained with the following API's:

FXWindow::getParent()

This function returns the window which is this window's immediate parent. For the root window, this returns NULL as the root window does not have a parent.

FXWindow::getRoot()

This function returns the root window, or the window's ultimate parent.

FXWindow::getShell()

This function returns the top level or shell window of this window. The shell window is always a child of the root window.

FXWindow::getOwner()

This returns the window's owner, if any. The owner of a window is the window that is resposible for this window in some way. For example, a modal dialog may be owned by a main window. The system usually ensures that a top level window stays on top of the window that owns it. Windows which have no owner return NULL as the owner window.

FXWindow::getFirst()

This returns the first child of this window, if any.

FXWindow::getLast()

This returns the last child of this window, if any.

FXWindow::getNext()

This returns the next sibling of this window. Use this function to iterate over all windows which have a common parent.

FXWindow::getPrev()

This returns the previous sibling of this window.

Querying Widget Tree Information

There are a number of common questions about the various possible relationships between windows in the widget tree. While it is possible to answer them with the API's above, it is cumbersome and so a number of API's are available to make this more easy:

FXWindow::isChildOf(window)

Determines if this window is a child of the given window.

FXWindow::containsChild(window)

Determines if this window contains the given window as a child.

FXWindow::containsChild(window)

Determines if this window contains the given window as a child; also returns TRUE if the given window is the same as this window.

FXWindow::numChildren()

Returns the number of children of this window by counting them.

FXWindow::indexOfChild(window)

Returns the 0-based position of the given window in this window's list of children. If the window is not a child of this window then it returns -1.

FXWindow::childAtIndex(index)

Returns the child window at the given position, or NULL if the index is invalid.

FXWindow::commonAncestor(window1,window2)

This function determines the lowest common ancestor of window1 and window2.

Primary,Clipboard, Drag and Drop Selections

Many widgets display some data. For example, a text widget can display some text. When the user highlights a range of text, a primary selection is in effect. This primary selection can be obtained by other widgets, or even by other programs. For instance a selection of some text may be pasted into a terminal by means of the middle mouse button under X-Windows (under MS-Windows, the primary selection only works within the same FOX program).

When a selection is copied or cut to the clipboard, a clipboard-selection is in effect. Usually, a clipboard selection is made by Ctrl-C for copy, or a Ctrl-X for cut. Again, other widgets or other programs can obtain this data from the clipboard. For instance, an application can obtain the clipboard selection by a paste operation, typically invoked by means of Ctrl-V.

Finally, when a drag operation is started from this widget, a drag-and-drop selection is in effect. Drag and drop selections are only in effect while a drag operation is ongoing. In contrast, a clipboard or primary selection remains in effect until another selection is made (possibly by another application).

The following API's pertain to the selections:

FXWindow::hasSelection()

Return true if this window owns the primary selection.

FXWindow::acquireSelection(types,FXuinumtypes)

Try to acquire the primary selection, given a list of drag types. The list of drag types must have been previously registered by means of FXApp::registerDragType().