F - Operating System Specific Issues

Fltk X-specific interface

On Unix/X you can include this file to access fltk's X-specific functions. Be warned that some of the structures and calls in it are subject to change in future version of fltk. Try to avoid doing this so your code is portable.

Handling other X events

Install a function to parse unrecognized events. If fltk cannot figure out what to do with an event, it calls each of these functions (most recent first) until one of them returns non-zero. If none of them returns non zero then the event is ignored.

Fltk calls this for any X events it does not recognize, or X events with a window id that fltk does not recognize. You can look at the X event with the fl_xevent.

The argument is zero for unrecognized X events. These handlers are also called for global shortcuts and some other events that the widget they were passed to did not handle. In this case the argument is non-zero (for instance FL_SHORTCUT).

extern XEvent* fl_xvent;

The most current X event.

extern ulong fl_event_time;

This is the time stamp from the most recent X event that reported it (not all do). Many X calls (like cut and paste) need this value.

Window fl_xid(const Fl_Window*);

Returns the xid for a window, or zero if not shown().

Fl_Window* fl_find(ulong xid);

Return the Fl_Window that corresponds to the given xid, or null if not found. This uses a cache so it is slightly faster than iterating through the windows yourself.

int fl_handle(const XEvent&);

This call allows you to supply the X events to fltk, which may allow fltk to cooperate with another toolkit or library. The return value is true if fltk understood the event (if the window does not belong to fltk and the add_handler() functions all ignore it this returns false).

Besides feeding events your code should call Fl::flush() periodically so that fltk redraws it's windows.

This function will call the callback functions. It will not return until they complete. In particular if a callback pops up a modal window (by calling fl_ask(), for instance) it will not return until the modal function returns.

These global variables are set before Fl_Widget::draw() is called, or by Fl_Window::make_current() You must use them to produce Xlib calls. Don't attempt to change them. A typical X drawing call is written like this:

XDrawSomething(fl_display, fl_window, fl_gc, ...);

Other information such as the position or size of the X window can be found by looking at Fl_Window::current(), which returns a pointer to the Fl_Window being drawn.

unsigned long fl_xpixel(Fl_Color i);

Returns the X pixel number used to draw the given fltk color index. This is the X pixel that fl_color(i) would use.

unsigned long fl_xpixel(uchar r, uchar g, uchar b);

Return the X pixel number used to draw the given rgb color. This is the X pixel that fl_color(r,g,b) would use.

extern XFontStruct* fl_xfont;

Points at the font selected by the most recent fl_font(font,size). This is not necessarily the current font of fl_gc (that's not set until fl_draw(const char*,...) is called).

Fltk uses only a single display, screen, X visual, and X colormap. This greatly simplifies it's internal structure and makes it much smaller and faster. You can change which it uses by setting global variables before the first Fl_Window::show() is called. You may also want to call Fl::visual(int), which is a portable interface to get a full color and/or double buffered visual.

int Fl::display(const char *)

Set which X display to use. This actually does setenv("DISPLAY", x) so that child programs will display on the same screen if called with exec(). This must be done before the display is opened. This call is provided on MSWindows, but it just sets the environment variable and has no other effect.

extern Display* fl_display;

The open X display. This is needed as an argument to most Xlib calls. Don't attempt to change it! This is zero before the display is opened.

void fl_open_display();

Open the display. Does nothing if it is already open. This will make sure fl_display is non-zero. You should call this if you wish to do X calls and there is a chance that your code will be called before the first show() of a window.

This may call Fl::abort() if there is an error opening the display.

void fl_close_display();

This closes the X connection. You do not need to call this to exit, and in fact it is faster to not do so! It may be useful to call this if you want your program to continue without the X connection. You cannot open the display again, and probably cannot call any fltk functions.

extern int fl_screen;

Which screen to use. This is set by fl_open_display() to the default screen. You can change it by setting this to a different value immediately afterwards. It can also be set by changing the last number in the Fl::display() string: host:0,#.

extern XVisualInfo* fl_visual;
extern Colormap fl_colormap;

The visual and colormap that fltk will use for all windows. These are set by fl_open_display() to the default visual and colormap. You can change them before calling show() on the first window. Typical code for changing the default visual:

Fl::args(argc, argv); // do this first so $DISPLAY is set
fl_open_display();
fl_visual = find_a_good_visual(fl_display, fl_screen);
if (!fl_visual) Fl::abort("No good visual");
fl_colormap = make_a_colormap(fl_display, fl_visual->visual, fl_visual->depth);
// it is now ok to show() windows:
window->show(argc, argv);

To do this, you need to make a subclass of Fl_Window and override some of these virtual functions:

virtual void Fl_Window::show()

If the window is already shown() this must cause it to be raised, this can usually be done by calling Fl_Window::show(). If not shown() your implementation must call either Fl_X::set_xid() or Fl_X::make_xid():

Fl_X* Fl_X::set_xid(Fl_Window*, Window xid);

Allocate a hidden structure called an Fl_X, put the xid into it, and set a pointer to it from the Fl_Window. This causes Fl_Window::shown() to return true.

void Fl_X::make_xid(Fl_Window*, XVisualInfo* = fl_visual, Colormap = fl_colormap);

This static method does the most onerous parts of creating an X window, including setting the label, resize limitations, etc. It then does set_xid with this new window and maps the window.

Example:

void MyWindow::show() {
  if (shown()) {Fl_Window::show(); return;}  // you must do this!
  fl_open_display();	// necessary if this is first window
  // we only calcualte the necessary visual & colormap once:
  static XVisualInfo *visual;
  static Colormap colormap;
  if (!visual) {
    visual = figure_out_visual();
    colormap = XCreateColormap(fl_display, RootWindow(fl_display,fl_screen),
			        vis->visual, AllocNone);
  }
  Fl_X::make_xid(this, visual, colormap);
}

virtual void Fl_Window::flush()

This virtual function is called by Fl::flush() to update the window. For fltk's own windows it does this by setting the global variables fl_window and fl_gc and then calling the draw() method. For your own windows you might just want to put all the drawing code in here.

The X region that is a combination of all damage() calls done so far is in Fl_X::i(this)->region. If null then you should redraw the entire window. The undocumented function fl_clip_region(XRegion) will initialize the fl clip stack with a region or null for no clipping. You must set region to null afterwards as fl_clip_region() now owns it and will delete it when done.

If damage()==2 then only X expose events have happened. This may be useful if you have an undamaged image (such as a backing buffer) around.

Here is a sample where an undamaged image is kept somewhere:

void MyWindow::flush() {
  fl_clip_region(Fl_X::i(this)->region);
  Fl_X::i(this)->region = 0;
  if (damage() != 2) {... draw things into backing store ...}
  ... copy backing store to window ...
}

virtual void Fl_Window::hide()

Destroy the window server copy of the window. Usually you will destroy contexts, pixmaps, or other resources used by the window, and then call Fl_Window::hide() to get rid of the main window identified by xid(). If you override this, you must also override the destructor as shown:

void MyWindow::hide() {
  if (mypixmap) {
    XFreePixmap(fl_display,mypixmap);
    mypixmap = 0;
  }
  Fl_Window::hide(); // you must call this
}

virtual void Fl_Window::~Fl_Window()

Because of the way C++ works, if you override hide() you must override the destructor as well (otherwise only the base class hide() is called):

MyWindow::~MyWindow() {
  hide();
}

(back to contents)

#include <FL/x.H>
Fltk MSWindows-specific interface

Handling other MSWindows messages

A single WNDCLASSEX called "FLTK" is created. All Fl_Windows are of this class. This window class is created the first time Fl_Window::show() is called.

You can probably combine fltk with other libraries that make their own MSWindows window classes. The easiest way is to call Fl::wait(), it will call DispatchMessage for all messages to the other windows. If necessary you can let the other library take over (as long as it calls DispatchMessage()), but you will have to arrange for the function Fl::flush() to be called regularily (otherwise widgets will not update), and timeouts and the idle function will not work.

extern MSG fl_msg;

The most recent message read by GetMessage (which is called by Fl::wait(). This may not be the most recent message sent to an fltk window, because silly MSWindows calls the handle procedures directly for some events (sigh).

void Fl::add_handler(int (*f)(int));

Install a function to parse unrecognized messages sent to fltk windows. If fltk cannot figure out what to do with a message, it calls each of these functions (most recent first) until one of them returns non-zero. The argument passed to the fuctions is zero. If all the handlers return zero then fltk calls DefWindowProc(...).

HWND fl_xid(const Fl_Window*);

Returns the window handle for a Fl_Window, or zero if not shown().

Fl_Window* fl_find(HWND xid)

Return the Fl_Window that corresponds to the given window handle, or null if not found. This uses a cache so it is slightly faster than iterating through the windows yourself.

These global variables are set before draw() is called, or by Fl_Window::make_current() You can refer to them when needed to produce GDI calls. Don't attempt to change them. The functions return GDI objects for the current color set by fl_color(), these are created as needed and cached. A typical GDI drawing call is written like this:

DrawSomething(fl_gc, ..., fl_brush());

It may also be useful to refer to Fl_Window::current() to get the window's size or position.

How to not get a MSDOS console window

To not produce a "console" window when you run your program add the following secret incantation to the Micro$oft linker:

        /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup

Unfortunately this seems to completely disable stdin/stdout, even if you run the program from a console. So don't do this until you have debugged your program!

Other hints

I use capital C as the extension for c++ source code, for instace for Fluid output. Unfortunately there is no way to convince VC++ to use this except to tell it to compile *everything* using C++ by putting the switch "/TP" in the options. This makes it impossible to combine old C code and fltk code.

Known bugs

If program is deactivated, Fl::wait() does not return until it is activated again, even though many events are delivered to the program. This can cause idle background processes to stop unexpectedly. This also happens while the user is dragging or resizing windows or otherwise holding the mouse down. I was forced to remove most of the efficiency fltk uses for redrawing in order to get windows to update while being moved. This is a design error in MSWindows and probably impossible to get around.

Fl_Gl_Window::can_do_overlay() returns true until the first time it attempts to draw an overlay, and then correctly returns whether or not there is overlay hardware.

Cut text contains ^J rather than ^M^J to break lines. This is a feature, not a bug.

I can't seem to get SetCapture (used by Fl::grab()) to work, and I can't find a way to stop the main window title from turning gray while menus are popped up.

glpuzzle program does not animate unless you resize it first. Unknown why.

Fl_Window::fullscreen() not implemented (should take over the screen without a title bar). Currently does maximize instead.

Import .bmp files into fluid. Wonko has the specs.

Can't set icon of windows.