Windowing Support (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Cursors, Previous: Misc. Functions, Up: Part V Some Useful Functions [Contents][Index]

### 33.2 Windowing Support

Some of the following routines are also used internally by the Forms Library as an attempt to localize window system dependencies and may be of some general use. Be warned that these routines may be subject to changes, both in their API and/or functionality.

You can create and show a window with the following routines

    Window fl_wincreate(const char *name);
    Window fl_winshow(Window win);

where the parameter `win` of `fl_winshow()` is the window ID returned by `fl_wincreate()`. The title of the window is set by the `name` argument.

Between the creation and showing of the window other attributes of the window can be set. Note that a window opened this way is always a top level window and uses all the Forms Library’s defaults (visual, depth etc.). Another thing about `fl_winshow()` is that it will wait for and gobble up the first `Expose` event and you can draw into the window immediately after the function returns.

It is sometimes more convenient to create and show a window in a single call using

    Window fl_winopen(const char *name);

This will open a (top-level) window with the title `name`. A window so opened can be drawn into as soon as the function returns, i.e., `fl_winopen()` waits until the window is ready to be drawn to.

The newly opened window will have the following default attributes

`event_mask`

  `ExposureMask`, `KeyPressMask`, `KeyReleaseMask`, `ButtonPressMask`, `ButtonReleaseMask`, `OwnerGrabButtonMask`, `ButtonMotionMask`, `PointerMotionMask`, `PointerMotionHintMask`, `StructureNotifyMask`

`backing_store`

  as set by `fl_cntl.backingStore`

`class`

  `InputOutput`

`visual`

  same as Forms Library’s default

`colormap`

  same as Forms Library’s default

To make a top-level window a sub-window of another window use the following routine

    int fl_winreparent(Window win, Window new_parent);

The origin of the window `win` will be at the origin of the parent window `new_parent`. At the time of the function call, both the window and the parent window must be valid windows.

By default, a newly opened window will have a size of 320 by 200 pixels and no other constraints. You can modify the default or constraints using the following routines prior to calling `fl_winopen()`:

    void fl_initial_winsize(FL_Coord w, FL_Coord h);
    void fl_winsize(FL_Coord w, FL_Coord h);

These two routines set the preferred window size. `w` and `h` are the width and height of the window in pixels. `fl_winsize()` in addition will make the window non-resizeable (but you can still resize the window programmatically) by setting the minimum and maximum window size to the requested size via `WMHints`. The effect of a window having this property is that it can’t be interactively resized (provided the window manager cooperates).

Also the state of the window when opening it can be influenced by the function

    void fl_initial_winstate(int state);

where `state` is on of the XLib constants `NormalState` (the default) or `IconicState`, which will result in the opened window being iconified. The third possible constant, `WithdrawnState`, doesn’t make much sense in this context.

It is sometimes desirable to have a window that is resizeable but only within a useful range. To set such a constraint use the following functions:

    void fl_winminsize(Window window, FL_Coord minw, FL_Coord minh);
    void fl_winmaxsize(Window window, FL_Coord maxw, FL_Coord maxh);

These two routines can also be used after a window has become visible. For windows still to be created/opened, use `None` for the window parameter. For example, if we want to open a window of 640 by 480 pixels and have it remain resizeable but within a permitted range, code similar to the following can be used:

    fl_initial_winsize(640, 480);
    fl_winminsize(None, 100,100);
    fl_winmaxsize(None, 1024,768)
    win = fl_winopen("MyWin");

In addition to the window size preference you can also set the preferred position of a window to be opened:

    void fl_winposition(FL_Coord x, FL_Coord y);

where `x` and `y` are the coordinates of the upper-left corner of the window relative to the root window.

Alternatively, you can set the geometry (position and size) in a single function call:

    void fl_initial_wingeometry(FL_Coord x, FL_Coord y,
                                FL_Coord w, FL_Coord h);
    void fl_wingeometry(FL_Coord x, FL_Coord y,
                        FL_Coord w, FL_Coord h);

Again, windows for which `fl_wingeometry()` had been created will not allow interactive resizing later on.

There are further routines that can be used to change other aspects of the window to be created:

    void fl_winaspect(Window win, FL_Coord x, FL_Coord y);

This will set the aspect ratio of the window for later interactive resizing.

To change the window title (and its associated icon title) use

    void fl_wintitle(Window win, const char *title);
    void fl_wintitle_f(Window win, const char *fmt, ...);

While the first function only accepts a simple string for the window title the second one allows to pass a format string just like the one used for `printf()` etc. and an appropriate number of further arguments which are used to construct the title.

To change the icon title only use the routines

    void fl_winicontitle(Window win, const char *title);
    void fl_winicontitle_f(Window win, const char *fmt, ...);

To install an icon for the window use

    void fl_winicon(Window win, Pixmap icon, Pixmap mask);

You can suppress the window manager’s decoration or make a window a transient one by using the following routines prior to creating the window

    void fl_noborder(void);
    void fl_transient(void);

You can also set the background of the window to a certain color using the following call

    void fl_winbackground(Window win, unsigned long pixel);

It is possible to set the steps by which the size of a window can be changed by using

    void fl_winstepsize(Window win, int xunit, int yunit);

where `xunit` and `yunit` are the number of pixels of changes per unit in x- and y- directions, respectively. Changes to the window size will be multiples of these units after this call. Note that this only applies to interactive resizing.

To change constraints (size and aspect ratio) on an active window, you can use the following routine

    void fl_reset_winconstraints(Window win);

The following routines are available to get information about an active window win:

    void fl_get_winsize(Window win, FL_Coord *w, FL_Coord *h);
    void fl_get_winorigin(Window win, FL_Coord *x, FL_Coord *y);
    void fl_get_wingeometry(Window win, FL_Coord *x, FL_Coord *y,
                            FL_Coord *w, FL_Coord *h);

All values returned are in pixels. The origin of a window is measured from the upper left hand corner of the root window.

To change the size of a window programmatically the following function is available:

    void fl_winresize(Window win, FL_Coord neww, FL_Coord newh);

Resizing will not change the origin of the window (relative to the root window). While the window gets resized originally set restraints will remain unchanged. E.g., if a window was not permitted to be resized interactively it will continue to remain unresizeable by the user.

To move a window without resizing it use the following function:

    void fl_winmove(Window win, FL_Coord newx, FL_Coord newy);

To move and resize a window, use the following routine

    void fl_winreshape(Window win, FL_Coord newx, FL_Coord newy,
                       FL_Coord neww, FL_Coord newh);

The following routine is available to iconify a window

    int fl_iconify(Window win);

The return value is nonzero when the message, asking for iconification of the window, was send successfully to the window manager, otherwise zero (but this may not be taken as a sure sign that the window was really iconified).

To make a window invisible use

    void fl_winhide(Window win);

A window hidden this way can be shown again later using `fl_winshow()`.

To hide and destroy a window, use the following calls

    void fl_winclose(Window win);

There will be no events generated from `fl_winclose()`, i.e., the function waits and gobbles up all events for window `win`. In addition, this routine also removes all callbacks associated with the closed window.

The following routine can be used to check if a window ID is valid or not

    int fl_winisvalid(Window win);

Note that excessive use of this function may negatively impact performance.

Usually an X application should work with window managers and accepts the keyboard focus assignment. In some special situations, explicit override of the keyboard focus might be warranted. To this end, the following routine exists:

    void fl_winfocus(Window win);

After this call keyboard input is directed to window `win`.

Next: Cursors, Previous: Misc. Functions, Up: Part V Some Useful Functions [Contents][Index]